FileDocCategorySizeDatePackage
KeyStore.javaAPI DocAndroid 1.5 API57388Wed May 06 22:41:06 BST 2009java.security

KeyStore

public class KeyStore extends Object
{@code KeyStore} is responsible for maintaining cryptographic keys and their owners.

The type of the system key store can be changed by setting the {@code 'keystore.type'} property in the file named {@code JAVA_HOME/lib/security/java.security}.

see
Certificate
see
PrivateKey
since
Android 1.0

Fields Summary
private static final String
SERVICE
private static org.apache.harmony.security.fortress.Engine
engine
private static final String
PROPERTYNAME
private static final String
DEFAULT_KEYSTORE_TYPE
private static String
NOTINITKEYSTORE
private boolean
isInit
private final KeyStoreSpi
implSpi
private final Provider
provider
private final String
type
Constructors Summary
protected KeyStore(KeyStoreSpi keyStoreSpi, Provider provider, String type)
Constructs a new instance of {@code KeyStore} with the given arguments.

param
keyStoreSpi the concrete key store.
param
provider the provider.
param
type the type of the {@code KeyStore} to be constructed.
since
Android 1.0


                                                                              
           
        this.type = type;
        this.provider = provider;
        this.implSpi = keyStoreSpi;
        isInit = false;
    
Methods Summary
public final java.util.Enumerationaliases()
Returns an {@code Enumeration} over all alias names stored in this {@code KeyStore}.

return
an {@code Enumeration} over all alias names stored in this {@code KeyStore}.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        return implSpi.engineAliases();
    
public final booleancontainsAlias(java.lang.String alias)
Indicates whether the given alias is present in this {@code KeyStore}.

param
alias the alias of an entry.
return
{@code true} if the alias exists, {@code false} otherwise.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        if (alias == null) {
            throw new NullPointerException(Messages.getString("security.3F")); //$NON-NLS-1$
        }
        return implSpi.engineContainsAlias(alias);
    
public final voiddeleteEntry(java.lang.String alias)
Deletes the entry identified with the given alias from this {@code KeyStore}.

param
alias the alias for the entry.
throws
KeyStoreException if this {@code KeyStore} is not initialized, or if the entry can not be deleted.
since
Android 1.0

        // BEGIN android-changed
        if (!isInit) {
            throwNotInitialized();
        }
        // END android-changed
        implSpi.engineDeleteEntry(alias);
    
public final booleanentryInstanceOf(java.lang.String alias, java.lang.Class entryClass)
Indicates whether the entry for the given alias is assignable to the provided {@code Class}.

param
alias the alias for the entry.
param
entryClass the type of the entry.
return
{@code true} if the {@code Entry} for the alias is assignable to the specified {@code entryClass}.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        if (alias == null) {
            throw new NullPointerException(Messages.getString("security.3F")); //$NON-NLS-1$
        }
        if (entryClass == null) {
            throw new NullPointerException(Messages.getString("security.40")); //$NON-NLS-1$
        }

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        return implSpi.engineEntryInstanceOf(alias, entryClass);
    
public final java.security.cert.CertificategetCertificate(java.lang.String alias)
Returns the trusted certificate for the entry with the given alias.

param
alias the alias for the entry.
return
the trusted certificate for the entry with the given alias, or {@code null} if the specified alias is not bound to an entry.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        return implSpi.engineGetCertificate(alias);
    
public final java.lang.StringgetCertificateAlias(java.security.cert.Certificate cert)
Returns the alias associated with the first entry whose certificate matches the specified certificate.

param
cert the certificate to find the associated entry's alias for.
return
the alias or {@code null} if no entry with the specified certificate can be found.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        return implSpi.engineGetCertificateAlias(cert);
    
public final java.security.cert.Certificate[]getCertificateChain(java.lang.String alias)
Returns the certificate chain for the entry with the given alias.

param
alias the alias for the entry.
return
the certificate chain for the entry with the given alias, or {@code null} if the specified alias is not bound to an entry.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        return implSpi.engineGetCertificateChain(alias);
    
public final java.util.DategetCreationDate(java.lang.String alias)
Returns the creation date of the entry with the given alias.

