Starting March 27, 2025, we recommend using android-latest-release
instead of aosp-main
to build and contribute to AOSP. For more information, see Changes to AOSP.
Authorization tags
Stay organized with collections
Save and categorize content based on your preferences.
The KeyMint (previously Keymaster) API makes extensive use of authorization tags, which are name-value pairs. Each possible tag has:
- An enum name with associated value
- An associated type (for example, integer, bytes, date, enum), which includes an
indication of whether multiple values are allowed
For example, the tag with name
Tag::BLOCK_MODE
has a base enum value of 4
and a TagType::ENUM_REP
type
marker that indicates that the associated value is a repeatable enum (in this
case, BlockMode
).
Tags perform a dual function on the API:
- As parameters for an operation performed on the API, for example, the
Tag::MAC_LENGTH
on an HMAC signing operation
indicates the requested HMAC length.
- As key characteristics, values that are permanently
bound to a particular key (that is, included in the key blob), for example,
the
Tag::EC_CURVE
indicates which elliptic curve a key is for.
Each key characteristic is associated with a security level that indicates
which part of the system polices the attribute:
- A key characteristic with security
level
TRUSTED_ENVIRONMENT
or STRONGBOX
is enforced
in the secure hardware.
- A key characteristic with security level
SOFTWARE
or KEYSTORE
is
enforced only by the keystore2
system service (and so such a
characteristic isn't resilient to OS compromise).
Many tags act as both key characteristics and parameters:
- The key characteristics indicate the set of allowed parameters for a key,
for example:
- The
Tag::PURPOSE
of an ECDSA key might include
both SIGN
and AGREE_KEY
.
- The
Tag::BLOCK_MODE
for an AES key might include ECB, CBC,
and CTR modes.
- A
begin()
request then includes a specific parameter value
for the operation, for example:
begin()
has an explicit purpose parameter that must match one of
the key characteristics' Tag::PURPOSE
values.
begin()
for an AES operation needs to include a single
value for Tag::BLOCK_MODE
in the params
field,
which must match one of the values in the key characteristics.
This dual function is particularly relevant for the collection of tags passed
as keyParams
on a key generation or import operation.
- Some of the tags act as parameters for the key generation operation
itself. For example, the
Tag::CERTIFICATE_SUBJECT
tag
affects only the (asymmetric) key generation process, by controlling a field in the
returned X.509 certificate.
- Other tags are bound to the newly generated key as key
characteristics, and are encapsulated in the returned keyblob so that they're
permanently associated with the key.
Detailed information about tag values can be found in the following
HAL interface specifications:
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-06-26 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-06-26 UTC."],[],[],null,["# Authorization tags\n\nThe KeyMint (previously Keymaster) API makes extensive use of *authorization tags*, which are name-value pairs. Each possible tag has:\n\n- An enum name with associated value\n- An associated type (for example, integer, bytes, date, enum), which includes an indication of whether multiple values are allowed\n\n\u003cbr /\u003e\n\nFor example, the tag with name\n[`Tag::BLOCK_MODE`](https://cs.android.com/android/platform/superproject/+/android-latest-release:hardware/interfaces/security/keymint/aidl/android/hardware/security/keymint/Tag.aidl?q=BLOCK_MODE)\nhas a base enum value of `4` and a `TagType::ENUM_REP` type\nmarker that indicates that the associated value is a repeatable enum (in this\ncase, `BlockMode`).\n\nTags perform a dual function on the API:\n\n- As parameters for an operation performed on the API, for example, the `Tag::MAC_LENGTH` on an HMAC signing operation indicates the requested HMAC length.\n- As *key characteristics* , values that are permanently bound to a particular key (that is, included in the key blob), for example, the `Tag::EC_CURVE` indicates which elliptic curve a key is for. Each key characteristic is associated with a security level that indicates which part of the system polices the attribute:\n - A key characteristic with security level `TRUSTED_ENVIRONMENT` or `STRONGBOX` is enforced in the secure hardware.\n - A key characteristic with security level `SOFTWARE` or `KEYSTORE` is enforced only by the `keystore2` system service (and so such a characteristic isn't resilient to OS compromise).\n\n\u003cbr /\u003e\n\nMany tags act as both key characteristics *and* parameters:\n\n- The key characteristics indicate the set of allowed parameters for a key, for example:\n - The `Tag::PURPOSE` of an ECDSA key might include both `SIGN` and `AGREE_KEY`.\n - The `Tag::BLOCK_MODE` for an AES key might include ECB, CBC, and CTR modes.\n- A `begin()` request then includes a specific parameter value for the operation, for example:\n - `begin()` has an explicit purpose parameter that must match one of the key characteristics' `Tag::PURPOSE` values.\n - `begin()` for an AES operation needs to include a single value for `Tag::BLOCK_MODE` in the `params` field, which must match one of the values in the key characteristics.\n\n\u003cbr /\u003e\n\nThis dual function is particularly relevant for the collection of tags passed\nas `keyParams` on a key generation or import operation.\n\n- Some of the tags act as parameters for the key generation operation itself. For example, the `Tag::CERTIFICATE_SUBJECT` tag affects only the (asymmetric) key generation process, by controlling a field in the returned X.509 certificate.\n- Other tags are bound to the newly generated key as key characteristics, and are encapsulated in the returned keyblob so that they're permanently associated with the key.\n\nDetailed information about tag values can be found in the following\nHAL interface specifications:\n\n- KeyMint --- All tags are defined in [`Tag.aidl`](https://cs.android.com/android/platform/superproject/+/android-latest-release:hardware/interfaces/security/keymint/aidl/android/hardware/security/keymint/Tag.aidl) on the relevant Android release branch.\n- Keymaster --- Tags are defined in `platform/hardware/interfaces/keymaster/`\u003cvar translate=\"no\"\u003ekeymaster-version\u003c/var\u003e`/types.hal` for each respective `keymaster-version`, such as [`3.0/types.hal`](https://cs.android.com/android/platform/superproject/+/android-latest-release:hardware/interfaces/keymaster/3.0/types.hal) for Keymaster 3 and [`4.0/types.hal`](https://cs.android.com/android/platform/superproject/+/android-latest-release:hardware/interfaces/keymaster/4.0/types.hal) for Keymaster 4. For Keymaster 2 and below, tags are defined in [`platform/hardware/libhardware/include/hardware/keymaster_defs.h`](https://cs.android.com/android/platform/superproject/+/android-latest-release:hardware/libhardware/include_all/hardware/keymaster_defs.h)."]]