Authorization tags

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: