iaik.pkcs.pkcs12

Class PKCS12KeyStore

java.lang.Object

java.security.KeyStoreSpi

iaik.pkcs.pkcs12.PKCS12KeyStore

public class PKCS12KeyStore
extends java.security.KeyStoreSpi

This class implements the KeyStore Service Provider Interface (SPI) to load and save PKCS#12 files, which contain private key entries (private keys and certificate chains) and certificate entries (X.509 certificates).

Note that there has been a change in the API from version IAIK-JCE 5.2 to IAIK-JCE 5.3. The PKCS12KeyStore implementation of version 5.2 (or lower) only supported private key entries (private keys and certificate chains) as this is the most widely used format for saving private keys with certificates in files (supported by Microsoft Windows^TM, Microsoft Internet Explorer^TM, Microsoft Outlook^TM, Mozilla Firefox, Mozilla Thunderbird,...).

If you want to instantiate a KeyStore, specify keystore type and provider.

 KeyStore ks = KeyStore.getInstance("PKCS12", "IAIK");
 

Before a KeyStore can be used, it must be loaded.

 ks.load(inputStream, password);
 

You must even load the KeyStore in case you instantiate a new empty KeyStore object. In this case, the parameters shall be null.

 ks.load(null, null);
 

Implementation Details

This implementation of the KeyStoreSpi loads and stores files according to the PKCS#12 v1.0: Personal Information Exchange Syntax. You can get this document from the RSA Laboratories.

The keystore loads private keys and certificate chains from a password-encrypted PKCS#12-file (e.g. .pfx, .p12). Inside the PKCS#12 file, the localKeyID is used to match the private key with the corresponding certificate. KeyEntries, set with method KeyStore.setKeyEntry(String, byte[], Certificate[]) or KeyStore.setKeyEntry(String, Key, char[], Certificate[]) use the current time (Milliseconds since 1970) as key ID. When loading a file, the creation date is extracted from this ID if possible. With method KeyStore.store(OutputStream, char[]), all keys and certificate chains are saved in a PKCS#12 file.

This implementation supports multiple keys and certificate chains within one PKCS#12 file, and also multiple certificate entries.

PKCS#12 carries certificates in CertBags, and keys in KeyBags. The relationship between a certificate contained in a CertBag and the corresponding key contained in a KeyBag may be established by giving Cert- and KeyBag the same lokaleKeyId and/or friendlyName attribute. This KeyStore implementation follows the following strategy for getting/setting the ceritifcates for Key- and Certificate Entries from/for a PKCS#12 KeyStore:

1. For any private key contained in the PKCS#12 object all CertBags are searched for matching localeKeyId or friendlyName/alias attributes. A certificate is bound to the private key of a KeyEntry if its CertBag has the same lokaleKeyId or friendlyName/alias (in that order) as the KeyBag that carries this private key. When calling keyStore.getCertificateChain this certificate is located at index 0 of the returned certificate chain. The remaining certificates of the certificate chain are got from all other CertBags (regardless of their attributes) by trying to build a certificate path for the "index-0" certificate based on IssuerDN/SubjecDN and AuthorityKeyIdentifier/SubjectKeyIdentifier (if available) relationship.
2. Any certificate contained in a CertBag with a friendlyName/alias that does not also belong to any KeyBag is considered as certificate (trust) entry.
3. Any certificate carried by a CertBag with no friendlyName/alias is ignored unless it belongs to the certificate chain of a key entry. Any certificate carried by a CertBag with a friendlyName/alias that is already used by a KeyBag is ignored unless it belongs to the certificate chain of a key entry. Note that ignored certificates are lost when storing the KeyStore anew.

