FileDocCategorySizeDatePackage
KeyStoreSpi.javaAPI DocAndroid 1.5 API21418Wed May 06 22:41:06 BST 2009java.security

KeyStoreSpi

public abstract class KeyStoreSpi extends Object
{@code KeyStoreSpi} is the Service Provider Interface (SPI) definition for {@link KeyStore}.
see
KeyStore
since
Android 1.0

Fields Summary
Constructors Summary
Methods Summary
public abstract java.util.EnumerationengineAliases()
Returns an {@code Enumeration} over all alias names stored in this {@code KeyStoreSpi}.

return
an {@code Enumeration} over all alias names stored in this {@code KeyStoreSpi}.
since
Android 1.0

public abstract booleanengineContainsAlias(java.lang.String alias)
Indicates whether the given alias is present in this {@code KeyStoreSpi}.

param
alias the alias of an entry.
return
{@code true} if the alias exists, {@code false} otherwise.
since
Android 1.0

public abstract voidengineDeleteEntry(java.lang.String alias)
Deletes the entry identified with the given alias from this {@code KeyStoreSpi}.

param
alias the alias for the entry.
throws
KeyStoreException if the entry can not be deleted.
since
Android 1.0

public booleanengineEntryInstanceOf(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}.
since
Android 1.0

        if (!engineContainsAlias(alias)) {
            return false;
        }

        try {
            if (engineIsCertificateEntry(alias)) {
                return entryClass
                        .isAssignableFrom(Class
                                .forName("java.security.KeyStore$TrustedCertificateEntry")); //$NON-NLS-1$
            }

            if (engineIsKeyEntry(alias)) {
                if (entryClass.isAssignableFrom(Class
                        .forName("java.security.KeyStore$PrivateKeyEntry"))) { //$NON-NLS-1$
                    return engineGetCertificate(alias) != null;
                }

                if (entryClass.isAssignableFrom(Class
                        .forName("java.security.KeyStore$SecretKeyEntry"))) { //$NON-NLS-1$
                    return engineGetCertificate(alias) == null;
                }
            }
        } catch (ClassNotFoundException ignore) {}

        return false;
    
