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
17package android.security;
18
19import android.content.Context;
20import android.security.KeyPairGeneratorSpec.Builder;
21
22import java.security.KeyPairGenerator;
23import java.security.PrivateKey;
24import java.security.KeyStore.ProtectionParameter;
25import 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 */
47public 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