/**
* Loads the keystore from the given input stream.
*
* <p>If a password is given, it is used to check the integrity of the keystore data. Otherwise,
* the integrity of the keystore is not checked.
*
* @param stream the input stream from which the keystore is loaded
* @param password the (optional) password used to check the integrity of the keystore.
* @exception IOException if there is an I/O or format problem with the keystore data
* @exception NoSuchAlgorithmException if the algorithm used to check the integrity of the
* keystore cannot be found
* @exception CertificateException if any of the certificates in the keystore could not be loaded
*/
public void engineLoad(InputStream stream, char[] password)
throws IOException, NoSuchAlgorithmException, CertificateException {
// Support loading from a stream only for a JKS or default type keystore
try {
KeyStore keystore = null;
try {
keystore = KeyStore.getInstance("JKS");
keystore.load(stream, password);
} catch (Exception e) {
// Retry
if (!"JKS".equalsIgnoreCase(DEFAULT_KEYSTORE_TYPE)) {
keystore = KeyStore.getInstance(DEFAULT_KEYSTORE_TYPE);
keystore.load(stream, password);
} else {
throw e;
}
}
String keystoreName = DEFAULT_STREAM_PREFIX + streamCounter++;
keystores.put(keystoreName, keystore);
} catch (Exception e) {
throw new UnsupportedOperationException(
"This keystore must be loaded using a " + "DomainLoadStoreParameter");
}
}
/**
* Returns the {@code PrivateKey} for the requested alias, or null if no there is no result.
*
* <p>This method may block while waiting for a connection to another process, and must never be
* called from the main thread.
*
* @param alias The alias of the desired private key, typically returned via {@link
* KeyChainAliasCallback#alias}.
* @throws KeyChainException if the alias was valid but there was some problem accessing it.
* @throws IllegalStateException if called from the main thread.
*/
@Nullable
@WorkerThread
public static PrivateKey getPrivateKey(@NonNull Context context, @NonNull String alias)
throws KeyChainException, InterruptedException {
if (alias == null) {
throw new NullPointerException("alias == null");
}
KeyChainConnection keyChainConnection = bind(context);
try {
final IKeyChainService keyChainService = keyChainConnection.getService();
final String keyId = keyChainService.requestPrivateKey(alias);
if (keyId == null) {
throw new KeyChainException("keystore had a problem");
}
return AndroidKeyStoreProvider.loadAndroidKeyStorePrivateKeyFromKeystore(
KeyStore.getInstance(), keyId);
} catch (RemoteException e) {
throw new KeyChainException(e);
} catch (RuntimeException e) {
// only certain RuntimeExceptions can be propagated across the IKeyChainService call
throw new KeyChainException(e);
} catch (UnrecoverableKeyException e) {
throw new KeyChainException(e);
} finally {
keyChainConnection.close();
}
}
/**
* Returns {@code true} if the current device's {@code KeyChain} binds any {@code PrivateKey} of
* the given {@code algorithm} to the device once imported or generated. This can be used to tell
* if there is special hardware support that can be used to bind keys to the device in a way that
* makes it non-exportable.
*
* @deprecated Whether the key is bound to the secure hardware is known only once the key has been
* imported. To find out, use:
* <pre>{@code
* PrivateKey key = ...; // private key from KeyChain
*
* KeyFactory keyFactory =
* KeyFactory.getInstance(key.getAlgorithm(), "AndroidKeyStore");
* KeyInfo keyInfo = keyFactory.getKeySpec(key, KeyInfo.class);
* if (keyInfo.isInsideSecureHardware()) {
* // The key is bound to the secure hardware of this Android
* }
* }</pre>
*/
@Deprecated
public static boolean isBoundKeyAlgorithm(
@NonNull @KeyProperties.KeyAlgorithmEnum String algorithm) {
if (!isKeyAlgorithmSupported(algorithm)) {
return false;
}
return KeyStore.getInstance().isHardwareBacked(algorithm);
}
/**
* {@link KeyGeneratorSpi} backed by Android KeyStore.
*
* @hide
*/
public abstract class KeyStoreKeyGeneratorSpi extends KeyGeneratorSpi {
public static class AES extends KeyStoreKeyGeneratorSpi {
public AES() {
super(KeymasterDefs.KM_ALGORITHM_AES, 128);
}
@Override
protected void engineInit(AlgorithmParameterSpec params, SecureRandom random)
throws InvalidAlgorithmParameterException {
super.engineInit(params, random);
if ((mKeySizeBits != 128) && (mKeySizeBits != 192) && (mKeySizeBits != 256)) {
throw new InvalidAlgorithmParameterException(
"Unsupported key size: " + mKeySizeBits + ". Supported: 128, 192, 256.");
}
}
}
protected abstract static class HmacBase extends KeyStoreKeyGeneratorSpi {
protected HmacBase(int keymasterDigest) {
super(
KeymasterDefs.KM_ALGORITHM_HMAC,
keymasterDigest,
KeymasterUtils.getDigestOutputSizeBits(keymasterDigest));
}
}
public static class HmacSHA1 extends HmacBase {
public HmacSHA1() {
super(KeymasterDefs.KM_DIGEST_SHA1);
}
}
public static class HmacSHA224 extends HmacBase {
public HmacSHA224() {
super(KeymasterDefs.KM_DIGEST_SHA_2_224);
}
}
public static class HmacSHA256 extends HmacBase {
public HmacSHA256() {
super(KeymasterDefs.KM_DIGEST_SHA_2_256);
}
}
public static class HmacSHA384 extends HmacBase {
public HmacSHA384() {
super(KeymasterDefs.KM_DIGEST_SHA_2_384);
}
}
public static class HmacSHA512 extends HmacBase {
public HmacSHA512() {
super(KeymasterDefs.KM_DIGEST_SHA_2_512);
}
}
private final KeyStore mKeyStore = KeyStore.getInstance();
private final int mKeymasterAlgorithm;
private final int mKeymasterDigest;
private final int mDefaultKeySizeBits;
private KeyGenParameterSpec mSpec;
private SecureRandom mRng;
protected int mKeySizeBits;
private int[] mKeymasterPurposes;
private int[] mKeymasterBlockModes;
private int[] mKeymasterPaddings;
private int[] mKeymasterDigests;
protected KeyStoreKeyGeneratorSpi(int keymasterAlgorithm, int defaultKeySizeBits) {
this(keymasterAlgorithm, -1, defaultKeySizeBits);
}
protected KeyStoreKeyGeneratorSpi(
int keymasterAlgorithm, int keymasterDigest, int defaultKeySizeBits) {
mKeymasterAlgorithm = keymasterAlgorithm;
mKeymasterDigest = keymasterDigest;
mDefaultKeySizeBits = defaultKeySizeBits;
if (mDefaultKeySizeBits <= 0) {
throw new IllegalArgumentException("Default key size must be positive");
}
if ((mKeymasterAlgorithm == KeymasterDefs.KM_ALGORITHM_HMAC) && (mKeymasterDigest == -1)) {
throw new IllegalArgumentException("Digest algorithm must be specified for HMAC key");
}
}
@Override
protected void engineInit(SecureRandom random) {
throw new UnsupportedOperationException(
"Cannot initialize without a " + KeyGenParameterSpec.class.getName() + " parameter");
}
@Override
protected void engineInit(int keySize, SecureRandom random) {
throw new UnsupportedOperationException(
"Cannot initialize without a " + KeyGenParameterSpec.class.getName() + " parameter");
}
@Override
protected void engineInit(AlgorithmParameterSpec params, SecureRandom random)
throws InvalidAlgorithmParameterException {
resetAll();
boolean success = false;
try {
if ((params == null) || (!(params instanceof KeyGenParameterSpec))) {
throw new InvalidAlgorithmParameterException(
"Cannot initialize without a " + KeyGenParameterSpec.class.getName() + " parameter");
}
KeyGenParameterSpec spec = (KeyGenParameterSpec) params;
if (spec.getKeystoreAlias() == null) {
throw new InvalidAlgorithmParameterException("KeyStore entry alias not provided");
}
mRng = random;
mSpec = spec;
mKeySizeBits = (spec.getKeySize() != -1) ? spec.getKeySize() : mDefaultKeySizeBits;
if (mKeySizeBits <= 0) {
throw new InvalidAlgorithmParameterException("Key size must be positive: " + mKeySizeBits);
} else if ((mKeySizeBits % 8) != 0) {
throw new InvalidAlgorithmParameterException(
"Key size in must be a multiple of 8: " + mKeySizeBits);
}
try {
mKeymasterPurposes = KeyProperties.Purpose.allToKeymaster(spec.getPurposes());
mKeymasterPaddings =
KeyProperties.EncryptionPadding.allToKeymaster(spec.getEncryptionPaddings());
mKeymasterBlockModes = KeyProperties.BlockMode.allToKeymaster(spec.getBlockModes());
if (((spec.getPurposes() & KeyProperties.PURPOSE_ENCRYPT) != 0)
&& (spec.isRandomizedEncryptionRequired())) {
for (int keymasterBlockMode : mKeymasterBlockModes) {
if (!KeymasterUtils.isKeymasterBlockModeIndCpaCompatible(keymasterBlockMode)) {
throw new InvalidAlgorithmParameterException(
"Randomized encryption (IND-CPA) required but may be violated"
+ " by block mode: "
+ KeyProperties.BlockMode.fromKeymaster(keymasterBlockMode)
+ ". See "
+ KeyGenParameterSpec.class.getName()
+ " documentation.");
}
}
}
if (spec.isDigestsSpecified()) {
// Digest(s) explicitly specified in the spec
mKeymasterDigests = KeyProperties.Digest.allToKeymaster(spec.getDigests());
if (mKeymasterDigest != -1) {
// Key algorithm implies a digest -- ensure it's specified in the spec as
// first digest.
if (!com.android.internal.util.ArrayUtils.contains(
mKeymasterDigests, mKeymasterDigest)) {
throw new InvalidAlgorithmParameterException(
"Digests specified in algorithm parameters ("
+ Arrays.asList(spec.getDigests())
+ ") must include "
+ " the digest "
+ KeyProperties.Digest.fromKeymaster(mKeymasterDigest)
+ " implied by key algorithm");
}
if (mKeymasterDigests[0] != mKeymasterDigest) {
// The first digest is not the one implied by the key algorithm.
// Swap the implied digest with the first one.
for (int i = 0; i < mKeymasterDigests.length; i++) {
if (mKeymasterDigests[i] == mKeymasterDigest) {
mKeymasterDigests[i] = mKeymasterDigests[0];
mKeymasterDigests[0] = mKeymasterDigest;
break;
}
}
}
}
} else {
// No digest specified in the spec
if (mKeymasterDigest != -1) {
// Key algorithm implies a digest -- use that digest
mKeymasterDigests = new int[] {mKeymasterDigest};
} else {
mKeymasterDigests = EmptyArray.INT;
}
}
if (mKeymasterAlgorithm == KeymasterDefs.KM_ALGORITHM_HMAC) {
if (mKeymasterDigests.length == 0) {
throw new InvalidAlgorithmParameterException(
"At least one digest algorithm must be specified");
}
}
} catch (IllegalStateException | IllegalArgumentException e) {
throw new InvalidAlgorithmParameterException(e);
}
success = true;
} finally {
if (!success) {
resetAll();
}
}
}
private void resetAll() {
mSpec = null;
mRng = null;
mKeySizeBits = -1;
mKeymasterPurposes = null;
mKeymasterPaddings = null;
mKeymasterBlockModes = null;
}
@Override
protected SecretKey engineGenerateKey() {
KeyGenParameterSpec spec = mSpec;
if (spec == null) {
throw new IllegalStateException("Not initialized");
}
if ((spec.isEncryptionAtRestRequired()) && (mKeyStore.state() != KeyStore.State.UNLOCKED)) {
throw new IllegalStateException(
"Requested to import a key which must be encrypted at rest using secure lock"
+ " screen credential, but the credential hasn't yet been entered by the user");
}
KeymasterArguments args = new KeymasterArguments();
args.addInt(KeymasterDefs.KM_TAG_KEY_SIZE, mKeySizeBits);
args.addInt(KeymasterDefs.KM_TAG_ALGORITHM, mKeymasterAlgorithm);
args.addInts(KeymasterDefs.KM_TAG_PURPOSE, mKeymasterPurposes);
args.addInts(KeymasterDefs.KM_TAG_BLOCK_MODE, mKeymasterBlockModes);
args.addInts(KeymasterDefs.KM_TAG_PADDING, mKeymasterPaddings);
args.addInts(KeymasterDefs.KM_TAG_DIGEST, mKeymasterDigests);
KeymasterUtils.addUserAuthArgs(
args,
spec.isUserAuthenticationRequired(),
spec.getUserAuthenticationValidityDurationSeconds());
args.addDate(
KeymasterDefs.KM_TAG_ACTIVE_DATETIME,
(spec.getKeyValidityStart() != null) ? spec.getKeyValidityStart() : new Date(0));
args.addDate(
KeymasterDefs.KM_TAG_ORIGINATION_EXPIRE_DATETIME,
(spec.getKeyValidityForOriginationEnd() != null)
? spec.getKeyValidityForOriginationEnd()
: new Date(Long.MAX_VALUE));
args.addDate(
KeymasterDefs.KM_TAG_USAGE_EXPIRE_DATETIME,
(spec.getKeyValidityForConsumptionEnd() != null)
? spec.getKeyValidityForConsumptionEnd()
: new Date(Long.MAX_VALUE));
if (((spec.getPurposes() & KeyProperties.PURPOSE_ENCRYPT) != 0)
&& (!spec.isRandomizedEncryptionRequired())) {
// Permit caller-provided IV when encrypting with this key
args.addBoolean(KeymasterDefs.KM_TAG_CALLER_NONCE);
}
byte[] additionalEntropy =
KeyStoreCryptoOperationUtils.getRandomBytesToMixIntoKeystoreRng(
mRng, (mKeySizeBits + 7) / 8);
int flags = spec.getFlags();
String keyAliasInKeystore = Credentials.USER_SECRET_KEY + spec.getKeystoreAlias();
KeyCharacteristics resultingKeyCharacteristics = new KeyCharacteristics();
int errorCode =
mKeyStore.generateKey(
keyAliasInKeystore, args, additionalEntropy, flags, resultingKeyCharacteristics);
if (errorCode != KeyStore.NO_ERROR) {
throw new ProviderException(
"Keystore operation failed", KeyStore.getKeyStoreException(errorCode));
}
@KeyProperties.KeyAlgorithmEnum String keyAlgorithmJCA;
try {
keyAlgorithmJCA =
KeyProperties.KeyAlgorithm.fromKeymasterSecretKeyAlgorithm(
mKeymasterAlgorithm, mKeymasterDigest);
} catch (IllegalArgumentException e) {
throw new ProviderException("Failed to obtain JCA secret key algorithm name", e);
}
return new KeyStoreSecretKey(keyAliasInKeystore, keyAlgorithmJCA);
}
}
