org.nhindirect.common.crypto.impl

Class AbstractPKCS11TokenKeyStoreProtectionManager

java.lang.Object

org.nhindirect.common.crypto.impl.AbstractPKCS11TokenKeyStoreProtectionManager

All Implemented Interfaces:

KeyStoreProtectionManager, MutableKeyStoreProtectionManager, WrappableKeyProtectionManager

Direct Known Subclasses:

DynamicPKCS11TokenKeyStoreProtectionManager, StaticPKCS11TokenKeyStoreProtectionManager

public abstract class AbstractPKCS11TokenKeyStoreProtectionManager
extends Object
implements MutableKeyStoreProtectionManager, WrappableKeyProtectionManager

Abstract base class for accessing key store pass phrases from a PKCS11 token. Concrete implementations define methods for logging into the token.

For key wrapping, this class utilizes the AES/CBC/PKCS5Padding algorithm with a static initialization vector.

Since:

1.3

Author:

Greg Meyer

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_KESTORE_TYPE
static byte[]	IV_BYTES
static String	SUNPKCS11_KEYSTORE_PROVIDER_NAME
static String	WRAP_ALGO

Constructor Summary

Constructors

Constructor and Description
AbstractPKCS11TokenKeyStoreProtectionManager() Empty constructor.
AbstractPKCS11TokenKeyStoreProtectionManager(PKCS11Credential credential, String keyStorePassPhraseAlias, String privateKeyPassPhraseAlias) Constructor that takes a credential interface for logging into the token.

Method Summary

Modifier and Type	Method and Description
void	clearEntry(String alias) Generic method to clear an arbitrary entry.
void	clearKey(String alias) Generic method to clear an arbitrary key.
void	clearKeyStoreProtectionKey() Clears the key use to protect the key store.
void	clearPrivateKeyProtectionKey() Clears the key use to protect the private key.
Map<String,KeyStore.Entry>	getAllEntries() Gets a Map of all entries managed by the token.
Map<String,Key>	getAllKeys() Gets a Map of all keys managed by the token.
KeyStore.Entry	getEntry(String entryName) Gets a specific entry by name
Key	getKey(String keyName) Gets a specific key by name.
Key	getKeyStoreProtectionKey() Gets the key protecting private keys in the key store.
KeyStore	getKS() Gets the underlying KeyStore object.
Key	getPrivateKeyProtectionKey() Gets the key protecting the key store as a whole.
abstract void	initTokenStore() Initializes access to the token.
void	setCredential(PKCS11Credential credential) Sets the credential used to log into the token.
void	setEntry(String alias, KeyStore.Entry entry) Generic method to set an arbitrary entry.
void	setKey(String alias, Key key) Generic method to set an arbitrary key.
void	setKeyStorePassPhraseAlias(String keyStorePassPhraseAlias) Sets the alias name of the key store key in the PKCS11 token.
void	setKeyStoreProtectionKey(Key key) Sets key used to protect the key store as a Key object.
void	setKeyStoreProtectionKeyAsBytes(byte[] key) Sets key used to protect the key store as a byte array.
void	setKeyStoreProtectionKeyAsString(String key) Sets key used to protect the key store as a string.
void	setKeyStoreProviderName(String keyStoreProviderName)
void	setKeyStoreSource(InputStream keyStoreSource)
void	setKeyStoreSourceAsString(String keyStoreSource)
void	setKeyStoreType(String keyStoreType)
void	setPcks11ConfigFile(String pcks11ConfigFile)
void	setPrivateKeyPassPhraseAlias(String privateKeyPassPhraseAlias) Sets the alias name of the private key protection key in the PKCS11 token.
void	setPrivateKeyProtectionKey(Key key) Sets key used to protect the private key as a Key object.
void	setPrivateKeyProtectionKeyAsBytes(byte[] key) Sets the key used to protect the private key as a byte array.
void	setPrivateKeyProtectionKeyAsString(String key) Sets the key used to protect the private key as a string.
Key	unwrapWithSecretKey(SecretKey kek, byte[] wrappedData, String keyAlg, int keyType) Unwraps the key with a symmetric secret key encryption key.
byte[]	wrapWithSecretKey(SecretKey kek, Key keyToWrap) Wraps a key with a symmetric secret key encryption key.

Methods inherited from class java.lang.Object

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

Field Detail

SUNPKCS11_KEYSTORE_PROVIDER_NAME

public static final String SUNPKCS11_KEYSTORE_PROVIDER_NAME

See Also:

Constant Field Values

DEFAULT_KESTORE_TYPE

public static final String DEFAULT_KESTORE_TYPE

See Also:

Constant Field Values

WRAP_ALGO

public static final String WRAP_ALGO

See Also:

Constant Field Values

IV_BYTES

public static final byte[] IV_BYTES

Constructor Detail

AbstractPKCS11TokenKeyStoreProtectionManager