param
alias the alias for the entry.
return
the creation date, or {@code null} if the specified alias is not bound to an entry.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        return implSpi.engineGetCreationDate(alias);
    
public static final java.lang.StringgetDefaultType()
Returns the default type for {@code KeyStore} instances.

The default is specified in the {@code 'keystore.type'} property in the file named {@code JAVA_HOME/lib/security/java.security}. If this property is not set, {@code "jks"} will be used.

return
the default type for {@code KeyStore} instances
since
Android 1.0

        String dt = AccessController.doPrivileged(
                new PrivilegedAction<String>() {
                    public String run() {
                        return Security.getProperty(PROPERTYNAME);
                    }
                }
            );
        return (dt == null ? DEFAULT_KEYSTORE_TYPE : dt);
    
public final java.security.KeyStore$EntrygetEntry(java.lang.String alias, java.security.KeyStore$ProtectionParameter param)
Returns the {@code Entry} with the given alias, using the specified {@code ProtectionParameter}.

param
alias the alias of the requested entry.
param
param the {@code ProtectionParameter} used to protect the requested entry, maybe {@code null}.
return
he {@code Entry} with the given alias, using the specified {@code ProtectionParameter}.
throws
NoSuchAlgorithmException if the required algorithm is not available.
throws
UnrecoverableEntryException if the entry can not be recovered.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        if (alias == null) {
            throw new NullPointerException(Messages.getString("security.3F")); //$NON-NLS-1$
        }
        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        return implSpi.engineGetEntry(alias, param);
    
public static java.security.KeyStoregetInstance(java.lang.String type)
Returns a new instance of {@code KeyStore} with the specified type.

param
type the type of the returned {@code KeyStore}.
return
a new instance of {@code KeyStore} with the specified type.
throws
KeyStoreException if an error occurred during the creation of the new {@code KeyStore}.
throws
NullPointerException if {@code type} is {@code null}.
see
#getDefaultType
since
Android 1.0

        if (type == null) {
            throw new NullPointerException(Messages.getString("security.07")); //$NON-NLS-1$
        }
        synchronized (engine) {
            try {
                engine.getInstance(type, null);
                return new KeyStore((KeyStoreSpi) engine.spi, engine.provider, type);
            } catch (NoSuchAlgorithmException e) {
                throw new KeyStoreException(e.getMessage());
            }
        }
    
public static java.security.KeyStoregetInstance(java.lang.String type, java.lang.String provider)
Returns a new instance of {@code KeyStore} from the specified provider with the given type.

param
type the type of the returned {@code KeyStore}.
param
provider name of the provider of the {@code KeyStore}.
return
a new instance of {@code KeyStore} from the specified provider with the given type.
throws
KeyStoreException if an error occurred during the creation of the new {@code KeyStore}.
throws
NoSuchProviderException if the specified provider is not available.
throws
IllegalArgumentException if {@code provider} is {@code null} or the empty string.
see
#getDefaultType
since
Android 1.0

        if ((provider == null) || (provider.length() == 0)) {
            throw new IllegalArgumentException(Messages.getString("security.02")); //$NON-NLS-1$
        }
        Provider impProvider = Security.getProvider(provider);
        if (impProvider == null) {
            throw new NoSuchProviderException(provider);
        }
        try {
            return getInstance(type, impProvider);
        } catch (Exception e) {
            throw new KeyStoreException(e.getMessage(), e);
        }
    
public static java.security.KeyStoregetInstance(java.lang.String type, java.security.Provider provider)
Returns a new instance of {@code KeyStore} from the specified provider with the given type.

param
type the type of the returned {@code KeyStore}.
param
provider the provider of the {@code KeyStore}.
return
a new instance of {@code KeyStore} from the specified provider with the given type.
throws
KeyStoreException if an error occurred during the creation of the new {@code KeyStore}.
throws
IllegalArgumentException if {@code provider} is {@code null} or the empty string.
see
#getDefaultType
since
Android 1.0

        // check parameters
        if (provider == null) {
            throw new IllegalArgumentException(Messages.getString("security.04")); //$NON-NLS-1$
        }
        if (type == null) {
            throw new NullPointerException(Messages.getString("security.07")); //$NON-NLS-1$
        }
        // return KeyStore instance
        synchronized (engine) {
            try {
                engine.getInstance(type, provider, null);
                return new KeyStore((KeyStoreSpi) engine.spi, provider, type);
            } catch (Exception e) {
            // override exception
                throw new KeyStoreException(e.getMessage());
            }
        }
    