public abstract java.security.cert.CertificateengineGetCertificate(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.
since
Android 1.0

public abstract java.lang.StringengineGetCertificateAlias(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.
since
Android 1.0

public abstract java.security.cert.Certificate[]engineGetCertificateChain(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.
since
Android 1.0

public abstract java.util.DateengineGetCreationDate(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.
since
Android 1.0

public java.security.KeyStore$EntryengineGetEntry(java.lang.String alias, java.security.KeyStore$ProtectionParameter protParam)
Returns the {@code Entry} with the given alias, using the specified {@code ProtectionParameter}.

param
alias the alias of the requested entry.
param
protParam 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 operation fails
since
Android 1.0

        if (!engineContainsAlias(alias)) {
            return null;
        }
        if (engineIsCertificateEntry(alias)) {
            return new KeyStore.TrustedCertificateEntry(
                    engineGetCertificate(alias));
        }
        char[] passW = null;
        if (protParam != null) {
            if (protParam instanceof KeyStore.PasswordProtection) {
                try {
                    passW = ((KeyStore.PasswordProtection) protParam)
                            .getPassword();
                } catch (IllegalStateException ee) {
                    throw new KeyStoreException(Messages.getString("security.36"), ee); //$NON-NLS-1$
                }
            } else if (protParam instanceof KeyStore.CallbackHandlerProtection) {
                passW = getPasswordFromCallBack(protParam);
            } else {
                throw new UnrecoverableEntryException(
                        Messages.getString("security.37", //$NON-NLS-1$
                                protParam.toString()));
            }
        }
        if (engineIsKeyEntry(alias)) {
            try {
                Key key = engineGetKey(alias, passW);
                if (key instanceof PrivateKey) {
                    return new KeyStore.PrivateKeyEntry((PrivateKey) key,
                            engineGetCertificateChain(alias));
                }
                if (key instanceof SecretKey) {
                    return new KeyStore.SecretKeyEntry((SecretKey) key);
                }
            } catch (UnrecoverableKeyException e) {
                throw new KeyStoreException(e);
            }
        }
        throw new NoSuchAlgorithmException(Messages.getString("security.38")); //$NON-NLS-1$
    
public abstract java.security.KeyengineGetKey(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
NoSuchAlgorithmException if the algorithm for recovering the key is not available.
throws
UnrecoverableKeyException if the key can not be recovered.
since
Android 1.0

public abstract booleanengineIsCertificateEntry(java.lang.String alias)
Indicates whether the specified alias is associated with a {@link KeyStore.TrustedCertificateEntry}.

param
alias the alias of an entry.
return
{@code true} if the given alias is associated with a certificate entry.
since
Android 1.0

public abstract booleanengineIsKeyEntry(java.lang.String alias)
Indicates whether the specified alias is associated with either a {@link KeyStore.PrivateKeyEntry} or a {@link KeyStore.SecretKeyEntry}.

param
alias the alias of an entry.
return
{@code true} if the given alias is associated with a key entry.
since
Android 1.0

public abstract voidengineLoad(java.io.InputStream stream, char[] password)
Loads this {@code KeyStoreSpi} from the given {@code InputStream}. Utilizes the given password to verify the stored data.

param
stream the {@code InputStream} to load this {@code KeyStoreSpi}'s data from.
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 the an exception occurred while loading the certificates of this code {@code KeyStoreSpi}.
since
Android 1.0

public voidengineLoad(java.security.KeyStore$LoadStoreParameter param)
Loads this {@code KeyStoreSpi} using the specified {@code LoadStoreParameter}.

param
param the {@code LoadStoreParameter} that specifies how to load this {@code KeyStoreSpi}, 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 the an exception occurred while loading the certificates of this code {@code KeyStoreSpi}.
throws
IllegalArgumentException if the given {@link KeyStore.LoadStoreParameter} is not recognized.
since
Android 1.0

        if (param == null) {
            engineLoad(null, null);
            return;
        }
        char[] pwd;
        KeyStore.ProtectionParameter pp = param.getProtectionParameter();
        if (pp instanceof KeyStore.PasswordProtection) {
            try {
                pwd = ((KeyStore.PasswordProtection) pp).getPassword();
                engineLoad(null, pwd);
                return;
            } catch (IllegalStateException e) {
                throw new IllegalArgumentException(e);
            }
        }
        if (pp instanceof KeyStore.CallbackHandlerProtection) {
            try {
                pwd = getPasswordFromCallBack(pp);
                engineLoad(null, pwd);
                return;
            } catch (UnrecoverableEntryException e) {
                throw new IllegalArgumentException(e);
            }
        }
        throw new UnsupportedOperationException(
                Messages.getString("security.35")); //$NON-NLS-1$
    
public abstract voidengineSetCertificateEntry(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 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

public voidengineSetEntry(java.lang.String alias, java.security.KeyStore$Entry entry, java.security.KeyStore$ProtectionParameter protParam)
Stores the given {@code Entry} in this {@code KeyStoreSpi} 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
protParam the {@code ProtectionParameter} to protect the entry.
throws
KeyStoreException if this operation fails.
since
Android 1.0

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

        if (engineContainsAlias(alias)) {
            engineDeleteEntry(alias);
        }

        if (entry instanceof KeyStore.TrustedCertificateEntry) {
            KeyStore.TrustedCertificateEntry trE = (KeyStore.TrustedCertificateEntry) entry;
            engineSetCertificateEntry(alias, trE.getTrustedCertificate());
            return;
        }

        char[] passW = null;
        if (protParam instanceof KeyStore.PasswordProtection) {
            try {
                passW = ((KeyStore.PasswordProtection) protParam).getPassword();
            } catch (IllegalStateException ee) {
                throw new KeyStoreException(Messages.getString("security.36"), ee); //$NON-NLS-1$
            }
        } else {
            if (protParam instanceof KeyStore.CallbackHandlerProtection) {
                try {
                    passW = getPasswordFromCallBack(protParam);
                } catch (Exception e) {
                    throw new KeyStoreException(e);
                }
            } else {
                throw new KeyStoreException(
                        Messages.getString("security.3A")); //$NON-NLS-1$
            }
        }

        if (entry instanceof KeyStore.PrivateKeyEntry) {
            KeyStore.PrivateKeyEntry prE = (KeyStore.PrivateKeyEntry) entry;
            engineSetKeyEntry(alias, prE.getPrivateKey(), passW, prE
                    .getCertificateChain());
            return;
        }

        if (entry instanceof KeyStore.SecretKeyEntry) {
            KeyStore.SecretKeyEntry skE = (KeyStore.SecretKeyEntry) entry;
            engineSetKeyEntry(alias, skE.getSecretKey(), passW, null);
            //            engineSetKeyEntry(alias, skE.getSecretKey().getEncoded(), null);
            return;
        }

        throw new KeyStoreException(
                Messages.getString("security.3B", entry.toString())); //$NON-NLS-1$
    
public abstract voidengineSetKeyEntry(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 the specified key can not be protected, or if this operation fails for another reason.
throws
IllegalArgumentException if {@code key} is a {@code PrivateKey} and {@code chain} does not contain any certificates.
since
Android 1.0

public abstract voidengineSetKeyEntry(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.

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

public abstract intengineSize()
Returns the number of entries stored in this {@code KeyStoreSpi}.

return
the number of entries stored in this {@code KeyStoreSpi}.
since
Android 1.0

public abstract voidengineStore(java.io.OutputStream stream, char[] password)
Writes this {@code KeyStoreSpi} 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
IOException if a problem occurred while writing to the stream.
throws
NoSuchAlgorithmException if the required algorithm is not available.
throws
CertificateException if the an exception occurred while storing the certificates of this code {@code KeyStoreSpi}.
since
Android 1.0

public voidengineStore(java.security.KeyStore$LoadStoreParameter param)
Stores this {@code KeyStoreSpi} using the specified {@code LoadStoreParameter}.

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

        throw new UnsupportedOperationException(Messages.getString("security.33")); //$NON-NLS-1$
    
static char[]getPasswordFromCallBack(java.security.KeyStore$ProtectionParameter protParam)


        if (protParam == null) {
            return null;
        }

        if (!(protParam instanceof KeyStore.CallbackHandlerProtection)) {
            throw new UnrecoverableEntryException(
                    Messages.getString("security.3C")); //$NON-NLS-1$
        }

        String clName = Security
                .getProperty("auth.login.defaultCallbackHandler"); //$NON-NLS-1$
        if (clName == null) {
            throw new UnrecoverableEntryException(
                    Messages.getString("security.3D")); //$NON-NLS-1$

        }

        try {
            Class<?> cl = Class.forName(clName);
            CallbackHandler cbHand = (CallbackHandler) cl.newInstance();
            PasswordCallback[] pwCb = { new PasswordCallback("password: ", true) }; //$NON-NLS-1$
            cbHand.handle(pwCb);
            return pwCb[0].getPassword();
        } catch (Exception e) {
            throw new UnrecoverableEntryException(e.toString());
        }