public AbstractPKCS11TokenKeyStoreProtectionManager()
                                             throws CryptoException

Empty constructor.

Throws:

CryptoException

AbstractPKCS11TokenKeyStoreProtectionManager

public AbstractPKCS11TokenKeyStoreProtectionManager(PKCS11Credential credential,
                                                    String keyStorePassPhraseAlias,
                                                    String privateKeyPassPhraseAlias)
                                             throws CryptoException

Constructor that takes a credential interface for logging into the token.

Parameters:

credential - The credential used to log into the token.

keyStorePassPhraseAlias - The alias name of the key store key in the PKCS11 token.

privateKeyPassPhraseAlias - The alias name of the private key protection key in the PKCS11 token.

Throws:

CryptoException

Method Detail

setCredential

public void setCredential(PKCS11Credential credential)

Sets the credential used to log into the token.

Parameters:

credential - The credential used to log into the token.

setKeyStorePassPhraseAlias

public void setKeyStorePassPhraseAlias(String keyStorePassPhraseAlias)

Sets the alias name of the key store key in the PKCS11 token.

Parameters:

keyStorePassPhraseAlias - The alias name of the key store key in the PKCS11 token.

setPrivateKeyPassPhraseAlias

public void setPrivateKeyPassPhraseAlias(String privateKeyPassPhraseAlias)

Sets the alias name of the private key protection key in the PKCS11 token.

Parameters:

privateKeyPassPhraseAlias - the alias name of the private key protection key in the PKCS11 token.

setKeyStoreType

public void setKeyStoreType(String keyStoreType)

setKeyStoreSource

public void setKeyStoreSource(InputStream keyStoreSource)

setKeyStoreSourceAsString

public void setKeyStoreSourceAsString(String keyStoreSource)

setKeyStoreProviderName

public void setKeyStoreProviderName(String keyStoreProviderName)

setPcks11ConfigFile

public void setPcks11ConfigFile(String pcks11ConfigFile)

initTokenStore

public abstract void initTokenStore()
                             throws CryptoException

Initializes access to the token. This is implementation specific and may require user interaction.

Throws:

CryptoException

getAllKeys

public Map<String,Key> getAllKeys()
                           throws CryptoException

Gets a Map of all keys managed by the token.

Specified by:

getAllKeys in interface KeyStoreProtectionManager

Returns:

Returns a map of all keys in the token. The mapping is string alias to the key.

Throws:

CryptoException

getKey

public Key getKey(String keyName)
           throws CryptoException

Gets a specific key by name.

Specified by:

getKey in interface KeyStoreProtectionManager

Parameters:

keyName - The name of the key to retrieve. Returns null if the key doesn't exist.

Returns:

They key specified by the name.

Throws:

CryptoException

getPrivateKeyProtectionKey

public Key getPrivateKeyProtectionKey()
                               throws CryptoException

Gets the key protecting the key store as a whole.

Specified by:

getPrivateKeyProtectionKey in interface KeyStoreProtectionManager

Returns:

The key protecting the key store as a whole.

Throws:

CryptoException

getKeyStoreProtectionKey

public Key getKeyStoreProtectionKey()
                             throws CryptoException

Gets the key protecting private keys in the key store.

Specified by:

getKeyStoreProtectionKey in interface KeyStoreProtectionManager

Returns:

The key protecting private keys in the key store.

Throws:

CryptoException

getAllEntries

public Map<String,KeyStore.Entry> getAllEntries()
                                         throws CryptoException

Gets a Map of all entries managed by the token.

Specified by:

getAllEntries in interface KeyStoreProtectionManager

Returns:

Returns a map of all entries in the token. The mapping is a string alias to the entry.

Throws:

CryptoException

getEntry

public KeyStore.Entry getEntry(String entryName)
                        throws CryptoException

Gets a specific entry by name

Specified by:

getEntry in interface KeyStoreProtectionManager

Parameters:

entryName - The name of the entry to retrieve. Returns null if the entry doesn't exist.

Returns:

They entry specified by the name.

Throws:

CryptoException

setPrivateKeyProtectionKey

public void setPrivateKeyProtectionKey(Key key)
                                throws CryptoException

Sets key used to protect the private key as a Key object.

Specified by:

setPrivateKeyProtectionKey in interface MutableKeyStoreProtectionManager

Parameters:

key - The key used to protect private keys.

Throws:

CryptoException

setPrivateKeyProtectionKeyAsBytes

public void setPrivateKeyProtectionKeyAsBytes(byte[] key)
                                       throws CryptoException

Sets the key used to protect the private key as a byte array.

Specified by:

setPrivateKeyProtectionKeyAsBytes in interface MutableKeyStoreProtectionManager

Parameters:

key - The key used to protect private keys.

Throws:

CryptoException

setPrivateKeyProtectionKeyAsString

public void setPrivateKeyProtectionKeyAsString(String key)
                                        throws CryptoException

Sets the key used to protect the private key as a string. This is useful when pass phrases are generated by a plain text tool.

