Merge "Documentation updates as per the API council review and proof reading."... (49875a89) · Commits · e / os / android_hardware_interfaces

security/authgraph/aidl/android/hardware/security/authgraph/Arc.cddl

+9 −11

Original line number	Diff line number	Diff line
		@@ -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
		)

security/authgraph/aidl/android/hardware/security/authgraph/IAuthGraphKeyExchange.aidl

+50 −34

Original line number	Diff line number	Diff line
		@@ -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);
		}

security/authgraph/aidl/android/hardware/security/authgraph/SessionInfo.aidl

+2 −2

Original line number	Diff line number	Diff line
		@@ -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;

security/authgraph/aidl/android/hardware/security/authgraph/SessionInitiationInfo.aidl

+6 −4

Original line number	Diff line number	Diff line
		@@ -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;