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.
63      * @return the X.509 certificate for this credential's CredentialKey.
64      */
getCredentialKeyCertificateChain( @onNull byte[] challenge)65     public abstract @NonNull Collection<X509Certificate> getCredentialKeyCertificateChain(
66             @NonNull byte[] challenge);
67 
68     /**
69      * Stores all of the data in the credential, with the specified access control profiles.
70      *
71      * <p>This method returns a COSE_Sign1 data structure signed by the CredentialKey with payload
72      * set to {@code ProofOfProvisioning} as defined below.
73      *
74      * <pre>
75      *     ProofOfProvisioning = [
76      *          "ProofOfProvisioning",        ; tstr
77      *          tstr,                         ; DocType
78      *          [ * AccessControlProfile ],
79      *          ProvisionedData,
80      *          bool                          ; true if this is a test credential, should
81      *                                        ; always be false.
82      *      ]
83      *
84      *      AccessControlProfile = {
85      *          "id": uint,
86      *          ? "readerCertificate" : bstr,
87      *          ? (
88      *               "userAuthenticationRequired" : bool,
89      *               "timeoutMillis" : uint,
90      *          )
91      *      }
92      *
93      *      ProvisionedData = {
94      *          * Namespace =&gt; [ + Entry ]
95      *      },
96      *
97      *      Namespace = tstr
98      *
99      *      Entry = {
100      *          "name" : tstr,
101      *          "value" : any,
102      *          "accessControlProfiles" : [ * uint ],
103      *      }
104      * </pre>
105      *
106      * <p>This data structure provides a guarantee to the issuer about the data which may be
107      * returned in the CBOR returned by
108      * {@link ResultData#getAuthenticatedData()} during a credential
109      * presentation.
110      *
111      * @param personalizationData   The data to provision, including access control profiles
112      *                              and data elements and their values, grouped into namespaces.
113      * @return A COSE_Sign1 data structure, see above.
114      */
personalize( @onNull PersonalizationData personalizationData)115     public abstract @NonNull byte[] personalize(
116             @NonNull PersonalizationData personalizationData);
117 }
118