org.dihedron.crypto

Class KeyRing

java.lang.Object

org.dihedron.crypto.KeyRing

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

MicrosoftKeyRing, PKCS12KeyRing, SmartCardKeyRing

public abstract class KeyRing
extends Object
implements Closeable

The base abstract class providing an abstract interface to several different kinds of key stores. Support for the Closeable interface provides a way to use this class (and its concrete sub-classes) in try-with-resources blocks (Java7 and later).

Author:

Andrea Funto'

Field Summary

Fields

Modifier and Type	Field and Description
static String	SIGNATURE_CRITICAL_EXTENSION_OID The critical extension that signature certificates must have in order to be recognised as valid for signing.

Constructor Summary

Constructors

Constructor and Description
KeyRing()

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Attempts to log out of the KeyStore, and releases its reference.
protected abstract void	closeImpl() Logs out of the key store, if supported by the underlying technology.
List<String>	enumerateAliases() Returns a list of aliases for the given key store.
Certificate	getCertificate(String alias) Retrieves the certificate for the given alias.
List<Certificate>	getCertificateChain(String signatureAlias) Gets the certificate chain for the given alias.
Certificate[]	getCertificateChainAsArray(String signatureAlias) Gets the certificate chain for the given alias, as an array of Certificates.
KeyPair	getKeyPair(String alias, String password) Gets a private and public key pair for the given alias.
KeyStore	getKeyStore() Deprecated.
Key	getPrivateKey(String alias) Returns the private key (or a proxy) for the given alias.
Key	getPrivateKey(String alias, String password) Returns the private key for the given alias, using the provided password to unlock it; the key pair (private/public) password can differ from that of the key store it is kept in.
Key	getPublicKey(String alias) Returns the public key for the given alias.
Key	getPublicKey(String alias, String password) Returns the public key for the given alias, using the provided password to unlock it; the key pair (private/public) password can differ from that of the key store it is kept in.
List<String>	getSignatureKeyAliases() Retrieves a list of aliases corresponding to certificates that bear the "signature" critical extension OID.
boolean	isCertificateAlias(String alias) Checks whether the alias has a corresponding certificate.
boolean	isPrivateKeyAlias(String alias) Checks whether the alias has a corresponding private key.
KeyRing	open() Acquires a reference to a KeyStore and returns its reference after having logged in.
protected abstract KeyStore	openImpl() Loads and logs in to the key store.

Methods inherited from class java.lang.Object

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

Field Detail

SIGNATURE_CRITICAL_EXTENSION_OID

public static final String SIGNATURE_CRITICAL_EXTENSION_OID

The critical extension that signature certificates must have in order to be recognised as valid for signing.

See Also:

Constant Field Values

Constructor Detail

KeyRing

public KeyRing()

Method Detail

open

public KeyRing open()
             throws CryptoException

Acquires a reference to a KeyStore and returns its reference after having logged in. Once the application is done with the KeyStore, it should go back to its wrapper to release its reference; this will effectively attempt to log out of it.

Returns:

a reference to the object itself, for method chaining.

Throws:

CryptoException

close

public void close()

Attempts to log out of the KeyStore, and releases its reference.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

CryptoException

openImpl

protected abstract KeyStore openImpl()
                              throws CryptoException

Loads and logs in to the key store.

Throws:

CryptoException - if an I/O or a key store specific error occurs while loading the key store.

closeImpl

protected abstract void closeImpl()
                           throws CryptoException

Logs out of the key store, if supported by the underlying technology.

Throws:

CryptoException - if a communication error with the underlying device occurs.

getKeyStore

@Deprecated
public KeyStore getKeyStore()

Deprecated.

Gives access to the underlying key store; it is deprecated because improper manipulation of the wrapped key store may result in inconsistent system state.

Returns:

the internal key store object.

enumerateAliases

public List<String> enumerateAliases()
                              throws CryptoException

Returns a list of aliases for the given key store.

Returns:

a list of aliases for the given key store.

Throws:

CryptoException - if an error occurs while enumerating the aliases in the key store.

isPrivateKeyAlias

public boolean isPrivateKeyAlias(String alias)
                          throws CryptoException

Checks whether the alias has a corresponding private key.

Parameters:

alias - the name of the alias

Returns:

true if it corresponds to a private key, false otherwise.

Throws:

CryptoException - if an error occurs while checking the given alias with the key store.

isCertificateAlias

public boolean isCertificateAlias(String alias)
                           throws CryptoException

Checks whether the alias has a corresponding certificate.

Parameters:

alias - the name of the alias.

Returns:

true if it corresponds to a certificate, false otherwise.

Throws:

CryptoException - if an error occurs while checking the given alias with the key store.

getPrivateKey

public Key getPrivateKey(String alias)
                  throws CryptoException

Returns the private key (or a proxy) for the given alias.

Parameters:

alias - the name of the alias.

Returns:

the private key.

Throws:

CryptoException - if there was an error accessing the private key for the given alias.

getPrivateKey

public Key getPrivateKey(String alias,
                String password)
                  throws CryptoException

Returns the private key for the given alias, using the provided password to unlock it; the key pair (private/public) password can differ from that of the key store it is kept in.

Parameters:

alias - the name of the alias.

password - the private key password.

Returns:

the private key.

Throws:

CryptoException - if there was an error accessing the private key for the given alias.

getPublicKey

public Key getPublicKey(String alias)
                 throws CryptoException

Returns the public key for the given alias.

Parameters:

alias - the name of the alias.

Returns:

the public key.

Throws:

CryptoException - if there was an error accessing the public key for the given alias.

getPublicKey

public Key getPublicKey(String alias,
               String password)
                 throws CryptoException

Returns the public key for the given alias, using the provided password to unlock it; the key pair (private/public) password can differ from that of the key store it is kept in.

Parameters:

alias - the name of the alias.

password - the public key password.

Returns:

the public key.

Throws:

CryptoException - if there was an error accessing the public key for the given alias.

getCertificate

public Certificate getCertificate(String alias)
                           throws CryptoException

Retrieves the certificate for the given alias.

Parameters:

alias - the name of the alias.

Returns:

the certificate.

Throws:

CryptoException - if an error occurs extracting the certificate for the given alias from the key store.

getKeyPair

public KeyPair getKeyPair(String alias,
                 String password)
                   throws CryptoException

Gets a private and public key pair for the given alias.

Parameters:

alias - the name of the alias.

password - the private an public key password.

Returns:

a key pair, containing both private and public key.

Throws:

CryptoException - if an error occurs extracting either the private of the public key.

getSignatureKeyAliases

public List<String> getSignatureKeyAliases()
                                    throws CryptoException

Retrieves a list of aliases corresponding to certificates that bear the "signature" critical extension OID.

Returns:

a list of signature aliases.

Throws:

CryptoException - if it cannot enumerate aliases in the keystore.

getCertificateChain

public List<Certificate> getCertificateChain(String signatureAlias)
                                      throws CryptoException

Gets the certificate chain for the given alias.

Parameters:

signatureAlias - the name of the alias.

Returns:

the certificate chain.

Throws:

CryptoException - if it cannot reconstruct the certificate chain.

getCertificateChainAsArray

public Certificate[] getCertificateChainAsArray(String signatureAlias)
                                         throws CryptoException

Gets the certificate chain for the given alias, as an array of Certificates.

Parameters:

signatureAlias - the name of the alias.

Returns:

an array of Certificates, or null if none found.

Throws:

CryptoException - if it cannot reconstruct the certificate chain.