Google Confidential and Proprietary

Keymaster2 Implementer’s Guide

Version 1
Contents

Overview
New Features
Semantic Changes
Key Attestation
Java API
HAL Changes
Attestation Certificate
Certificate SEQUENCE
TBSCertificate SEQUENCE
Attestation Extension
Schema
KeyDescription Fields
AuthorizationList Fields
RootOfTrust Fields
VerifiedBootState Values
SecurityLevel Values
Unique ID
Attestation Keys and Certificates
Version Binding
HAL Changes
Secure Configuration
Miscellaneous HAL changes
Obsolete methods removed
Unused methods removed
Input to finish
Argument changes
Key blob upgrades
Tag Changes
KM_TAG_EC_CURVE (new)
KM_TAG_KEY_SIZE (changed)
KM_TAG_INCLUDE_UNIQUE_ID (new)
KM_TAG_ALLOW_WHILE_ON_BODY (new)

2016-03-23 1
 Google Confidential and Proprietary

KM_TAG_OS_VERSION (new)
KM_TAG_OS_PATCHLEVEL (new)
KM_TAG_RESET_SINCE_ID_ROTATION (new)
© 2016 Google, Inc. All Rights Reserved. No express or implied warranties are provided for herein. All specifications are subject to change and any
expected future products, features or functionality will be provided on an if and when available basis.

Overview
Keymaster2, the third version of the keystore HAL, extends the capabilities of
hardware-backed key storage on Android devices. This document describes the changes
relative to ​
keymaster1​
, and is intended primarily for use by parties who are implementing the
keymaster2 API in secure hardware.

New Features
The largest change in keymaster2 is the addition of support for key attestation. Key
attestation provides public key certificates that contain a detailed description of the key and
its access controls, to make the key’s existence in secure hardware and its configuration
remotely verifiable.

Another important change is the binding of keys to operating system and patch level version.
This ensures that an attacker who discovers a weakness in an old version of system or TEE
software cannot roll a device back to the vulnerable version and use keys created with the
newer version. In addition, when a key with a given version and patch level is used on a device
that has been upgraded to a newer version or patch level, the key is upgraded before it can be
used, and the previous version of the key invalidated. In this way, as the device is upgraded,
the keys will “ratchet” forward along with the device, but any reversion of the device to a
previous release will cause the keys to be unusable.

This OS version and patch level binding is in addition to the Root of Trust binding required by
keymaster1.

There are some simplifications to the HAL interface:

● The get_supported_* methods have been removed. Keymaster2 requires all defined
algorithms, padding modes, digests, and key formats to be supported, so there is no
use for the get_supported_* methods.
● The finish() method accepts input, reducing the number of round trips to the TEE in
cases where the input is available all at once, and simplifying implementation of AEAD
decryption.

2016-03-23 2
 Google Confidential and Proprietary

Semantic Changes
Some tags have been clarified, or their meanings revised slightly, as seen in the ​
Tag Changes
section below.

Key Attestation
Keystore provides a more secure place to create, store, and use cryptographic keys in a
controlled way. When hardware-backed key storage is available and used, key material is
more secure against extraction from the device, and keymaster1 enforces restrictions in a
hard-to-subvert way.

This is only true, however, if the keystore keys are known to be in hardware-backed storage.
There is presently no way for apps or remote servers to reliably verify if this is the case. The
keystore daemon loads the available keymaster HAL and believes whatever the HAL says with
respect to hardware backing of keys.

Key attestation aims to provide a way to strongly determine if an asymmetric key pair is
hardware-backed, what the properties of the key are, and what constraints are applied to its
usage.

Java API
Note: This section is informational only. Keymaster2 implementers neither implement nor use
the Java API. This is provided to help implementers understand how the feature will be used
by applications. System components may use it differently, which is why it’s crucial this
section not be treated as normative.

To use attestation, an application developer:

● Creates a key generation request, specifying a key alias and key generation
parameters for an EC or RSA key pair.
● Sets the “attestation challenge” for the request, with
[Link](byte[])​ . This both provides
challenge data (which may be empty), and indicates that an attestation is requested.
● Generates the key pair.
● Requests the certificate chain from ​ AndroidKeyStore​ . The first certificate in the
chain is the attestation; the other certificates provide the chain of trust back to and
including the root attestation key.

2016-03-23 3
 Google Confidential and Proprietary

