From 7a32f3e5555df1741585b8842e7023cffa6fc5a0 Mon Sep 17 00:00:00 2001 From: Hasini Gunasinghe Date: Fri, 17 Nov 2023 02:18:23 +0000 Subject: [PATCH] Documentation updates as per the API council review and proof reading. This CL updates description of the `Nonce` used in key exchange as per API council review. Additionally, this includes updates to the documentation that are found to be suitable as per further proof reading. Test: N/A Change-Id: Ie59e3a10eb8844fcfac9dad60c9d431ae499ee40 --- .../hardware/security/authgraph/Arc.cddl | 20 ++--- .../authgraph/IAuthGraphKeyExchange.aidl | 84 +++++++++++-------- .../security/authgraph/SessionInfo.aidl | 4 +- .../authgraph/SessionInitiationInfo.aidl | 10 ++- 4 files changed, 67 insertions(+), 51 deletions(-) diff --git a/security/authgraph/aidl/android/hardware/security/authgraph/Arc.cddl b/security/authgraph/aidl/android/hardware/security/authgraph/Arc.cddl index 4c1b965ab1..0bc39d6c99 100644 --- a/security/authgraph/aidl/android/hardware/security/authgraph/Arc.cddl +++ b/security/authgraph/aidl/android/hardware/security/authgraph/Arc.cddl @@ -28,19 +28,19 @@ ArcProtectedHeaders = { ? -70003 : int, ; Timestamp in milliseconds since some starting point (generally ; the most recent device boot) which all of the applications within ; the secure domain must agree upon - ? -70004 : bstr .size 16, ; Nonce used in key exchange methods + ? -70004 : bstr .size 16, ; Nonce (a cryptographic random number of 16 bytes) used in key + ; exchange methods ? -70005 : PayloadType, ; Payload type, if needed to disambiguate, when processing an arc ? -70006 : int, ; Version of the payload structure (if applicable) ? -70007 : int, ; Sequence number (if needed to prevent replay attacks) ? -70008 : Direction ; Direction of the encryption key (i.e. whether it is used to ; encrypt incoming messages or outgoing messages) ? -70009 : bool, ; "authentication_completed" - this is used during authenticated - ; key exchange indicate whether signature verification is done - ? -70010 : bstr .size 32 ; "session_id" computed during key exchange protocol + ; key exchange to indicate whether signature verification is done + ? -70010 : bstr .size 32 ; "session_id" computed during the key exchange protocol } -; Permissions indicate what an arc can be used with. Permissions are added to an arc during the -; `create()` primitive operation and are propagated during `mint` and `snap` primitive operations. +; Permissions indicate what an arc can be used with. Permission = &( -4770552 : IdentityEncoded, ; "source_id" - in the operations performed by a source, the ; source adds its own identity to the permissions of an arc. @@ -54,12 +54,10 @@ Permission = &( ; biometrics. ) -; Limitations indicate what restrictions are applied on the usage of an arc. Permissions are added -; to an arc during the `create` primitive operation and are propagated during `snap` primitive -; operation. +; Limitations indicate what restrictions are applied on the usage of an arc. Limitation = &( - -4770554 : bstr, ; "challenge" - is added to an arc that transfers an auth key to a channel - ; key, in order to ensure the freshness of the authentication. + -4770554 : bstr, ; "challenge" - is added to an arc that encrypts an auth key from a + ; channel key, in order to ensure the freshness of the authentication. ; A challenge is issued by a sink (e.g. Keymint TA, Biometric TAs). ) @@ -83,7 +81,7 @@ Payload = &( ; Any other payload formats should also be defined here ) -SecretKey = &( ; One of the payload types of an Arc is a secret key +SecretKey = &( SymmetricKey, ECPrivateKey, ; Private key of a key pair generated for key exchange ) diff --git a/security/authgraph/aidl/android/hardware/security/authgraph/IAuthGraphKeyExchange.aidl b/security/authgraph/aidl/android/hardware/security/authgraph/IAuthGraphKeyExchange.aidl index 6ceb09cd08..a3fb95963f 100644 --- a/security/authgraph/aidl/android/hardware/security/authgraph/IAuthGraphKeyExchange.aidl +++ b/security/authgraph/aidl/android/hardware/security/authgraph/IAuthGraphKeyExchange.aidl @@ -41,8 +41,8 @@ import android.hardware.security.authgraph.SessionInitiationInfo; interface IAuthGraphKeyExchange { /** * This method is invoked on P1 (source). - * Create an ephermeral EC key pair on NIST curve P-256 and a nonce (of 16 bytes) for - * key exchange. + * Create an ephermeral EC key pair on NIST curve P-256 and a nonce (a cryptographic random + * number of 16 bytes) for key exchange. * * @return SessionInitiationInfo including the `Key` containing the public key of the created * key pair and an arc from the per-boot key to the private key, the nonce, the persistent @@ -52,8 +52,8 @@ interface IAuthGraphKeyExchange { * `SessionInitiationInfo` serves two purposes: * i. A mapping to correlate `create` and `finish` calls to P1 in a particular instance of the * key exchange protocol. - * ii.A way to minimize the in-memory storage (P1 can include the nonce in the protected headers - * of the arc). + * ii.A way to minimize the in-memory storage of P1 allocated for key exchange (P1 can include + * the nonce in the protected headers of the arc). * However, P1 should maintain some form of in-memory record to be able to verify that the input * `Key` sent to `finish` is from an unfinished instance of a key exchange protocol, to prevent * any replay attacks in `finish`. @@ -66,9 +66,9 @@ interface IAuthGraphKeyExchange { * 0. If either `peerPubKey`, `peerId`, `peerNonce` is not in the expected format, return * errors: INVALID_PEER_KE_KEY, INVALID_IDENTITY, INVALID_PEER_NONCE respectively. * 1. Create an ephemeral EC key pair on NIST curve P-256. - * 2. Create a nonce (of 16 bytes). - * 3. Compute the diffie-hellman shared secret: Z. - * 4. Compute a salt = bstr .cbor [ + * 2. Create a nonce (a cryptographic random number of 16 bytes). + * 3. Compute the Diffie-Hellman shared secret: Z. + * 4. Compute a salt_input = bstr .cbor [ * source_version: int, ; from input `peerVersion` * sink_pub_key: bstr .cbor PlainPubKey, ; from step #1 * source_pub_key: bstr .cbor PlainPubKey, ; from input `peerPubKey` @@ -77,7 +77,8 @@ interface IAuthGraphKeyExchange { * sink_cert_chain: bstr .cbor ExplicitKeyDiceCertChain, ; from own identity * source_cert_chain: bstr .cbor ExplicitKeyDiceCertChain, ; from input `peerId` * ] - * 5. Extract a cryptographic secret S from Z, using the salt from #4 above. + * 5. Extract a cryptographic secret S from Z, using the SHA256 digest of the salt_input + * as the salt. * 6. Derive two symmetric encryption keys of 256 bits with: * i. b"KE_ENCRYPTION_KEY_SOURCE_TO_SINK" as context for the key used to encrypt incoming * messages @@ -96,28 +97,29 @@ interface IAuthGraphKeyExchange { * part of the party's identity. * * @param peerPubKey - the public key of the key pair created by the peer (P1) for key exchange + * in `create` * * @param peerId - the persistent identity of the peer * - * @param peerNonce - nonce created by the peer + * @param peerNonce - nonce created by the peer in `create` * * @param peerVersion - an integer representing the latest protocol version (i.e. AIDL version) * supported by the peer * - * @return KeInitResult including the `Key` containing the public key of the created key pair, - * the nonce, the persistent identity, two shared key arcs from step #7, session id, signature - * over the session id and the negotiated protocol version. The negotiated protocol version - * should be less than or equal to the peer's version. + * @return KeInitResult including the `Key` containing the public key of the key pair created in + * step #1, the nonce from step #2, the persistent identity of P2, two shared key arcs + * from step #7, session id from step #10, signature over the session id from step #11 and the + * negotiated protocol version. The negotiated protocol version should be less than or equal to + * the `peerVersion`. * - * Note: The two shared key arcs in the return type: `KeInitResult` serves two purposes: + * Note: The two shared key arcs in the return type: `KeInitResult` serve two purposes: * i. A mapping to correlate `init` and `authenticationComplete` calls to P2 in a particular * instance of the key exchange protocol. * ii.A way to minimize the in-memory storage of P2 allocated for key exchange. * However, P2 should maintain some in-memory record to be able to verify that the input - * `sharedkeys` sent to `authenticationComplete` and to any subsequent AuthGraph protocol - * methods are valid shared keys agreed with the party identified by `peerId`, to prevent - * any replay attacks in `authenticationComplete` and in any subsequent AuthGraph protocol - * methods which use the shared keys to encrypt the secret messages. + * `sharedkeys` sent to `authenticationComplete` are from an unfinished instance of a key + * exchange protocol carried out with the party identified by `peerId`, to prevent any replay + * attacks in `authenticationComplete`. */ KeInitResult init( in PubKey peerPubKey, in Identity peerId, in byte[] peerNonce, in int peerVersion); @@ -133,8 +135,8 @@ interface IAuthGraphKeyExchange { * exchange protocol, return error: INVALID_KE_KEY. Similarly, if the public key or the * arc containing the private key in `ownKey` is invalid, return INVALID_PUB_KEY_IN_KEY * and INVALID_PRIV_KEY_ARC_IN_KEY respectively. - * 1. Compute the diffie-hellman shared secret: Z. - * 2. Compute a salt = bstr .cbor [ + * 1. Compute the Diffie-Hellman shared secret: Z. + * 2. Compute a salt_input = bstr .cbor [ * source_version: int, ; the protocol version used in `create` * sink_pub_key: bstr .cbor PlainPubKey, ; from input `peerPubKey` * source_pub_key: bstr .cbor PlainPubKey, ; from the output of `create` @@ -143,7 +145,8 @@ interface IAuthGraphKeyExchange { * sink_cert_chain: bstr .cbor ExplicitKeyDiceCertChain, ; from input `peerId` * source_cert_chain: bstr .cbor ExplicitKeyDiceCertChain, ; from own identity * ] - * 3. Extract a cryptographic secret S from Z, using the salt from #2 above. + * 3. Extract a cryptographic secret S from Z, using the SHA256 digest of the salt_input + * as the salt. * 4. Derive two symmetric encryption keys of 256 bits with: * i. b"KE_ENCRYPTION_KEY_SOURCE_TO_SINK" as context for the key used to encrypt outgoing * messages @@ -164,25 +167,26 @@ interface IAuthGraphKeyExchange { * part of the party's identity. * * @param peerPubKey - the public key of the key pair created by the peer (P2) for key exchange + * in `init` * * @param peerId - the persistent identity of the peer * * @param peerSignature - the signature created by the peer over the session id computed by the - * peer + * peer in `init` * - * @param peerNonce - nonce created by the peer + * @param peerNonce - nonce created by the peer in `init` * * @param peerVersion - an integer representing the protocol version (i.e. AIDL version) * negotiated with the peer * - * @param ownKey - the key created by P1 (source) in `create()` for key exchange + * @param ownKey - the key created by P1 (source) in `create` for key exchange * - * @return SessionInfo including the two shared key arcs from step #9, session id and the - * signature over the session id. + * @return SessionInfo including the two shared key arcs from step #9, session id from step #7 + * and the signature over the session id from step #10. * - * Note: The two shared key arcs in the return type: `SessionInfo` serves two purposes: + * Note: The two shared key arcs in the return type: `SessionInfo` serve two purposes: * i. A mapping to correlate the key exchange protocol taken place with a particular peer and - * subsequent AuthGraph protocols execued with the same peer. + * subsequent AuthGraph protocols executed with the same peer. * ii.A way to minimize the in-memory storage for shared keys. * However, P1 should maintain some in-memory record to be able to verify that the shared key * arcs sent to any subsequent AuthGraph protocol methods are valid shared keys agreed with the @@ -196,21 +200,33 @@ interface IAuthGraphKeyExchange { * This method is invoked on P2 (sink). * Perform the following steps: * 0. If input `sharedKeys` is invalid (i.e. they cannot be decrypted with P2's per-boot key - * or they are not in P2's in-memory records as valid shared keys agreed with the party - * identified by `peerId`), return error: INVALID_SHARED_KEY_ARCS. + * or they are not in P2's in-memory records for unfinished instances of a key exchange + * protocol carried out with the party identified by the identity included in the + * `source_id` protected header of the shared key arcs), + * return error: INVALID_SHARED_KEY_ARCS. * 1. Verify that both shared key arcs have the same session id and peer identity. - * 2. Verify the peer's signature over the session id attached to the shared key arcs' - * headers. If successful, proceed, otherwise, return error: INVALID_SIGNATURE. - * 3. Mark authentication_complete = true in the shared key arcs' headers + * 2. Verify the `peerSignature` over the session id included in the `session_id` protected + * header of the shared key arcs. + * If successful, proceed, otherwise, return error: INVALID_SIGNATURE. + * 3. Mark authentication_complete = true in the shared key arcs' headers. * * @param peerSignature - the signature created by the peer over the session id computed by the - * peer + * peer in `finish` * * @param sharedKeys - two shared key arcs created by P2 in `init`. P2 obtains from the arcs' * protected headers, the session id and the peer's identity to verify the * peer's signature over the session id. * * @return Arc[] - an array of two updated shared key arcs + * + * Note: The two returned shared key arcs serve two purposes: + * i. A mapping to correlate the key exchange protocol taken place with a particular peer and + * subsequent AuthGraph protocols executed with the same peer. + * ii.A way to minimize the in-memory storage for shared keys. + * However, P2 should maintain some in-memory record to be able to verify that the shared key + * arcs sent to any subsequent AuthGraph protocol methods are valid shared keys agreed with the + * party identified by the identity included in the `source_id` protected header of the shared + * key arcs, to prevent any replay attacks. */ Arc[2] authenticationComplete(in SessionIdSignature peerSignature, in Arc[2] sharedKeys); } diff --git a/security/authgraph/aidl/android/hardware/security/authgraph/SessionInfo.aidl b/security/authgraph/aidl/android/hardware/security/authgraph/SessionInfo.aidl index ef49a1a1c0..82b8c17622 100644 --- a/security/authgraph/aidl/android/hardware/security/authgraph/SessionInfo.aidl +++ b/security/authgraph/aidl/android/hardware/security/authgraph/SessionInfo.aidl @@ -26,8 +26,8 @@ import android.hardware.security.authgraph.SessionIdSignature; @RustDerive(Clone=true, Eq=true, PartialEq=true) parcelable SessionInfo { /** - * The arcs that encrypt the two derived symmetric encryption keys (for two-way communication) - * from the party's per-boot key. + * The arcs that encrypt the two derived symmetric encryption keys (for two-way communication). + * The encryption key is the party's per-boot key. */ Arc[2] sharedKeys; diff --git a/security/authgraph/aidl/android/hardware/security/authgraph/SessionInitiationInfo.aidl b/security/authgraph/aidl/android/hardware/security/authgraph/SessionInitiationInfo.aidl index c630d91907..8179ac2fc5 100644 --- a/security/authgraph/aidl/android/hardware/security/authgraph/SessionInitiationInfo.aidl +++ b/security/authgraph/aidl/android/hardware/security/authgraph/SessionInitiationInfo.aidl @@ -27,20 +27,22 @@ import android.hardware.security.authgraph.Key; @RustDerive(Clone=true, Eq=true, PartialEq=true) parcelable SessionInitiationInfo { /** - * An ephemeral EC key created for the ECDH process. + * An ephemeral EC key created for the Elliptic-curve Diffie-Hellman (ECDH) process. */ Key key; /** - * The identity of the party who created the Diffie-Hellman key exchange key. + * The identity of the party who creates this `SessionInitiationInfo`. */ Identity identity; /** - * Nonce value specific to this session. The nonce serves three purposes: + * Nonce (a cryptographic random number of 16 bytes) specific to this session. + * The nonce serves three purposes: * 1. freshness of key exchange * 2. creating a session id (a publicly known value related to the exchanged keys) - * 3. usage as salt into the HKDF-EXTRACT function during key derivation from the shared DH key + * 3. usage as salt into the HKDF-EXTRACT function during key derivation from the Diffie-Hellman + * shared secret */ byte[] nonce;