Package org.apache.hadoop.crypto.key

Class KeyProvider

java.lang.Object

org.apache.hadoop.crypto.key.KeyProvider

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

Direct Known Subclasses:

JavaKeyStoreProvider, KeyProviderExtension, KMSClientProvider, LoadBalancingKMSClientProvider, UserProvider

@Public
@Stable
public abstract class KeyProvider
extends java.lang.Object
implements java.io.Closeable

A provider of secret key material for Hadoop applications. Provides an abstraction to separate key storage from users of encryption. It is intended to support getting or storing keys in a variety of ways, including third party bindings.

KeyProvider implementations must be thread safe.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	KeyProvider.KeyVersion	The combination of both the key version name and the key material.
static class	KeyProvider.Metadata	Key metadata that is associated with the key.
static class	KeyProvider.Options	Options when creating key objects.

Field Summary

Fields

Modifier and Type	Field	Description
static int	DEFAULT_BITLENGTH
static java.lang.String	DEFAULT_BITLENGTH_NAME
static java.lang.String	DEFAULT_CIPHER
static java.lang.String	DEFAULT_CIPHER_NAME
static java.lang.String	JCEKS_KEY_SERIAL_FILTER
static java.lang.String	JCEKS_KEY_SERIALFILTER_DEFAULT

Constructor Summary

Constructors

Constructor	Description
KeyProvider(Configuration conf)	Constructor.

Method Summary

Modifier and Type	Method	Description
protected static java.lang.String	buildVersionName(java.lang.String name, int version)	Build a version string from a basename and version number.
void	close()	Can be used by implementing classes to close any resources that require closing
abstract KeyProvider.KeyVersion	createKey(java.lang.String name, byte[] material, KeyProvider.Options options)	Create a new key.
KeyProvider.KeyVersion	createKey(java.lang.String name, KeyProvider.Options options)	Create a new key generating the material for it.
abstract void	deleteKey(java.lang.String name)	Delete the given key.
static KeyProvider	findProvider(java.util.List<KeyProvider> providerList, java.lang.String keyName)	Find the provider with the given key.
abstract void	flush()	Ensures that any changes to the keys are written to persistent store.
protected byte[]	generateKey(int size, java.lang.String algorithm)	Generates a key material.
static java.lang.String	getBaseName(java.lang.String versionName)	Split the versionName in to a base name.
Configuration	getConf()	Return the provider configuration.
KeyProvider.KeyVersion	getCurrentKey(java.lang.String name)	Get the current version of the key, which should be used for encrypting new data.
abstract java.util.List<java.lang.String>	getKeys()	Get the key names for all keys.
KeyProvider.Metadata[]	getKeysMetadata(java.lang.String... names)	Get key metadata in bulk.
abstract KeyProvider.KeyVersion	getKeyVersion(java.lang.String versionName)	Get the key material for a specific version of the key.
abstract java.util.List<KeyProvider.KeyVersion>	getKeyVersions(java.lang.String name)	Get the key material for all versions of a specific key name.
abstract KeyProvider.Metadata	getMetadata(java.lang.String name)	Get metadata about the key.
void	invalidateCache(java.lang.String name)	Can be used by implementing classes to invalidate the caches.
boolean	isTransient()	Indicates whether this provider represents a store that is intended for transient use - such as the UserProvider is.
boolean	needsPassword()	Does this provider require a password? This means that a password is required for normal operation, and it has not been found through normal means.
java.lang.String	noPasswordError()	If a password for the provider is needed, but is not provided, this will return an error message and instructions for supplying said password to the provider.
java.lang.String	noPasswordWarning()	If a password for the provider is needed, but is not provided, this will return a warning and instructions for supplying said password to the provider.
static KeyProvider.Options	options(Configuration conf)	A helper function to create an options object.
KeyProvider.KeyVersion	rollNewVersion(java.lang.String name)	Roll a new version of the given key generating the material for it.
abstract KeyProvider.KeyVersion	rollNewVersion(java.lang.String name, byte[] material)	Roll a new version of the given key.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CIPHER_NAME

