/* * Copyright (C) 2015 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.security.keystore; import android.annotation.IntRange; import android.annotation.NonNull; import android.annotation.Nullable; import java.security.Key; import java.security.KeyStore.ProtectionParameter; import java.security.cert.Certificate; import java.util.Date; import javax.crypto.Cipher; /** * Specification of how a key or key pair is secured when imported into the * Android KeyStore facility. This class * specifies parameters such as whether user authentication is required for using the key, what uses * the key is authorized for (e.g., only in {@code CTR} mode, or only for signing -- decryption not * permitted), the key's and validity start and end dates. * *
To import a key or key pair into the Android KeyStore, create an instance of this class using * the {@link Builder} and pass the instance into {@link java.security.KeyStore#setEntry(String, java.security.KeyStore.Entry, ProtectionParameter) KeyStore.setEntry} * with the key or key pair being imported. * *
To obtain the secret/symmetric or private key from the Android KeyStore use * {@link java.security.KeyStore#getKey(String, char[]) KeyStore.getKey(String, null)} or * {@link java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter) KeyStore.getEntry(String, null)}. * To obtain the public key from the Android KeyStore use * {@link java.security.KeyStore#getCertificate(String)} and then * {@link Certificate#getPublicKey()}. * *
NOTE: The key material of keys stored in the Android KeyStore is not accessible. * *
Instances of this class are immutable. * *
{@code * SecretKey key = ...; // AES key * * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore"); * keyStore.load(null); * keyStore.setEntry( * "key1", * new KeyStore.SecretKeyEntry(key), * new KeyProtection.Builder(KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT) * .setBlockMode(KeyProperties.BLOCK_MODE_CBC) * .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7) * .build()); * // Key imported, obtain a reference to it. * SecretKey keyStoreKey = (SecretKey) keyStore.getKey("key1", null); * // The original key can now be thrown away. * }* *
{@code * PrivateKey privateKey = ...; // EC private key * Certificate[] certChain = ...; // Certificate chain with the first certificate * // containing the corresponding EC public key. * * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore"); * keyStore.load(null); * keyStore.setEntry( * "key2", * new KeyStore.PrivateKeyEntry(privateKey, certChain), * new KeyProtection.Builder(KeyProperties.PURPOSE_SIGN) * .setDigests(KeyProperties.DIGEST_SHA256) * // Only permit this key to be used if the user * // authenticated within the last ten minutes. * .setUserAuthenticationRequired(true) * .setUserAuthenticationValidityDurationSeconds(10 * 60) * .build()); * // Key pair imported, obtain a reference to it. * PrivateKey keyStorePrivateKey = (PrivateKey) keyStore.getKey("key2", null); * PublicKey publicKey = keyStore.getCertificate("key2").getPublicKey(); * // The original private key can now be thrown away. * }*/ public final class KeyProtection implements ProtectionParameter { private final Date mKeyValidityStart; private final Date mKeyValidityForOriginationEnd; private final Date mKeyValidityForConsumptionEnd; private final @KeyProperties.PurposeEnum int mPurposes; private final @KeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings; private final @KeyProperties.SignaturePaddingEnum String[] mSignaturePaddings; private final @KeyProperties.DigestEnum String[] mDigests; private final @KeyProperties.BlockModeEnum String[] mBlockModes; private final boolean mRandomizedEncryptionRequired; private final boolean mUserAuthenticationRequired; private final int mUserAuthenticationValidityDurationSeconds; private KeyProtection( Date keyValidityStart, Date keyValidityForOriginationEnd, Date keyValidityForConsumptionEnd, @KeyProperties.PurposeEnum int purposes, @KeyProperties.EncryptionPaddingEnum String[] encryptionPaddings, @KeyProperties.SignaturePaddingEnum String[] signaturePaddings, @KeyProperties.DigestEnum String[] digests, @KeyProperties.BlockModeEnum String[] blockModes, boolean randomizedEncryptionRequired, boolean userAuthenticationRequired, int userAuthenticationValidityDurationSeconds) { mKeyValidityStart = Utils.cloneIfNotNull(keyValidityStart); mKeyValidityForOriginationEnd = Utils.cloneIfNotNull(keyValidityForOriginationEnd); mKeyValidityForConsumptionEnd = Utils.cloneIfNotNull(keyValidityForConsumptionEnd); mPurposes = purposes; mEncryptionPaddings = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(encryptionPaddings)); mSignaturePaddings = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(signaturePaddings)); mDigests = ArrayUtils.cloneIfNotEmpty(digests); mBlockModes = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(blockModes)); mRandomizedEncryptionRequired = randomizedEncryptionRequired; mUserAuthenticationRequired = userAuthenticationRequired; mUserAuthenticationValidityDurationSeconds = userAuthenticationValidityDurationSeconds; } /** * Gets the time instant before which the key is not yet valid. * * @return instant or {@code null} if not restricted. */ @Nullable public Date getKeyValidityStart() { return Utils.cloneIfNotNull(mKeyValidityStart); } /** * Gets the time instant after which the key is no long valid for decryption and verification. * * @return instant or {@code null} if not restricted. */ @Nullable public Date getKeyValidityForConsumptionEnd() { return Utils.cloneIfNotNull(mKeyValidityForConsumptionEnd); } /** * Gets the time instant after which the key is no long valid for encryption and signing. * * @return instant or {@code null} if not restricted. */ @Nullable public Date getKeyValidityForOriginationEnd() { return Utils.cloneIfNotNull(mKeyValidityForOriginationEnd); } /** * Gets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used. * Attempts to use the key for any other purpose will be rejected. * *
See {@link KeyProperties}.{@code PURPOSE} flags. */ public @KeyProperties.PurposeEnum int getPurposes() { return mPurposes; } /** * Gets the set of padding schemes (e.g., {@code PKCS7Padding}, {@code PKCS1Padding}, * {@code NoPadding}) with which the key can be used when encrypting/decrypting. Attempts to use * the key with any other padding scheme will be rejected. * *
See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants. */ @NonNull public @KeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() { return ArrayUtils.cloneIfNotEmpty(mEncryptionPaddings); } /** * Gets the set of padding schemes (e.g., {@code PSS}, {@code PKCS#1}) with which the key * can be used when signing/verifying. Attempts to use the key with any other padding scheme * will be rejected. * *
See {@link KeyProperties}.{@code SIGNATURE_PADDING} constants. */ @NonNull public @KeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() { return ArrayUtils.cloneIfNotEmpty(mSignaturePaddings); } /** * Gets the set of digest algorithms (e.g., {@code SHA-256}, {@code SHA-384}) with which the key * can be used. * *
See {@link KeyProperties}.{@code DIGEST} constants. * * @throws IllegalStateException if this set has not been specified. * * @see #isDigestsSpecified() */ @NonNull public @KeyProperties.DigestEnum String[] getDigests() { if (mDigests == null) { throw new IllegalStateException("Digests not specified"); } return ArrayUtils.cloneIfNotEmpty(mDigests); } /** * Returns {@code true} if the set of digest algorithms with which the key can be used has been * specified. * * @see #getDigests() */ public boolean isDigestsSpecified() { return mDigests != null; } /** * Gets the set of block modes (e.g., {@code CBC}, {@code CTR}) with which the key can be used * when encrypting/decrypting. Attempts to use the key with any other block modes will be * rejected. * *
See {@link KeyProperties}.{@code BLOCK_MODE} constants. */ @NonNull public @KeyProperties.BlockModeEnum String[] getBlockModes() { return ArrayUtils.cloneIfNotEmpty(mBlockModes); } /** * Returns {@code true} if encryption using this key must be sufficiently randomized to produce * different ciphertexts for the same plaintext every time. The formal cryptographic property * being required is indistinguishability under chosen-plaintext attack ({@code * IND-CPA}). This property is important because it mitigates several classes of * weaknesses due to which ciphertext may leak information about plaintext. For example, if a * given plaintext always produces the same ciphertext, an attacker may see the repeated * ciphertexts and be able to deduce something about the plaintext. */ public boolean isRandomizedEncryptionRequired() { return mRandomizedEncryptionRequired; } /** * Returns {@code true} if user authentication is required for this key to be used. * * @see #getUserAuthenticationValidityDurationSeconds() */ public boolean isUserAuthenticationRequired() { return mUserAuthenticationRequired; } /** * Gets the duration of time (seconds) for which this key can be used after the user is * successfully authenticated. This has effect only if user authentication is required. * * @return duration in seconds or {@code -1} if authentication is required for every use of the * key. * * @see #isUserAuthenticationRequired() */ public int getUserAuthenticationValidityDurationSeconds() { return mUserAuthenticationValidityDurationSeconds; } /** * Builder of {@link KeyProtection} instances. */ public final static class Builder { private @KeyProperties.PurposeEnum int mPurposes; private Date mKeyValidityStart; private Date mKeyValidityForOriginationEnd; private Date mKeyValidityForConsumptionEnd; private @KeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings; private @KeyProperties.SignaturePaddingEnum String[] mSignaturePaddings; private @KeyProperties.DigestEnum String[] mDigests; private @KeyProperties.BlockModeEnum String[] mBlockModes; private boolean mRandomizedEncryptionRequired = true; private boolean mUserAuthenticationRequired; private int mUserAuthenticationValidityDurationSeconds = -1; /** * Creates a new instance of the {@code Builder}. * * @param purposes set of purposes (e.g., encrypt, decrypt, sign) for which the key can be * used. Attempts to use the key for any other purpose will be rejected. * *
See {@link KeyProperties}.{@code PURPOSE} flags. */ public Builder(@KeyProperties.PurposeEnum int purposes) { mPurposes = purposes; } /** * Sets the time instant before which the key is not yet valid. * *
By default, the key is valid at any instant. * * @see #setKeyValidityEnd(Date) */ @NonNull public Builder setKeyValidityStart(Date startDate) { mKeyValidityStart = Utils.cloneIfNotNull(startDate); return this; } /** * Sets the time instant after which the key is no longer valid. * *
By default, the key is valid at any instant. * * @see #setKeyValidityStart(Date) * @see #setKeyValidityForConsumptionEnd(Date) * @see #setKeyValidityForOriginationEnd(Date) */ @NonNull public Builder setKeyValidityEnd(Date endDate) { setKeyValidityForOriginationEnd(endDate); setKeyValidityForConsumptionEnd(endDate); return this; } /** * Sets the time instant after which the key is no longer valid for encryption and signing. * *
By default, the key is valid at any instant. * * @see #setKeyValidityForConsumptionEnd(Date) */ @NonNull public Builder setKeyValidityForOriginationEnd(Date endDate) { mKeyValidityForOriginationEnd = Utils.cloneIfNotNull(endDate); return this; } /** * Sets the time instant after which the key is no longer valid for decryption and * verification. * *
By default, the key is valid at any instant. * * @see #setKeyValidityForOriginationEnd(Date) */ @NonNull public Builder setKeyValidityForConsumptionEnd(Date endDate) { mKeyValidityForConsumptionEnd = Utils.cloneIfNotNull(endDate); return this; } /** * Sets the set of padding schemes (e.g., {@code OAEPPadding}, {@code PKCS7Padding}, * {@code NoPadding}) with which the key can be used when encrypting/decrypting. Attempts to * use the key with any other padding scheme will be rejected. * *
This must be specified for keys which are used for encryption/decryption. * *
For RSA private keys used by TLS/SSL servers to authenticate themselves to clients it * is usually necessary to authorize the use of no/any padding * ({@link KeyProperties#ENCRYPTION_PADDING_NONE}). This is because RSA decryption is * required by some cipher suites, and some stacks request decryption using no padding * whereas others request PKCS#1 padding. * *
See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants. */ @NonNull public Builder setEncryptionPaddings( @KeyProperties.EncryptionPaddingEnum String... paddings) { mEncryptionPaddings = ArrayUtils.cloneIfNotEmpty(paddings); return this; } /** * Sets the set of padding schemes (e.g., {@code PSS}, {@code PKCS#1}) with which the key * can be used when signing/verifying. Attempts to use the key with any other padding scheme * will be rejected. * *
This must be specified for RSA keys which are used for signing/verification. * *
See {@link KeyProperties}.{@code SIGNATURE_PADDING} constants. */ @NonNull public Builder setSignaturePaddings( @KeyProperties.SignaturePaddingEnum String... paddings) { mSignaturePaddings = ArrayUtils.cloneIfNotEmpty(paddings); return this; } /** * Sets the set of digest algorithms (e.g., {@code SHA-256}, {@code SHA-384}) with which the * key can be used when signing/verifying or generating MACs. Attempts to use the key with * any other digest algorithm will be rejected. * *
For HMAC keys, the default is the digest algorithm specified in * {@link Key#getAlgorithm()}. For asymmetric signing keys the set of digest algorithms * must be specified. * *
For private keys used for TLS/SSL client or server authentication it is usually * necessary to authorize the use of no digest ({@link KeyProperties#DIGEST_NONE}). This is * because TLS/SSL stacks typically generate the necessary digest(s) themselves and then use * a private key to sign it. * *
See {@link KeyProperties}.{@code DIGEST} constants. */ @NonNull public Builder setDigests(@KeyProperties.DigestEnum String... digests) { mDigests = ArrayUtils.cloneIfNotEmpty(digests); return this; } /** * Sets the set of block modes (e.g., {@code CBC}, {@code CTR}, {@code ECB}) with which the * key can be used when encrypting/decrypting. Attempts to use the key with any other block * modes will be rejected. * *
This must be specified for encryption/decryption keys. * *
See {@link KeyProperties}.{@code BLOCK_MODE} constants. */ @NonNull public Builder setBlockModes(@KeyProperties.BlockModeEnum String... blockModes) { mBlockModes = ArrayUtils.cloneIfNotEmpty(blockModes); return this; } /** * Sets whether encryption using this key must be sufficiently randomized to produce * different ciphertexts for the same plaintext every time. The formal cryptographic * property being required is indistinguishability under chosen-plaintext attack * ({@code IND-CPA}). This property is important because it mitigates several classes * of weaknesses due to which ciphertext may leak information about plaintext. For example, * if a given plaintext always produces the same ciphertext, an attacker may see the * repeated ciphertexts and be able to deduce something about the plaintext. * *
By default, {@code IND-CPA} is required. * *
When {@code IND-CPA} is required: *
Before disabling this requirement, consider the following approaches instead: *
By default, the key can be used without user authentication. * *
When user authentication is required, the user authorizes the use of the key by * authenticating to this Android device using a subset of their secure lock screen * credentials. Different authentication methods are used depending on whether the every * use of the key must be authenticated (as specified by * {@link #setUserAuthenticationValidityDurationSeconds(int)}). * More * information. * * @see #setUserAuthenticationValidityDurationSeconds(int) */ @NonNull public Builder setUserAuthenticationRequired(boolean required) { mUserAuthenticationRequired = required; return this; } /** * Sets the duration of time (seconds) for which this key can be used after the user is * successfully authenticated. This has effect only if user authentication is required. * *
By default, the user needs to authenticate for every use of the key. * * @param seconds duration in seconds or {@code -1} if the user needs to authenticate for * every use of the key. * * @see #setUserAuthenticationRequired(boolean) */ @NonNull public Builder setUserAuthenticationValidityDurationSeconds( @IntRange(from = -1) int seconds) { if (seconds < -1) { throw new IllegalArgumentException("seconds must be -1 or larger"); } mUserAuthenticationValidityDurationSeconds = seconds; return this; } /** * Builds an instance of {@link KeyProtection}. * * @throws IllegalArgumentException if a required field is missing */ @NonNull public KeyProtection build() { return new KeyProtection( mKeyValidityStart, mKeyValidityForOriginationEnd, mKeyValidityForConsumptionEnd, mPurposes, mEncryptionPaddings, mSignaturePaddings, mDigests, mBlockModes, mRandomizedEncryptionRequired, mUserAuthenticationRequired, mUserAuthenticationValidityDurationSeconds); } } }