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.annotation.NonNull;
20import android.app.KeyguardManager;
21import android.content.Context;
22import android.security.keystore.KeyProtection;
23
24import java.security.KeyPairGenerator;
25import 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
50public 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