public final java.security.KeygetKey(java.lang.String alias, char[] password)
Returns the key with the given alias, using the password to recover the key from the store.

param
alias the alias for the entry.
param
password the password used to recover the key.
return
the key with the specified alias, or {@code null} if the specified alias is not bound to an entry.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
throws
NoSuchAlgorithmException if the algorithm for recovering the key is not available.
throws
UnrecoverableKeyException if the key can not be recovered.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        return implSpi.engineGetKey(alias, password);
    
public final java.security.ProvidergetProvider()
Returns the provider associated with this {@code KeyStore}.

return
the provider associated with this {@code KeyStore}.
since
Android 1.0

        return provider;
    
public final java.lang.StringgetType()
Returns the type of this {@code KeyStore}.

return
the type of this {@code KeyStore}.
since
Android 1.0

        return type;
    
public final booleanisCertificateEntry(java.lang.String alias)
Indicates whether the specified alias is associated with a {@link TrustedCertificateEntry}.

param
alias the alias of an entry.
return
{@code true} if the given alias is associated with a certificate entry.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        // BEGIN android-changed
        if (!isInit) {
            throwNotInitialized();
        }
        // END android-changed
        return implSpi.engineIsCertificateEntry(alias);
    
public final booleanisKeyEntry(java.lang.String alias)
Indicates whether the specified alias is associated with either a {@link PrivateKeyEntry} or a {@link SecretKeyEntry}.

param
alias the alias of an entry.
return
{@code true} if the given alias is associated with a key entry.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        // BEGIN android-changed
        if (!isInit) {
            throwNotInitialized();
        }
        // END android-changed
        return implSpi.engineIsKeyEntry(alias);
    
public final voidload(java.io.InputStream stream, char[] password)
Initializes this {@code KeyStore} from the provided {@code InputStream}. Pass {@code null} as the {@code stream} argument to initialize an empty {@code KeyStore} or to initialize a {@code KeyStore} which does not rely on an {@code InputStream}. This {@code KeyStore} utilizes the given password to verify the stored data.

param
stream the {@code InputStream} to load this {@code KeyStore}'s data from or {@code null}.
param
password the password to verify the stored data, maybe {@code null}.
throws
IOException if a problem occurred while reading from the stream.
throws
NoSuchAlgorithmException if the required algorithm is not available.
throws
CertificateException if an exception occurred while loading the certificates of this {@code KeyStore}.
since
Android 1.0

        implSpi.engineLoad(stream, password);
        isInit = true;
    
public final voidload(java.security.KeyStore$LoadStoreParameter param)
Loads this {@code KeyStore} using the specified {@code LoadStoreParameter}.

param
param the {@code LoadStoreParameter} that specifies how to load this {@code KeyStore}, maybe {@code null}.
throws
IOException if a problem occurred while reading from the stream.
throws
NoSuchAlgorithmException if the required algorithm is not available.
throws
CertificateException if an exception occurred while loading the certificates of this {@code KeyStore}.
throws
IllegalArgumentException if the given {@link LoadStoreParameter} is not recognized.
since
Android 1.0

        implSpi.engineLoad(param);
        isInit = true;
    
public final voidsetCertificateEntry(java.lang.String alias, java.security.cert.Certificate cert)
Associates the given alias with a certificate.

If the specified alias already exists, it will be reassigned.

param
alias the alias for the certificate.
param
cert the certificate.
throws
KeyStoreException if this {@code KeyStore} is not initialized, or an existing alias is not associated to an entry containing a trusted certificate, or this method fails for any other reason.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        implSpi.engineSetCertificateEntry(alias, cert);
    
public final voidsetEntry(java.lang.String alias, java.security.KeyStore$Entry entry, java.security.KeyStore$ProtectionParameter param)
Stores the given {@code Entry} in this {@code KeyStore} and associates the entry with the given {@code alias}. The entry is protected by the specified {@code ProtectionParameter}.

