identity/1.0/IIdentityCredentialStore.hal

/*
 * 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@1.0;

import IWritableIdentityCredential;
import IIdentityCredential;

/**
 * IIdentityCredentialStore provides an interface to a secure store for user identity documents.
 * This HAL is deliberately fairly general and abstract.  To the extent possible, specification of
 * the message formats and semantics of communication with credential verification devices and
 * issuing authorities (IAs) is out of scope for this HAL.  It provides the interface with secure
 * storage but a credential-specific Android application will be required to implement the
 * presentation and verification protocols and processes appropriate for the specific credential
 * type.
 *
 * The design of this HAL makes few assumptions about the underlying secure hardware.  In particular
 * it does not assume that the secure hardware has any storage beyond that needed for a persistent,
 * hardware-bound AES-128 key.  However, its design allows the use of secure hardware that does have
 * storage, specifically to enable "direct access".  Most often credentials will be accessed through
 * this HAL and through the Android layers above it but that requires that the Android device be
 * powered up and fully functional.  It is desirable to allow identity credential usage when the
 * Android device's battery is too low to boot the Android operating system, so direct access to the
 * secure hardware via NFC may allow data retrieval, if the secure hardware chooses to implement it.
 * Definition of how data is retrieved in low power mode is explicitly out of scope for this HAL
 * specification; it's up to the relevant identity credential standards to define.
 *
 * The 'default' HAL instance is explicitly not for direct access and the 'direct_access' HAL
 * instance - if available - is for direct access. Applications are expected to provision their
 * credential to both instances (and the contents may differ), not just one of them.
 *
 * Multiple credentials can be created.  Each credential comprises:
 *
 * - A document type, which is a UTF-8 string of at most 256 bytes.
 *
 * - A set of namespaces, which serve to disambiguate value names.  Namespaces are UTF-8 strings of
 *   up to 256 bytes in length (most should be much shorter).  It is recommended that namespaces be
 *   structured as reverse domain names so that IANA effectively serves as the namespace registrar.
 *
 * - For each namespase, a set of name/value pairs, each with an associated set of access control
 *   profile IDs.  Names are UTF-8 strings of up to 256 bytes in length (most should be much
 *   shorter).  Values stored must be encoed as valid CBOR (https://tools.ietf.org/html/rfc7049) and
 *   the encoeded size is is limited to at most 512 KiB.
 *
 * - A set of access control profiles, each with a profile ID and a specification of the
 *   conditions which satisfy the profile's requirements.
 *
 * - An asymmetric key pair which is used to authenticate the credential to the IA, called the
 *   CredentialKey. This key is attested to by the secure hardware using Android Keystore
 *   attestation (https://source.android.com/security/keystore/attestation). See
 *   getAttestationCertificate() in the IWritableIdentityCredential for more information.
 *
 * - A set of zero or more named reader authentication public keys, which are used to authenticate
 *   an authorized reader to the credential.
 *
 * - A set of named signing keys, which are used to sign collections of values and session
 *   transcripts.
 *
 * Cryptographic notation:
 *
 * Throughout this HAL, cryptographic operations are specified in detail.  To avoid repeating the
 * definition of the notation, it's specified here.  It is assumed that the reader is familiar with
 * standard cryptographic algorithms and constructs.
 *
 *     AES-GCM-ENC(K, N, D, A) represents AES-GCM encryption with key 'K', nonce 'N', additional
 *         authenticated data 'A' and data 'D'.  The nonce is usually specified as 'R', meaning 12
 *         random bytes.  The nonce is always 12 bytes and is prepended to the ciphertext. The GCM
 *         tag is 16 bytes, appended to the ciphertext.  AES-GCM-DEC with the same argument notation
 *         represents the corresponding decryption operation.
 *
 *    ECDSA(K, D) represents ECDSA signing of data 'D' with key 'K'.
 *
 *    || represents concatenation
 *
 *    {} represents an empty input; 0 bytes of data.
 *
 *    HBK represents a device-unique, hardware-bound AES-128 key which exists only in secure
 *        hardware, except for "test" credential stores (see createCredential(), below).  For test
 *        stores, an all-zero value is used in place of the HBK.
 *
 * Data encoding notation:
 *
 * Various fields need to be encoded as precisely-specified byte arrays.  Where existing standards
 * define appropriate encodings, those are used.  For example, X.509 certificates.  Where new
 * encodings are needed, CBOR is used.  CBOR maps are described in CDDL notation
 * (https://tools.ietf.org/html/draft-ietf-cbor-cddl-06).
 */
