1; CDDL for the Secret Management API.
2
3; The input parameter to the `processSecretManagementRequest` operation in
4; `ISecretkeeper.aidl` is always an encrypted request message, CBOR-encoded as a
5; COSE_Encrypt0 object.  The encryption uses the first of the keys agreed using
6; the associated AuthGraph instance, referred to as `KeySourceToSink`. Additionally,
7; an external aad is used - RequestSeqNum.
8ProtectedRequestPacket = CryptoPayload<RequestPacket, KeySourceToSink, RequestSeqNum>
9
10CryptoPayload<Payload, Key, SeqNum> = [ ; COSE_Encrypt0 (untagged), [RFC 9052 s5.2]
11    protected: bstr .cbor {
12        1 : 3,                  ; Algorithm: AES-GCM mode w/ 256-bit key, 128-bit tag
13        4 : bstr                ; key identifier set to session ID produced
14                                ; by AuthGraph key exchange.
15    },
16    unprotected: {
17        5 : bstr .size 12       ; IV
18    },
19    ciphertext : bstr           ; AES-GCM-256(Key, bstr .cbor Payload)
20                                ; AAD for the encryption is CBOR-serialized
21                                ; Enc_structure (RFC 9052 s5.3) with SeqNum as the external_aad.
22]
23
24; Once decrypted, the request packet is an encoded CBOR array holding:
25; - An initial integer indicating which request is present.
26; - Subsequent objects holding the parameters for that specific request.
27RequestPacket =
28    [GetVersionOpcode, GetVersionParams] /
29    [StoreSecretOpcode, StoreSecretParams] /
30    [GetSecretOpcode, GetSecretParams]
31
32GetVersionOpcode = 1            ; Get version of the SecretManagement API
33StoreSecretOpcode = 2           ; Store a secret
34GetSecretOpcode = 3             ; Get the secret
35
36; Retrieve Secretkeeper version.
37GetVersionParams = ()
38
39; Store a secret identified by the given ID, with access to the secret policed
40; by the associated sealing policy.
41StoreSecretParams = (
42    id : SecretId,
43    secret : Secret,
44    sealing_policy : bstr .cbor DicePolicy,
45)
46
47; INCLUDE DicePolicy.cddl for: DicePolicy
48
49; Retrieve a secret identified by the given ID, policed according to the sealing
50; policy that was associated with the secret.  If successful, optionally also
51; update the sealing policy for the secret.
52GetSecretParams = (
53    id : SecretId,
54    ; Retrieving the value of a secret may optionally also update the sealing
55    ; policy associated with a secret.
56    updated_sealing_policy : bstr .cbor DicePolicy / nil,
57)
58
59SecretId = bstr .size 64        ; Unique identifier of the secret.
60Secret = bstr .size 32          ; The secret value.
61
62; A monotonically incrementing number is associated with each RequestPacket to prevent replay
63; of messages within a session. This starts with 0 and is incremented (by 1) for each request
64; in a session. Secretkeeper implementation must maintain an expected RequestSeqNum for each
65; session (increasing it by 1 for each SecretManagement request received). This will be used in
66; in decryption (external_aad).
67RequestSeqNum = bstr .cbor uint     ; Encoded in accordance with Core Deterministic Encoding
68                                    ; Requirements [RFC 8949 s4.2.1]
69
70; The return value from a successful `processSecretManagementRequest` operation is a
71; response message encrypted with the second of the keys agreed using the associated
72; AuthGraph instance, referred to as `KeySinkToSource`.
73ProtectedResponsePacket = CryptoPayload<ResponsePacket, KeySinkToSource, ResponseSeqNum>
74
75; Once decrypted, the inner response message is encoded as a CBOR array holding:
76; - An initial integer return code value.
77; - Subsequently:
78;    - If the return code is zero: result value(s).
79;    - If the return code is non-zero: an error message.
80ResponsePacket =
81    [0, Result] /
82    [error_code: ErrorCode, error_message: tstr]
83
84; An error code in the inner response message indicates a failure in
85; secret management processing.
86ErrorCode = &(
87    ; Use this as if no other error code can be used.
88    ErrorCode_UnexpectedServerError: 1,
89    ; Indicate the Request was malformed & hence couldnt be served.
90    ErrorCode_RequestMalformed: 2,
91    ; Requested Entry not found.
92    ErrorCode_EntryNotFound: 3,
93    ; Error happened while serialization or deserialization.
94    ErrorCode_SerializationError: 4,
95    ; Indicates that Dice Policy matching did not succeed & hence access not granted.
96    ErrorCode_DicePolicyError: 5,
97)
98
99; The particular result variant present is determined by which request
100; message was originally sent.
101Result = &(
102    GetVersionResult,
103    StoreSecretResult,
104    GetSecretResult,
105)
106
107GetVersionResult = (1)
108
109StoreSecretResult = ()
110
111GetSecretResult = (secret : Secret)
112
113; Analogous to RequestSeqNum, Secretkeeper must maintain ResponseSeqNum for each session.
114; This will be input to the encryption (ProtectedResponsePacket) as external_aad.
115ResponseSeqNum = bstr .cbor uint    ; Encoded in accordance with Core Deterministic Encoding
116                                    ; Requirements [RFC 8949 s4.2.1]
117