Specified by:

setPrivateKeyProtectionKeyAsString in interface MutableKeyStoreProtectionManager

Parameters:

key - The key used to protect private keys.

Throws:

CryptoException

clearPrivateKeyProtectionKey

public void clearPrivateKeyProtectionKey()
                                  throws CryptoException

Clears the key use to protect the private key. Some implementations require that the key be cleared before a new value can be set. For deterministic results, you should always clear the key before setting a new value.

Specified by:

clearPrivateKeyProtectionKey in interface MutableKeyStoreProtectionManager

Throws:

CryptoException

setKeyStoreProtectionKey

public void setKeyStoreProtectionKey(Key key)
                              throws CryptoException

Sets key used to protect the key store as a Key object.

Specified by:

setKeyStoreProtectionKey in interface MutableKeyStoreProtectionManager

Parameters:

key - The key used to protect the key store.

Throws:

CryptoException

setKeyStoreProtectionKeyAsBytes

public void setKeyStoreProtectionKeyAsBytes(byte[] key)
                                     throws CryptoException

Sets key used to protect the key store as a byte array.

Specified by:

setKeyStoreProtectionKeyAsBytes in interface MutableKeyStoreProtectionManager

Parameters:

key - The key used to protect the key store.

Throws:

CryptoException

setKeyStoreProtectionKeyAsString

public void setKeyStoreProtectionKeyAsString(String key)
                                      throws CryptoException

Sets key used to protect the key store as a string. This is useful when pass phrases are generated by a plain text tool.

Specified by:

setKeyStoreProtectionKeyAsString in interface MutableKeyStoreProtectionManager

Parameters:

key - The key used to protect the key store.

Throws:

CryptoException

clearKeyStoreProtectionKey

public void clearKeyStoreProtectionKey()
                                throws CryptoException

Clears the key use to protect the key store. Some implementations require that the key be cleared before a new value can be set. For deterministic results, you should always clear the key before setting a new value.

Specified by:

clearKeyStoreProtectionKey in interface MutableKeyStoreProtectionManager

Throws:

CryptoException

setKey

public void setKey(String alias,
                   Key key)
            throws CryptoException

Generic method to set an arbitrary key.

Specified by:

setKey in interface MutableKeyStoreProtectionManager

Parameters:

alias - Alias of the key that will be set.

key - The key that will be set.

Throws:

CryptoException

clearKey

public void clearKey(String alias)
              throws CryptoException

Generic method to clear an arbitrary key.

Specified by:

clearKey in interface MutableKeyStoreProtectionManager

Parameters:

alias - Alias of the key that will be cleared.

Throws:

CryptoException

setEntry

public void setEntry(String alias,
                     KeyStore.Entry entry)
              throws CryptoException

Generic method to set an arbitrary entry.

Specified by:

setEntry in interface MutableKeyStoreProtectionManager

Parameters:

alias - Alias of the entry that will be set.

entry - The entry that will be set.

Throws:

CryptoException

clearEntry

public void clearEntry(String alias)
                throws CryptoException

Generic method to clear an arbitrary entry.

Specified by:

clearEntry in interface MutableKeyStoreProtectionManager

Parameters:

alias - Alias of the entry that will be cleared.

Throws:

CryptoException

getKS

public KeyStore getKS()

Gets the underlying KeyStore object.}

Specified by:

getKS in interface MutableKeyStoreProtectionManager

Returns:

The KeyStore object backing the protection manager.

wrapWithSecretKey

public byte[] wrapWithSecretKey(SecretKey kek,
                                Key keyToWrap)
                         throws CryptoException

Wraps a key with a symmetric secret key encryption key.}

Specified by:

wrapWithSecretKey in interface WrappableKeyProtectionManager

Parameters:

kek - The key encryption key.

keyToWrap - The key to be wrapped.

Returns:

A wrapped representation of the key as a byte array.

Throws:

CryptoException

unwrapWithSecretKey

public Key unwrapWithSecretKey(SecretKey kek,
                               byte[] wrappedData,
                               String keyAlg,
                               int keyType)
                        throws CryptoException

Unwraps the key with a symmetric secret key encryption key.}

Specified by:

unwrapWithSecretKey in interface WrappableKeyProtectionManager

Parameters:

kek - The key encryption key.

wrappedData - The wrapped key as a byte array.

keyAlg - The algorithm of the key that is being decrypted. Typical parameters are "RSA", "DSA", and "AES" depending on the key type.

keyType - The type of key that is wrapped. Valid values should use the Cipher.PRIVATE_KEY and Cipher.SECRET_KEY constants.

Returns:

The unwrapped key. Depending on implementation, the actual key material may not be available using the getEncoded() method; the sensitive key information is held on the token. The returned key may still be used for cryptographic operations, but the Provider name parameter of the cryptographic functions will generally need to match the Provider name of the underlying keystore.

Throws:

CryptoException