The following example generates a key pair and requests an attestation.

// Create KeyPairGenerator and set generation parameters for an ECDSA key pair
// using the NIST P­256 curve. “Key1” is the key alias.
KeyPairGenerator keyPairGenerator = [Link](
KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore");
[Link](
new [Link]("Key1", KeyProperties.PURPOSE_SIGN)
.setAlgorithmParameterSpec(new ECGenParameterSpec("secp256r1"))
.setDigests(KeyProperties.DIGEST_SHA256,
KeyProperties.DIGEST_SHA384,
KeyProperties.DIGEST_SHA512)
// Only permit the private key to be used if the user
// authenticated within the last five minutes.
.setUserAuthenticationRequired(true)
.setUserAuthenticationValidityDurationSeconds(5 * 60)
// Request an attestation with challenge “hello world”.
.setAttestationChallenge(“hello world”.toBytes());
.build());
// Generate the key pair. This will result in calls to both generate_key() and
// attest_key() at the keymaster2 HAL.
KeyPair keyPair = [Link]();

// Get the certificate chain

KeyStore keyStore = [Link]("AndroidKeyStore");
[Link](null);
Certificate[] certs = [Link](keystoreAlias);

// certs[0] is the attestation certificate. certs[1] signs certs[0], etc.,

// up to certs[[Link] ­ 1].

HAL Changes
To support attestation, we added a new set of tags, type, and method to the HAL.

The new tags are:

​M_TAG_ATTESTATION_CHALLENGE
● K
● ​
KM_TAG_INCLUDE_UNIQUE_ID
● ​
KM_TAG_RESET_SINCE_ID_ROTATION

The new type is:

typedef struct {
keymaster_blob_t* entries;

2016-03-23 4
 Google Confidential and Proprietary

size_t entry_count;
} keymaster_cert_chain_t;

The new method is:

keymaster_error_t (*attest_key)(​
const​​
struct​keymaster2_device* dev,
const​keymaster_key_blob_t* key_to_attest,
​
const​keymaster_key_param_set_t* attest_params,
​
keymaster_cert_chain_t* cert_chain);

● dev​ is the keymaster device structure.

● key_to_attest​ is the key blob returned from ​ generate_key​ for which the
attestation will be created.
● attest_params is a list of any parameters required for attestation. This includes
KM_TAG_ATTESTATION_CHALLENGE​ and possibly
KM_TAG_RESET_SINCE_ID_ROTATION​ , as well as ​
KM_TAG_APPLICATION_ID​ and
KM_TAG_APPLICATION_DATA​ . The latter two are required to decrypt the key blob if
they were specified during key generation.
● cert_chain​ is the output parameter, which returns an array of certificates. Entry 0 is
the ​
attestation certificate​, meaning it certifies the key from ​
key_to_attest​ and
contains the ​attestation extension​ .

The ​
attest_key​ method is considered a public key operation on the attested key, because it
can be called at any time and does not require that authorization constraints be met. For
example, if the attested key requires user authentication for use, an attestation can be
generated without user authentication.

Attestation Certificate
The attestation certificate is a standard X.509 certificate, with an optional attestation
extension that contains a description of the attested key. The certificate is signed with a
factory-provisioned ​attestation key​that uses the same algorithm as the key being attested
(RSA for RSA, EC for EC). The attestation certificate must contain all of the following fields
and must not contain any additional fields. Where a fixed field value is specified below, the
field must contain that value. CTS tests will validate that the certificate content is exactly as
defined.

Certificate SEQUENCE
Field name​
(see ​
RFC 5280​
) Value

tbsCertificate TBSCertificate SEQUENCE

2016-03-23 5
 Google Confidential and Proprietary

signatureAlgorithm AlgorithmIdentifier of algorithm used to sign

key: ECDSA for EC keys, RSA for RSA keys.

signatureValue BIT STRING, signature computed on ASN.1

DER-encoded tbsCertificate.

TBSCertificate SEQUENCE
Field name ​
(see ​
RFC 5280​
) Value

version INTEGER 2 (means v3 certificate)

serialNumber INTEGER 1 (fixed value: same on ​

all​
certs)

signature AlgorithmIdentifier of algorithm used to sign key:

ECDSA for EC keys, RSA for RSA keys.

issuer CN = “Android Keymaster2” (fixed value: same on ​

all
certs)

validity SEQUENCE of two dates, containing the values of

KM_TAG_ACTIVE_DATETIME​ and
KM_TAG_USAGE_EXPIRE_DATETIME​ . Those values
are in milliseconds since Jan 1, 1970. See ​ RFC 5280
for correct date representations in certificates.

subject CN = “A Keymaster Key” (fixed value: same on ​

all
certs)

subjectPublicKeyInfo SubjectPublicKeyInfo containing attested public key.

extensions/Key Usage digitalSignature: set if key has purpose

KM_PURPOSE_SIGN​ or ​
KM_PURPOSE_VERIFY

All other bits unset.

extensions/CRL Distribution Points Value TBD

extensions/“attestation” The OID is [Link].4.1.11129.2.1.17; the content is

defined in the ​Attestation Extension​ section. As with
all X.509 certificate extensions, the content is
represented as an OCTET_STRING containing a DER
encoding of the attestation SEQUENCE.

2016-03-23 6
 Google Confidential and Proprietary

Attestation Extension
The attestation extension contains a complete description of the keymaster authorizations
associated with the key, in a structure that directly corresponds to the authorization lists as
used in Android and the keymaster HAL. Each tag in an authorization list is represented by an
ASN.1 SEQUENCE entry, explicitly tagged with the keymaster tag number, but with the type
descriptor (four high order bits) masked out. For example, ​ KM_TAG_PURPOSE​ is defined in
keymaster_defs.h as ​ KM_ENUM_REP​ | 1. For the attestation extension, we remove the
KM_ENUM_REP​ value, leaving tag 1.

Values are translated in a straightforward way to ASN.1 types, as per the table below:

Keymaster type ASN.1 type

KM_ENUM INTEGER

KM_ENUM_REP SET of INTEGER

KM_UINT INTEGER

KM_UINT_REP SET of INTEGER

KM_ULONG INTEGER

KM_ULONG_REP SET of INTEGER

KM_DATE INTEGER (milliseconds since Jan 1, 1970 00:00:00 GMT)

KM_BOOL NULL (in keymaster, tag present means true, absent means
false, the same semantics apply to the ASN.1 encoding)

KM_BIGNUM Not presently used, so no mapping is defined

KM_BYTES OCTET_STRING

Note that some tags are omitted from the schema and should not be included in attestations.
For example, the values of ​
KM_TAG_USER_ID​ and ​
KM_TAG_SECURE_USER_ID​ have no
meaning off-device, and ​
KM_TAG_MIN_MAC_LENGTH​ and ​
KM_TAG_CALLER_NONCE​ are
useless with asymmetric keys.

Schema
The attestation extension content is described by the following ASN.1 schema:

2016-03-23 7
 Google Confidential and Proprietary

KeyDescription ::= SEQUENCE {

attestationVersion INTEGER,
attestationSecurityLevel SecurityLevel,
keymasterVersion INTEGER,
keymasterSecurityLevel SecurityLevel,
attestationChallenge OCTET_STRING,
uniqueId OCTET_STRING,
softwareEnforced AuthorizationList,
teeEnforced AuthorizationList,
}

SecurityLevel ::= ENUMERATED {

Software (0),
TrustedEnvironment (1),
}

AuthorizationList ::= SEQUENCE {

purpose [1] EXPLICIT SET OF INTEGER OPTIONAL,
algorithm [2] EXPLICIT INTEGER OPTIONAL,
keySize [3] EXPLICIT INTEGER OPTIONAL.
digest [5] EXPLICIT SET OF INTEGER OPTIONAL,
padding [6] EXPLICIT SET OF INTEGER OPTIONAL,
ecCurve [10] EXPLICIT INTEGER OPTIONAL,
rsaPublicExponent [200] EXPLICIT INTEGER OPTIONAL,
activeDateTime [400] EXPLICIT INTEGER OPTIONAL
originationExpireDateTime [401] EXPLICIT INTEGER OPTIONAL
usageExpireDateTime [402] EXPLICIT INTEGER OPTIONAL
noAuthRequired [503] EXPLICIT NULL OPTIONAL,
userAuthType [504] EXPLICIT INTEGER OPTIONAL,
authTimeout [505] EXPLICIT INTEGER OPTIONAL,
allowWhileOnBody [506] EXPLICIT NULL
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,
}

RootOfTrust ::= SEQUENCE {

verifiedBootKey OCTET_STRING,
deviceLocked BOOLEAN,
verifiedBootState VerifiedBootState,
}

2016-03-23 8
 Google Confidential and Proprietary

VerifiedBootState ::= ENUMERATED {

Green (0),
Yellow (1),
Orange (2),
Red (3),
}

KeyDescription Fields
The keymasterVersion and attestationChallenge fields are identified positionally, rather than
by tag, so the tags in the encoded form only specify field type. The remaining fields are
implicitly tagged as specified in the schema.

Field name Type Value

attestationVersion INTEGER 1

attestationSecurity SecurityLevel The security level of this attestation. It is

possible to get software attestations of
hardware-backed keys. Such attestations
cannot be trusted if the Android system is
compromised.

keymasterVersion INTEGER Version of keymaster device, 0, 1, or 2.

keymasterSecurity SecurityLevel The security level of the keymaster

implementation.

attestationChallenge OCTET_STRING Value of ​ ,

KM_TAG_ATTESTATION_CHALLENGE​
specified to attestation request.

uniqueId OCTET_STRING Optional ​

unique ID​
, present if key has
KM_TAG_INCLUDE_UNIQUE_ID

softwareEnforced AuthorizationList Optional, keymaster authorizations that are not

enforced by the TEE, if any.

teeEnforced AuthorizationList Optional, Keymaster authorizations that are

enforced by the TEE, if any.

2016-03-23 9
 Google Confidential and Proprietary

AuthorizationList Fields
AuthorizationList fields are all optional and are identified by keymaster tag value, with the type
bits masked out. Explicit tagging is used so the fields also contain a tag indicating their ASN.1
type, for easier parsing.

See keymaster_defs.h for details on each field’s values. Keymaster tag names were
transformed into field names by omitting the KM_TAG prefix and changing the remainder to
camel case, so ​
KM_TAG_KEY_SIZE​ became ​ keySize​ .

Note that many tags from keymaster_defs.h were not included in the schema, for a variety of
reasons. Some tags are not applicable to asymmetric keys, some have no meaning off-device,
etc.

RootOfTrust Fields
The RootOfTrust Fields are identified positionally and all are required.

Field name Type Value

verifiedBootKey OCTET_STRING A secure hash of the key used to verify the

system image. SHA-256 recommended.

deviceLocked BOOLEAN True if the bootloader is locked, which means

that only signed images can be flashed, and
that verified boot checking is done.

verifiedBootState VerifiedBootState State of verified boot.

osVersion INTEGER The current version of the OS, as an integer in

the format MMmmss, where MM is a two-digit
major version number, mm is a two-digit
minor version number, and ss is a two-digit
sub-minor version number. For example,
version 6.0.1 would be represented as 060001

patchMonthYear INTEGER The month and year of the last patch, as an

integer in the format YYYYMM, where YYYY is
a four-digit year and MM is a two-digit month.
For example, April 2016 would be represented
as 201604.

2016-03-23 10
 Google Confidential and Proprietary

VerifiedBootState Values
The values of verifiedBootState have the following meanings:

Value Meaning

Green Indicates a full chain of trust extending from the bootloader to verified
partitions, including the bootloader, boot partition, and all verified
partitions

Yellow Indicates the boot partition has been verified using the embedded
certificate, and the signature is valid. The bootloader displays a warning
and the fingerprint of the public key before allowing the boot process to
continue.

In this state, the ​

verifiedBootKey​
value will be the hash of the embedded
certificate, meaning the unchangeable certificate burned into ROM.

Orange Indicates a device may be freely modified. Device integrity is left to the
user to verify out-of-band. The bootloader displays a warning to the user
before allowing the boot process to continue.

In this state, the ​

verifiedBootKey​
value will be the hash of the
user-installed certificate.

Red Indicates the device has failed verification. No attestation certificate will
ever actually contain this value, because in this state the bootloader is
required to halt. It’s included here for completeness.

SecurityLevel Values
The values of securityLevel have the following meanings:

Value Meaning

Software The code that creates or manages the relevant element

(attestation or key) is implemented in the Android system and
could be altered if that system is compromised.

TrustedEnvironment The code that creates or manages the relevant element

(attestation or key) is implemented in a Trusted Execution

2016-03-23 11
 Google Confidential and Proprietary

Environment (TEE). It could be altered if the TEE is compromised,

but the TEE is highly resistant to remote compromise and
moderately resistant to compromise by direct hardware attack.

Unique ID
The Unique ID is a 128-bit value that identifies the device, but only for a limited period of time.
The value is computed with:

HMAC_SHA256(T || C || R, HBK)

Where:

● T is the “temporal counter value”, computed by dividing the value of

KM_TAG_CREATION_DATETIME​ by 2592000000, dropping any remainder. T changes
every 30 days (2592000000 = 30 * 24 * 60 * 60 * 1000).
● C is the value of ​
KM_TAG_APPLICATION_ID
● R is 1 if ​
KM_TAG_RESET_SINCE_ID_ROTATION​ is present in the attest_params
parameter to the attest_key call, or 0 if the tag is not present.
● HBK is a unique hardware-bound secret known to the Trusted Execution Environment
and never revealed by it. The secret must contain at least 128 bits of entropy and must
be unique to the individual device (probabilistic uniqueness is acceptable given the
128 bits of entropy). It’s recommended that HBK be derived from fused key material
via HMAC or AES_CMAC.

Truncate the HMAC_SHA256 output to 128 bits.

Attestation Keys and Certificates

Two keys, one RSA and one ECDSA, and the corresponding certificate chains, are securely
provisioned into the device.

Version Binding
Keymaster1 requires that all keymaster keys be cryptographically bound to the device “Root
of Trust”, which means the verified boot key. Keymaster2 adds an additional requirement to
bind all keys to the patch level of the system image.

2016-03-23 12
 Google Confidential and Proprietary

HAL Changes
To support version binding and version attestation, tags ​
KM_TAG_OS_VERSION​ and
KM_TAG_OS_PATCHLEVEL​ and the new methods ​ configure​ and ​
upgrade_key​ were
added. The version tags must be automatically added by keymaster2 implementations to all
newly-generated (or updated, see ​
upgrade_key​ ) keys. Further, any attempt to use a key that
does not have patch level matching the current system OS patch level must be rejected with
KM_ERROR_KEY_REQUIRES_UPGRADE​ . Note that keys with an OS version number that does
not match the current OS version may be used and must not be rejected if the patch level
matches.

KM_TAG_OS_VERSION​ is a ​
KM_UINT​that represents the major, minor, and sub-minor
portions of an Android system version as MMmmss, where MM is the major version, mm is
the minor version and ss is the sub-minor version. For example 6.1.2 would be represented as
060102.

KM_TAG_OS_PATCHLEVEL​ is a ​ that represents the year and month of the last

KM_UINT​
update to the system as YYYYMM, where YYYY is the four-digit year and MM is the two-digit
month. For example, March 2016 would be represented as 201603.

To allow keys to be upgraded to the new OS version and patch level of the system image, a
new method has been added to the HAL:

keymaster_error_t (*upgrade_key)(const struct keymaster2_device* dev,

const keymaster_key_blob_t* key_to_upgrade,
const keymaster_key_param_set_t* upgrade_params,
keymaster_key_blob_t* upgraded_key);

● dev​ is the device structure

● key_to_upgrade​ is the key which requires upgrading
● upgrade_params​ are parameters needed to upgrade the key. These will include
KM_TAG_APPLICATION_ID​ and ​
KM_TAG_APPLICATION_DATA​ , which are necessary
to decrypt the key blob, if they were provided during generation.
● upgraded_key​ is the output parameter, used to return the new key blob.

If ​
upgrade_key​ is called with a key blob that cannot be parsed or is otherwise invalid, it
returns ​
KM_ERROR_INVALID_KEY_BLOB​ . If it is called with a key whose patch level is greater
than the current system value, it returns ​
KM_ERROR_INVALID_ARGUMENT​ . In the event of
errors communicating with the secure world, it returns an appropriate error value (e.g.
KM_SECURE_HW_ACCESS_DENIED​ ,​
KM_SECURE_HW_BUSY​ , etc.) Otherwise, it returns
KM_ERROR_OK​ and returns a new key blob in ​ upgraded_key​ .

2016-03-23 13
 Google Confidential and Proprietary

key_to_upgrade​ remains valid after the ​upgrade_key​ call, and could theoretically be used
again if the device were downgraded. In practice, keystore will generally call ​delete_key​ on
the ​
key_to_upgrade​ blob shortly after the call to upgrade_key. If ​
key_to_upgrade​ had
tag ​
KM_TAG_ROLLBACK_RESISTANT​ , then ​
upgraded_key​ SHOULD have it as well (and
should be rollback resistant).

Secure Configuration
To implement version binding, the keymaster TA must have a way to securely receive the
current OS version and patch level (hereafter “version information”), and to ensure that the
information it receives strongly matches the information about the running system.

To support secure delivery of version information to the TA, an ​

os_version​ field​has been
added to the boot image header. The boot image build script automatically populates this
field. OEMs and keymaster TA implementers must work together to modify device
bootloaders to extract the version information from the boot image and pass it to the TA
before the non-secure system is booted. This ensures that attackers cannot interfere with
provisioning of version information to the TA.

It is also necessary to ensure that the system image has the same version information as the
boot image. To that end, the configure method has been added to the keymaster HAL:

keymaster_error_t (*configure)(const struct keymaster2_device* dev,

const keymaster_key_param_set_t* params);

The ​
params​ argument contains ​KM_TAG_OS_VERSION​ and ​
KM_TAG_OS_PATCHLEVEL​ . This
method will be called by keymaster2 clients after opening the HAL, but before calling any
other methods. If any other method is called before configure, the TA must return
KM_ERROR_KEYMASTER_NOT_CONFIGURED​ .

The first time ​

configure​ is called after the device boots, it should verify that the version
information provided matches what was provided by the bootloader. If the version
information does not match, ​ configure​ must return ​ KM_ERROR_INVALID_ARGUMENT​ , and
all other keymaster methods must continue returning
KM_ERROR_KEYMASTER_NOT_CONFIGURED​ . If the information matches, ​configure​ returns
KM_ERROR_OK​ , and other keymaster methods begin functioning normally.

Subsequent calls to configure must return the same value returned by the first call, and do not
change the state of keymaster. Note that this process will require that all OTAs update both
system and boot images; they can’t be updated separately in order to keep the version
information in sync.

2016-03-23 14
 Google Confidential and Proprietary

Because ​ configure​ will be called by the system whose contents it is intended to validate,
there is a narrow window of opportunity for an attacker to compromise the system image and
force it to provide version information that matches the boot image, but which is not the
actual version of the system. The combination of boot image verification, dm-verity validation
of the system image contents, and the fact that ​ configure​ is called very early in the system
boot should make this window of opportunity difficult to exploit.

Miscellaneous HAL changes

Obsolete methods removed

The following keymaster0 methods were superseded in keymaster1, but left in the HAL.
They’ve been removed in keymaster2:

● import_keypair​ (keymaster0 method, superseded by ​

import_key​ )
● get_keypair_public​ (keymaster0 method, superseded by ​
export_key​ )
● delete_keypair​ (keymaster0 method, superseded by ​
delete_key​ )
● delete_all​(keymaster0 method, superseded by ​
delete_all_keys​ )
● (keymaster0 method, superseded by ​
sign_data​ begin​/​
update​/​
verify​)
● verify_data​(keymaster0 method, superseded by ​
begin​/​
update​/​
verify​ )

Unused methods removed

The following keymaster1 methods were never used because the strategy shifted from
allowing keymaster clients to query supported primitives to requiring keymaster
implementations to support all primitives:

● (keymaster1 method, not used)

get_supported_algorithms​
● get_supported_block_modes​(keymaster1 method, not used)
● get_supported_padding_modes​ (keymaster1 method, not used)
● get_supported_import_formats​ (keymaster1 method, not used)
● get_supported_export_formats​ (keymaster1 method, not used)

In addition ​
get_supported_digests​ has been removed. It was used in keymaster1 to
allow some implementations to support a minimal digest set. In keymaster2 all defined
digests must be supported.

2016-03-23 15
 Google Confidential and Proprietary

Input to ​
finish
finish​ now accepts an ​input​ parameter, which allows operations on small amounts of
data to be performed with only two TrustZone calls, ​
begin​ then ​
finish​ , reducing total
operation latency by omitting a round trip.

The input to ​finish​ is also particularly helpful for implementing AES-GCM decryption.
Keymaster1 implementations have to contend with the fact that the tag comes in as the last
few bytes of the final ​update​ , but implementations don’t know when the final ​ update​ has
arrived until they receive ​
finish​ . This means that it’s necessary to buffer the last few bytes
of every update as a possible tag value.

Keymaster2 AES-GCM decryption implementations can simply not consume the last few
bytes of each ​
update​ , trusting keystore to send the unconsumed data on the next call. When
the end of the stream is reached, keystore will send the tag as input to ​ .
finish​

Argument changes
Some method arguments were changed in small ways to make them more consistent and
easier to work with:

● The ​ generate_key​ output parameter is now a pointer to a characteristics struct,

rather than a pointer to a pointer to a characteristics struct. The HAL no longer has to
allocate the returned structure and the caller no longer has to free it, though the HAL
still allocates its contents and the caller has to free them.
● The ​ get_key_characteristics​ output parameter is now a pointer to a
characteristics struct, rather than a pointer to a pointer to a characteristics struct. The
HAL no longer has to allocate the returned structure and the caller no longer has to
free it, though the HAL still allocates its contents and the caller has to free them.

Key blob upgrades

To allow keymaster implementations to upgrade key versions and more easily change key
representations, etc., the ​
upgrade_key​ method and the error code
KM_ERROR_KEY_REQUIRES_UPGRADE​ have been added. Keymaster implementations may
return ​
KM_ERROR_KEY_REQUIRES_UPGRADE​ when ​ get_key_characteristics​ ,
export_key​ or ​
begin​ are are called, and the client is then required to call ​ to
upgrade_key​
get a new key blob.

See ​
Version Binding​
for details.

2016-03-23 16
 Google Confidential and Proprietary

Tag Changes
This section summarizes the changes to keymaster tags between versions 1 and 2.

(new)
KM_TAG_EC_CURVE​
In keymaster1, the curve used for EC keys was guessed from the specified key size. To
improve flexibility moving forward, keymaster introduces an explicit way to specify curves. EC
key generation requests may have ​ KM_TAG_EC_CURVE​ or ​
KM_TAG_KEY_SIZE​ or both.

Possible values are defined by the following enumeration:

typedef enum {
KM_EC_CURVE_P_224 = 0,
KM_EC_CURVE_P_256 = 1,
KM_EC_CURVE_P_384 = 2,
KM_EC_CURVE_P_521 = 3,
} keymaster_ec_curve_t;

This tag is not repeatable.

If a generation request contains ​ only, fall back to the keymaster1 logic,

KM_TAG_KEY_SIZE​
choosing the appropriate NIST curve.

If the request contains ​ only, use the specified curve (curves are defined
KM_TAG_EC_CURVE​
in keymaster_ec_curve_t).

If the request contains both, use the curve specified by ​ , and validate that
KM_TAG_EC_CURVE​
the specified key size is appropriate for that curve. If not, return
KM_ERROR_INVALID_ARGUMENT​ .

(changed)
KM_TAG_KEY_SIZE​
This tag is no longer the preferred mechanism for selecting the EC curve. Its use is
unchanged for non-EC keys. See ​ KM_TAG_EC_CURVE​ .

(new)
KM_TAG_INCLUDE_UNIQUE_ID​
This tag is specified during key generation to indicate that an attestation certificate for the
generated key should contain a ​ Unique ID​
.

2016-03-23 17
 Google Confidential and Proprietary

(new)
KM_TAG_ALLOW_WHILE_ON_BODY​
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.

(new)
KM_TAG_OS_VERSION​
This tag is never sent to the keymaster TA, but is added to the hardware-enforced
authorization list by the TA.

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.

This tag is not repeatable.

(new)
KM_TAG_OS_PATCHLEVEL​
This tag is never sent to the keymaster TA, but is added to the hardware-enforced
authorization list by the TA.

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.

Keys that have a patch level different than the current patch level are not usable. An attempt
to use such a key will cause ​
begin​ ,​
get_key_characteristics​ or ​
export_key​ to return
KM_ERROR_KEY_REQUIRES_UPGRADE​ . See ​
Version Binding​.

This tag is not repeatable.

(new)
KM_TAG_RESET_SINCE_ID_ROTATION​
This tag will be sent to attest_key in attest_params when the device has been factory reset
since the last time the unique ID changed. Its purpose is to ensure that most factory resets
cause an immediate ID change. See ​ Unique ID​.

This tag is not repeatable.

2016-03-23 18