1 /*
2  * Copyright 2020 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 
23 /**
24  * A class used to specify access controls.
25  */
26 public class AccessControlProfile {
27     private AccessControlProfileId mAccessControlProfileId = new AccessControlProfileId(0);
28     private X509Certificate mReaderCertificate = null;
29     private boolean mUserAuthenticationRequired = true;
30     private long mUserAuthenticationTimeout = 0;
31 
AccessControlProfile()32     private AccessControlProfile() {
33     }
34 
getAccessControlProfileId()35     AccessControlProfileId getAccessControlProfileId() {
36         return mAccessControlProfileId;
37     }
38 
getUserAuthenticationTimeout()39     long getUserAuthenticationTimeout() {
40         return mUserAuthenticationTimeout;
41     }
42 
isUserAuthenticationRequired()43     boolean isUserAuthenticationRequired() {
44         return mUserAuthenticationRequired;
45     }
46 
getReaderCertificate()47     X509Certificate getReaderCertificate() {
48         return mReaderCertificate;
49     }
50 
51     /**
52      * A builder for {@link AccessControlProfile}.
53      */
54     public static final class Builder {
55         private AccessControlProfile mProfile;
56 
57         /**
58          * Each access control profile has numeric identifier that must be unique within the
59          * context of a Credential and may be used to reference the profile.
60          *
61          * <p>By default, the resulting {@link AccessControlProfile} will require user
62          * authentication with a timeout of zero, thus requiring the holder to authenticate for
63          * every presentation where data elements using this access control profile is used.</p>
64          *
65          * @param accessControlProfileId the access control profile identifier.
66          */
Builder(@onNull AccessControlProfileId accessControlProfileId)67         public Builder(@NonNull AccessControlProfileId accessControlProfileId) {
68             mProfile = new AccessControlProfile();
69             mProfile.mAccessControlProfileId = accessControlProfileId;
70         }
71 
72         /**
73          * Set whether user authentication is required.
74          *
75          * <p>This should be used sparingly since disabling user authentication on just a single
76          * data element can easily create a
77          * <a href="https://en.wikipedia.org/wiki/Relay_attack">Relay Attack</a> if the device
78          * on which the credential is stored is compromised.</p>
79          *
80          * @param userAuthenticationRequired Set to true if user authentication is required,
81          *                                   false otherwise.
82          * @return The builder.
83          */
setUserAuthenticationRequired(boolean userAuthenticationRequired)84         public @NonNull Builder setUserAuthenticationRequired(boolean userAuthenticationRequired) {
85             mProfile.mUserAuthenticationRequired = userAuthenticationRequired;
86             return this;
87         }
88 
89         /**
90          * Sets the authentication timeout to use.
91          *
92          * <p>The authentication timeout specifies the amount of time, in milliseconds, for which a
93          * user authentication is valid, if user authentication is required (see
94          * {@link #setUserAuthenticationRequired(boolean)}).</p>
95          *
96          * <p>If the timeout is zero, then authentication is always required for each reader
97          * session.</p>
98          *
99          * @param userAuthenticationTimeoutMillis the authentication timeout, in milliseconds.
100          * @return The builder.
101          */
setUserAuthenticationTimeout(long userAuthenticationTimeoutMillis)102         public @NonNull Builder setUserAuthenticationTimeout(long userAuthenticationTimeoutMillis) {
103             mProfile.mUserAuthenticationTimeout = userAuthenticationTimeoutMillis;
104             return this;
105         }
106 
107         /**
108          * Sets the reader certificate to use when checking access control.
109          *
110          * <p>If set, this is checked against the certificate chain presented by
111          * reader. The access check is fulfilled only if one of the certificates
112          * in the chain, matches the certificate set by this method.</p>
113          *
114          * @param readerCertificate the certificate to use for the access control check.
115          * @return The builder.
116          */
setReaderCertificate(@onNull X509Certificate readerCertificate)117         public @NonNull Builder setReaderCertificate(@NonNull X509Certificate readerCertificate) {
118             mProfile.mReaderCertificate = readerCertificate;
119             return this;
120         }
121 
122         /**
123          * Creates a new {@link AccessControlProfile} from the data supplied to the builder.
124          *
125          * @return The created {@link AccessControlProfile} object.
126          */
build()127         public @NonNull AccessControlProfile build() {
128             return mProfile;
129         }
130     }
131 }
132