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 53 private KeyStoreParameter( 54 int flags) { 55 mFlags = flags; 56 } 57 58 /** 59 * @hide 60 */ 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 */ 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 */ 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 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 147 public KeyStoreParameter build() { 148 return new KeyStoreParameter( 149 mFlags); 150 } 151 } 152 } 153