If the specified alias already exists, it will be reassigned.

param
alias the alias for the entry.
param
entry the entry to store.
param
param the {@code ProtectionParameter} to protect the entry.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        if (alias == null) {
            throw new NullPointerException(Messages.getString("security.3F")); //$NON-NLS-1$
        }
        if (entry == null) {
            throw new NullPointerException(Messages.getString("security.39")); //$NON-NLS-1$
        }
        implSpi.engineSetEntry(alias, entry, param);
    
public final voidsetKeyEntry(java.lang.String alias, java.security.Key key, char[] password, java.security.cert.Certificate[] chain)
Associates the given alias with the key, password and certificate chain.

If the specified alias already exists, it will be reassigned.

param
alias the alias for the key.
param
key the key.
param
password the password.
param
chain the certificate chain.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
throws
IllegalArgumentException if {@code key} is a {@code PrivateKey} and {@code chain} does not contain any certificates.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }

        // Certificate chain is required for PrivateKey
        if (null != key && key instanceof PrivateKey
                && (chain == null || chain.length == 0)) {
            throw new IllegalArgumentException(Messages
                    .getString("security.52")); //$NON-NLS-1$
        }
        implSpi.engineSetKeyEntry(alias, key, password, chain);
    
public final voidsetKeyEntry(java.lang.String alias, byte[] key, java.security.cert.Certificate[] chain)
Associates the given alias with a key and a certificate chain.

If the specified alias already exists, it will be reassigned.

If this {@code KeyStore} is of type {@code "jks"}, {@code key} must be encoded conform to the PKS#8 standard as an {@link javax.crypto.EncryptedPrivateKeyInfo}.

param
alias the alias for the key.
param
key the key in an encoded format.
param
chain the certificate chain.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
throws
IllegalArgumentException if {@code key} is a {@code PrivateKey} and {@code chain} does.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        implSpi.engineSetKeyEntry(alias, key, chain);
    
public final intsize()
Returns the number of entries stored in this {@code KeyStore}.

return
the number of entries stored in this {@code KeyStore}.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        return implSpi.engineSize();
    
public final voidstore(java.io.OutputStream stream, char[] password)
Writes this {@code KeyStore} to the specified {@code OutputStream}. The data written to the {@code OutputStream} is protected by the specified password.

param
stream the {@code OutputStream} to write the store's data to.
param
password the password to protect the data.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
throws
IOException if a problem occurred while writing to the stream.
throws
NoSuchAlgorithmException if the required algorithm is not available.
throws
CertificateException if an exception occurred while storing the certificates of this {@code KeyStore}.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        // BEGIN android-removed
        // copied from a newer version of harmony
        // Just delegate stream and password to implSpi
        // if (stream == null) {
        //     throw new IOException(Messages.getString("security.51")); //$NON-NLS-1$
        // }
        // if (password == null) {
        //     throw new IOException(Messages.getString("security.50")); //$NON-NLS-1$
        // }
        // END android-removed
        implSpi.engineStore(stream, password);
    
public final voidstore(java.security.KeyStore$LoadStoreParameter param)
Stores this {@code KeyStore} using the specified {@code LoadStoreParameter}.

param
param the {@code LoadStoreParameter} that specifies how to store this {@code KeyStore}, maybe {@code null}.
throws
KeyStoreException if this {@code KeyStore} is not initialized.
throws
IOException if a problem occurred while writing to the stream.
throws
NoSuchAlgorithmException if the required algorithm is not available.
throws
CertificateException if an exception occurred while storing the certificates of this {@code KeyStore}.
throws
IllegalArgumentException if the given {@link LoadStoreParameter} is not recognized.
since
Android 1.0

        if (!isInit) {
            // BEGIN android-changed
            throwNotInitialized();
            // END android-changed
        }
        implSpi.engineStore(param);
    
private static voidthrowNotInitialized()
Throws the standard "keystore not initialized" exception.

        if (NOTINITKEYSTORE == null) {
            NOTINITKEYSTORE = Messages.getString("security.4F"); //$NON-NLS-1$
        }
        throw new KeyStoreException(NOTINITKEYSTORE);