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 KeyStoreParameter( int flags)52 private KeyStoreParameter( 53 int flags) { 54 } 55 56 /** 57 * @hide 58 */ getFlags()59 public int getFlags() { 60 return 0; 61 } 62 63 /** 64 * Returns {@code true} if the {@link java.security.KeyStore} entry must be encrypted at rest. 65 * This will protect the entry with the secure lock screen credential (e.g., password, PIN, or 66 * pattern). 67 * 68 * <p>Note that encrypting the key at rest requires that the secure lock screen (e.g., password, 69 * PIN, pattern) is set up, otherwise key generation will fail. Moreover, this key will be 70 * deleted when the secure lock screen is disabled or reset (e.g., by the user or a Device 71 * Administrator). Finally, this key cannot be used until the user unlocks the secure lock 72 * screen after boot. 73 * 74 * @see KeyguardManager#isDeviceSecure() 75 * 76 * @deprecated Data at rest encryption is enabled by default. If extra binding to the 77 * lockscreen credential is desired, use 78 * {@link android.security.keystore.KeyGenParameterSpec 79 * .Builder#setUserAuthenticationRequired(boolean)}. 80 * This flag will be ignored from Android S. 81 */ 82 @Deprecated isEncryptionRequired()83 public boolean isEncryptionRequired() { 84 return false; 85 } 86 87 /** 88 * Builder class for {@link KeyStoreParameter} objects. 89 * <p> 90 * This will build protection parameters for use with the 91 * <a href="{@docRoot}training/articles/keystore.html">Android KeyStore 92 * facility</a>. 93 * <p> 94 * This can be used to require that KeyStore entries be stored encrypted. 95 * <p> 96 * Example: 97 * 98 * <pre class="prettyprint"> 99 * KeyStoreParameter params = new KeyStoreParameter.Builder(mContext) 100 * .setEncryptionRequired() 101 * .build(); 102 * </pre> 103 * 104 * @deprecated Use {@link KeyProtection.Builder} instead. 105 */ 106 @Deprecated 107 public final static class Builder { 108 109 /** 110 * Creates a new instance of the {@code Builder} with the given 111 * {@code context}. The {@code context} passed in may be used to pop up 112 * some UI to ask the user to unlock or initialize the Android KeyStore 113 * facility. 114 */ Builder(@onNull Context context)115 public Builder(@NonNull Context context) { 116 if (context == null) { 117 throw new NullPointerException("context == null"); 118 } 119 } 120 121 /** 122 * Sets whether this {@link java.security.KeyStore} entry must be encrypted at rest. 123 * Encryption at rest will protect the entry with the secure lock screen credential (e.g., 124 * password, PIN, or pattern). 125 * 126 * <p>Note that enabling this feature requires that the secure lock screen (e.g., password, 127 * PIN, pattern) is set up, otherwise setting the {@code KeyStore} entry will fail. 128 * Moreover, this entry will be deleted when the secure lock screen is disabled or reset 129 * (e.g., by the user or a Device Administrator). Finally, this entry cannot be used until 130 * the user unlocks the secure lock screen after boot. 131 * 132 * @see KeyguardManager#isDeviceSecure() 133 * 134 * @deprecated Data at rest encryption is enabled by default. If extra binding to the 135 * lockscreen credential is desired, use 136 * {@link android.security.keystore.KeyGenParameterSpec 137 * .Builder#setUserAuthenticationRequired(boolean)}. 138 * This flag will be ignored from Android S. 139 */ 140 @NonNull setEncryptionRequired(boolean required)141 public Builder setEncryptionRequired(boolean required) { 142 return this; 143 } 144 145 /** 146 * Builds the instance of the {@code KeyStoreParameter}. 147 * 148 * @throws IllegalArgumentException if a required field is missing 149 * @return built instance of {@code KeyStoreParameter} 150 */ 151 @NonNull build()152 public KeyStoreParameter build() { 153 return new KeyStoreParameter(0 /* flags */); 154 } 155 } 156 } 157