/*
* Copyright (C) 2012 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;
import com.android.org.conscrypt.NativeCrypto;
import android.content.Context;
import android.text.TextUtils;
import java.math.BigInteger;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.cert.Certificate;
import java.security.spec.AlgorithmParameterSpec;
import java.security.spec.DSAParameterSpec;
import java.security.spec.RSAKeyGenParameterSpec;
import java.util.Date;
import javax.security.auth.x500.X500Principal;
/**
* This provides the required parameters needed for initializing the
* {@code KeyPairGenerator} that works with
* <a href="{@docRoot}training/articles/keystore.html">Android KeyStore
* facility</a>. The Android KeyStore facility is accessed through a
* {@link java.security.KeyPairGenerator} API using the {@code AndroidKeyStore}
* provider. The {@code context} passed in may be used to pop up some UI to ask
* the user to unlock or initialize the Android KeyStore facility.
* <p>
* After generation, the {@code keyStoreAlias} is used with the
* {@link java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter)}
* interface to retrieve the {@link PrivateKey} and its associated
* {@link Certificate} chain.
* <p>
* The KeyPair generator will create a self-signed certificate with the subject
* as its X.509v3 Subject Distinguished Name and as its X.509v3 Issuer
* Distinguished Name along with the other parameters specified with the
* {@link Builder}.
* <p>
* The self-signed X.509 certificate may be replaced at a later time by a
* certificate signed by a real Certificate Authority.
*/
public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec {
/*
* These must be kept in sync with system/security/keystore/defaults.h
*/
/* DSA */
private static final int DSA_DEFAULT_KEY_SIZE = 1024;
private static final int DSA_MIN_KEY_SIZE = 512;
private static final int DSA_MAX_KEY_SIZE = 8192;
/* EC */
private static final int EC_DEFAULT_KEY_SIZE = 256;
private static final int EC_MIN_KEY_SIZE = 192;
private static final int EC_MAX_KEY_SIZE = 521;
/* RSA */
private static final int RSA_DEFAULT_KEY_SIZE = 2048;
private static final int RSA_MIN_KEY_SIZE = 512;
private static final int RSA_MAX_KEY_SIZE = 8192;
private final Context mContext;
private final String mKeystoreAlias;
private final String mKeyType;
private final int mKeySize;
private final AlgorithmParameterSpec mSpec;
private final X500Principal mSubjectDN;
private final BigInteger mSerialNumber;
private final Date mStartDate;
private final Date mEndDate;
private final int mFlags;
/**
* Parameter specification for the "{@code AndroidKeyPairGenerator}"
* instance of the {@link java.security.KeyPairGenerator} API. The
* {@code context} passed in may be used to pop up some UI to ask the user
* to unlock or initialize the Android keystore facility.
* <p>
* After generation, the {@code keyStoreAlias} is used with the
* {@link java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter)}
* interface to retrieve the {@link PrivateKey} and its associated
* {@link Certificate} chain.
* <p>
* The KeyPair generator will create a self-signed certificate with the
* properties of {@code subjectDN} as its X.509v3 Subject Distinguished Name
* and as its X.509v3 Issuer Distinguished Name, using the specified
* {@code serialNumber}, and the validity date starting at {@code startDate}
* and ending at {@code endDate}.
*
* @param context Android context for the activity
* @param keyStoreAlias name to use for the generated key in the Android
* keystore
* @param keyType key algorithm to use (RSA, DSA, EC)
* @param keySize size of key to generate
* @param spec the underlying key type parameters
* @param subjectDN X.509 v3 Subject Distinguished Name
* @param serialNumber X509 v3 certificate serial number
* @param startDate the start of the self-signed certificate validity period
* @param endDate the end date of the self-signed certificate validity
* period
* @throws IllegalArgumentException when any argument is {@code null} or
* {@code endDate} is before {@code startDate}.
* @hide should be built with KeyPairGeneratorSpecBuilder
*/
public KeyPairGeneratorSpec(Context context, String keyStoreAlias, String keyType, int keySize,
AlgorithmParameterSpec spec, X500Principal subjectDN, BigInteger serialNumber,
Date startDate, Date endDate, int flags) {
if (context == null) {
throw new IllegalArgumentException("context == null");
} else if (TextUtils.isEmpty(keyStoreAlias)) {
throw new IllegalArgumentException("keyStoreAlias must not be empty");
} else if (subjectDN == null) {
throw new IllegalArgumentException("subjectDN == null");
} else if (serialNumber == null) {
throw new IllegalArgumentException("serialNumber == null");
} else if (startDate == null) {
throw new IllegalArgumentException("startDate == null");
} else if (endDate == null) {
throw new IllegalArgumentException("endDate == null");
} else if (endDate.before(startDate)) {
throw new IllegalArgumentException("endDate < startDate");
}
final int keyTypeInt = KeyStore.getKeyTypeForAlgorithm(keyType);
if (keySize == -1) {
keySize = getDefaultKeySizeForType(keyTypeInt);
}
checkCorrectParametersSpec(keyTypeInt, keySize, spec);
checkValidKeySize(keyTypeInt, keySize);
mContext = context;
mKeystoreAlias = keyStoreAlias;
mKeyType = keyType;
mKeySize = keySize;
mSpec = spec;
mSubjectDN = subjectDN;
mSerialNumber = serialNumber;
mStartDate = startDate;
mEndDate = endDate;
mFlags = flags;
}
private static int getDefaultKeySizeForType(int keyType) {
if (keyType == NativeCrypto.EVP_PKEY_DSA) {
return DSA_DEFAULT_KEY_SIZE;
} else if (keyType == NativeCrypto.EVP_PKEY_EC) {
return EC_DEFAULT_KEY_SIZE;
} else if (keyType == NativeCrypto.EVP_PKEY_RSA) {
return RSA_DEFAULT_KEY_SIZE;
}
throw new IllegalArgumentException("Invalid key type " + keyType);
}
private static void checkValidKeySize(int keyType, int keySize) {
if (keyType == NativeCrypto.EVP_PKEY_DSA) {
if (keySize < DSA_MIN_KEY_SIZE || keySize > DSA_MAX_KEY_SIZE) {
throw new IllegalArgumentException("DSA keys must be >= " + DSA_MIN_KEY_SIZE
+ " and <= " + DSA_MAX_KEY_SIZE);
}
} else if (keyType == NativeCrypto.EVP_PKEY_EC) {
if (keySize < EC_MIN_KEY_SIZE || keySize > EC_MAX_KEY_SIZE) {
throw new IllegalArgumentException("EC keys must be >= " + EC_MIN_KEY_SIZE
+ " and <= " + EC_MAX_KEY_SIZE);
}
} else if (keyType == NativeCrypto.EVP_PKEY_RSA) {
if (keySize < RSA_MIN_KEY_SIZE || keySize > RSA_MAX_KEY_SIZE) {
throw new IllegalArgumentException("RSA keys must be >= " + RSA_MIN_KEY_SIZE
+ " and <= " + RSA_MAX_KEY_SIZE);
}
} else {
throw new IllegalArgumentException("Invalid key type " + keyType);
}
}
private static void checkCorrectParametersSpec(int keyType, int keySize,
AlgorithmParameterSpec spec) {
if (keyType == NativeCrypto.EVP_PKEY_DSA && spec != null) {
if (!(spec instanceof DSAParameterSpec)) {
throw new IllegalArgumentException("DSA keys must have DSAParameterSpec specified");
}
} else if (keyType == NativeCrypto.EVP_PKEY_RSA && spec != null) {
if (spec instanceof RSAKeyGenParameterSpec) {
RSAKeyGenParameterSpec rsaSpec = (RSAKeyGenParameterSpec) spec;
if (keySize != -1 && keySize != rsaSpec.getKeysize()) {
throw new IllegalArgumentException("RSA key size must match: " + keySize
+ " vs " + rsaSpec.getKeysize());
}
} else {
throw new IllegalArgumentException("RSA may only use RSAKeyGenParameterSpec");
}
}
}
/**
* Gets the Android context used for operations with this instance.
*/
public Context getContext() {
return mContext;
}
/**
* Returns the alias that will be used in the {@code java.security.KeyStore}
* in conjunction with the {@code AndroidKeyStore}.
*/
public String getKeystoreAlias() {
return mKeystoreAlias;
}
/**
* Returns the key type (e.g., "RSA", "DSA", "EC") specified by this
* parameter.
*/
public String getKeyType() {
return mKeyType;
}
/**
* Returns the key size specified by this parameter. For instance, for RSA
* this will return the modulus size and for EC it will return the field
* size.
*/
public int getKeySize() {
return mKeySize;
}
/**
* Returns the {@link AlgorithmParameterSpec} that will be used for creation
* of the key pair.
*/
public AlgorithmParameterSpec getAlgorithmParameterSpec() {
return mSpec;
}
/**
* Gets the subject distinguished name to be used on the X.509 certificate
* that will be put in the {@link java.security.KeyStore}.
*/
public X500Principal getSubjectDN() {
return mSubjectDN;
}
/**
* Gets the serial number to be used on the X.509 certificate that will be
* put in the {@link java.security.KeyStore}.
*/
public BigInteger getSerialNumber() {
return mSerialNumber;
}
/**
* Gets the start date to be used on the X.509 certificate that will be put
* in the {@link java.security.KeyStore}.
*/
public Date getStartDate() {
return mStartDate;
}
/**
* Gets the end date to be used on the X.509 certificate that will be put in
* the {@link java.security.KeyStore}.
*/
public Date getEndDate() {
return mEndDate;
}
/**
* @hide
*/
int getFlags() {
return mFlags;
}
/**
* Returns {@code true} if this parameter will require generated keys to be
* encrypted in the {@link java.security.KeyStore}.
*/
public boolean isEncryptionRequired() {
return (mFlags & KeyStore.FLAG_ENCRYPTED) != 0;
}
/**
* Builder class for {@link KeyPairGeneratorSpec} objects.
* <p>
* This will build a parameter spec for use with the <a href="{@docRoot}
* training/articles/keystore.html">Android KeyStore facility</a>.
* <p>
* The required fields must be filled in with the builder.
* <p>
* Example:
*
* <pre class="prettyprint">
* Calendar start = new Calendar();
* Calendar end = new Calendar();
* end.add(1, Calendar.YEAR);
*
* KeyPairGeneratorSpec spec =
* new KeyPairGeneratorSpec.Builder(mContext).setAlias("myKey")
* .setSubject(new X500Principal("CN=myKey")).setSerial(BigInteger.valueOf(1337))
* .setStartDate(start.getTime()).setEndDate(end.getTime()).build();
* </pre>
*/
public final static class Builder {
private final Context mContext;
private String mKeystoreAlias;
private String mKeyType = "RSA";
private int mKeySize = -1;
private AlgorithmParameterSpec mSpec;
private X500Principal mSubjectDN;
private BigInteger mSerialNumber;
private Date mStartDate;
private Date mEndDate;
private int mFlags;
/**
* Creates a new instance of the {@code Builder} with the given
* {@code context}. The {@code context} passed in may be used to pop up
* some UI to ask the user to unlock or initialize the Android KeyStore
* facility.
*/
public Builder(Context context) {
if (context == null) {
throw new NullPointerException("context == null");
}
mContext = context;
}
/**
* Sets the alias to be used to retrieve the key later from a
* {@link java.security.KeyStore} instance using the
* {@code AndroidKeyStore} provider.
*/
public Builder setAlias(String alias) {
if (alias == null) {
throw new NullPointerException("alias == null");
}
mKeystoreAlias = alias;
return this;
}
/**
* Sets the key type (e.g., RSA, DSA, EC) of the keypair to be created.
*/
public Builder setKeyType(String keyType) throws NoSuchAlgorithmException {
if (keyType == null) {
throw new NullPointerException("keyType == null");
} else {
try {
KeyStore.getKeyTypeForAlgorithm(keyType);
} catch (IllegalArgumentException e) {
throw new NoSuchAlgorithmException("Unsupported key type: " + keyType);
}
}
mKeyType = keyType;
return this;
}
/**
* Sets the key size for the keypair to be created. For instance, for a
* key type of RSA this will set the modulus size and for a key type of
* EC it will select a curve with a matching field size.
*/
public Builder setKeySize(int keySize) {
if (keySize < 0) {
throw new IllegalArgumentException("keySize < 0");
}
mKeySize = keySize;
return this;
}
/**
* Sets the underlying key type's parameters. This is required for DSA
* where you must set this to an instance of
* {@link java.security.spec.DSAParameterSpec}.
*/
public Builder setAlgorithmParameterSpec(AlgorithmParameterSpec spec) {
if (spec == null) {
throw new NullPointerException("spec == null");
}
mSpec = spec;
return this;
}
/**
* Sets the subject used for the self-signed certificate of the
* generated key pair.
*/
public Builder setSubject(X500Principal subject) {
if (subject == null) {
throw new NullPointerException("subject == null");
}
mSubjectDN = subject;
return this;
}
/**
* Sets the serial number used for the self-signed certificate of the
* generated key pair.
*/
public Builder setSerialNumber(BigInteger serialNumber) {
if (serialNumber == null) {
throw new NullPointerException("serialNumber == null");
}
mSerialNumber = serialNumber;
return this;
}
/**
* Sets the start of the validity period for the self-signed certificate
* of the generated key pair.
*/
public Builder setStartDate(Date startDate) {
if (startDate == null) {
throw new NullPointerException("startDate == null");
}
mStartDate = startDate;
return this;
}
/**
* Sets the end of the validity period for the self-signed certificate
* of the generated key pair.
*/
public Builder setEndDate(Date endDate) {
if (endDate == null) {
throw new NullPointerException("endDate == null");
}
mEndDate = endDate;
return this;
}
/**
* Indicates that this key must be encrypted at rest on storage. Note
* that enabling this will require that the user enable a strong lock
* screen (e.g., PIN, password) before creating or using the generated
* key is successful.
*/
public Builder setEncryptionRequired() {
mFlags |= KeyStore.FLAG_ENCRYPTED;
return this;
}
/**
* Builds the instance of the {@code KeyPairGeneratorSpec}.
*
* @throws IllegalArgumentException if a required field is missing
* @return built instance of {@code KeyPairGeneratorSpec}
*/
public KeyPairGeneratorSpec build() {
return new KeyPairGeneratorSpec(mContext, mKeystoreAlias, mKeyType, mKeySize, mSpec,
mSubjectDN, mSerialNumber, mStartDate, mEndDate, mFlags);
}
}
}
|
