en/security/keystore/tags.html - platform/docs/source.android.com - Git at Google

 <html devsite>
   <head>
     <title>Keymaster Authorization Tags</title>
     <meta name="project_path" value="/_project.yaml" />
     <meta name="book_path" value="/_book.yaml" />
   </head>
   <body>
   <!--
       Copyright 2017 The Android Open Source Project

       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at

           http://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing, software
       distributed under the License is distributed on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.
   -->


 <p>This page provides details to assist implementers of Keymaster HALs.
 It covers each tag in the HAL, which Keymaster version that tag is available
 in, and whether the tag is repeatable. Except as noted in the tag descriptions,
 all of the tags below are used during key generation to specify key
 characteristics.</p>
 <p>For Keymaster 4, tags are defined in
 <code>platform/hardware/interfaces/keymaster/<var>keymaster-version</var>/types.hal</code>,
 such as
 <a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/keymaster/3.0/types.hal" class="external">
 3.0/types.hal</a> for Keymaster 3 and
 <a href="https://android.googlesource.com/platform/hardware/interfaces/+/master/keymaster/4.0/types.hal" class="external">
 4.0/types.hal</a> for Keymaster 4. For Keymaster 2 and below, tags are defined in
 <code><a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware" class="external">
 platform/hardware/libhardware/include/hardware/keymaster_defs.h</a></code>.</p>

 <p>For functions, see the
 <a href="/security/keystore/implementer-ref">Keymaster Functions</a> page.</p>

 <p class="note">To support Keymaster 3's transition from the old-style
 C-structure HAL to the C++ HAL interface generated from a definition in the new
 Hardware Interface Definition Language (HIDL), tag names have changed in
 Android 8.0. Tags, like all other keymaster enums, are now defined as C++
 scoped enums. For example, tags, formerly prefixed with <code>KM_TAG_</code>,
 are now prefixed with <code>Tag::</code>.</p>

 <h2 id="active_datetime">Tag::ACTIVE_DATETIME</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the date and time at which the key becomes active. Prior to this
 time, any attempt to use the key fails with
 <code>ErrorCode::KEY_NOT_YET_VALID</code>.</p>

 <p>The value is a 64-bit integer representing milliseconds since January 1,
 1970.</p>


 <h2 id="algorithm">Tag::ALGORITHM</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the cryptographic algorithm with which the key is used.</p>

 <p>Possible values are defined by the following enumeration:</p>

 <strong>Keymaster 3</strong>
 <pre class="devsite-click-to-copy">
 enum class Algorithm : uint32_t {
     RSA = 1,
     EC = 3,
     AES = 32,
     HMAC = 128,
 };
 </pre>

 <strong>Keymaster 2 and earlier</strong>
 <pre class="devsite-click-to-copy">
 typedef enum {
     KM_ALGORITHM_RSA = 1,
     KM_ALGORITHM_EC = 3,
     KM_ALGORITHM_AES = 32,
     KM_ALGORITHM_HMAC = 128,
 } keymaster_algorithm_t;
 </pre>


 <h2 id="all_applications">Tag::ALL_APPLICATIONS</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Reserved for future use.</p>


 <h2 id="allow_while_on_body">Tag::ALLOW_WHILE_ON_BODY</h2>

 <p><strong>Version</strong>: 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>This tag is applicable only for Android Wear devices with on-body sensors. At
 this point, it's not expected that any TEE will be able to provide secure access
 to an on-body sensor, or that on-body sensors are very secure, so this is
 expected to be a purely software-enforced feature.</p>

 <h2 id="all_users">Tag::ALL_USERS</h2>

 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Reserved for future use.</p>

 <h2 id="application_data">Tag::APPLICATION_DATA</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>When provided to
 <a href="/security/keystore/implementer-ref#generate_key">generateKey</a>
 or <a href="/security/keystore/implementer-ref#import_key">importKey</a>,
 this tag specifies data that is necessary during all uses of the key. In
 particular, calls to
 <a href="/security/keystore/implementer-ref#export_key">exportKey</a> and
 <a href="/security/keystore/implementer-ref#get_key_characteristics">getKeyCharacteristics</a>
 need to provide the same value to the <code>clientId</code> parameter, and calls
 to <a href="/security/keystore/implementer-ref#begin">begin</a> need to provide
 this tag and the same associated data as part of the <code>inParams</code>
 set. If the correct data is not provided, the function returns
 <code>ErrorCode::INVALID_KEY_BLOB</code>.</p>

 <p>The content of this tag is bound to the key <em>cryptographically</em>,
 meaning it must not be possible for an adversary who has access to all of the
 secure world secrets but does not have 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.</p>

 <p>The value is a blob, an arbitrary-length array of bytes.</p>


 <h2 id="application_id">Tag::APPLICATION_ID</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>When provided to
 <a href="/security/keystore/implementer-ref#generate_key">generateKey</a>
 or <a href="/security/keystore/implementer-ref#import_key">importKey</a>,
 this tag specifies data that is necessary during all uses of the key. In
 particular, calls to
 <a href="/security/keystore/implementer-ref#export_key">exportKey</a> and
 <a href="/security/keystore/implementer-ref#get_key_characteristics">getKeyCharacteristics</a>
 need to provide the same value in the <code>clientId</code> parameter, and
 calls to <a href="/security/keystore/implementer-ref#begin">begin</a> need to
 provide this tag and the same associated data as part of the
 <code>inParams</code> set. If the correct data is not provided, the function
 returns <code>ErrorCode::INVALID_KEY_BLOB</code>.</p>

 <p>The content of this tag is bound to the key <em>cryptographically</em>,
 meaning it an adversary who can access all of the secure world secrets—but
 does not have access to the tag content—can't decrypt the
 key (without brute-forcing the tag content).</p>

 <p>The value is a blob, an arbitrary-length array of bytes.</p>


 <h2 id="associated_data">Tag::ASSOCIATED_DATA</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Provides "associated data" for AES-GCM encryption or decryption. This tag is
 provided to <a href="/security/keystore/implementer-ref#update">update</a> and
 specifies data that is not encrypted/decrypted, but is used in computing
 the GCM tag.</p>

 <p>The value is a blob, an arbitrary-length array of bytes.</p>

 <h2 id="attestation_application_id">Tag::ATTESTATION_APPLICATION_ID</h2>
 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

  <p>Used to identify the set of possible applications of which one
  has initiated a key attestation.</p>

 <p>The value is a blob, an arbitrary-length array of bytes.</p>

 <h2 id="attestation_challenge">Tag::ATTESTATION_CHALLENGE</h2>
 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Used to provide challenge in attestation.</p>
 <p>The value is a blob, an arbitrary-length array of bytes.</p>

 <h2 id="attestation_id_brand">Tag::ATTESTATION_ID_BRAND</h2>
 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Provides the device's brand name, as returned by <code>Build.BRAND</code>
 in Android. This field is set only when requesting attestation of the
 device's identifiers.</p>
 <p>If the device does not support ID attestation (or
 <code>destroyAttestationIds()</code> was previously called and the device can
 no longer attest its IDs), any key attestation request that includes
 this tag fails with <code>ErrorCode::CANNOT_ATTEST_IDS</code>.</p>
 <p>The value is a blob, an arbitrary-length array of bytes.</p>

 <h2 id="attestation_id_device">Tag::ATTESTATION_ID_DEVICE</h2>
 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Provides the device's device name, as returned by <code>Build.DEVICE</code>
 in Android. This field is set only when requesting attestation of the
 device's identifiers.</p>
 <p>If the device does not support ID attestation (or
 <code>destroyAttestationIds()</code> was previously called and the device can
 no longer attest its IDs), any key attestation request that includes
 this tag fails with <code>ErrorCode::CANNOT_ATTEST_IDS</code>.</p>
 <p>The value is a blob, an arbitrary-length array of bytes.</p>

 <h2 id="attestation_id_imei">Tag::ATTESTATION_ID_IMEI</h2>
 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? Yes</p>

 <p>Provides the IMEIs for all radios on the device. This field is set only
 when requesting attestation of the device's identifiers.</p>
 <p>If the device does not support ID attestation (or
 <code>destroyAttestationIds()</code> was previously called and the device can
 no longer attest its IDs), any key attestation request that includes
 this tag fails with <code>ErrorCode::CANNOT_ATTEST_IDS</code>.</p>
 <p>The value is a blob, an arbitrary-length array of bytes.</p>

 <h2 id="attestation_id_manufacturer">Tag::ATTESTATION_ID_MANUFACTURER</h2>
 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Provides the device's manufacturer name, as returned by
 <code>Build.MANUFACTURER</code> in Android. This field is set only when
 requesting attestation of the device's identifiers.</p>
 <p>If the device does not support ID attestation (or
 <code>destroyAttestationIds()</code> was previously called and the device can
 no longer attest its IDs), any key attestation request that includes
 this tag fails with <code>ErrorCode::CANNOT_ATTEST_IDS</code>.</p>
 <p>The value is a blob, an arbitrary-length array of bytes.</p>

 <h2 id="attestation_id_meid">Tag::ATTESTATION_ID_MEID</h2>
 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? Yes</p>

 <p>Provides the MEIDs for all radios on the device. This field will only be set
 when requesting attestation of the device's identifiers.</p>
 <p>If the device does not support ID attestation (or
 <code>destroyAttestationIds()</code> was previously called and the device can
 no longer attest its IDs), any key attestation request that includes
 this tag fails with <code>ErrorCode::CANNOT_ATTEST_IDS</code>.</p>
 <p>The value is a blob, an arbitrary-length array of bytes.</p>

 <h2 id="attestation_id_model">Tag::ATTESTATION_ID_MODEL</h2>
 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Provides the device's model name, as returned by
 <code>Build.MODEL</code> in Android. This field is set only when
 requesting attestation of the device's identifiers.</p>
 <p>If the device does not support ID attestation (or
 <code>destroyAttestationIds()</code> was previously called and the device can
 no longer attest its IDs), any key attestation request that includes
 this tag fails with <code>ErrorCode::CANNOT_ATTEST_IDS</code>.</p>

 <p>The value is a blob, an arbitrary-length array of bytes.</p>


 <h2 id="attestation_id_product">Tag::ATTESTATION_ID_PRODUCT</h2>
 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Provides the device's product name, as returned by
 <code>Build.PRODUCT</code> in Android. This field is set only when
 requesting attestation of the device's identifiers.</p>
 <p>If the device does not support ID attestation (or
 <code>destroyAttestationIds()</code> was previously called and the device can
 no longer attest its IDs), any key attestation request that includes
 this tag fails with <code>ErrorCode::CANNOT_ATTEST_IDS</code>.</p>
 <p>The value is a blob, an arbitrary-length array of bytes.</p>

 <h2 id="attestation_id_serial">Tag::ATTESTATION_ID_SERIAL</h2>
 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Provides the device's serial number. This field is set only when
 requesting attestation of the device's identifiers.</p>
 <p>If the device does not support ID attestation (or
 <code>destroyAttestationIds()</code> was previously called and the device can
 no longer attest its IDs), any key attestation request that includes
 this tag fails with <code>ErrorCode::CANNOT_ATTEST_IDS</code>.</p>
 <p>The value is a blob, an arbitrary-length array of bytes.</p>

 <h2 id="auth_timeout">Tag::AUTH_TIMEOUT</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the time in seconds for which the key is authorized for use, after
 authentication. If <a href="#user_secure_id">Tag::USER_SECURE_ID</a>
 is present and this tag is not, then the key needs authentication for every
 usage (see <a href="/security/keystore/implementer-ref#begin">begin</a> for the
 details of the authentication-per-operation flow).</p>

 <p>The value is a 32-bit integer specifying the time in seconds after a successful
 authentication of the user specified by
 <a href="#user_secure_id">Tag::USER_SECURE_ID</a> with
 the authentication method specified
 by <a href="#mac_length">Tag::USER_AUTH_TYPE</a> that the key can be used.</p>


 <h2 id="auth_token">Tag::AUTH_TOKEN</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Provides an
 <a href="/security/keystore/authentication/#authentication_token_format">authentication
 token</a> to <a href="/security/keystore/implementer-ref#begin">begin</a>,
 <a href="/security/keystore/implementer-ref#update">update</a> or
 <a href="/security/keystore/implementer-ref#finish">finish</a>,
 to prove user authentication for a key operation that requires
 it (key has <a href="#user_secure_id">Tag::USER_SECURE_ID</a>).</p>

 <p>The value is a blob which contains a <code>hw_auth_token_t</code> structure.</p>


 <h2 id="blob_usage_requirements">Tag::BLOB_USAGE_REQUIREMENTS</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the necessary system environment conditions for the generated
 key to be used.</p>

 <p>Possible values are defined by the following enumeration:</p>

 <strong>Keymaster 3</strong>
 <pre class="devsite-click-to-copy">
 enum class KeyBlobUsageRequirements : uint32_t {
     STANDALONE = 0,
     REQUIRES_FILE_SYSTEM = 1,
 };
 </pre>

 <strong>Keymaster 2 and earlier</strong>
 <pre class="devsite-click-to-copy">
 typedef enum {
     KM_BLOB_STANDALONE = 0,
     KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
 } keymaster_key_blob_usage_requirements_t;
 </pre>

 <p>This tag can be specified during key generation to require that the key is
 usable in the specified condition. It needs to be returned with the key
 characteristics from
 <a href="/security/keystore/implementer-ref#generate_key">generateKey</a> and
 <a href="/security/keystore/implementer-ref#get_key_characteristics">getKeyCharacteristics</a>.
 If the caller specifies <code>Tag::BLOB_USAGE_REQUIREMENTS</code> with
 value <code>KeyBlobUsageRequirements::STANDALONE</code> the trustlet returns a key blob
 that can be used without file system support. This is critical for devices
 with encrypted disks, where the file system may not be available until
 after a Keymaster key is used to decrypt the disk.</p>


 <h2 id="block_mode">Tag::BLOCK_MODE</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? Yes</p>

 <p>Specifies the block cipher mode(s) with which the key may be used.
 This tag is only relevant to AES keys.</p>

 <p>Possible values are defined by the following enumeration:</p>

 <strong>Keymaster 3</strong>
 <pre class="devsite-click-to-copy">
 enum class BlockMode : uint32_t {
     ECB = 1,
     CBC = 2,
     CTR = 3,
     GCM = 32,
 };
 </pre>

 <strong>Keymaster 2 and earlier</strong>
 <pre class="devsite-click-to-copy">
 typedef enum {
     KM_MODE_ECB = 1,
     KM_MODE_CBC = 2,
     KM_MODE_CTR = 3,
     KM_MODE_GCM = 32,
 } keymaster_block_mode_t;
 </pre>

 <p>This tag is repeatable, and for AES key operations specify a mode in
 the <code>additionalParams</code> argument of
 <a href="/security/keystore/implementer-ref#begin">begin</a>.
 If the specifiedmode is not in the modes associated with the key, the
 operation fails with <code>ErrorCode::INCOMPATIBLE_BLOCK_MODE</code>.</p>

 <h2 id="boot_patchlevel">Tag::BOOT_PATCHLEVEL</h2>
 <p><strong>Version</strong>: 4</p>
 <p>Tag::BOOT_PATCHLEVEL specifies the boot image (kernel) security patch level
 with which the key may be used. This tag is never sent to the keymaster TA, but
 is added to the hardware-enforced authorization list by the TA. Any attempt to
 use a key with a <code>Tag::BOOT_PATCHLEVEL</code> value different from the
 currently-running system patchlevel causes <code>begin()</code>,
 <code>getKeyCharacteristics()</code> or <code>exportKey()</code> to return
 <code>ErrorCode::KEY_REQUIRES_UPGRADE</code>. See <code>upgradeKey()</code>
 for details.
 </p>
 <p>
 The value of the tag is an integer of the form YYYYMMDD, where YYYY is the
 four-digit year of the last update, MM is the two-digit month and DD is the
 two-digit day of the last update. For example, for a key generated on an
 Android device last updated on June 5, 2018, the value would be 20180605.
 If the day is not known, 00 may be substituted.
 </p>
 <p>
 During each boot, the bootloader must provide the patch level of the boot image
 to the secure envirionment (mechanism is implementation-defined).
 </p>
 <p>
 Must be hardware-enforced.
 </p>

 <h2 id="bootloader_only">Tag::BOOTLOADER_ONLY</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies only the bootloader can use the key.</p>

 <p>This tag is boolean, so the possible values are true (if the tag is present)
 and false (if the tag is not present).</p>

 <p>Any attempt to use a key with <code>Tag::BOOTLOADER_ONLY</code> from the
 Android system fails with <code>ErrorCode::INVALID_KEY_BLOB</code>.</p>


 <h2 id="caller_nonce">Tag::CALLER_NONCE</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies that the caller can provide a nonce for nonce-requiring operations.</p>

 <p>This tag is boolean, so the possible values are true (if the tag is present)
 and false (if the tag is not present).</p>

 <p>This tag is used only for AES keys, and is only relevant for CBC, CTR and GCM
 block modes. If the tag is not present, implementations should reject any
 operation that provides <a href="#nonce">Tag::NONCE</a> to
 <a href="/security/keystore/implementer-ref#begin">begin</a>
 with <code>ErrorCode::CALLER_NONCE_PROHIBITED</code>.</p>


 <h2 id="creation_datetime">Tag::CREATION_DATETIME</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the date and time the key was created, in milliseconds since January
 1, 1970. This tag is optional and informational only.</p>


 <h2 id="digest">Tag::DIGEST</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? Yes</p>

 <p>Specifies the digest algorithms that may be used with the key to perform
 signing and verification operations. This tag is relevant to RSA, ECDSA and
 HMAC keys.</p>

 <p>Possible values are defined by the following enumeration:</p>

 <strong>Keymaster 3</strong>
 <pre class="devsite-click-to-copy">
 enum class Digest : uint32_t {
     NONE = 0,
     MD5 = 1,
     SHA1 = 2,
     SHA_2_224 = 3,
     SHA_2_256 = 4,
     SHA_2_384 = 5,
     SHA_2_512 = 6,
 };
 </pre>

 <strong>Keymaster 2 and earlier</strong>
 <pre class="devsite-click-to-copy">
 typedef enum {
     KM_DIGEST_NONE = 0,
     KM_DIGEST_MD5 = 1,
     KM_DIGEST_SHA1 = 2,
     KM_DIGEST_SHA_2_224 = 3,
     KM_DIGEST_SHA_2_256 = 4,
     KM_DIGEST_SHA_2_384 = 5,
     KM_DIGEST_SHA_2_512 = 6,
 }
 keymaster_digest_t;
 </pre>

 <p>This tag is repeatable. For signing and verification operations, specify
 a digest in the <code>additionalParams</code> argument of
 <a href="/security/keystore/implementer-ref#begin">begin</a>.
 If the specified digest is not in the digests associated with the key, the
 operation fails with <code>ErrorCode::INCOMPATIBLE_DIGEST</code>.</p>

 <h2 id="ec_curve">Tag::EC_CURVE</h2>

 <p><strong>Version</strong>: 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>In Keymaster 1, the curve used for EC keys was guessed from the specified key
 size. To improve flexibility moving forward, Keymaster 2 introduced an explicit
 way to specify curves. EC key generation requests may have
 <code>Tag::EC_CURVE</code>, <code>Tag::KEY_SIZE</code>, or both.</p>

 <p>Possible values are defined by the following enumeration:</p>

 <strong>Keymaster 3</strong>
 <pre class="devsite-click-to-copy">
 enum class EcCurve : uint32_t {
     P_224 = 0,
     P_256 = 1,
     P_384 = 2,
     P_521 = 3,
 };
 </pre>

 <strong>Keymaster 2 and earlier</strong>
 <pre class="devsite-click-to-copy">
 enum class EcCurve : uint32_t {
     P_224 = 0,
     P_256 = 1,
     P_384 = 2,
 P_521 = 3,
 };
 </pre>

 <p>If a generation request only contains <code>Tag::KEY_SIZE</code>,
 fall back to the Keymaster 1 logic, choosing the appropriate NIST curve.</p>

 <p>If the request only contains <code>Tag::EC_CURVE</code>, use the
 specified curve. For Keymaster 3 and later, curves are defined in
 <code>EcCurve</code>. For Keymaster 2 and earlier, curves are defined
 in <code>keymaster_ec_curve_t</code>.</p>

 <p>If the request contains both, use the curve specified by
 <code>Tag::EC_CURVE</code>, and validate that the specified key size is
 appropriate for that curve. If not, return
 <code>ErrorCode::INVALID_ARGUMENT</code>.</p>


 <h2 id="include_unique_id">Tag::INCLUDE_UNIQUE_ID</h2>

 <p><strong>Version</strong>: 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>This tag is specified during key generation to indicate that an attestation
 certificate for the generated key should contain an application-scoped and
 time-bounded device-unique ID, as specified by
 <a href="#unique_id">Tag::UNIQUE_ID</a>.</p>

 <p>This tag is boolean, so the possible values are true (if the tag is present)
 and false (if the tag is not present).</p>

 <h2 id="key_size">Tag::KEY_SIZE</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the size, in bits, of the key, measuring in the normal way for the
 key's algorithm. For example, for RSA keys, <code>Tag::KEY_SIZE</code> specifies
 the size of the public modulus. For AES keys it specifies the length
 of the secret key material.</p>
 <p class="note">In Keymaster 2 and later, <code>Tag::KEY_SIZE</code> is no longer the
 preferred mechanism for selecting ECC (elliptic curve cryptography) curves.
 While it is unchanged for other key types, ECC curves are selected using the
 tag <a href="#ec_curve"><code>Tag::EC_CURVE</code></a>.</p>


 <h2 id="mac_length">Tag::MAC_LENGTH</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Provides the requested length of a MAC or GCM authentication tag, in bits.</p>

 <p>The value is the MAC length in bits. It is a multiple of 8 and at
 least as large as the value of <a href="#min_mac_length">Tag::MIN_MAC_LENGTH</a>
 associated with the key.</p>


 <h2 id="max_uses_per_boot">Tag::MAX_USES_PER_BOOT</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the maximum number of times that a key may be used between system
 reboots. This is another mechanism to rate-limit key use.</p>

 <p>The value is a 32-bit integer representing uses per boot.</p>

 <p>When a key with this tag is used in an operation, a key-associated counter
 should be incremented during the
 <a href="/security/keystore/implementer-ref#begin">begin</a> call. After the key
 counter has exceeded this value, all subsequent attempts to use the key fail
 with <code>ErrorCode::MAX_OPS_EXCEEDED</code>, until the device is restarted. This
 implies that a trustlet keeps a table of use counters for keys with this tag.
 Because Keymaster memory is often limited, this table can have a fixed maximum
 size and Keymaster can fail operations that attempt to use keys with this tag
 when the table is full. The table needs to acommodate at least 16 keys. If an
 operation fails because the table is full, Keymaster returns
 <code>ErrorCode::TOO_MANY_OPERATIONS</code>.</p>


 <h2 id="min_mac_length">Tag::MIN_MAC_LENGTH</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>This tag specifies the minimum length of MAC that can be requested or
  verified with this key for HMAC keys and AES keys that support GCM mode.</p>

 <p>This value is the minimum MAC length, in bits. It is a multiple of 8. For
 HMAC keys, the value is at least 64. For GCM keys, the value is at least 96
 and no more than 128.</p>


 <h2 id="min_seconds_between_ops">Tag::MIN_SECONDS_BETWEEN_OPS</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the minimum amount of time that elapses between allowed
 operations using a key. This can be used to rate-limit uses of keys in contexts
 where unlimited use may enable brute force attacks.</p>

 <p>The value is a 32-bit integer representing seconds between allowed operations.</p>

 <p>When a key with this tag is used in an operation, start a timer
 during the <a href="/security/keystore/implementer-ref#finish">finish</a> or
 <a href="/security/keystore/implementer-ref#abort">abort</a> call. Any
 call to <a href="/security/keystore/implementer-ref#begin">begin</a> that is received
 before the timer indicates that the interval specified by
 <code>Tag::MIN_SECONDS_BETWEEN_OPS</code> has elapsed fails with
 <code>ErrorCode::KEY_RATE_LIMIT_EXCEEDED</code>.This
 implies that a trustlet keeps a table of use counters for keys with this tag.
 Because Keymaster memory is often limited, this table can have a fixed maximum size
 and Keymaster can fail operations that attempt to use keys with this tag
 when the table is full. The table needs to acommodate at least 32 in-use
 keys and aggressively reuse table slots when key minimum-usage intervals expire.
 If an operation fails because the table is full, Keymaster returns
 <code>ErrorCode::TOO_MANY_OPERATIONS</code>.</p>


 <h2 id="no_auth_required">Tag::NO_AUTH_REQUIRED</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies that no authentication is required to use this key. This tag is
 mutually exclusive with <a href="#user_secure_id">Tag::USER_SECURE_ID</a>.</p>

 <p>This tag is boolean, so the possible values are true (if the tag is present)
 and false (if the tag is not present).</p>


 <h2 id="nonce">Tag::NONCE</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Provides or returns a nonce or Initialization Vector (IV) for AES GCM, CBC, or
 CTR encryption or decryption. This tag is provided to
 <a href="/security/keystore/implementer-ref#begin">begin</a>
 during encryption and decryption operations. It is only provided to
 <a href="/security/keystore/implementer-ref#begin">begin</a>
 if the key has <a href="#caller_nonce">Tag::CALLER_NONCE</a>. If not provided,
 an appropriate nonce or IV will be randomly generated by
 Keymaster and returned from begin.</p>

 <p>The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend
 on the mode: GCM nonces are 12 bytes in length; CBC and CTR IVs are 16 bytes in
 length.</p>


 <h2 id="origin">Tag::ORIGIN</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies where the key was created, if known. This tag may not be specified
 during key generation or import, and must be added to the key characteristics
 by the trustlet.</p>

 <strong>Keymaster 3</strong>
 <p>The possible values are defined in
 <code>android::hardware::keymaster::v3_0::KeyOrigin</code>:</p>
 <pre class="devsite-click-to-copy">
 enum class KeyOrigin : uint32_t {
     GENERATED = 0,
     DERIVED = 1,
     IMPORTED = 2,
     UNKNOWN = 3,
 };
 </pre>

 <strong>Keymaster 2 and earlier</strong>
 <p>The possible values are defined in <code>keymaster_origin_t</code>:</p>
 <pre class="devsite-click-to-copy">
 typedef enum {
     KM_ORIGIN_GENERATED = 0,
     KM_ORIGIN_IMPORTED = 2,
     KM_ORIGIN_UNKNOWN = 3,
 } keymaster_key_origin_t
 </pre>

 <p>The full meaning of the value depends not only on the value but on whether it's
 found in the hardware-enforced or software-enforced characteristics list.</p>

 <p><code>GENERATED</code> indicates that Keymaster generated the key.
 If in the hardware-enforced list,
 the key was generated in secure hardware and is permanently hardware bound. If
 in the software-enforced list, the key was generated in SoftKeymaster and is
 not hardware bound.</p>

 <p><code>DERIVED</code> indicates that the key was derived inside Keymaster.
 Likely exists off-device.</p>

 <p><code>IMPORTED</code> indicates that the key was generated outside
 of Keymaster and imported into
 Keymaster. If in the hardware-enforced list, it is permanently hardware bound,
 although copies outside of secure hardware may exist. If in the
 software-enforces list, the key was imported into SoftKeymaster and is not
 hardware bound.</p>

 <p><code>UNKNOWN</code> should only appear in the hardware-enforced list.
 It indicates that the key is
 hardware bound, but it is not known whether the key was originally generated in
 secure hardware or was imported. This only occurs when keymaster0 hardware is
 being used to emulate keymaster1 services.</p>


 <h2 id="origination_expire_datetime">Tag::ORIGINATION_EXPIRE_DATETIME</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the date and time at which the key expires for signing and encryption
 purposes. After this time, any attempt to use a key
 with <a href="#purpose">KeyPurpose::SIGN</a> or
 <a href="#purpose">KeyPurpose::ENCRYPT</a> provided
 to <a href="/security/keystore/implementer-ref#begin">begin</a> fails
 with <code>ErrorCode::KEY_EXPIRED</code>.</p>

 <p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>


 <h2 id="os_patchlevel">Tag::OS_PATCHLEVEL</h2>

 <p><strong>Version</strong>: 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>This tag is never sent to the keymaster TA, but is added to the
 hardware-enforced authorization list by the TA.</p>

 <p>The value of the tag is an integer of the form YYYYMM, where YYYY is the
 four-digit year of the last update and MM is the two-digit month of the last
 update. For example, for a key generated on an Android device last updated in
 December 2015, the value would be 201512.</p>

 <p>Keys that have a patch level different than the current patch level are not
 usable. An attempt to use such a key causes
 <a href="/security/keystore/implementer-ref#begin">begin</a>,
 <a href="/security/keystore/implementer-ref#get_key_characteristics">getKeyCharacteristics</a>,
 or <a href="/security/keystore/implementer-ref#export_key">exportKey</a>
 to return <code>ErrorCode::KEY_REQUIRES_UPGRADE</code>. See
 <a href="/security/keystore/version-binding">Version Binding</a> for more details.</p>


 <h2 id="os_version">Tag::OS_VERSION</h2>

 <p><strong>Version</strong>: 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>This tag is never sent to the keymaster TA, but is added to the
 hardware-enforced authorization list by the TA.</p>

 <p>The value of the tag is an integer of the form MMmmss, where MM is the major
 version number, mm is the minor version number, and ss is the sub-minor version
 number. For example, for a key generated on Android version 4.0.3, the value
 would be 040003.</p>


 <h2 id="padding">Tag::PADDING</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? Yes</p>

 <p>Specifies the padding modes that may be used with the key. This tag is
 relevant to RSA and AES keys.</p>

 <p>Possible values are defined by the following enumeration:</p>

 <strong>Keymaster 3</strong>
 <pre class="devsite-click-to-copy">
 enum class PaddingMode : uint32_t {
     NONE = 1,
     RSA_OAEP = 2,
     RSA_PSS = 3,
     RSA_PKCS1_1_5_ENCRYPT = 4,
     RSA_PKCS1_1_5_SIGN = 5,
     PKCS7 = 64,
 };
 </pre>

 <strong>Keymaster 2 and earlier</strong>
 <pre class="devsite-click-to-copy">
 typedef enum {
     KM_PAD_NONE = 1,
     KM_PAD_RSA_OAEP = 2,
     KM_PAD_RSA_PSS = 3,
     KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
     KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
     KM_PAD_PKCS7 = 64,
 } keymaster_padding_t;
 </pre>

 <p><code>PaddingMode::RSA_OAEP</code> and
 <code>PaddingMode::RSA_PKCS1_1_5_ENCRYPT</code> are used
 only for RSA encryption/decryption keys and specify RSA PKCS#1v2 OAEP
 padding and RSA PKCS#1 v1.5 randomized padding, respectively.
 <code>PaddingMode::RSA_PSS</code> and
 <code>PaddingMode::RSA_PKCS1_1_5_SIGN</code> are used only for RSA
 signing/verification keys and specify RSA PKCS#1v2 PSS
 padding and RSA PKCS#1 v1.5 deterministic padding, respectively.</p>

 <p class="note"><strong>Note</strong>: The RSA PSS padding mode is
 incompatible with <a href="#digest">Digest::NONE</a>.</p>

 <p><code>PaddingMode::NONE</code> may be used with either RSA or
 AES keys. For AES keys, if <code>PaddingMode::NONE</code> is used
 with block mode ECB or CBC and the data to be encrypted or decrypted
 is not a multiple of the AES block size in length, the call to finish
 fails with <code>ErrorCode::INVALID_INPUT_LENGTH</code>.</p>

 <p><code>PaddingMode::PKCS7</code> may only be used with AES keys, and
 only with ECB and CBC modes.</p>

 <p>This tag is repeatable. A padding mode must be specified in the call to
 <a href="/security/keystore/implementer-ref#begin">begin</a>.
 If the specified mode is not authorized for the key, the operation fails
 with <code>ErrorCode::INCOMPATIBLE_BLOCK_MODE</code>.</p>


 <h2 id="purpose">Tag::PURPOSE</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? Yes</p>

 <p>Specifies the set of purposes for which the key may be used.</p>

 <p>Possible values are defined by the following enumeration:</p>

 <strong>Keymaster 3</strong>
 <pre class="devsite-click-to-copy">
 enum class KeyPurpose : uint32_t {
     ENCRYPT = 0,
     DECRYPT = 1,
     SIGN = 2,
     VERIFY = 3,
     DERIVE_KEY = 4,  // since 3.0
     WRAP_KEY = 5,    // since 3.0
 };
 </pre>

 <strong>Keymaster 2 and earlier</strong>
 <pre class="devsite-click-to-copy">
 typedef enum {
     KM_PURPOSE_ENCRYPT = 0,
     KM_PURPOSE_DECRYPT = 1,
     KM_PURPOSE_SIGN = 2,
     KM_PURPOSE_VERIFY = 3,
 } keymaster_purpose_t;
 </pre>

 <p>This tag is repeatable; keys may be generated with multiple values, although an
 operation has a single purpose. When the
 <a href="/security/keystore/implementer-ref#begin">begin</a> function is called to
 start an operation, the purpose of the operation is
 specified. If the purpose specified to the operation is not authorized by the
 key, the operation fails with <code>ErrorCode::INCOMPATIBLE_PURPOSE</code>.</p>


 <h2 id="reset_since_id_rotation">Tag::RESET_SINCE_ID_ROTATION</h2>

 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>
 <p>Specifies whether the device has beeen factory reset
 since the last unique ID rotation. Used for key attestation.</p>

 <p>This tag is boolean, so the possible values are true (if the tag is present)
 and false (if the tag is not present).</p>


 <h2 id="rollback_resistant">Tag::ROLLBACK_RESISTANT</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Indicates that the key is rollback-resistant, meaning that when deleted
 by <a href="/security/keystore/implementer-ref#delete_key">deleteKey</a> or
 <a href="/security/keystore/implementer-ref#delete_all_keys">deleteAllKeys</a>,
 the key is guaranteed to be permanently deleted and unusable. It's possible
 that keys without this tag could be deleted and then restored from backup.</p>

 <p>This tag is boolean, so the possible values are true (if the tag is present)
 and false (if the tag is not present).</p>


 <h2 id="root_of_trust">Tag::ROOT_OF_TRUST</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>


 <p>Specifies the <em>root of trust</em>, the key used by verified boot to
 validate the operating system booted (if any). This tag is never provided
 to or returned from Keymaster in the key characteristics.</p>

 <h2 id="rsa_public_exponent">Tag::RSA_PUBLIC_EXPONENT</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the value of the public exponent for an RSA key pair. This tag is
 relevant only to RSA keys, and necessary for all RSA keys.</p>

 <p>The value is a 64-bit unsigned integer that satisfies the requirements of an
 RSA public exponent. This value has to be a prime number. Trustlets support the
 value 2^16+1 and may support other reasonable values, in particular the value 3.
 If no exponent is specified or if the specified exponent is not supported,
 key generation fails with <code>ErrorCode::INVALID_ARGUMENT</code>.</p>


 <h2 id="unique_id">Tag::UNIQUE_ID</h2>

 <p><strong>Version</strong>: 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Used to provide unique ID in attestation.</p>
 <p>The value is a blob, an arbitrary-length array of bytes.</p>


 <h2 id="usage_expire_datetime">Tag::USAGE_EXPIRE_DATETIME</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the date and time at which the key expires for verification and
 decryption purposes. After this time, any attempt to use a key with
 <a href="#purpose">KeyPurpose::VERIFY</a> or <a href="#purpose">KeyPurpose::DECRYPT</a>
 provided to <a href="/security/keystore/implementer-ref#begin">begin</a> fails
 with <code>ErrorCode::KEY_EXPIRED</code>.</p>

 <p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>


 <h2 id="user_auth_type">Tag::USER_AUTH_TYPE</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies the types of user authenticators that may be used to authorize this
 key. When Keymaster is requested to perform an operation with a key with this
 tag, it receives an authentication token, and the token's
 <code>authenticator_type</code> field needs to match the value in the tag. For example,
 <code>(ntoh(token.authenticator_type) & auth_type_tag_value) != 0</code>,
 where <code>ntoh</code> is a function that converts
 network-ordered integers to host-ordered integers and
 <code>auth_type_tag_value</code> is the value of this tag.</p>

 <p>The value is a 32-bit integer bitmask of values from the enumeration:</p>

 <strong>Keymaster 3</strong>
 <pre class="devsite-click-to-copy">
 enum class HardwareAuthenticatorType : uint32_t {
     NONE = 0u, // 0
     PASSWORD = 1 &lt;&lt; 0,
     FINGERPRINT = 1 &lt;&lt; 1,
     ANY = UINT32_MAX,
 };
 </pre>

 <strong>Keymaster 2 and earlier</strong>
 <pre class="devsite-click-to-copy">
 typedef enum {
     HW_AUTH_NONE = 0,
     HW_AUTH_PASSWORD = 1 &lt;&lt; 0,
     HW_AUTH_FINGERPRINT = 1 &lt;&lt; 1,
     // Additional entries should be powers of 2.
     HW_AUTH_ANY = UINT32_MAX,
 } hw_authenticator_type_t;
 </pre>


 <h2 id="user_secure_id">Tag::USER_SECURE_ID</h2>

 <p><strong>Version</strong>: 1, 2, 3, 4</p>
 <p><strong>Repeatable</strong>? No</p>

 <p>Specifies that a key may only be used under a particular secure user
 authentication state. This tag is mutually exclusive
 with <a href="#no_auth_required">Tag::NO_AUTH_REQUIRED</a>.</p>

 <p>The value is a 64-bit integer specifying the authentication policy state value
 which needs to be present in an authentication token (provided to
 <a href="/security/keystore/implementer-ref#begin">begin</a> with
 the <a href="#auth_token">Tag::AUTH_TOKEN</a>) to authorize use of the key. Any
 call to <a href="/security/keystore/implementer-ref#begin">begin</a>
 with a key with this tag that does not provide an
 authentication token, or provides an
 authentication token without a matching policy state value, fails.</p>

 <p>This tag is repeatable. If any of the provided values matches any policy state
 value in the authentication token, the key is authorized for use. Otherwise the operation
 fails with <code>ErrorCode::KEY_USER_NOT_AUTHENTICATED</code>.</p>

 <h2 id="vendor_patchlevel">Tag::VENDOR_PATCHLEVEL</h2>
 <p><strong>Version</strong>: 4</p>
 <p>This tag specifies the vendor image security patch level with which the key
 may be used. This tag is never sent to the keymaster TA, but is added to the
 hardware-enforced authorization list by the TA. Any attempt to use a key with a
 <code>Tag::VENDOR_PATCHLEVEL</code> value different from the currently-running
 system patchlevel must cause <code>begin()</code>,
 <code>getKeyCharacteristics()</code> or <code>exportKey()</code> to return
 <code>ErrorCode::KEY_REQUIRES_UPGRADE</code>. See <code>upgradeKey()</code>
 for details.
 </p>
 <p>
 The value of the tag is an integer of the form YYYYMMDD, where YYYY is the
 four-digit year of the last update, MM is the two-digit month and DD is the
 two-digit day of the last update. For example, for a key generated on an
 Android device last updated on June 5, 2018, the value would be 20180605.</p>
 <p>
 The IKeymasterDevice HAL must read the current vendor patchlevel from the system
 property <code>ro.vendor.build.security_patch</code> and deliver it to the
 secure environment when the HAL is first loaded (mechanism is
 implementation-defined). The secure environment must not accept another
 patchlevel until after the next boot.
 </p>
 <p>
 Must be hardware-enforced.
 </p>

 </body>
 </html>