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

Commit 5b60a1b7 authored by Shawn Willden's avatar Shawn Willden
Browse files

Minor corrections to the Keymaster4 documentation. 

Gramatical and punctuation corrections; addition of missing
userSecureId to AuthorizationList schema and removal of extraneous
rollbackResistant from same; correction of OS_PATCHLEVEL source
property; and addition of missing TAG_UNLOCKED_DEVICE_REQUIRED
documentation.

Bug: 69550260
Test: N/A
Change-Id: I04092b7df3af69201ba1467cddc09f6f44e861a8
parent 5ed6bca9

current.txt

+2 −2
Original line number Diff line number Diff line
@@ -347,8 +347,8 @@ dd83be076b6b3f10ed62ab34d8c8b95f2415961fb785200eb842e7bfb2b0ee92 android.hardwar 
675682dd3007805c985eaaec91612abc88f4c25b3431fb84070b7584a1a741fb android.hardware.health@2.0::IHealth

434c4c32c00b0e54bb05e40c79503208b40f786a318029a2a4f66e34f10f2a76 android.hardware.health@2.0::IHealthInfoCallback

c9e498f1ade5e26f00d290b4763a9671ec6720f915e7d592844b62e8cb1f9b5c android.hardware.health@2.0::types

5c8e06f9945276d1a9e8f7e37cf0ea8894bdb906fa80809cb06c36abb39afc4f android.hardware.keymaster@4.0::IKeymasterDevice

6695eb5744108035506004dd136068b1aaebe809cf9d4a69c2fe33b73058bb85 android.hardware.keymaster@4.0::types

201f9723353fdbd40bf3705537fb7e015e4c399879425e68688fe0f43606ea4d android.hardware.keymaster@4.0::IKeymasterDevice

1b7d2090c0a28b229d37c4b96160796b1f0d703950ac6ccc163fccd280830503 android.hardware.keymaster@4.0::types

6d5c646a83538f0f9d8438c259932509f4353410c6c76e56db0d6ca98b69c3bb android.hardware.media.bufferpool@1.0::IAccessor

b8c7ed58aa8740361e63d0ce9e7c94227572a629f356958840b34809d2393a7c android.hardware.media.bufferpool@1.0::IClientManager

4a2c0dc82780e6c90731725a103feab8ab6ecf85a64e049b9cbd2b2c61620fe1 android.hardware.media.bufferpool@1.0::IConnection

keymaster/4.0/IKeymasterDevice.hal

