Merge "KeyMint AIDL tweaks" am: 07045b7e83 am: 0951649aaf (7958c312) · Commits · e / os / android_hardware_interfaces

security/keymint/aidl/android/hardware/security/keymint/BeginResult.aidl

+4 −1

Original line number	Original line	Diff line number	Diff line
	@@ -25,7 +25,10 @@ import android.hardware.security.keymint.KeyParameter;
	*/		*/
	@VintfStability		@VintfStability
	parcelable BeginResult {		parcelable BeginResult {
	/* This is the challenge used in verifyAuthorization. It must be a nonce. */		/**
			* This is the challenge used to verify authorization of an operation.
			* See IKeyMintOperation.aidl entrypoints updateAad() and update().
			*/
	long challenge;		long challenge;

	/**		/**

security/keymint/aidl/android/hardware/security/keymint/IKeyMintDevice.aidl

+111 −95

File changed.

Preview size limit exceeded, changes collapsed.

security/keymint/aidl/android/hardware/security/keymint/IKeyMintOperation.aidl

+42 −66

Original line number	Original line	Diff line number	Diff line
	@@ -31,12 +31,12 @@ interface IKeyMintOperation {
	* update() is called. If updateAad() is called after update(), it must return		* update() is called. If updateAad() is called after update(), it must return
	* ErrorCode::INVALID_TAG.		* ErrorCode::INVALID_TAG.
	*		*
	* If operation is in an invalid state (was aborted or had an error) update() must return		* If the operation is in an invalid state (was aborted or had an error) update() must return
	* ErrorCode::INVALID_OPERATION_HANDLE.		* ErrorCode::INVALID_OPERATION_HANDLE.
	*		*
	* If this method returns an error code other than ErrorCode::OK, the operation is aborted and		* If this method returns an error code other than ErrorCode::OK, the operation is aborted and
	* the operation handle must be invalidated. Any future use of the handle, with this method,		* the operation handle must be invalidated. Any future use of this object must return
	* finish, or abort, must return ErrorCode::INVALID_OPERATION_HANDLE.		* ErrorCode::INVALID_OPERATION_HANDLE.
	*		*
	* == Authorization Enforcement ==		* == Authorization Enforcement ==
	*		*
	@@ -58,9 +58,10 @@ interface IKeyMintOperation {
	*		*
	* o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.		* o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
	*		*
	* o The challenge field in the auth token must contain the operationHandle		* o The challenge field in the auth token must contain the value returned from
			* IKeyMintDevice::begin(), given by the challenge field of the BeginResult structure.
	*		*
	* If any of these conditions are not met, update() must return		* If any of these conditions are not met, updateAad() must return
	* ErrorCode::KEY_USER_NOT_AUTHENTICATED.		* ErrorCode::KEY_USER_NOT_AUTHENTICATED.
	*		*
	* The caller must provide the auth token on every call to updateAad(), update() and finish().		* The caller must provide the auth token on every call to updateAad(), update() and finish().
	@@ -74,7 +75,7 @@ interface IKeyMintOperation {
	*		*
	* @param input Additional Authentication Data to be processed.		* @param input Additional Authentication Data to be processed.
	*		*
	* @param authToken Authentication token. Can be nullable if not provided.		* @param authToken Authentication token, if provided.
	*		*
	* @param timeStampToken timestamp token, certifies the freshness of an auth token in case		* @param timeStampToken timestamp token, certifies the freshness of an auth token in case
	* the security domain of this KeyMint instance has a different clock than the		* the security domain of this KeyMint instance has a different clock than the
	@@ -93,18 +94,9 @@ interface IKeyMintOperation {
	* If operation is in an invalid state (was aborted or had an error) update() must return		* If operation is in an invalid state (was aborted or had an error) update() must return
	* ErrorCode::INVALID_OPERATION_HANDLE.		* ErrorCode::INVALID_OPERATION_HANDLE.
	*		*
	* To provide more flexibility for buffer handling, implementations of this method have the		* Implementations may choose how much data to return as a result of the update. This is
	* option of consuming less data than was provided. The caller is responsible for looping to		* only relevant for encryption and decryption operations, because signing returns no data
	* feed the rest of the data in subsequent calls. The amount of input consumed must be returned		* until finish. It is recommended to return data as early as possible, rather than buffer it.
	* in the inputConsumed parameter. Implementations must always consume at least one byte,
	* unless the operation cannot accept any more; if more than zero bytes are provided and zero
	* bytes are consumed, callers must consider this an error and abort the operation.
	* TODO(seleneh) update the code to always consume alll the input data. b/168665179.
	*
	* Implementations may also choose how much data to return, as a result of the update. This is
	* only relevant for encryption and decryption operations, because signing and verification
	* return no data until finish. It is recommended to return data as early as possible, rather
	* than buffer it.
	*		*
	* If this method returns an error code other than ErrorCode::OK, the operation is aborted and		* If this method returns an error code other than ErrorCode::OK, the operation is aborted and
	* the operation handle must be invalidated. Any future use of the handle, with this method,		* the operation handle must be invalidated. Any future use of the handle, with this method,
	@@ -112,8 +104,8 @@ interface IKeyMintOperation {
	*		*
	* == Authorization Enforcement ==		* == Authorization Enforcement ==
	*		*
	* Key authorization enforcement is performed primarily in begin(). The one exception is the		* Key authorization enforcement is performed primarily in IKeyMintDevice::begin(). The one
	* case where the key has:		* exception is the case where the key has:
	*		*
	* o One or more Tag::USER_SECURE_IDs, and		* o One or more Tag::USER_SECURE_IDs, and
	*		*
	@@ -130,7 +122,8 @@ interface IKeyMintOperation {
	*		*
	* o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.		* o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
	*		*
	* o The challenge field in the auth token must contain the operationHandle		* o The challenge field in the auth token must contain the challenge value contained in the
			* BeginResult returned from IKeyMintDevice::begin().
	*		*
	* If any of these conditions are not met, update() must return		* If any of these conditions are not met, update() must return
	* ErrorCode::KEY_USER_NOT_AUTHENTICATED.		* ErrorCode::KEY_USER_NOT_AUTHENTICATED.
	@@ -139,22 +132,20 @@ interface IKeyMintOperation {
	*		*
	* -- RSA keys --		* -- RSA keys --
	*		*
	* For signing and verification operations with Digest::NONE, this method must accept the entire		* For signing operations with Digest::NONE, this method must accept the entire block to be
	* block to be signed or verified in a single update. It may not consume only a portion of the		* signed in a single update. It may not consume only a portion of the block in these cases.
	* block in these cases. However, the caller may choose to provide the data in multiple		* However, the caller may choose to provide the data in multiple updates, and update() must
	* updates, and update() must accept the data this way as well. If the caller provides more		* accept the data this way as well. If the caller provides more data to sign than can be used
	* data to sign than can be used (length of data exceeds RSA key size), update() must return		* (length of data exceeds RSA key size), update() must return ErrorCode::INVALID_INPUT_LENGTH.
	* ErrorCode::INVALID_INPUT_LENGTH.
	*		*
	* -- ECDSA keys --		* -- ECDSA keys --
	*		*
	* For signing and verification operations with Digest::NONE, this method must accept the entire		* For signing operations with Digest::NONE, this method must accept the entire block to be
	* block to be signed or verified in a single update. This method may not consume only a		* signed in a single update. This method may not consume only a portion of the block.
	* portion of the block. However, the caller may choose to provide the data in multiple updates		* However, the caller may choose to provide the data in multiple updates and update() must
	* and update() must accept the data this way as well. If the caller provides more data to sign		* accept the data this way as well. If the caller provides more data to sign than can be used,
	* than can be used, the data is silently truncated. (This differs from the handling of excess		* the data is silently truncated. (This differs from the handling of excess data provided in
	* data provided in similar RSA operations. The reason for this is compatibility with legacy		* similar RSA operations. The reason for this is compatibility with legacy clients.)
	* clients.)
	*		*
	* -- AES keys --		* -- AES keys --
	*		*
	@@ -182,7 +173,7 @@ interface IKeyMintOperation {
	in @nullable TimeStampToken timeStampToken);		in @nullable TimeStampToken timeStampToken);

	/**		/**
	* Finalizes a cryptographic operation begun with begin() and invalidates operation.		* Finalizes a cryptographic operation begun with begin() and invalidates the operation.
	*		*
	* This method is the last one called in an operation, so all processed data must be returned.		* This method is the last one called in an operation, so all processed data must be returned.
	*		*
	@@ -190,8 +181,7 @@ interface IKeyMintOperation {
	* Any future use of the operation, with finish(), update(), or abort(), must return		* Any future use of the operation, with finish(), update(), or abort(), must return
	* ErrorCode::INVALID_OPERATION_HANDLE.		* ErrorCode::INVALID_OPERATION_HANDLE.
	*		*
	* Signing operations return the signature as the output. Verification operations accept the		* Signing operations return the signature as the output.
	* signature in the signature parameter, and return no output.
	*		*
	* == Authorization enforcement ==		* == Authorization enforcement ==
	*		*
	@@ -230,24 +220,19 @@ interface IKeyMintOperation {
	* Some additional requirements, depending on the padding mode:		* Some additional requirements, depending on the padding mode:
	*		*
	* o PaddingMode::NONE. For unpadded signing and encryption operations, if the provided data is		* o PaddingMode::NONE. For unpadded signing and encryption operations, if the provided data is
	* shorter than the key, the data must be zero-padded on the left before		* shorter than the key, the data must be zero-padded on the left before signing/encryption.
	* signing/encryption. If the data is the same length as the key, but numerically larger,		* If the data is the same length as the key, but numerically larger, finish() must return
	* finish() must return ErrorCode::INVALID_ARGUMENT. For verification and decryption		* ErrorCode::INVALID_ARGUMENT. For decryption operations, the data must be exactly as long
	* operations, the data must be exactly as long as the key. Otherwise, return		* as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
	* ErrorCode::INVALID_INPUT_LENGTH.
	*		*
	* o PaddingMode::RSA_PSS. For PSS-padded signature operations, the PSS salt length must match		* o PaddingMode::RSA_PSS. For PSS-padded signature operations, the PSS salt length must match
	* the size of the PSS digest selected. The digest specified with Tag::DIGEST in inputParams		* the size of the PSS digest selected. The digest specified with Tag::DIGEST in params
	* on begin() must be used as the PSS digest algorithm, MGF1 must be used as the mask		* on begin() must be used as the PSS digest algorithm, MGF1 must be used as the mask
	* generation function and SHA1 must be used as the MGF1 digest algorithm.		* generation function and SHA1 must be used as the MGF1 digest algorithm.
	*		*
	* o PaddingMode::RSA_OAEP. The digest specified with Tag::DIGEST in inputParams on begin is
	* used as the OAEP digest algorithm, MGF1 must be used as the mask generation function and
	* and SHA1 must be used as the MGF1 digest algorithm.
	*
	* -- ECDSA keys --		* -- ECDSA keys --
	*		*
	* If the data provided for unpadded signing or verification is too long, truncate it.		* If the data provided for undigested signing is too long, truncate it.
	*		*
	* -- AES keys --		* -- AES keys --
	*		*
	@@ -256,18 +241,14 @@ interface IKeyMintOperation {
	* o BlockMode::ECB or BlockMode::CBC. If padding is PaddingMode::NONE and the data length is		* o BlockMode::ECB or BlockMode::CBC. If padding is PaddingMode::NONE and the data length is
	* not a multiple of the AES block size, finish() must return		* not a multiple of the AES block size, finish() must return
	* ErrorCode::INVALID_INPUT_LENGTH. If padding is PaddingMode::PKCS7, pad the data per the		* ErrorCode::INVALID_INPUT_LENGTH. If padding is PaddingMode::PKCS7, pad the data per the
	* PKCS#7 specification, including adding an additional padding block if the data is a multiple		* PKCS#7 specification, including adding an additional padding block if the data is a
	* of the block length.		* multiple of the block length.
	*		*
	* o BlockMode::GCM. During encryption, after processing all plaintext, compute the tag		* o BlockMode::GCM. During encryption, after processing all plaintext, compute the tag
	* (Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption,		* (Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption,
	* process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, finish()		* process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, finish()
	* must return ErrorCode::VERIFICATION_FAILED.		* must return ErrorCode::VERIFICATION_FAILED.
	*		*
	* TODO: update() will need to be refactored into 2 function. b/168665179.
	*
	* @param inParams Additional parameters for the operation.
	*
	* @param input Data to be processed, per the parameters established in the call to begin().		* @param input Data to be processed, per the parameters established in the call to begin().
	* finish() must consume all provided data or return ErrorCode::INVALID_INPUT_LENGTH.		* finish() must consume all provided data or return ErrorCode::INVALID_INPUT_LENGTH.
	*		*
	@@ -284,8 +265,6 @@ interface IKeyMintOperation {
	* Tag::TRUSTED_CONFIRMATION_REQUIRED.		* Tag::TRUSTED_CONFIRMATION_REQUIRED.
	*		*
	* @return The output data, if any.		* @return The output data, if any.
	*
	* @return outParams Any output parameters generated by finish().
	*/		*/
	byte[] finish(in @nullable byte[] input, in @nullable byte[] signature,		byte[] finish(in @nullable byte[] input, in @nullable byte[] signature,
	in @nullable HardwareAuthToken authToken,		in @nullable HardwareAuthToken authToken,
	@@ -293,13 +272,10 @@ interface IKeyMintOperation {
	in @nullable byte[] confirmationToken);		in @nullable byte[] confirmationToken);

	/**		/**
	* Aborts a cryptographic operation begun with begin(), freeing all internal resources. If an		* Aborts a cryptographic operation begun with IKeyMintDevice::begin(), freeing all internal
	* operation was finalized, calling update, finish, or abort yields		* resources. If an operation was finalized, calling updateAad, update, finish, or abort yields
	* ErrorCode::INVALID_OPERATION_HANDLE. An operation is finalized if finish or abort was		* ErrorCode::INVALID_OPERATION_HANDLE. An operation is finalized if finish or abort was called
	* called on it, or if update returned an ErrorCode.		* on it, or if updateAad or update returned an ErrorCode.
	*
	* @param operationHandle The operation handle returned by begin(). This handle must be
	* invalid when abort() returns.
	*		*
	* @return error See the ErrorCode enum in ErrorCode.aidl.		* @return error See the ErrorCode enum in ErrorCode.aidl.
	*/		*/

security/keymint/aidl/android/hardware/security/keymint/IRemotelyProvisionedComponent.aidl

+1 −1

Original line number	Original line	Diff line number	Diff line
	@@ -78,7 +78,7 @@ import android.hardware.security.keymint.RpcHardwareInfo;
	* While a proper BCC, as described above, reflects the complete boot sequence from boot ROM to the		* While a proper BCC, as described above, reflects the complete boot sequence from boot ROM to the
	* secure area image of the IRemotelyProvisionedComponent, it's also possible to use a "degenerate"		* secure area image of the IRemotelyProvisionedComponent, it's also possible to use a "degenerate"
	* BCC which consists only of a single, self-signed certificate containing the public key of a		* BCC which consists only of a single, self-signed certificate containing the public key of a
	* hardware-bound key pair. This is an appopriate solution for devices which haven't implemented		* hardware-bound key pair. This is an appropriate solution for devices which haven't implemented
	* everything necessary to produce a proper BCC, but can derive a unique key pair in the secure		* everything necessary to produce a proper BCC, but can derive a unique key pair in the secure
	* area. In this degenerate case, DK_pub is the same as KM_pub.		* area. In this degenerate case, DK_pub is the same as KM_pub.
	*		*

security/keymint/aidl/android/hardware/security/keymint/KeyCreationResult.aidl

+2 −2

Original line number	Original line	Diff line number	Diff line
	@@ -58,7 +58,7 @@ parcelable KeyCreationResult {
	* There are a few variations in what is contained in `certificateChain`, depending on whether		* There are a few variations in what is contained in `certificateChain`, depending on whether
	* the caller requested attestation, whether they provided an attestation key (via the		* the caller requested attestation, whether they provided an attestation key (via the
	* `attestationKey` parameter of `generateKey()`, `importKey()` or `importWrappedKey()`), and in		* `attestationKey` parameter of `generateKey()`, `importKey()` or `importWrappedKey()`), and in
	* the non-attestaion case, whether the key can self-sign.		* the non-attestation case, whether the key can self-sign.
	*		*
	* 1. Asymmetric key attestation with factory key. If Tag::ATTESTATION_CHALLENGE is provided		* 1. Asymmetric key attestation with factory key. If Tag::ATTESTATION_CHALLENGE is provided
	* and the `attestationKey` parameter on the generate/import call is null, the returned		* and the `attestationKey` parameter on the generate/import call is null, the returned
	@@ -70,7 +70,7 @@ parcelable KeyCreationResult {
	* attestation keys.		* attestation keys.
	*		*
	* 2. Asymmetric key attestation with caller-provided key. If Tag::ATTESTATION_CHALLENGE is		* 2. Asymmetric key attestation with caller-provided key. If Tag::ATTESTATION_CHALLENGE is
	* provided and the `attestationKey` parameter on the generat/import call is non-null and		* provided and the `attestationKey` parameter on the generate/import call is non-null and
	* contains the key blob of a key with KeyPurpose::ATTEST_KEY, the returned certificate		* contains the key blob of a key with KeyPurpose::ATTEST_KEY, the returned certificate
	* chain must contain only an attestation certificate signed with the specified key. The		* chain must contain only an attestation certificate signed with the specified key. The
	* caller must know the certificate chain for the provided key. Tag::		* caller must know the certificate chain for the provided key. Tag::