1 /*
2  * Copyright 2019 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.security.identity;
18 
19 import android.annotation.NonNull;
20 
21 import java.security.cert.X509Certificate;
22 import java.util.Collection;
23 
24 /**
25  * Class used to personalize a new identity credential.
26  *
27  * <p>Credentials cannot be updated or modified after creation; any changes require deletion and
28  * re-creation.
29  *
30  * Use {@link IdentityCredentialStore#createCredential(String, String)} to create a new credential.
31  */
32 public abstract class WritableIdentityCredential {
33     /**
34      * @hide
35      */
WritableIdentityCredential()36     protected WritableIdentityCredential() {}
37 
38     /**
39      * Generates and returns an X.509 certificate chain for the CredentialKey which identifies this
40      * credential to the issuing authority. The certificate contains an
41      * <a href="https://source.android.com/security/keystore/attestation">Android Keystore</a>
42      * attestation extension which describes the key and the security hardware in which it lives.
43      *
44      * <p>Additionally, the attestation extension will contain the tag Tag::IDENTITY_CREDENTIAL_KEY
45      * which indicates it is an Identity Credential key (which can only sign/MAC very specific
46      * messages) and not an Android Keystore key (which can be used to sign/MAC anything).
47      *
48      * <p>The issuer <b>MUST</b> carefully examine this certificate chain including (but not
49      * limited to) checking that the root certificate is well-known, the tag
50      * Tag::IDENTITY_CREDENTIAL_KEY present, the passed in challenge is present, the tag
51      * Tag::ATTESTATION_APPLICATION_ID is set to the expected Android application, the device
52      * has verified boot enabled, each certificate in the chain is signed by its successor,
53      * none of the certificates have been revoked, and so on.
54      *
55      * <p>It is not strictly necessary to use this method to provision a credential if the issuing
56      * authority doesn't care about the nature of the security hardware. If called, however, this
57      * method must be called before {@link #personalize(PersonalizationData)}.
58      *
59      * @param challenge is a non-empty byte array whose contents should be unique, fresh and
60      *                  provided by the issuing authority. The value provided is embedded in the
61      *                  attestation extension and enables the issuing authority to verify that the
62      *                  attestation certificate is fresh. Implementations are required to support
63      *                  challenges at least 32 bytes of length.
64      * @return the X.509 certificate for this credential's CredentialKey.
65      */
getCredentialKeyCertificateChain( @onNull byte[] challenge)66     public abstract @NonNull Collection<X509Certificate> getCredentialKeyCertificateChain(
67             @NonNull byte[] challenge);
68 
69     /**
70      * Stores all of the data in the credential, with the specified access control profiles.
71      *
72      * <p>This method returns a COSE_Sign1 data structure signed by the CredentialKey with payload
73      * set to {@code ProofOfProvisioning} as defined below.
74      *
75      * <pre>
76      *     ProofOfProvisioning = [
77      *          "ProofOfProvisioning",        ; tstr
78      *          tstr,                         ; DocType
79      *          [ * AccessControlProfile ],
80      *          ProvisionedData,
81      *          bool                          ; true if this is a test credential, should
82      *                                        ; always be false.
83      *      ]
84      *
85      *      AccessControlProfile = {
86      *          "id": uint,
87      *          ? "readerCertificate" : bstr,
88      *          ? (
89      *               "userAuthenticationRequired" : bool,
90      *               "timeoutMillis" : uint,
91      *          )
92      *      }
93      *
94      *      ProvisionedData = {
95      *          * Namespace =&gt; [ + Entry ]
96      *      },
97      *
98      *      Namespace = tstr
99      *
100      *      Entry = {
101      *          "name" : tstr,
102      *          "value" : any,
103      *          "accessControlProfiles" : [ * uint ],
104      *      }
105      * </pre>
106      *
107      * <p>This data structure provides a guarantee to the issuer about the data which may be
108      * returned in the CBOR returned by
109      * {@link ResultData#getAuthenticatedData()} during a credential
110      * presentation.
111      *
112      * @param personalizationData   The data to provision, including access control profiles
113      *                              and data elements and their values, grouped into namespaces.
114      * @return A COSE_Sign1 data structure, see above.
115      */
personalize( @onNull PersonalizationData personalizationData)116     public abstract @NonNull byte[] personalize(
117             @NonNull PersonalizationData personalizationData);
118 }
119