Home | History | Annotate | Download | only in security 
      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.content.Context;
     20 import android.security.KeyPairGeneratorSpec.Builder;
     21 
     22 import java.security.KeyPairGenerator;
     23 import java.security.PrivateKey;
     24 import java.security.KeyStore.ProtectionParameter;
     25 import java.security.cert.Certificate;
     26 
     27 /**
     28  * This provides the optional parameters that can be specified for
     29  * {@code KeyStore} entries that work with
     30  * <a href="{@docRoot}guide/topics/security/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 public final class KeyStoreParameter implements ProtectionParameter {
     48     private int mFlags;
     49 
     50     private KeyStoreParameter(int flags) {
     51         mFlags = flags;
     52     }
     53 
     54     /**
     55      * @hide
     56      */
     57     public int getFlags() {
     58         return mFlags;
     59     }
     60 
     61     /**
     62      * Returns {@code true} if this parameter requires entries to be encrypted
     63      * on the disk.
     64      */
     65     public boolean isEncryptionRequired() {
     66         return (mFlags & KeyStore.FLAG_ENCRYPTED) != 0;
     67     }
     68 
     69     /**
     70      * Builder class for {@link KeyStoreParameter} objects.
     71      * <p>
     72      * This will build protection parameters for use with the
     73      * <a href="{@docRoot}guide/topics/security/keystore.html">Android KeyStore
     74      * facility</a>.
     75      * <p>
     76      * This can be used to require that KeyStore entries be stored encrypted.
     77      * <p>
     78      * Example:
     79      *
     80      * <pre class="prettyprint">
     81      * KeyStoreParameter params = new KeyStoreParameter.Builder(mContext)
     82      *         .setEncryptionRequired()
     83      *         .build();
     84      * </pre>
     85      */
     86     public final static class Builder {
     87         private int mFlags;
     88 
     89         /**
     90          * Creates a new instance of the {@code Builder} with the given
     91          * {@code context}. The {@code context} passed in may be used to pop up
     92          * some UI to ask the user to unlock or initialize the Android KeyStore
     93          * facility.
     94          */
     95         public Builder(Context context) {
     96             if (context == null) {
     97                 throw new NullPointerException("context == null");
     98             }
     99 
    100             // Context is currently not used, but will be in the future.
    101         }
    102 
    103         /**
    104          * Indicates that this key must be encrypted at rest on storage. Note
    105          * that enabling this will require that the user enable a strong lock
    106          * screen (e.g., PIN, password) before creating or using the generated
    107          * key is successful.
    108          */
    109         public Builder setEncryptionRequired(boolean required) {
    110             if (required) {
    111                 mFlags |= KeyStore.FLAG_ENCRYPTED;
    112             } else {
    113                 mFlags &= ~KeyStore.FLAG_ENCRYPTED;
    114             }
    115             return this;
    116         }
    117 
    118         /**
    119          * Builds the instance of the {@code KeyPairGeneratorSpec}.
    120          *
    121          * @throws IllegalArgumentException if a required field is missing
    122          * @return built instance of {@code KeyPairGeneratorSpec}
    123          */
    124         public KeyStoreParameter build() {
    125             return new KeyStoreParameter(mFlags);
    126         }
    127     }
    128 }
    129