Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 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 | |
Alex Klyubin | 54bb159 | 2015-05-11 12:30:03 -0700 | [diff] [blame] | 19 | import android.annotation.NonNull; |
Alex Klyubin | eedda45 | 2015-05-07 17:34:24 -0700 | [diff] [blame] | 20 | import android.app.KeyguardManager; |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 21 | import android.content.Context; |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 22 | import android.security.keystore.KeyProtection; |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 23 | |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 24 | import java.security.KeyPairGenerator; |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 25 | import java.security.KeyStore.ProtectionParameter; |
Alex Klyubin | f853f64 | 2015-04-08 13:36:22 -0700 | [diff] [blame] | 26 | |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 27 | /** |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 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. |
Alex Klyubin | eedda45 | 2015-05-07 17:34:24 -0700 | [diff] [blame] | 46 | * |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 47 | * @deprecated Use {@link KeyProtection} instead. |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 48 | */ |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 49 | @Deprecated |
Kenny Root | 1c219f6 | 2013-04-18 17:57:03 -0700 | [diff] [blame] | 50 | public final class KeyStoreParameter implements ProtectionParameter { |
Alex Klyubin | 1eda77a | 2015-04-28 14:21:01 -0700 | [diff] [blame] | 51 | private final int mFlags; |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 52 | |
Alex Klyubin | 1eda77a | 2015-04-28 14:21:01 -0700 | [diff] [blame] | 53 | private KeyStoreParameter( |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 54 | int flags) { |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 55 | mFlags = flags; |
Alex Klyubin | 1eda77a | 2015-04-28 14:21:01 -0700 | [diff] [blame] | 56 | } |
| 57 | |
| 58 | /** |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 59 | * @hide |
| 60 | */ |
| 61 | public int getFlags() { |
| 62 | return mFlags; |
| 63 | } |
| 64 | |
| 65 | /** |
Alex Klyubin | eedda45 | 2015-05-07 17:34:24 -0700 | [diff] [blame] | 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). |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 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() |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 77 | */ |
| 78 | public boolean isEncryptionRequired() { |
| 79 | return (mFlags & KeyStore.FLAG_ENCRYPTED) != 0; |
| 80 | } |
| 81 | |
| 82 | /** |
Kenny Root | 1c219f6 | 2013-04-18 17:57:03 -0700 | [diff] [blame] | 83 | * Builder class for {@link KeyStoreParameter} objects. |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 84 | * <p> |
Kenny Root | 1c219f6 | 2013-04-18 17:57:03 -0700 | [diff] [blame] | 85 | * This will build protection parameters for use with the |
Robert Ly | 716cc7d | 2014-05-07 21:16:15 -0700 | [diff] [blame] | 86 | * <a href="{@docRoot}training/articles/keystore.html">Android KeyStore |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 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"> |
Kenny Root | 1c219f6 | 2013-04-18 17:57:03 -0700 | [diff] [blame] | 94 | * KeyStoreParameter params = new KeyStoreParameter.Builder(mContext) |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 95 | * .setEncryptionRequired() |
Kenny Root | 1c219f6 | 2013-04-18 17:57:03 -0700 | [diff] [blame] | 96 | * .build(); |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 97 | * </pre> |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 98 | * |
| 99 | * @deprecated Use {@link KeyProtection.Builder} instead. |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 100 | */ |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 101 | @Deprecated |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 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 | */ |
Alex Klyubin | 54bb159 | 2015-05-11 12:30:03 -0700 | [diff] [blame] | 111 | public Builder(@NonNull Context context) { |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 112 | if (context == null) { |
| 113 | throw new NullPointerException("context == null"); |
| 114 | } |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 115 | } |
| 116 | |
| 117 | /** |
Alex Klyubin | 5418393 | 2015-05-08 15:25:48 -0700 | [diff] [blame] | 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). |
Alex Klyubin | eedda45 | 2015-05-07 17:34:24 -0700 | [diff] [blame] | 121 | * |
| 122 | * <p>Note that enabling this feature requires that the secure lock screen (e.g., password, |
Alex Klyubin | 5418393 | 2015-05-08 15:25:48 -0700 | [diff] [blame] | 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. |
Alex Klyubin | eedda45 | 2015-05-07 17:34:24 -0700 | [diff] [blame] | 127 | * |
| 128 | * @see KeyguardManager#isDeviceSecure() |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 129 | */ |
Alex Klyubin | 54bb159 | 2015-05-11 12:30:03 -0700 | [diff] [blame] | 130 | @NonNull |
Kenny Root | 1c219f6 | 2013-04-18 17:57:03 -0700 | [diff] [blame] | 131 | public Builder setEncryptionRequired(boolean required) { |
| 132 | if (required) { |
| 133 | mFlags |= KeyStore.FLAG_ENCRYPTED; |
| 134 | } else { |
| 135 | mFlags &= ~KeyStore.FLAG_ENCRYPTED; |
| 136 | } |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 137 | return this; |
| 138 | } |
| 139 | |
| 140 | /** |
Alex Klyubin | baf2838 | 2015-03-26 14:46:55 -0700 | [diff] [blame] | 141 | * Builds the instance of the {@code KeyStoreParameter}. |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 142 | * |
| 143 | * @throws IllegalArgumentException if a required field is missing |
Alex Klyubin | baf2838 | 2015-03-26 14:46:55 -0700 | [diff] [blame] | 144 | * @return built instance of {@code KeyStoreParameter} |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 145 | */ |
Alex Klyubin | 54bb159 | 2015-05-11 12:30:03 -0700 | [diff] [blame] | 146 | @NonNull |
Kenny Root | 1c219f6 | 2013-04-18 17:57:03 -0700 | [diff] [blame] | 147 | public KeyStoreParameter build() { |
Alex Klyubin | 1eda77a | 2015-04-28 14:21:01 -0700 | [diff] [blame] | 148 | return new KeyStoreParameter( |
Alex Klyubin | 3f8d4d8 | 2015-05-13 09:15:00 -0700 | [diff] [blame] | 149 | mFlags); |
Kenny Root | 2eeda72 | 2013-04-10 11:30:58 -0700 | [diff] [blame] | 150 | } |
| 151 | } |
| 152 | } |