+10 −11
Original line number Diff line number Diff line
@@ -217,8 +217,8 @@ interface IKeymasterDevice { 
     * must be a TEE Keymaster as well.  The HMAC key used to MAC and verify authentication tokens

     * (HardwareAuthToken, VerificationToken and ConfirmationToken all use this HMAC key) must be

     * shared between TEE and StrongBox so they can each validate tokens produced by the other.

     * This method is the first step in the process for for agreeing on a shared key.  It is called

     * by Android during startup.  The system calls it on each of the HAL instances and collects the

     * This method is the first step in the process for agreeing on a shared key.  It is called by

     * Android during startup.  The system calls it on each of the HAL instances and collects the

     * results in preparation for the second step.

     *

     * @return error ErrorCode::OK on success, ErrorCode::UNIMPLEMENTED if HMAC agreement is not
@@ -324,7 +324,7 @@ interface IKeymasterDevice { 
     *             sharingCheck = HMAC(H, "Keymaster HMAC Verification")

     *

     *         The string is UTF-8 encoded, 27 bytes in length.  If the returned values of all

     *         IKeymasterDevice instances don't match, Keystore will assume that HMAC agreement

     *         IKeymasterDevice instances don't match, clients must assume that HMAC agreement

     *         failed.

     */

    computeSharedHmac(vec<HmacSharingParameters> params)
@@ -718,16 +718,19 @@ interface IKeymasterDevice { 
     * AuthorizationList ::= SEQUENCE {

     *     purpose                    [1] EXPLICIT SET OF INTEGER OPTIONAL,

     *     algorithm                  [2] EXPLICIT INTEGER OPTIONAL,

     *     keySize                    [3] EXPLICIT INTEGER OPTIONAL.

     *     keySize                    [3] EXPLICIT INTEGER OPTIONAL,

     *     blockMode                  [4] EXPLICIT SET OF INTEGER OPTIONAL,

     *     digest                     [5] EXPLICIT SET OF INTEGER OPTIONAL,

     *     padding                    [6] EXPLICIT SET OF INTEGER OPTIONAL,

     *     callerNonce                [7] EXPLICIT NULL OPTIONAL,

     *     minMacLength               [8] EXPLICIT INTEGER OPTIONAL,

     *     ecCurve                    [10] EXPLICIT INTEGER OPTIONAL,

     *     rsaPublicExponent          [200] EXPLICIT INTEGER OPTIONAL,

     *     rollbackResistance         [303] EXPLICIT NULL OPTIONAL,

     *     activeDateTime             [400] EXPLICIT INTEGER OPTIONAL

     *     originationExpireDateTime  [401] EXPLICIT INTEGER OPTIONAL

     *     usageExpireDateTime        [402] EXPLICIT INTEGER OPTIONAL

     *     activeDateTime             [400] EXPLICIT INTEGER OPTIONAL,

     *     originationExpireDateTime  [401] EXPLICIT INTEGER OPTIONAL,

     *     usageExpireDateTime        [402] EXPLICIT INTEGER OPTIONAL,

     *     userSecureId               [502] EXPLICIT INTEGER OPTIONAL,

     *     noAuthRequired             [503] EXPLICIT NULL OPTIONAL,

     *     userAuthType               [504] EXPLICIT INTEGER OPTIONAL,

     *     authTimeout                [505] EXPLICIT INTEGER OPTIONAL,
@@ -735,15 +738,11 @@ interface IKeymasterDevice { 
     *     trustedUserPresenceReq     [507] EXPLICIT NULL OPTIONAL,

     *     trustedConfirmationReq     [508] EXPLICIT NULL OPTIONAL,

     *     unlockedDeviceReq          [509] EXPLICIT NULL OPTIONAL,

     *     allApplications            [600] EXPLICIT NULL OPTIONAL,

     *     applicationId              [601] EXPLICIT OCTET_STRING OPTIONAL,

     *     creationDateTime           [701] EXPLICIT INTEGER OPTIONAL,

     *     origin                     [702] EXPLICIT INTEGER OPTIONAL,

     *     rollbackResistant          [703] EXPLICIT NULL OPTIONAL,

     *     rootOfTrust                [704] EXPLICIT RootOfTrust OPTIONAL,

     *     osVersion                  [705] EXPLICIT INTEGER OPTIONAL,

     *     osPatchLevel               [706] EXPLICIT INTEGER OPTIONAL,

     *     attestationChallenge       [708] EXPLICIT OCTET_STRING OPTIONAL,

     *     attestationApplicationId   [709] EXPLICIT OCTET_STRING OPTIONAL,

     *     attestationIdBrand         [710] EXPLICIT OCTET_STRING OPTIONAL,

     *     attestationIdDevice        [711] EXPLICIT OCTET_STRING OPTIONAL,

keymaster/4.0/types.hal

+29 −20
Original line number Diff line number Diff line
@@ -460,6 +460,8 @@ enum Tag : uint32_t { 
     * called on one key with TRUSTED_USER_PRESENCE_REQUIRED, and another begin() comes in for that

     * key or another with TRUSTED_USER_PRESENCE_REQUIRED, Keymaster must return

     * ErrorCode::CONCURRENT_PROOF_OF_PRESENCE_REQUESTED.

     *

     * Must be hardware-enforced.

     */

    TRUSTED_USER_PRESENCE_REQUIRED = TagType:BOOL | 507,
@@ -470,11 +472,17 @@ enum Tag : uint32_t { 
     *

     * 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

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

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

     *

     * Must be hardware-enforced.

     */

    TRUSTED_CONFIRMATION_REQUIRED = TagType:BOOL | 508,



    /**

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

     * unlocked.

     *

     * Must be software-enforced.

     */

    UNLOCKED_DEVICE_REQUIRED = TagType:BOOL | 509,
@@ -490,7 +498,7 @@ enum Tag : uint32_t { 
     * access to the tag content to decrypt the key without brute-forcing the tag content, which

     * applications can prevent by specifying sufficiently high-entropy content.

     *

     * Must be hardware-enforced.

     * Must never appear in KeyCharacteristics.

     */

    APPLICATION_ID = TagType:BYTES | 601,
@@ -511,7 +519,7 @@ enum Tag : uint32_t { 
     * access to the tag content to decrypt the key without brute-forcing the tag content, which

     * applications can prevent by specifying sufficiently high-entropy content.

     *

     * Must be hardware-enforced.

     * Must never appear in KeyCharacteristics.

     */

    APPLICATION_DATA = TagType:BYTES | 700,
@@ -557,11 +565,12 @@ enum Tag : uint32_t { 
     * key generated on Android version 4.0.3, the value would be 040003.

     *

     * The IKeymasterDevice HAL must read the current OS version from the system property

     * ro.build.id and deliver it to the secure environment when the HAL is first loaded (mechanism

     * is implementation-defined).  The secure environment must not accept another version until

     * after the next boot.  If the content of ro.build.id has additional version information after

     * the sub-minor version number, it must not be included in Tag::OS_VERSION.  If the content is

     * non-numeric, the secure environment must use 0 as the system version.

     * ro.build.version.release and deliver it to the secure environment when the HAL is first

     * loaded (mechanism is implementation-defined).  The secure environment must not accept another

     * version until after the next boot.  If the content of ro.build.version.release has additional

     * version information after the sub-minor version number, it must not be included in

     * Tag::OS_VERSION.  If the content is non-numeric, the secure environment must use 0 as the

     * system version.

     *

     * Must be hardware-enforced.

     */
@@ -659,8 +668,8 @@ enum Tag : uint32_t { 


    /**

     * Tag::ATTESTATION_ID_BRAND provides the device's brand name, as returned by Build.BRAND in

     * Android, to attestKey().  This field is set only when requesting attestation of the device's

     * identifiers.

     * Android, to attestKey().  This field must be set only when requesting attestation of the

     * device's identifiers.

     *

     * If the device does not support ID attestation (or destroyAttestationIds() was previously

     * called and the device can no longer attest its IDs), any key attestation request that
@@ -672,8 +681,8 @@ enum Tag : uint32_t { 


    /**

     * Tag::ATTESTATION_ID_DEVICE provides the device's device name, as returned by Build.DEVICE in

     * Android, to attestKey().  This field is set only when requesting attestation of the device's

     * identifiers.

     * Android, to attestKey().  This field must be set only when requesting attestation of the

     * device's identifiers.

     *

     * If the device does not support ID attestation (or destroyAttestationIds() was previously

     * called and the device can no longer attest its IDs), any key attestation request that
@@ -685,7 +694,7 @@ enum Tag : uint32_t { 


    /**

     * Tag::ATTESTATION_ID_PRODUCT provides the device's product name, as returned by Build.PRODUCT

     * in Android, to attestKey().  This field is set only when requesting attestation of the

     * in Android, to attestKey().  This field must be set only when requesting attestation of the

     * device's identifiers.

     *

     * If the device does not support ID attestation (or destroyAttestationIds() was previously
@@ -697,7 +706,7 @@ enum Tag : uint32_t { 
    ATTESTATION_ID_PRODUCT = TagType:BYTES | 712,



    /**

     * Tag::ATTESTATION_ID_SERIAL the device's serial number.  This field is set only when

     * Tag::ATTESTATION_ID_SERIAL the device's serial number.  This field must be set only when

     * requesting attestation of the device's identifiers.

     *

     * If the device does not support ID attestation (or destroyAttestationIds() was previously
@@ -710,7 +719,7 @@ enum Tag : uint32_t { 


    /**

     * Tag::ATTESTATION_ID_IMEI provides the IMEIs for all radios on the device to attestKey().

     * This field is set only when requesting attestation of the device's identifiers.

     * This field must be set only when requesting attestation of the device's identifiers.

     *

     * If the device does not support ID attestation (or destroyAttestationIds() was previously

     * called and the device can no longer attest its IDs), any key attestation request that
@@ -723,7 +732,7 @@ enum Tag : uint32_t { 


    /**

     * Tag::ATTESTATION_ID_MEID provides the MEIDs for all radios on the device to attestKey().

     * This field will only be set when requesting attestation of the device's identifiers.

     * This field must be set only when requesting attestation of the device's identifiers.

     *

     * If the device does not support ID attestation (or destroyAttestationIds() was previously

     * called and the device can no longer attest its IDs), any key attestation request that
@@ -736,7 +745,7 @@ enum Tag : uint32_t { 


    /**

     * Tag::ATTESTATION_ID_MANUFACTURER provides the device's manufacturer name, as returned by

     * Build.MANUFACTURER in Android, to attstKey().  This field is set only when requesting

     * Build.MANUFACTURER in Android, to attstKey().  This field must be set only when requesting

     * attestation of the device's identifiers.

     *

     * If the device does not support ID attestation (or destroyAttestationIds() was previously
@@ -749,8 +758,8 @@ enum Tag : uint32_t { 


    /**

     * Tag::ATTESTATION_ID_MODEL provides the device's model name, as returned by Build.MODEL in

     * Android, to attestKey().  This field is set only when requesting attestation of the device's

     * identifiers.

     * Android, to attestKey().  This field must be set only when requesting attestation of the

     * device's identifiers.

     *

     * If the device does not support ID attestation (or destroyAttestationIds() was previously

     * called and the device can no longer attest its IDs), any key attestation request that
@@ -815,7 +824,7 @@ enum Tag : uint32_t { 
     * Tag::NONCE is used to provide or return a nonce or Initialization Vector (IV) for AES-GCM,

     * AES-CBC, AES-CTR, or 3DES-CBC encryption or decryption.  This tag is provided to begin during

     * encryption and decryption operations.  It is only provided to begin if the key has

     * Tag::CALLER_NONCE.  If not provided, an appropriate nonce or IV will be randomly generated by

     * Tag::CALLER_NONCE.  If not provided, an appropriate nonce or IV must be randomly generated by

     * Keymaster and returned from begin.

     *

     * The value is a blob, an arbitrary-length array of bytes.  Allowed lengths depend on the mode: