1 /*
2  * Copyright (C) 2013 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;
18 
19 import android.annotation.NonNull;
20 import android.app.KeyguardManager;
21 import android.content.Context;
22 import android.security.keystore.KeyProtection;
23 
24 import java.security.KeyPairGenerator;
25 import java.security.KeyStore.ProtectionParameter;
26 
27 /**
28  * This provides the optional parameters that can be specified for
29  * {@code KeyStore} entries that work with
30  * <a href="{@docRoot}training/articles/keystore.html">Android KeyStore
31  * facility</a>. The Android KeyStore facility is accessed through a
32  * {@link java.security.KeyStore} API using the {@code AndroidKeyStore}
33  * provider. The {@code context} passed in may be used to pop up some UI to ask
34  * the user to unlock or initialize the Android KeyStore facility.
35  * <p>
36  * Any entries placed in the {@code KeyStore} may be retrieved later. Note that
37  * there is only one logical instance of the {@code KeyStore} per application
38  * UID so apps using the {@code sharedUid} facility will also share a
39  * {@code KeyStore}.
40  * <p>
41  * Keys may be generated using the {@link KeyPairGenerator} facility with a
42  * {@link KeyPairGeneratorSpec} to specify the entry's {@code alias}. A
43  * self-signed X.509 certificate will be attached to generated entries, but that
44  * may be replaced at a later time by a certificate signed by a real Certificate
45  * Authority.
46  *
47  * @deprecated Use {@link KeyProtection} instead.
48  */
49 @Deprecated
50 public final class KeyStoreParameter implements ProtectionParameter {
51     private final int mFlags;
52 
KeyStoreParameter( int flags)53     private KeyStoreParameter(
54             int flags) {
55         mFlags = flags;
56     }
57 
58     /**
59      * @hide
60      */
getFlags()61     public int getFlags() {
62         return mFlags;
63     }
64 
65     /**
66      * Returns {@code true} if the {@link java.security.KeyStore} entry must be encrypted at rest.
67      * This will protect the entry with the secure lock screen credential (e.g., password, PIN, or
68      * pattern).
69      *
70      * <p>Note that encrypting the key at rest requires that the secure lock screen (e.g., password,
71      * PIN, pattern) is set up, otherwise key generation will fail. Moreover, this key will be
72      * deleted when the secure lock screen is disabled or reset (e.g., by the user or a Device
73      * Administrator). Finally, this key cannot be used until the user unlocks the secure lock
74      * screen after boot.
75      *
76      * @see KeyguardManager#isDeviceSecure()
77      */
isEncryptionRequired()78     public boolean isEncryptionRequired() {
79         return (mFlags & KeyStore.FLAG_ENCRYPTED) != 0;
80     }
81 
82     /**
83      * Builder class for {@link KeyStoreParameter} objects.
84      * <p>
85      * This will build protection parameters for use with the
86      * <a href="{@docRoot}training/articles/keystore.html">Android KeyStore
87      * facility</a>.
88      * <p>
89      * This can be used to require that KeyStore entries be stored encrypted.
90      * <p>
91      * Example:
92      *
93      * <pre class="prettyprint">
94      * KeyStoreParameter params = new KeyStoreParameter.Builder(mContext)
95      *         .setEncryptionRequired()
96      *         .build();
97      * </pre>
98      *
99      *  @deprecated Use {@link KeyProtection.Builder} instead.
100      */
101     @Deprecated
102     public final static class Builder {
103         private int mFlags;
104 
105         /**
106          * Creates a new instance of the {@code Builder} with the given
107          * {@code context}. The {@code context} passed in may be used to pop up
108          * some UI to ask the user to unlock or initialize the Android KeyStore
109          * facility.
110          */
Builder(@onNull Context context)111         public Builder(@NonNull Context context) {
112             if (context == null) {
113                 throw new NullPointerException("context == null");
114             }
115         }
116 
117         /**
118          * Sets whether this {@link java.security.KeyStore} entry must be encrypted at rest.
119          * Encryption at rest will protect the entry with the secure lock screen credential (e.g.,
120          * password, PIN, or pattern).
121          *
122          * <p>Note that enabling this feature requires that the secure lock screen (e.g., password,
123          * PIN, pattern) is set up, otherwise setting the {@code KeyStore} entry will fail.
124          * Moreover, this entry will be deleted when the secure lock screen is disabled or reset
125          * (e.g., by the user or a Device Administrator). Finally, this entry cannot be used until
126          * the user unlocks the secure lock screen after boot.
127          *
128          * @see KeyguardManager#isDeviceSecure()
129          */
130         @NonNull
setEncryptionRequired(boolean required)131         public Builder setEncryptionRequired(boolean required) {
132             if (required) {
133                 mFlags |= KeyStore.FLAG_ENCRYPTED;
134             } else {
135                 mFlags &= ~KeyStore.FLAG_ENCRYPTED;
136             }
137             return this;
138         }
139 
140         /**
141          * Builds the instance of the {@code KeyStoreParameter}.
142          *
143          * @throws IllegalArgumentException if a required field is missing
144          * @return built instance of {@code KeyStoreParameter}
145          */
146         @NonNull
build()147         public KeyStoreParameter build() {
148             return new KeyStoreParameter(
149                     mFlags);
150         }
151     }
152 }
153