12eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root/* 22eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * Copyright (C) 2013 The Android Open Source Project 32eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * 42eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * Licensed under the Apache License, Version 2.0 (the "License"); 52eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * you may not use this file except in compliance with the License. 62eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * You may obtain a copy of the License at 72eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * 82eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * http://www.apache.org/licenses/LICENSE-2.0 92eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * 102eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * Unless required by applicable law or agreed to in writing, software 112eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * distributed under the License is distributed on an "AS IS" BASIS, 122eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 132eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * See the License for the specific language governing permissions and 142eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * limitations under the License. 152eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root */ 162eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 172eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Rootpackage android.security; 182eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 192eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Rootimport android.content.Context; 202eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 212eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Rootimport java.security.KeyPairGenerator; 222eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Rootimport java.security.KeyStore.ProtectionParameter; 232eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 242eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root/** 252eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * This provides the optional parameters that can be specified for 261c219f619291ba818bc2542390a2988539d94ed0Kenny Root * {@code KeyStore} entries that work with 27716cc7dcac1bb9279326ab92a78a246b3a70de4eRobert Ly * <a href="{@docRoot}training/articles/keystore.html">Android KeyStore 281c219f619291ba818bc2542390a2988539d94ed0Kenny Root * facility</a>. The Android KeyStore facility is accessed through a 292eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * {@link java.security.KeyStore} API using the {@code AndroidKeyStore} 302eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * provider. The {@code context} passed in may be used to pop up some UI to ask 312eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * the user to unlock or initialize the Android KeyStore facility. 322eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * <p> 332eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * Any entries placed in the {@code KeyStore} may be retrieved later. Note that 342eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * there is only one logical instance of the {@code KeyStore} per application 352eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * UID so apps using the {@code sharedUid} facility will also share a 362eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * {@code KeyStore}. 372eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * <p> 382eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * Keys may be generated using the {@link KeyPairGenerator} facility with a 391c219f619291ba818bc2542390a2988539d94ed0Kenny Root * {@link KeyPairGeneratorSpec} to specify the entry's {@code alias}. A 402eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * self-signed X.509 certificate will be attached to generated entries, but that 412eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * may be replaced at a later time by a certificate signed by a real Certificate 422eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * Authority. 432eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root */ 441c219f619291ba818bc2542390a2988539d94ed0Kenny Rootpublic final class KeyStoreParameter implements ProtectionParameter { 452eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root private int mFlags; 462eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 471c219f619291ba818bc2542390a2988539d94ed0Kenny Root private KeyStoreParameter(int flags) { 482eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root mFlags = flags; 492eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root } 502eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 512eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root /** 522eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * @hide 532eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root */ 542eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root public int getFlags() { 552eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root return mFlags; 562eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root } 572eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 582eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root /** 592eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * Returns {@code true} if this parameter requires entries to be encrypted 602eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * on the disk. 612eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root */ 622eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root public boolean isEncryptionRequired() { 632eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root return (mFlags & KeyStore.FLAG_ENCRYPTED) != 0; 642eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root } 652eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 662eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root /** 671c219f619291ba818bc2542390a2988539d94ed0Kenny Root * Builder class for {@link KeyStoreParameter} objects. 682eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * <p> 691c219f619291ba818bc2542390a2988539d94ed0Kenny Root * This will build protection parameters for use with the 70716cc7dcac1bb9279326ab92a78a246b3a70de4eRobert Ly * <a href="{@docRoot}training/articles/keystore.html">Android KeyStore 712eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * facility</a>. 722eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * <p> 732eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * This can be used to require that KeyStore entries be stored encrypted. 742eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * <p> 752eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * Example: 762eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * 772eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * <pre class="prettyprint"> 781c219f619291ba818bc2542390a2988539d94ed0Kenny Root * KeyStoreParameter params = new KeyStoreParameter.Builder(mContext) 791c219f619291ba818bc2542390a2988539d94ed0Kenny Root * .setEncryptionRequired() 801c219f619291ba818bc2542390a2988539d94ed0Kenny Root * .build(); 812eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * </pre> 822eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root */ 832eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root public final static class Builder { 842eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root private int mFlags; 852eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 862eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root /** 872eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * Creates a new instance of the {@code Builder} with the given 882eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * {@code context}. The {@code context} passed in may be used to pop up 892eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * some UI to ask the user to unlock or initialize the Android KeyStore 902eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * facility. 912eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root */ 922eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root public Builder(Context context) { 932eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root if (context == null) { 942eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root throw new NullPointerException("context == null"); 952eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root } 962eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 972eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root // Context is currently not used, but will be in the future. 982eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root } 992eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 1002eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root /** 1012eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * Indicates that this key must be encrypted at rest on storage. Note 1022eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * that enabling this will require that the user enable a strong lock 1032eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * screen (e.g., PIN, password) before creating or using the generated 1042eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * key is successful. 1052eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root */ 1061c219f619291ba818bc2542390a2988539d94ed0Kenny Root public Builder setEncryptionRequired(boolean required) { 1071c219f619291ba818bc2542390a2988539d94ed0Kenny Root if (required) { 1081c219f619291ba818bc2542390a2988539d94ed0Kenny Root mFlags |= KeyStore.FLAG_ENCRYPTED; 1091c219f619291ba818bc2542390a2988539d94ed0Kenny Root } else { 1101c219f619291ba818bc2542390a2988539d94ed0Kenny Root mFlags &= ~KeyStore.FLAG_ENCRYPTED; 1111c219f619291ba818bc2542390a2988539d94ed0Kenny Root } 1122eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root return this; 1132eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root } 1142eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root 1152eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root /** 1161c219f619291ba818bc2542390a2988539d94ed0Kenny Root * Builds the instance of the {@code KeyPairGeneratorSpec}. 1172eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * 1182eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root * @throws IllegalArgumentException if a required field is missing 1191c219f619291ba818bc2542390a2988539d94ed0Kenny Root * @return built instance of {@code KeyPairGeneratorSpec} 1202eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root */ 1211c219f619291ba818bc2542390a2988539d94ed0Kenny Root public KeyStoreParameter build() { 1221c219f619291ba818bc2542390a2988539d94ed0Kenny Root return new KeyStoreParameter(mFlags); 1232eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root } 1242eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root } 1252eeda7286f3c7cb79f7eb71ae6464cad213d12a3Kenny Root} 126