Note that one and the same certificate may belong to the certificate chain of an key entry and also may represent a trust entry (when its CertBag has a friendlyName/alias that is not used by any KeyBag.
Note that certificate entries are trust entries! When you open a PKCS#12 file created by some other application be sure that all certificate entries got from this KeyStore actually represent your trusted certificates!

Version:

File Revision 12

Constructor Summary

Constructors

Constructor and Description
PKCS12KeyStore() Creates a new PKCS#12 KeyStore object.

Method Summary

Methods

Modifier and Type	Method and Description
java.util.Enumeration	engineAliases()
boolean	engineContainsAlias(java.lang.String alias) Checks if the given alias exists in this keystore.
void	engineDeleteEntry(java.lang.String alias) Deletes the entry identified by the given alias from this keystore.
java.security.cert.Certificate	engineGetCertificate(java.lang.String alias) Returns the certificate associated with the given alias.
java.lang.String	engineGetCertificateAlias(java.security.cert.Certificate cert) Returns the (alias) name of the first keystore entry whose certificate matches the given certificate.
java.security.cert.Certificate[]	engineGetCertificateChain(java.lang.String alias) Returns the certificate chain associated with the given alias.
java.util.Date	engineGetCreationDate(java.lang.String alias) Returns the creation date of the entry identified by the given alias or - if not available - the date on which the certificate became valid.
java.security.Key	engineGetKey(java.lang.String alias, char[] password) Returns the key associated with the given alias, using the given password to recover it.
boolean	engineIsCertificateEntry(java.lang.String alias) Checks if the entry with the given alias represents a certificate entry.
boolean	engineIsKeyEntry(java.lang.String alias) Returns true if the entry identified by the given alias was created by a call to setKeyEntry, or created by a call to setEntry with a PrivateKeyEntry or a SecretKeyEntry.
void	engineLoad(java.io.InputStream stream, char[] password) Loads the keystore from the given input stream.
void	engineSetCertificateEntry(java.lang.String alias, java.security.cert.Certificate cert) Assigns the given certificate to the given alias.
void	engineSetKeyEntry(java.lang.String alias, byte[] key, java.security.cert.Certificate[] chain) Assigns the given key (that has already been protected) to the given alias.
void	engineSetKeyEntry(java.lang.String alias, java.security.Key key, char[] password, java.security.cert.Certificate[] chain) Assigns the given key to the given alias, protecting it with the given password.
int	engineSize()
void	engineStore(java.io.OutputStream stream, char[] password) Stores this keystore to the given output stream, and protects its integrity with the given password.

Methods inherited from class java.security.KeyStoreSpi

engineEntryInstanceOf, engineGetEntry, engineLoad, engineSetEntry, engineStore

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PKCS12KeyStore

public PKCS12KeyStore()

Creates a new PKCS#12 KeyStore object.

Method Detail

engineLoad

public void engineLoad(java.io.InputStream stream,
              char[] password)
                throws java.io.IOException,
                       java.security.NoSuchAlgorithmException,
                       java.security.cert.CertificateException

Loads the keystore from the given input stream. A password may be given to unlock the keystore and to check the integrity of the keystore. If a password is not given, no password has been set when saving the keystore.

Set both parameters to null to initialize an new empty keystore.

Specified by:

engineLoad in class java.security.KeyStoreSpi

Parameters:

stream - the input stream from which the keystore is loaded, or null

password - the password used to check the integrity of the keystore, the password used to unlock the keystore, or null

Throws:

java.io.IOException - if there is an I/O or format problem with the keystore data, if a password is required but not given, or if the given password was incorrect

java.security.NoSuchAlgorithmException - if the algorithm used to check the integrity of the keystore cannot be found

java.security.cert.CertificateException - if any of the certificates in the keystore could not be loaded

engineAliases

public java.util.Enumeration engineAliases()

Specified by:

engineAliases in class java.security.KeyStoreSpi

Returns:

An enumeration of the alias names of all entries in this keystore.

engineContainsAlias

public boolean engineContainsAlias(java.lang.String alias)

Checks if the given alias exists in this keystore.

Specified by:

engineContainsAlias in class java.security.KeyStoreSpi

Parameters:

alias - The alias name.

Returns:

true if the alias exists, false otherwise.

engineDeleteEntry

public void engineDeleteEntry(java.lang.String alias)
                       throws java.security.KeyStoreException

Deletes the entry identified by the given alias from this keystore.

Specified by:

engineDeleteEntry in class java.security.KeyStoreSpi

Parameters:

alias - The alias name.

Throws:

java.security.KeyStoreException - If the entry cannot be removed.

engineGetCertificate

public java.security.cert.Certificate engineGetCertificate(java.lang.String alias)

Returns the certificate associated with the given alias. If the given alias name identifies an entry created by a call to setKeyEntry, or created by a call to setEntry with a PrivateKeyEntry, then the first element of the certificate chain in that entry (if a chain exists) is returned. If the given alias name identifies an entry created by a call to setCertificateEntry, or created by a call to setEntry with a certificate, then this certificate is returned.

Specified by:

engineGetCertificate in class java.security.KeyStoreSpi

Parameters:

alias - the alias name

Returns:

the certificate, or null if the given alias does not exist or does not reference a certificate.

engineGetCertificateAlias

public java.lang.String engineGetCertificateAlias(java.security.cert.Certificate cert)

Returns the (alias) name of the first keystore entry whose certificate matches the given certificate. This method attempts to match the given certificate with each keystore entry. If the entry being considered was created by a call to setKeyEntry, or created by a call to setEntry with a PrivateKeyEntry, then the given certificate is compared to the first element of that entry's certificate chain. If the entry being considered was created by a call to setCertificateEntry, or created by a call to setEntry with a certificate, then the given certificate is compared to the certificate of this entry.

Specified by:

engineGetCertificateAlias in class java.security.KeyStoreSpi

Parameters:

cert - the certificate to match with.

Returns:

the alias name of the first entry with matching certificate, or null if no such entry exists in this keystore.

engineGetCertificateChain

public java.security.cert.Certificate[] engineGetCertificateChain(java.lang.String alias)

Returns the certificate chain associated with the given alias. The certificate chain must have been associated with the alias by a call to setKeyEntry, or by a call to setEntry with a PrivateKeyEntry.

Specified by:

engineGetCertificateChain in class java.security.KeyStoreSpi

Parameters:

alias - the alias name

Returns:

the certificate chain (ordered with the user's certificate first and the root certificate authority last), or null if the given alias does not exist or does not contain a certificate chain

engineGetCreationDate

public java.util.Date engineGetCreationDate(java.lang.String alias)

Returns the creation date of the entry identified by the given alias or - if not available - the date on which the certificate became valid.

Specified by:

engineGetCreationDate in class java.security.KeyStoreSpi

Parameters:

alias - the alias name

Returns:

the creation date of this entry, or null if the given alias does not exist

engineGetKey

public java.security.Key engineGetKey(java.lang.String alias,
                             char[] password)
                               throws java.security.NoSuchAlgorithmException,
                                      java.security.UnrecoverableKeyException

Returns the key associated with the given alias, using the given password to recover it. The key must have been associated with the alias by a call to setKeyEntry, or by a call to setEntry with a PrivateKeyEntry or SecretKeyEntry.

Specified by:

engineGetKey in class java.security.KeyStoreSpi

Parameters:

alias - the alias name

password - the password for recovering the key

Returns:

the requested key, or null if the given alias does not exist or does not identify a key-related entry.

Throws:

java.security.NoSuchAlgorithmException - if the algorithm for recovering the key cannot be found

java.security.UnrecoverableKeyException - if the key cannot be recovered (e.g. the given password is wrong).

engineIsCertificateEntry

public boolean engineIsCertificateEntry(java.lang.String alias)

Checks if the entry with the given alias represents a certificate entry.

Specified by:

engineIsCertificateEntry in class java.security.KeyStoreSpi

Parameters:

alias - the alias for the keystore entry to be checked

Returns:

true if the keystore contains an entry with the given alias is present and the entry represents a certificate entry, false otherwise

engineIsKeyEntry

public boolean engineIsKeyEntry(java.lang.String alias)

Returns true if the entry identified by the given alias was created by a call to setKeyEntry, or created by a call to setEntry with a PrivateKeyEntry or a SecretKeyEntry.

Specified by:

engineIsKeyEntry in class java.security.KeyStoreSpi

Parameters:

alias - the alias for the keystore entry to be checked

Returns:

true if the entry identified by the given alias is a key-related, false otherwise.

engineSetCertificateEntry

public void engineSetCertificateEntry(java.lang.String alias,
                             java.security.cert.Certificate cert)
                               throws java.security.KeyStoreException

Assigns the given certificate to the given alias.
If the given alias already exists and identifies another cert entry, the keystore information associated with it is overridden by the given certificate. However, if an already exiting alias identifies a key entry, a KeyStore exception is thrown to not allow using the same alias for key- and cert-entries.

Specified by:

engineSetCertificateEntry in class java.security.KeyStoreSpi

Parameters:

alias - the alias name

cert - the certificate to be associated with the alias

Throws:

java.security.KeyStoreException - if this operation fails, e.g. the given alias was already used for a KeyEntry of this keystore

engineSetKeyEntry

public void engineSetKeyEntry(java.lang.String alias,
                     byte[] key,
                     java.security.cert.Certificate[] chain)
                       throws java.security.KeyStoreException

Assigns the given key (that has already been protected) to the given alias. If the protected key is of type java.security.PrivateKey, it must be accompanied by a certificate chain certifying the corresponding public key. This certificate chain must be arranged having the end-user certificate at index 0 and the top-CA-certificate at the end of the chain. If the given alias already exists and identifies another key entry, the keystore information associated with it is overridden by the given key and certificate chain. However, if an already exiting alias identifies a cert entry, a KeyStore exception is thrown to not allow using the same alias for key- and cert-entries.

Specified by:

engineSetKeyEntry in class java.security.KeyStoreSpi

Parameters:

alias - the alias name

key - the key (in protected format) to be associated with the alias

chain - the certificate chain for the corresponding public key (only useful if the protected key is of type java.security.PrivateKey).

Throws:

java.security.KeyStoreException - if this operation fails, e.g. the given alias was already used for a CertEntry of this keystore

engineSetKeyEntry

public void engineSetKeyEntry(java.lang.String alias,
                     java.security.Key key,
                     char[] password,
                     java.security.cert.Certificate[] chain)
                       throws java.security.KeyStoreException

Assigns the given key to the given alias, protecting it with the given password. If the given key is of type PrivateKey, it must be accompanied by a certificate chain certifying the corresponding public key. This certificate chain must be arranged having the end-user certificate at index 0 and the top-CA-certificate at the end of the chain. If the given alias already exists and identifies another key entry, the keystore information associated with it is overridden by the given key and certificate chain. However, if an already exiting alias identifies a cert entry, a KeyStore exception is thrown to not allow using the same alias for key- and cert-entries.

The provided password is ignored. Only the password provided to the engineStore(OutputStream, char[]) is used.

Specified by:

engineSetKeyEntry in class java.security.KeyStoreSpi

Parameters:

alias - the alias name

key - the key to be associated with the alias

password - the password to encrypt the key with

chain - the certificate chain for the corresponding public key (only required if the given key is of type java.security.PrivateKey).

Throws:

java.security.KeyStoreException - if the given key cannot be protected, or this operation fails for some other reason, e.g. the given alias was already used for a CertEntry of this keystore

engineSize

public int engineSize()

Specified by:

engineSize in class java.security.KeyStoreSpi

Returns:

The number of entries in this keystore.

engineStore

public void engineStore(java.io.OutputStream stream,
               char[] password)
                 throws java.io.IOException,
                        java.security.NoSuchAlgorithmException,
                        java.security.cert.CertificateException

Stores this keystore to the given output stream, and protects its integrity with the given password.

Specified by:

engineStore in class java.security.KeyStoreSpi

Parameters:

stream - the output stream to which this keystore is written.

password - the password to generate the keystore integrity check

Throws:

java.io.IOException - if there was an I/O problem with data

java.security.NoSuchAlgorithmException - if the appropriate data integrity algorithm could not be found

java.security.cert.CertificateException - if any of the certificates included in the keystore data could not be stored