public static final java.lang.String DEFAULT_CIPHER_NAME

See Also:

Constant Field Values

DEFAULT_CIPHER

public static final java.lang.String DEFAULT_CIPHER

See Also:

Constant Field Values

DEFAULT_BITLENGTH_NAME

public static final java.lang.String DEFAULT_BITLENGTH_NAME

See Also:

Constant Field Values

DEFAULT_BITLENGTH

public static final int DEFAULT_BITLENGTH

See Also:

Constant Field Values

JCEKS_KEY_SERIALFILTER_DEFAULT

public static final java.lang.String JCEKS_KEY_SERIALFILTER_DEFAULT

See Also:

Constant Field Values

JCEKS_KEY_SERIAL_FILTER

public static final java.lang.String JCEKS_KEY_SERIAL_FILTER

See Also:

Constant Field Values

Constructor Detail

KeyProvider

public KeyProvider(Configuration conf)

Constructor.

Parameters:

conf - configuration for the provider

Method Detail

getConf

public Configuration getConf()

Return the provider configuration.

Returns:

the provider configuration

options

public static KeyProvider.Options options(Configuration conf)

A helper function to create an options object.

Parameters:

conf - the configuration to use

Returns:

a new options object

isTransient

public boolean isTransient()

Indicates whether this provider represents a store that is intended for transient use - such as the UserProvider is. These providers are generally used to provide access to keying material rather than for long term storage.

Returns:

true if transient, false otherwise

getKeyVersion

public abstract KeyProvider.KeyVersion getKeyVersion(java.lang.String versionName)
                                              throws java.io.IOException

Get the key material for a specific version of the key. This method is used when decrypting data.

Parameters:

versionName - the name of a specific version of the key

Returns:

the key material

Throws:

java.io.IOException - raised on errors performing I/O.

getKeys

public abstract java.util.List<java.lang.String> getKeys()
                                                  throws java.io.IOException

Get the key names for all keys.

Returns:

the list of key names

Throws:

java.io.IOException - raised on errors performing I/O.

getKeysMetadata

public KeyProvider.Metadata[] getKeysMetadata(java.lang.String... names)
                                       throws java.io.IOException

Get key metadata in bulk.

Parameters:

names - the names of the keys to get

Returns:

Metadata Array.

Throws:

java.io.IOException - raised on errors performing I/O.

getKeyVersions

public abstract java.util.List<KeyProvider.KeyVersion> getKeyVersions(java.lang.String name)
                                                               throws java.io.IOException

Get the key material for all versions of a specific key name.

Parameters:

name - the base name of the key.

Returns:

the list of key material

Throws:

java.io.IOException - raised on errors performing I/O.

getCurrentKey

public KeyProvider.KeyVersion getCurrentKey(java.lang.String name)
                                     throws java.io.IOException

Get the current version of the key, which should be used for encrypting new data.

Parameters:

name - the base name of the key

Returns:

the version name of the current version of the key or null if the key version doesn't exist

Throws:

java.io.IOException - raised on errors performing I/O.

getMetadata

public abstract KeyProvider.Metadata getMetadata(java.lang.String name)
                                          throws java.io.IOException

Get metadata about the key.

Parameters:

name - the basename of the key

Returns:

the key's metadata or null if the key doesn't exist

Throws:

java.io.IOException - raised on errors performing I/O.

createKey

public abstract KeyProvider.KeyVersion createKey(java.lang.String name,
                                                 byte[] material,
                                                 KeyProvider.Options options)
                                          throws java.io.IOException

Create a new key. The given key must not already exist.

Parameters:

name - the base name of the key

material - the key material for the first version of the key.

options - the options for the new key.

Returns:

the version name of the first version of the key.

Throws:

java.io.IOException - raised on errors performing I/O.

generateKey

protected byte[] generateKey(int size,
                             java.lang.String algorithm)
                      throws java.security.NoSuchAlgorithmException

Generates a key material.

Parameters:

size - length of the key.

algorithm - algorithm to use for generating the key.

Returns:

the generated key.

Throws:

java.security.NoSuchAlgorithmException - no such algorithm exception.