interface IIdentityCredentialStore {

    /**
     * Returns information about hardware.
     *
     * The isDirectAccess output parameter indicates whether this credential store
     * implementation is for direct access. Credentials provisioned in credential
     * stores with this set to true, should use reader authentication on all data elements.
     *
     * @return result is OK on success, FAILED if an error occurred.
     *
     * @return credentialStoreName the name of the credential store implementation.
     *
     * @return credentialStoreAuthorName the name of the credential store author.
     *
     * @return dataChunkSize the maximum size of data chunks.
     *
     * @return isDirectAccess whether the provisioned credential is available through
     *     direct access.
     *
     * @return supportedDocTypes if empty, then any document type is supported, otherwise
     *     only the document types returned are supported.
     */
    getHardwareInformation()
        generates(Result result,
                  string credentialStoreName,
                  string credentialStoreAuthorName,
                  uint32_t dataChunkSize,
                  bool isDirectAccess,
                  vec<string> supportedDocTypes);

    /**
     * createCredential creates a new Credential.  When a Credential is created, two cryptographic
     * keys are created: StorageKey, an AES key used to secure the externalized Credential
     * contents, and CredentialKeyPair, an EC key pair used to authenticate the store to the IA.  In
     * addition, all of the Credential data content is imported and a certificate for the
     * CredentialKeyPair and a signature produced with the CredentialKeyPair are created.  These
     * latter values may be checked by an issuing authority to verify that the data was imported
     * into secure hardware and that it was imported unmodified.
     *
     * @param docType is an optional name (may be an empty string) that identifies the type of
     *     credential being created, e.g. "org.iso.18013-5.2019.mdl" (the doc type of the ISO
     *     driving license standard).
     *
     * @param testCredential indicates if this is a test store.  Test credentials must use an
     *     all-zeros hardware-bound key (HBK) and must set the test bit in the
     *     personalizationReceipt (see finishAddingEntries(), in IWritableIdentityCredential).
     *
     * @return result is OK on success, FAILED if an error occurred.
     *
     * @return writableCredential is an IWritableIdentityCredential HIDL interface that provides
     *     operations to provision a credential.
     */
    createCredential(string docType, bool testCredential)
        generates(Result result, IWritableIdentityCredential writableCredential);

    /**
     * getCredential retrieves an IIdentityCredential HIDL interface which allows use of a stored
     * Credential.
     *
     * The cipher suite used to communicate with the remote verifier must also be specified. Currently
     * only a single cipher-suite is supported and the details of this are as follow:
     *
     *  - ECDHE with HKDF-SHA-256 for key agreement.
     *  - AES-256 with GCM block mode for authenticated encryption (nonces are incremented by one
     *    for every message).
     *  - ECDSA with SHA-256 for signing (used for signing session transcripts to defeat
     *    man-in-the-middle attacks), signing keys are not ephemeral.
     *
     * Support for other cipher suites may be added in a future version of this HAL.
     *
     * @param credentialData is a CBOR-encoded structure containing metadata about the credential
     *     and an encrypted byte array that contains data used to secure the credential.  See the
     *     return argument of the same name in finishAddingEntries(), in IWritableIdentityCredential.
     *
     * @return result is OK on success or INVALID_DATA if the passed in credentialData
     *     cannot be decoded or decrypted.
     *
     * @return credential is an IIdentityCredential HIDL interface that provides operations on the
     *     Credential.
     */
    getCredential(vec<uint8_t> credentialData)
        generates (Result result, IIdentityCredential credential);
};