| /* |
| * Copyright 2020 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. |
| */ |
| |
| package android.hardware.identity; |
| |
| import android.hardware.identity.Certificate; |
| import android.hardware.identity.SecureAccessControlProfile; |
| |
| /** |
| * IWritableIdentityCredential is used to personalize a new identity credential. Credentials cannot |
| * be updated or modified after creation; any changes require deletion and re-creation. |
| */ |
| @VintfStability |
| interface IWritableIdentityCredential { |
| /** |
| * Gets the certificate chain for credentialKey which can be used to prove the hardware |
| * characteristics to an issuing authority. Must not be called more than once. |
| * |
| * The following non-optional fields for the X.509 certificate shall be set as follows: |
| * |
| * - version: INTEGER 2 (means v3 certificate). |
| * |
| * - serialNumber: INTEGER 1 (fixed value: same on all certs). |
| * |
| * - signature: must be set to ECDSA. |
| * |
| * - subject: CN shall be set to "Android Identity Credential Key". (fixed value: |
| * same on all certs) |
| * |
| * - issuer: Same as the subject field of the batch attestation key. |
| * |
| * - validity: Should be set to current time and expire at the same time as the |
| * attestation batch certificate used. |
| * |
| * - subjectPublicKeyInfo: must contain attested public key. |
| * |
| * The certificate chain must be generated using Keymaster Attestation |
| * (see https://source.android.com/security/keystore/attestation) with the |
| * following additional requirements on the data in the attestation extension: |
| * |
| * - The attestationVersion field in the attestation extension must be at least 3. |
| * |
| * - The attestationSecurityLevel field must be set to either Software (0), |
| * TrustedEnvironment (1), or StrongBox (2) depending on how attestation is |
| * implemented. |
| * |
| * - The keymasterVersion field in the attestation extension must be set to the. |
| * same value as used for Android Keystore keys. |
| * |
| * - The keymasterSecurityLevel field in the attestation extension must be set to |
| * either Software (0), TrustedEnvironment (1), or StrongBox (2) depending on how |
| * the Trusted Application backing the HAL implementation is implemented. |
| * |
| * - The attestationChallenge field must be set to the passed-in challenge. |
| * |
| * - The uniqueId field must be empty. |
| * |
| * - The softwareEnforced field in the attestation extension must include |
| * Tag::ATTESTATION_APPLICATION_ID which must be set to the bytes of the passed-in |
| * attestationApplicationId. |
| * |
| * - The teeEnforced field in the attestation extension must include |
| * |
| * - Tag::IDENTITY_CREDENTIAL_KEY which indicates that the key is an Identity |
| * Credential key (which can only sign/MAC very specific messages) and not an Android |
| * Keystore key (which can be used to sign/MAC anything). This must not be set |
| * for test credentials. |
| * |
| * - Tag::PURPOSE must be set to SIGN |
| * |
| * - Tag::KEY_SIZE must be set to the appropriate key size, in bits (e.g. 256) |
| * |
| * - Tag::ALGORITHM must be set to EC |
| * |
| * - Tag::NO_AUTH_REQUIRED must be set |
| * |
| * - Tag::DIGEST must be set to SHA_2_256 |
| * |
| * - Tag::EC_CURVE must be set to P_256 |
| * |
| * - Tag::ROOT_OF_TRUST must be set |
| * |
| * - Tag::OS_VERSION and Tag::OS_PATCHLEVEL must be set |
| * |
| * Additional authorizations may be appear in the softwareEnforced and teeEnforced |
| * fields. For example if the device has a boot or vendor partitions, then BOOT_PATCHLEVEL |
| * and VENDOR_PATCHLEVEL should be set. |
| * |
| * Since the chain is required to be generated using Keymaster Attestation, the returned |
| * certificate chain has the following properties: |
| * |
| * - The certificate chain is of at least length three. |
| * |
| * - The root of trust is the same as for Keymaster Attestation. This is usually |
| * a certificate owned by Google but depending on the specific Android device it may |
| * be another certificate. |
| * |
| * As with any user of attestation, the Issuing Authority (as a relying party) wishing |
| * to issue a credential to a device using these APIs, must carefully examine the |
| * returned certificate chain for all of the above (and more). In particular, the Issuing |
| * Authority should check the root of trust (which include verified boot state), patch level, |
| * attestation application id, etc. |
| * |
| * This all depends on the needs of the Issuing Authority and the kind of credential but |
| * in general an Issuing Authority should never issue a credential to a device without |
| * verified boot enabled, to an unrecognized application, or if it appears the device |
| * hasn't been updated for a long time. |
| * |
| * See https://github.com/google/android-key-attestation for an example of how to |
| * examine attestations generated from Android devices. |
| * |
| * @param attestationApplicationId is the DER encoded value to be stored |
| * in Tag::ATTESTATION_APPLICATION_ID. This schema is described in |
| * https://developer.android.com/training/articles/security-key-attestation#certificate_schema_attestationid |
| * |
| * @param attestationChallenge a challenge set by the issuer to ensure freshness. If |
| * this is empty, the call fails with STATUS_INVALID_DATA. Implementations must |
| * support challenges of at least 32 bytes. |
| * |
| * @return the X.509 certificate chain for the credentialKey |
| */ |
| Certificate[] getAttestationCertificate( |
| in byte[] attestationApplicationId, in byte[] attestationChallenge); |
| |
| /** |
| * Start the personalization process. |
| * |
| * startPersonalization must not be called more than once. |
| * |
| * The setExpectedProofOfProvisioningSize() method will be called before this method. |
| * |
| * @param accessControlProfileCount specifies the number of access control profiles that will |
| * be provisioned with addAccessControlProfile(). |
| * |
| * @param entryCounts specifies the number of data entries that will be provisioned with |
| * beginAddEntry() and addEntry(). Each item in the array specifies how many entries |
| * will be added for each name space. |
| */ |
| void startPersonalization(in int accessControlProfileCount, in int[] entryCounts); |
| |
| /** |
| * Add an access control profile, which defines the requirements or retrieval of one or more |
| * entries. If both readerCertificate and userAuthenticationRequired are empty/false, |
| * associated entries are open access, requiring no authentication to read (though the caller |
| * is free to require other authentication above this HAL). |
| * |
| * This method must be called exactly as many times as specified in the startPersonalization() |
| * accessControlProfileCount parameter. If this is requirement is not met, the method fails |
| * with STATUS_INVALID_DATA. |
| * |
| * @param id a numeric identifier that must be unique within the context of a Credential and may |
| * be used to reference the profile. This id must be non-negative and less than 32 (allowing |
| * for a total of 32 profiles). If this is not satisfied the call fails with |
| * STATUS_INVALID_DATA. |
| * |
| * @param readerCertificate if non-empty, specifies a single X.509 certificate (not a chain of |
| * certificates) that must be used to authenticate requests (see the readerSignature |
| * parameter in IIdentityCredential.startRetrieval). |
| * |
| * @param userAuthenticationRequired if true, specifies that the user is required to |
| * authenticate to allow requests. Required authentication freshness is specified by |
| * timeout below. |
| * |
| * @param timeoutMillis specifies the amount of time, in milliseconds, for which a user |
| * authentication (see userAuthenticationRequired above) is valid, if |
| * userAuthenticationRequired is true. If the timout is zero then authentication is |
| * required for each reader session. If userAuthenticationRequired is false, the timeout |
| * must be zero. If this requirement is not met the call fails with STATUS_INVALID_DATA. |
| * |
| * @param secureUserId must be non-zero if userAuthenticationRequired is true. It is not |
| * related to any Android user ID or UID, but is created in the Gatekeeper application |
| * in the secure environment. If this requirement is not met the call fails with |
| * STATUS_INVALID_DATA. |
| * |
| * @return a structure with the passed-in data and MAC created with storageKey for |
| * authenticating the data at a later point in time. |
| */ |
| SecureAccessControlProfile addAccessControlProfile(in int id, in Certificate readerCertificate, |
| in boolean userAuthenticationRequired, in long timeoutMillis, in long secureUserId); |
| |
| /** |
| * Begins the process of adding an entry to the credential. All access control profiles must be |
| * added before calling this method. Entries must be added in namespace "groups", meaning all |
| * entries of one namespace must be added before adding entries from another namespace. |
| * |
| * This method must be called exactly as many times as the sum of the items in the entryCounts |
| * parameter specified in the startPersonalization(), and must be followed by one or more calls |
| * to addEntryValue(). If this requirement is not met the method fails with STATUS_INVALID_DATA. |
| * |
| * @param accessControlProfileIds specifies the set of access control profiles that can |
| * authorize access to the provisioned element. |
| * |
| * @param nameSpace is the namespace of the element, e.g. "org.iso.18013.5.1" |
| * |
| * @param name is the name of the element. |
| * |
| * @param entrySize is the size of the entry value. If this requirement |
| * is not met this method fails with STATUS_INVALID_DATA. |
| */ |
| void beginAddEntry(in int[] accessControlProfileIds, in @utf8InCpp String nameSpace, |
| in @utf8InCpp String name, in int entrySize); |
| |
| /** |
| * Continues the process of adding an entry, providing a value or part of a value. |
| * |
| * In the common case, this method will be called only once per entry added. In the case of |
| * values that are larger than the secure environment's GCM chunk size |
| * (see IIdentityCredentialStore.getHardwareInformation()), the caller must provide the |
| * value in chunks. All chunks must be exactly gcmChunkSize except the last and the sum of all |
| * chunk sizes must equal the value of the beginAddEntry() entrySize argument. If this |
| * requirement is not met the call fails with STATUS_INVALID_DATA. |
| * |
| * @param content is the entry value, encoded as CBOR. In the case the content exceeds |
| * gcmChunkSize, this may be partial content up to gcmChunkSize bytes long. |
| * |
| * @return the encrypted and MACed content. For directly-available credentials the contents are |
| * implementation-defined. For other credentials, the result contains |
| * |
| * AES-GCM-ENC(storageKey, R, Data, AdditionalData) |
| * |
| * where: |
| * |
| * Data = any ; value |
| * |
| * AdditionalData = { |
| * "Namespace" : tstr, |
| * "Name" : tstr, |
| * "AccessControlProfileIds" : [ + uint ], |
| * } |
| */ |
| byte[] addEntryValue(in byte[] content); |
| |
| /** |
| * Finishes adding entries and returns a signature that an issuing authority may use to |
| * validate that all data was provisioned correctly. |
| * |
| * After this method is called, the IWritableIdentityCredential is no longer usable. |
| * |
| * @param out credentialData is a CBOR-encoded structure (in CDDL notation): |
| * |
| * CredentialData = [ |
| * tstr, ; docType, an optional name that identifies the type of credential |
| * bool, ; testCredential, indicates if this is a test credential |
| * bstr ; an opaque byte vector with encrypted data, see below |
| * ] |
| * |
| * The last element is an opaque byte vector which contains encrypted copies of the |
| * secrets used to secure the new credential's data and to authenticate the credential to |
| * the issuing authority. It contains: |
| * |
| * AES-GCM-ENC(HBK, R, CredentialKeys, docType) |
| * |
| * where HBK is a unique hardware-bound key that has never existed outside of the secure |
| * environment (except it's all zeroes if testCredential is True) and CredentialKeys is |
| * the CBOR-encoded structure (in CDDL notation) given below. |
| * |
| * In API versions 1 and 2 it was the following |
| * |
| * CredentialKeys = [ |
| * bstr, ; storageKey, a 128-bit AES key |
| * bstr ; credentialPrivKey, the private key for credentialKey |
| * ; in uncompressed form |
| * ] |
| * |
| * In API version 3 or later it must be the following |
| * |
| * CredentialKeys = [ |
| * bstr, ; storageKey, a 128-bit AES key |
| * bstr ; credentialPrivKey, the private key for credentialKey |
| * ; in uncompressed form |
| * bstr ; SHA-256(ProofOfProvisioning) |
| * ] |
| * |
| * Additional elements may be added to the CredentialKeys array in future versions. |
| * |
| * @param out proofOfProvisioningSignature proves to the IA that the credential was imported |
| * into the secure hardware without alteration or error. When the final addEntry() call is |
| * made (when the number of provisioned entries equals the sum of the items in |
| * startPersonalization() entryCounts parameter), a COSE_Sign1 structure |
| * signed by CredentialKey with payload set to the ProofOfProvisioning CBOR below: |
| * |
| * ProofOfProvisioning = [ |
| * "ProofOfProvisioning", |
| * tstr, ; DocType |
| * [ * AccessControlProfile ], |
| * ProvisionedData, |
| * bool ; true if this is a test credential, should |
| * ; always be false. |
| * ] |
| * |
| * AccessControlProfile = { |
| * "id" : uint, |
| * ? "readerCertificate" : bstr, |
| * ? ( |
| * "userAuthenticationRequired" : bool, |
| * "timeoutMillis" : uint, |
| * ) |
| * } |
| * |
| * ProvisionedData = { |
| * * Namespace => [ + Entry ] |
| * }, |
| * |
| * Namespace = tstr |
| * |
| * Entry = { |
| * "name" : tstr, |
| * "value" : any, |
| * "accessControlProfiles" : [ * uint ], |
| * } |
| */ |
| @SuppressWarnings(value={"out-array"}) |
| void finishAddingEntries(out byte[] credentialData, out byte[] proofOfProvisioningSignature); |
| |
| /** |
| * Sets the expected size of the ProofOfProvisioning returned by finishAddingEntries(). This |
| * method must be called before startPersonalization() is called. |
| * |
| * This information is provided to make it possible for a HAL implementation to |
| * incrementally build up cryptographically authenticated data which includes the |
| * ProofOfProvisioning CBOR. |
| * |
| * @param expectedProofOfProvisioningSize the expected size of ProofOfProvisioning. |
| */ |
| void setExpectedProofOfProvisioningSize(in int expectedProofOfProvisioningSize); |
| |
| /** |
| * Sets the attestation key used to sign the credentialKey certificate. This method is used to |
| * support remotely provisioned attestation keys, removing the credential's dependency on any |
| * factory-provisioned attestation key. |
| * |
| * This method must be called before getAttestationCertificate. After this method is called, |
| * the certificate chain returned by getAttestationCertificate will contain a leaf certificate |
| * signed by attestationKeyBlob and the chain in attestationCertificate will make up the rest |
| * of the returned chain. |
| * |
| * Returns EX_UNSUPPORTED_FUNCTION if remote provisioning is not supported |
| * (see IIdentityCredentialStore.getHardwareInformation()). |
| * |
| * This method was added in API version 4. |
| * |
| * @param attestationKeyBlob is a key blob generated by the IRemotelyProvisionedComponent that |
| * is returned by ICredentialStore.getRemotelyProvisionedComponent. The format is vendor- |
| * specified, and matches the key blob returned by IKeyMintDevice.generateKey. |
| * |
| * @param attestationCertificate contains the X.509 certificate chain that certifies the |
| * attestationKeyBlob. This certificate is expected to have been remotely provisioned |
| * by a trusted authority. This parameter must contain a concatenated chain of DER-encoded |
| * X.509 certificates. The certificates must be ordered such that the attestation key |
| * certificate is first (starting at byte 0). The issuer certificate for the attestation |
| * certificate immediately follows, continuing this chain to the final, root certificate. |
| * |
| * @see getAttestationCertificate |
| * @see android.hardware.identity.ICredentialStore#getRemotelyProvisionedComponent |
| */ |
| void setRemotelyProvisionedAttestationKey( |
| in byte[] attestationKeyBlob, in byte[] attestationCertificate); |
| } |