createKey

public KeyProvider.KeyVersion createKey(java.lang.String name,
                                        KeyProvider.Options options)
                                 throws java.security.NoSuchAlgorithmException,
                                        java.io.IOException

Create a new key generating the material for it. The given key must not already exist.

This implementation generates the key material and calls the createKey(String, byte[], Options) method.

Parameters:

name - the base name of the key

options - the options for the new key.

Returns:

the version name of the first version of the key.

Throws:

java.io.IOException - raised on errors performing I/O.

java.security.NoSuchAlgorithmException - no such algorithm exception.

deleteKey

public abstract void deleteKey(java.lang.String name)
                        throws java.io.IOException

Delete the given key.

Parameters:

name - the name of the key to delete

Throws:

java.io.IOException - raised on errors performing I/O.

rollNewVersion

public abstract KeyProvider.KeyVersion rollNewVersion(java.lang.String name,
                                                      byte[] material)
                                               throws java.io.IOException

Roll a new version of the given key.

Parameters:

name - the basename of the key

material - the new key material

Returns:

the name of the new version of the key

Throws:

java.io.IOException - raised on errors performing I/O.

close

public void close()
           throws java.io.IOException

Can be used by implementing classes to close any resources that require closing

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException

rollNewVersion

public KeyProvider.KeyVersion rollNewVersion(java.lang.String name)
                                      throws java.security.NoSuchAlgorithmException,
                                             java.io.IOException

Roll a new version of the given key generating the material for it.

This implementation generates the key material and calls the rollNewVersion(String, byte[]) method.

Parameters:

name - the basename of the key

Returns:

the name of the new version of the key

Throws:

java.io.IOException - raised on errors performing I/O.

java.security.NoSuchAlgorithmException - This exception is thrown when a particular cryptographic algorithm is requested but is not available in the environment.

invalidateCache

public void invalidateCache(java.lang.String name)
                     throws java.io.IOException

Can be used by implementing classes to invalidate the caches. This could be used after rollNewVersion to provide a strong guarantee to return the new version of the given key.

Parameters:

name - the basename of the key

Throws:

java.io.IOException - raised on errors performing I/O.

flush

public abstract void flush()
                    throws java.io.IOException

Ensures that any changes to the keys are written to persistent store.

Throws:

java.io.IOException - raised on errors performing I/O.

getBaseName

public static java.lang.String getBaseName(java.lang.String versionName)
                                    throws java.io.IOException

Split the versionName in to a base name. Converts "/aaa/bbb@3" to "/aaa/bbb".

Parameters:

versionName - the version name to split

Returns:

the base name of the key

Throws:

java.io.IOException - raised on errors performing I/O.

buildVersionName

protected static java.lang.String buildVersionName(java.lang.String name,
                                                   int version)

Build a version string from a basename and version number. Converts "/aaa/bbb" and 3 to "/aaa/bbb@3".

Parameters:

name - the basename of the key

version - the version of the key

Returns:

the versionName of the key.

findProvider

public static KeyProvider findProvider(java.util.List<KeyProvider> providerList,
                                       java.lang.String keyName)
                                throws java.io.IOException

Find the provider with the given key.

Parameters:

providerList - the list of providers

keyName - the key name we are looking for.

Returns:

the KeyProvider that has the key

Throws:

java.io.IOException - raised on errors performing I/O.

needsPassword

public boolean needsPassword()
                      throws java.io.IOException

Does this provider require a password? This means that a password is required for normal operation, and it has not been found through normal means. If true, the password should be provided by the caller using setPassword().

Returns:

Whether or not the provider requires a password

Throws:

java.io.IOException - raised on errors performing I/O.

noPasswordWarning

public java.lang.String noPasswordWarning()

If a password for the provider is needed, but is not provided, this will return a warning and instructions for supplying said password to the provider.

Returns:

A warning and instructions for supplying the password

noPasswordError

public java.lang.String noPasswordError()

If a password for the provider is needed, but is not provided, this will return an error message and instructions for supplying said password to the provider.

Returns:

An error message and instructions for supplying the password