docs: Expanded description of "Key Attestation" N Preview feature.
The Key Attestation section within the Android N Preview "API
Overview" page now links to a separate page, which contains a
procedure for completing the attestation process, as well as the
certificate schema and its elements' associated descriptions.
Bug: 28851641
Change-Id: If96af7f5e7e6ba9297f48f20c669591b1a9ee9ce
diff --git a/docs/html/preview/_book.yaml b/docs/html/preview/_book.yaml
index 0d4b81b..ad67249 100644
--- a/docs/html/preview/_book.yaml
+++ b/docs/html/preview/_book.yaml
@@ -220,6 +220,8 @@
value: TV 录制
- name: zh-tw-lang
value: 電視錄製
+ - title: Key Attestation
+ path: /preview/features/key-attestation.html
- title: Network Security Configuration
path: /preview/features/security-config.html
path_attributes:
diff --git a/docs/html/preview/api-overview.jd b/docs/html/preview/api-overview.jd
index d457d5c..606b38f 100644
--- a/docs/html/preview/api-overview.jd
+++ b/docs/html/preview/api-overview.jd
@@ -701,48 +701,37 @@
For more information, see <a href="{@docRoot}preview/features/direct-boot.html">Direct Boot</a>.</p>
</p>
-
<h2 id="key_attestation">Key Attestation</h2>
-<p>Hardware-backed keystores provide a much safer method to create, store,
-and use cryptographic keys on Android devices. They protect keys from the
-Linux kernel, potential Android vulnerabilities, and extraction
-from rooted devices.</p>
+<p>
+ Android N introduces <em>key attestation</em>, a new security tool that helps
+ you make sure that the key pairs stored within a device's <a class=
+ "external-link" href=
+ "https://source.android.com/security/keystore/"><em>hardware-backed
+ keystore</em></a> properly protect the sensitive information that your app
+ uses. By using this tool, you gain additional confidence that your app
+ interacts with keys that reside in secure hardware, even if the device
+ running your app is rooted. If you use keys from the hardware-backed keystore
+ in your apps, you should use this tool, particularly if you use the keys to
+ verify sensitive information within your app.
+</p>
-<p>To make it easier and more secure to use hardware-backed keystores,
-Android N introduces Key Attestation. Apps and off-devices can use Key
-Attestation to strongly determine whether an RSA or EC key pair is
-hardware-backed, what the properties of the key pair are, and what
- constraints are applied to its usage and validity. </p>
+<p>
+ Key attestation allows you to verify that an RSA or EC key pair has been
+ created and stored in a device’s hardware-backed keystore within the device’s
+ trusted execution environment (TEE). The tool also allows you to use an
+ off-device service, such as your app's back-end server, to determine and
+ strongly verify the uses and validity of the key pair. These features provide
+ an additional level of security that protects the key pair, even if someone
+ roots the device or compromises the security of the Android platform running
+ on the device.
+</p>
-<p>Apps and off-device services can request information about a key pair
-through an X.509 attestation certificate which must be signed by a valid
-attestation key. The attestation key is an ECDSA signing key which is
-injected into the device’s hardware-backed keystore at the factory.
-Therefore, an attestation certificate signed by a valid attestation
-key confirms the existence of a hardware-backed keystore, along with
- details of key pairs in that keystore.</p>
-
-<p>To ensure that the device is using a secure, official Android factory
-image, Key Attestation requires that the device <a
-class="external-link"
-href="https://source.android.com/security/verifiedboot/verified-boot.html#bootloader_requirements">bootloader</a>
-provide the following information to the <a class="external-link"
-href="https://source.android.com/security/trusty/index.html">Trusted
-Execution Environment (TEE)</a>:</p>
-
-<ul>
-<li>The OS version and patch level installed on the device</li>
-<li>The <a href="https://source.android.com/security/verifiedboot/index.html"
-class="external-link" >Verified Boot</a> public key and lock status</li>
- </ul>
-
-<p>For more information about the hardware-backed keystore feature,
-see the guide for <a href="https://source.android.com/security/keystore/"
-class="external-link">Hardware-backed Keystore</a>.</p>
-
-<p>In addition to Key Attestation, Android N also introduces
- fingerprint-bound keys that are not revoked on fingerprint enrollment.</p>
+<p>
+ For more information, see the
+ <a href="{@docRoot}preview/features/key-attestation.html">Key Attestation</a>
+ developer documentation.
+</p>
<h2 id="network_security_config">Network Security Config</h2>
diff --git a/docs/html/preview/features/key-attestation.jd b/docs/html/preview/features/key-attestation.jd
new file mode 100644
index 0000000..98b8340
--- /dev/null
+++ b/docs/html/preview/features/key-attestation.jd
@@ -0,0 +1,845 @@
+page.title=Key Attestation
+page.metaDescription=New support in Android N for verifying security properties of hardware-backed keys.
+page.keywords="android N", "security", "TEE", "hardware-backed", "keystore", "certificate", "key attestation"
+
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#verifying">Retrieving and Verifying a Hardware-backed Key Pair</a></li>
+ <li><a href="#certificate_schema">Certificate Extension Data Schema</a></li>
+ </ol>
+ </div>
+</div>
+
+<p>
+ Key Attestation gives you more confidence that the keys you use in your app
+ are stored in a device's hardware-backed keystore. The following sections
+ describe how to verify the properties of hardware-backed keys and how to
+ interpret the schema of the attestation certificate's extension data.
+</p>
+
+<h2 id="verifying">
+ Retrieving and Verifying a Hardware-backed Key Pair
+</h2>
+
+<p>
+ During key attestation, you specify the alias of a key pair. The attestation
+ tool, in return, provides a certificate chain, which you can use to verify
+ the properties of that key pair.
+</p>
+
+<p>
+ The root certificate within this chain is signed using an attestation key,
+ which the device manufacturer injects into the device’s hardware-backed
+ keystore at the factory.
+</p>
+
+<p class="note">
+ <strong>Note:</strong> On devices that ship with Android N and Google Play
+ services, the root certificate is issued by Google. You should verify that
+ this root certificate appears within Google’s list of root certificates.
+</p>
+
+<p>
+ To implement key attestation, complete the following steps:
+</p>
+
+<ol>
+ <li>
+ Use a {@link java.security.KeyStore KeyStore} object's
+ {@link java.security.KeyStore#getCertificateChain getCertificateChain()}
+ method to get a reference to the chain of X.509 certificates associated with
+ the hardware-backed keystore.
+ </li>
+
+ <li>
+ <p>
+ Check each certificate’s validity using a
+ {@link java.security.cert.CRL CRL} object's
+ {@link java.security.cert.CRL#isRevoked isRevoked()} method.
+ </p>
+
+ <p class="caution">
+ <strong>Caution:</strong> Although you can complete this process within
+ your app directly, it’s safer to check the certificates’ revocation lists
+ on a separate server that you trust.
+ </p>
+ </li>
+
+ <li>
+ <p>
+ Create an <code>Attestation</code> object, passing in the first element of
+ the certificate chain as an argument:</p>
+
+<pre>
+// "certificates" contains the certificate chain associated with a specific key
+// pair in the device's hardware-backed keystore.
+X509Certificate attestationCert = (X509Certificate) certificates[0];
+Attestation hardwareKeyAttestation = new Attestation(attestationCert);
+</pre>
+
+ <p>
+ An attestation object extracts the extension data within this certificate
+ and stores this information in a more accessible format. For more details
+ about the schema of the extension data, see <a href=
+ "#certificate_schema">Certificate Extension Data Schema</a>.
+ </p>
+ </li>
+
+ <li>
+ <p>
+ Use the accessor methods within the <code>Attestation</code> class to
+ retrieve the extension data from the certificate. These methods use the
+ same names and structure hierarchy as in the certificate extension data
+ schema.
+ </p>
+
+ <p>
+ For example, to view the verified boot key for the device’s TEE, use the
+ following method sequence:
+ </p>
+
+<pre>
+// "hardwareKeyAttestation" contains the first element of the attestation
+// certificate chain.
+AuthorizationList teeAuthList = hardwareKeyAttestation.getTeeEnforced();
+RootOfTrust teeRootOfTrust = teeAuthList.getRootOfTrust();
+byte[] teeVerifiedBootKey = teeRootOfTrust.getVerifiedBootKey();
+</pre>
+
+ </li>
+
+ <li>
+ <p>
+ Compare the extension data from the <code>Attestation</code> object with
+ the set of values that you expect the hardware-backed key to contain.
+ </p>
+
+ <p class="caution">
+ <strong>Caution:</strong> Although you can complete this process within
+ your app directly, it’s safer to check the certificate’s extension data
+ on a separate server that you trust.
+ </p>
+ </li>
+</ol>
+
+<h2 id="certificate_schema">
+ Certificate Extension Data Schema
+</h2>
+
+<p>
+ Key attestation verifies the extension data that appears in the first
+ certificate within the chain in a device’s hardware-backed keystore. The
+ certificate stores the information according to the following ASN.1 schema:
+</p>
+
+<pre class="no-pretty-print">
+KeyDescription ::= SEQUENCE {
+ attestationVersion INTEGER,
+ attestationSecurityLevel SecurityLevel,
+ keymasterVersion INTEGER,
+ keymasterSecurityLevel SecurityLevel,
+ attestationChallenge OCTET_STRING,
+ <var>reserved OCTET_STRING</var>,
+ 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 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 INTEGER OPTIONAL,
+ attestationApplicationId [709] EXPLICIT OCTET_STRING OPTIONAL,
+}
+
+RootOfTrust ::= SEQUENCE {
+ verifiedBootKey OCTET_STRING,
+ deviceLocked BOOLEAN,
+ verifiedBootState VerifiedBootState,
+}
+
+VerifiedBootState ::= ENUMERATED {
+ Verified (0),
+ SelfSigned (1),
+ Unverified (2),
+ Failed (3),
+}
+</pre>
+
+<p>
+ The following list presents a description of each element within the schema:
+</p>
+
+<h3 id="certificate_schema_keydescription">
+ KeyDescription
+</h3>
+
+<p>
+ This sequence of values presents general information about the key pair being
+ verified through key attestation and provides easy access to additional
+ details.
+</p>
+
+<dl>
+ <dt>
+ <code>attestationVersion</code>
+ </dt>
+
+ <dd>
+ The version of the key attestation feature. Should be set to 1.
+ </dd>
+
+ <dt>
+ <code>attestationSecurity</code>
+ </dt>
+
+ <dd>
+ <p>
+ The <a href="#certificate_schema_securitylevel">security
+ level</a> of the attestation.
+ </p>
+
+ <p class="note">
+ <strong>Note:</strong> Although it is possible to attest keys that are
+ stored in the Android system—that is, if the
+ <code>attestationSecurity</code> value is set to Software—you
+ cannot trust these attestations if the Android system becomes compromised.
+ </p>
+ </dd>
+
+ <dt>
+ <code>keymasterVersion</code>
+ </dt>
+
+ <dd>
+ The version of the Keymaster hardware abstraction layer (HAL). Use 0 to
+ represent version 0.2 or 0.3, 1 to represent version 1.0, and 2 to represent
+ version 2.0.
+ </dd>
+
+ <dt>
+ <code>keymasterSecurity</code>
+ </dt>
+
+ <dd>
+ The <a href="#certificate_schema_securitylevel">security
+ level</a> of the Keymaster implementation.
+ </dd>
+
+ <dt>
+ <code>attestationChallenge</code>
+ </dt>
+
+ <dd>
+ The challenge string associated with a key pair that is verified using key
+ attestation.
+ </dd>
+
+ <dt>
+ <code><var>reserved</var></code>
+ </dt>
+
+ <dd>
+ Only system apps use this value. In all other apps, this value is empty.
+ </dd>
+
+ <dt>
+ <code>softwareEnforced</code>
+ </dt>
+
+ <dd>
+ Optional. The Keymaster <a href=
+ "#certificate_schema_authorizationlist">authorization
+ list</a> that is enforced by the Android system, not by the device’s TEE.
+ </dd>
+
+ <dt>
+ <code>teeEnforced</code>
+ </dt>
+
+ <dd>
+ Optional. The Keymaster <a href=
+ "#certificate_schema_authorizationlist">authorization
+ list</a> that is enforced by the device’s TEE.
+ </dd>
+</dl>
+
+<h3 id="certificate_schema_securitylevel">
+ SecurityLevel
+</h3>
+
+<p>
+ This data structure indicates the extent to which a software feature, such as
+ a key pair, is protected based on its location within the device.
+</p>
+
+<p>
+ Because the data structure is an enumeration, it takes on exactly one of the
+ following values:
+</p>
+
+<dl>
+ <dt>
+ Software
+ </dt>
+
+ <dd>
+ The logic for creating and managing the feature is implemented in the
+ Android system. For the purposes of creating and storing key pairs, this
+ location is less secure than the TEE but is more secure than your app's
+ process space.
+ </dd>
+
+ <dt>
+ TrustedEnvironment
+ </dt>
+
+ <dd>
+ The logic for creating and managing the feature is implemented in secure
+ hardware, such as a TEE. For the purposes of creating and storing key pairs,
+ this location is more secure because secure hardware is highly resistant to
+ remote compromise.
+ </dd>
+</dl>
+
+<h3 id="certificate_schema_authorizationlist">
+ AuthorizationList
+</h3>
+
+<p>
+ This data structure contains the key pair’s properties themselves, as defined
+ in the Keymaster hardware abstraction layer (HAL). You compare these values
+ to the device’s current state or to a set of expected values to verify that a
+ key pair is still valid for use in your app.
+</p>
+
+<p>
+ Each field name corresponds to a similarly-named Keymaster tag. For example,
+ the <code>keySize</code> field in an authorization list corresponds to the
+ <code>KM_TAG_KEY_SIZE</code> Keymaster tag.
+</p>
+
+<p>
+ Each field in the following list is optional:
+</p>
+
+<dl>
+ <dt>
+ <code>purpose</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_purpose">
+ KM_TAG_PURPOSE</a></code> Keymaster tag, which uses a tag ID value of 1.
+ </dd>
+
+ <dt>
+ <code>algorithm</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_algorithm">
+ KM_TAG_ALGORITHM</a></code> Keymaster tag, which uses a tag ID value of
+ 2.
+ </p>
+
+ <p>
+ When an <code>AuthorizationList</code> object is associated with key
+ attestation, this value is always <code>KM_ALGORITHM_RSA</code> or
+ <code>KM_ALGORITHM_EC</code>.
+ </p>
+ </dd>
+
+ <dt>
+ <code>keySize</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_key_size">
+ KM_TAG_KEY_SIZE</a></code> Keymaster tag, which uses a tag ID value of 3.
+ </dd>
+
+ <dt>
+ <code>digest</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_digest">
+ KM_TAG_DIGEST</a></code> Keymaster tag, which uses a tag ID value of 5.
+ </dd>
+
+ <dt>
+ <code>padding</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_padding">
+ KM_TAG_PADDING</a></code> Keymaster tag, which uses a tag ID value of 6.
+ </dd>
+
+ <dt>
+ <code>ecCurve</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code>KM_TAG_EC_CURVE</code> Keymaster tag, which uses
+ a tag ID value of 10.
+ </p>
+
+ <p>
+ The set of parameters used to generate an elliptic curve (EC) key pair,
+ which uses ECDSA for signing and verification, within the Android system
+ keystore.
+ </p>
+ </dd>
+
+ <dt>
+ <code>rsaPublicExponent</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_rsa_public_exponent">
+ KM_TAG_RSA_PUBLIC_EXPONENT</a></code> Keymaster tag, which uses a tag ID
+ value of 200.
+ </dd>
+
+ <dt>
+ <code>activeDateTime</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_active_datetime">
+ KM_TAG_ACTIVE_DATETIME</a></code> Keymaster tag, which uses a tag ID value
+ of 400.
+ </dd>
+
+ <dt>
+ <code>originationExpireDateTime</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_origination_expire_datetime">
+ KM_TAG_ORIGINATION_EXPIRE_DATETIME</a></code> Keymaster tag, which uses a
+ tag ID value of 401.
+ </dd>
+
+ <dt>
+ <code>usageExpireDateTime</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_usage_expire_datetime">
+ KM_TAG_USAGE_EXPIRE_DATETIME</a></code> Keymaster tag, which uses a tag ID
+ value of 402.
+ </dd>
+
+ <dt>
+ <code>noAuthRequired</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_no_auth_required">
+ KM_TAG_NO_AUTH_REQUIRED</a></code> Keymaster tag, which uses a tag ID
+ value of 503.
+ </p>
+
+ <p>
+ When an <code>AuthorizationList</code> object is associated with key
+ attestation, this value is always true.
+ </p>
+ </dd>
+
+ <dt>
+ <code>userAuthType</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_user_auth_type">
+ KM_TAG_USER_AUTH_TYPE</a></code> Keymaster tag, which uses a tag ID value
+ of 504.
+ </dd>
+
+ <dt>
+ <code>authTimeout</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_auth_timeout">
+ KM_TAG_AUTH_TIMEOUT</a></code> Keymaster tag, which uses a tag ID value of
+ 505.
+ </dd>
+
+ <dt>
+ <code>allowWhileOnBody</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code>KM_TAG_ALLOW_WHILE_ON_BODY</code> Keymaster tag,
+ which uses a tag ID value of 506.
+ </p>
+
+ <p>
+ Allows the key to be used after its authentication timeout period if the
+ user is still wearing the device on their body. Note that a secure
+ on-body sensor determines whether the device is being worn on the user’s
+ body.
+ </p>
+
+ <p>
+ When an <code>AuthorizationList</code> object is associated with key
+ attestation, this value is always true.
+ </p>
+ </dd>
+
+ <dt>
+ <code>allApplications</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code>KM_TAG_ALL_APPLICATIONS</code> Keymaster tag,
+ which uses a tag ID value of 600.
+ </p>
+
+ <p>
+ Indicates whether all apps on a device can access the key pair.
+ </p>
+
+ <p>
+ When an <code>AuthorizationList</code> object is associated with key
+ attestation, this value is always true.
+ </p>
+ </dd>
+
+ <dt>
+ <code>applicationId</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_application_id">
+ KM_TAG_APPLICATION_ID</a></code> Keymaster tag, which uses a tag ID value
+ of 601.
+ </dd>
+
+ <dt>
+ <code>creationDateTime</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_creation_datetime">
+ KM_TAG_CREATION_DATETIME</a></code> Keymaster tag, which uses a tag ID
+ value of 701.
+ </dd>
+
+ <dt>
+ <code>origin</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_origin">
+ KM_TAG_ORIGIN</a></code> Keymaster tag, which uses a tag ID value of 702.
+ </p>
+
+ <p>
+ When an <code>AuthorizationList</code> object is associated with key
+ attestation, this value is usually set to
+ <code>KM_ORIGIN_GENERATED</code>. If the attestation uses Keymaster
+ version 0.2 or 0.3, however, the origin may be set to
+ <code>KM_ORIGIN_UNKNOWN</code> instead.
+ </p>
+ </dd>
+
+ <dt>
+ <code>rollbackResistant</code>
+ </dt>
+
+ <dd>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_rollback_resistant">
+ KM_TAG_ROLLBACK_RESISTANT</a></code> Keymaster tag, which uses a tag ID
+ value of 703.
+ </dd>
+
+ <dt>
+ <code>rootOfTrust</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code><a href=
+ "https://source.android.com/security/keystore/implementer-ref.html#km_tag_root_of_trust">
+ KM_TAG_ROOT_OF_TRUST</a></code> Keymaster tag, which uses a tag ID value
+ of 704.
+ </p>
+
+ <p>
+ For more details, see the section describing the <code><a href=
+ "#certificate_schema_rootoftrust">RootOfTrust</a></code>
+ data structure.
+ </p>
+ </dd>
+
+ <dt>
+ <code>osVersion</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code>KM_TAG_OS_VERSION</code> Keymaster tag, which
+ uses a tag ID value of 705.
+ </p>
+
+ <p>
+ The version of the Android operating system associated with the
+ Keymaster, specified as a six-digit integer. For example, version 6.0.1
+ is represented as 060001.
+ </p>
+
+ <p>
+ Only Keymaster version 1.0 or higher includes this value in the
+ authorization list.
+ </p>
+ </dd>
+
+ <dt>
+ <code>osPatchLevel</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code>KM_TAG_PATCHLEVEL</code> Keymaster tag, which
+ uses a tag ID value of 706.
+ </p>
+
+ <p>
+ The month and year associated with the security patch that is being used
+ within the Keymaster, specified as a six-digit integer. For example, the
+ June 2016 patch is represented as 201606.
+ </p>
+
+ <p>
+ Only Keymaster version 1.0 or higher includes this value in the
+ authorization list.
+ </p>
+ </dd>
+
+ <dt>
+ <code>attestationChallenge</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code>KM_TAG_ATTESTATION_CHALLENGE</code> Keymaster
+ tag, which uses a tag ID value of 708.
+ </p>
+
+ <p>
+ The challenge string associated with the key pair that is defined in the
+ Keymaster.
+ </p>
+ </dd>
+
+ <dt>
+ <code>attestationApplicationId</code>
+ </dt>
+
+ <dd>
+ <p>
+ Corresponds to the <code>KM_TAG_ATTESTATION_APPLICATION_ID</code>
+ Keymaster tag, which uses a tag ID value of 709.
+ </p>
+
+ <p>
+ The unique ID of the attestation certificate that signed the key pair
+ that is in the Keymaster.
+ </p>
+ </dd>
+</dl>
+
+<h3 id="certificate_schema_rootoftrust">
+ RootOfTrust
+</h3>
+
+<p>
+ This collection of values defines key information about the device’s status.
+</p>
+
+<p>
+ Each field in the following list is required:
+</p>
+
+<dl>
+ <dt>
+ <code>verifiedBootKey</code>
+ </dt>
+
+ <dd>
+ <p>
+ A secure hash of the key that verifies the system image. It is recommended
+ that you use the SHA-256 algorithm for this hash.
+ </p>
+ </dd>
+
+ <dt>
+ <code>deviceLocked</code>
+ </dt>
+
+ <dd>
+ True if the device’s bootloader is locked, which enables Verified Boot
+ checking and prevents an unsigned device image from being flashed onto the
+ device. For more information about this feature, see the <a class=
+ "external-link" href=
+ "https://source.android.com/security/verifiedboot/verified-boot.html">Verifying
+ Boot</a> documentation.
+ </dd>
+
+ <dt>
+ <code>verifiedBootState</code>
+ </dt>
+
+ <dd>
+ The <a href="#certificate_schema_verifiedbootstate">boot
+ state</a> of the device, according to the Verified Boot feature.
+ </dd>
+
+ <dt>
+ <code>osVersion</code>
+ </dt>
+
+ <dd>
+ The current version of the Android operating system on the device,
+ specified as a six-digit integer. For example, version 6.0.1 is represented
+ as 060001.
+ </dd>
+
+ <dt>
+ <code>patchMonthYear</code>
+ </dt>
+
+ <dd>
+ The month and year associated with the security patch that is currently
+ installed on the device, specified as a six-digit integer. For example, the
+ June 2016 patch is represented as 201606.
+ </dd>
+</dl>
+
+<h3 id="certificate_schema_verifiedbootstate">
+ VerifiedBootState
+</h3>
+
+<p>
+ This data structure provides the device’s current boot state, which
+ represents the level of protection provided to the user and to apps after the
+ device finishes booting. For more information about this feature, see the
+ <a class="external-link" href=
+ "https://source.android.com/security/verifiedboot/verified-boot.html#boot_state">
+ Boot State</a> section within the Verifying Boot documentation.
+</p>
+
+<p>
+ This data structure is an enumeration, so it takes on exactly one of the
+ following values:
+</p>
+
+<dl>
+ <dt>
+ Verified
+ </dt>
+
+ <dd>
+ <p>
+ Indicates a full chain of trust, which includes the bootloader, the boot
+ partition, and all verified partitions.
+ </p>
+
+ <p>
+ When the device is in this boot state, the <code>verifiedBootKey</code> is
+ the hash of the device-embedded certificate, which the device manufacturer
+ adds to the device's ROM at the factory.
+ </p>
+ </dd>
+
+ <dt>
+ SelfSigned
+ </dt>
+
+ <dd>
+ <p>
+ Indicates that the device-embedded certificate has verified the device’s
+ boot partition and that the signature is valid.
+ </p>
+
+ <p>
+ When the device is in this boot state, the <code>verifiedBootKey</code> is
+ the hash of a user-installed certificate, which signs a boot partition
+ that the user adds to the device in place of the original,
+ manufacturer-provided boot partition.
+ </p>
+ </dd>
+
+ <dt>
+ Unverified
+ </dt>
+
+ <dd>
+ Indicates that the user can modify the device freely. Therefore, the user is
+ responsible for verifying the device’s integrity.
+ </dd>
+
+ <dt>
+ Failed
+ </dt>
+
+ <dd>
+ Indicates that the device has failed verification. The attestation
+ certificate should never use this value for <code>VerifiedBootState</code>.
+ </dd>
+</dl>
