Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 382e3483 authored by David Drysdale's avatar David Drysdale
Browse files

KeyMint HAL: clarify spec text 

 - Make clear that CERTIFICATE_NOT_{BEFORE,AFTER} must be specified for
   generating/importing asymmetric keys.
 - Fix enforcement level of Tag::UNLOCKED_DEVICE_REQUIRED.
 - Fix reference to exportKey() for Tag::STORAGE_KEY to mention
   convertStorageKeyToEphemeral instead.
 - Mark Tag::CONFIRMATION_TOKEN as deprecated.

Test: none, comment change
Bug: 188672564
Merged-In: I68727b024f6b6743403941763aefca64e3eb091a
Change-Id: I68727b024f6b6743403941763aefca64e3eb091a
Ignore-AOSP-First: already merged in aosp/master
parent 3fd4ec47

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

+8 −0
Original line number Diff line number Diff line
@@ -277,6 +277,10 @@ interface IKeyMintDevice { 
     *   must return ErrorCode::INVALID_ARGUMENT.  The values 3 and 65537 must be supported.  It is

     *   recommended to support all prime values up to 2^64.

     *

     * o Tag::CERTIFICATE_NOT_BEFORE and Tag::CERTIFICATE_NOT_AFTER specify the valid date range for

     *   the returned X.509 certificate holding the public key. If omitted, generateKey must return

     *   ErrorCode::MISSING_NOT_BEFORE or ErrorCode::MISSING_NOT_AFTER.

     *

     * The following parameters are not necessary to generate a usable RSA key, but generateKey must

     * not return an error if they are omitted:

     *
@@ -297,6 +301,10 @@ interface IKeyMintDevice { 
     * Tag::EC_CURVE must be provided to generate an ECDSA key.  If it is not provided, generateKey

     * must return ErrorCode::UNSUPPORTED_KEY_SIZE. TEE IKeyMintDevice implementations must support

     * all curves.  StrongBox implementations must support P_256.



     * Tag::CERTIFICATE_NOT_BEFORE and Tag::CERTIFICATE_NOT_AFTER must be provided to specify the

     * valid date range for the returned X.509 certificate holding the public key. If omitted,

     * generateKey must return ErrorCode::MISSING_NOT_BEFORE or ErrorCode::MISSING_NOT_AFTER.

     *

     * == AES Keys ==

     *

security/keymint/aidl/android/hardware/security/keymint/Tag.aidl

+14 −12
Original line number Diff line number Diff line
@@ -484,11 +484,11 @@ enum Tag { 
    /**

     * Tag::TRUSTED_CONFIRMATION_REQUIRED is only applicable to keys with KeyPurpose SIGN, and

     * specifies that this key must not be usable unless the user provides confirmation of the data

     *  to be signed.  Confirmation is proven to keyMint via an approval token.  See

     *  CONFIRMATION_TOKEN, as well as the ConfirmationUI HAL.

     * to be signed.  Confirmation is proven to keyMint via an approval token.  See the authToken

     * parameter of begin(), as well as the ConfirmationUI HAL.

     *

     * If an attempt to use a key with this tag does not have a cryptographically valid

     * CONFIRMATION_TOKEN provided to finish() or if the data provided to update()/finish() does not

     * token provided to finish() or if the data provided to update()/finish() does not

     * match the data described in the token, keyMint must return NO_USER_CONFIRMATION.

     *

     * Must be hardware-enforced.
@@ -497,9 +497,11 @@ enum Tag { 


    /**

     * Tag::UNLOCKED_DEVICE_REQUIRED specifies that the key may only be used when the device is

     * unlocked.

     * unlocked, as reported to KeyMint via authToken operation parameter and the

     * IKeyMintDevice::deviceLocked() method

     *

     * Must be software-enforced.

     * Must be hardware-enforced (but is also keystore-enforced on a per-user basis: see the

     * deviceLocked() documentation).

     */

    UNLOCKED_DEVICE_REQUIRED = (7 << 28) /* TagType:BOOL */ | 509,
@@ -870,8 +872,9 @@ enum Tag { 
     *

     * STORAGE_KEY is used to denote that a key generated or imported is a key used for storage

     * encryption. Keys of this type can either be generated or imported or secure imported using

     * keyMint. exportKey() can be used to re-wrap storage key with a per-boot ephemeral key

     * wrapped key once the key characteristics are enforced.

     * keyMint. The convertStorageKeyToEphemeral() method of IKeyMintDevice can be used to re-wrap

     * storage key with a per-boot ephemeral key wrapped key once the key characteristics are

     * enforced.

     *

     * Keys with this tag cannot be used for any operation within keyMint.

     * ErrorCode::INVALID_OPERATION is returned when a key with Tag::STORAGE_KEY is provided to
@@ -919,11 +922,10 @@ enum Tag { 
    RESET_SINCE_ID_ROTATION = (7 << 28) /* TagType:BOOL */ | 1004,



    /**

     * Tag::CONFIRMATION_TOKEN is used to deliver a cryptographic token proving that the user

     * confirmed a signing request.  The content is a full-length HMAC-SHA256 value.  See the

     * ConfirmationUI HAL for details of token computation.

     * OBSOLETE: Do not use. See the authToken parameter for IKeyMintDevice::begin and for

     * IKeyMintOperation methods instead.

     *

     * Must never appear in KeyCharacteristics.

     * TODO(b/191738660): Delete when keystore1 is deleted.

     */

    CONFIRMATION_TOKEN = (9 << 28) /* TagType:BYTES */ | 1005,