org.apache.hadoop.crypto.key

Class KeyProvider

java.lang.Object

org.apache.hadoop.crypto.key.KeyProvider

Direct Known Subclasses:

KeyProviderExtension, LoadBalancingKMSClientProvider

@InterfaceAudience.Public
@InterfaceStability.Unstable
public abstract class KeyProvider
extends Object

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 and 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 and Description
static int	DEFAULT_BITLENGTH
static String	DEFAULT_BITLENGTH_NAME
static String	DEFAULT_CIPHER
static String	DEFAULT_CIPHER_NAME
static String	JCEKS_KEY_SERIAL_FILTER
static String	JCEKS_KEY_SERIALFILTER_DEFAULT

Constructor Summary

Constructors

Constructor and Description
KeyProvider(Configuration conf) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected static String	buildVersionName(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(String name, byte[] material, KeyProvider.Options options) Create a new key.
KeyProvider.KeyVersion	createKey(String name, KeyProvider.Options options) Create a new key generating the material for it.
abstract void	deleteKey(String name) Delete the given key.
static KeyProvider	findProvider(List<KeyProvider> providerList, 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, String algorithm) Generates a key material.
static String	getBaseName(String versionName) Split the versionName in to a base name.
Configuration	getConf() Return the provider configuration.
KeyProvider.KeyVersion	getCurrentKey(String name) Get the current version of the key, which should be used for encrypting new data.
abstract List<String>	getKeys() Get the key names for all keys.
KeyProvider.Metadata[]	getKeysMetadata(String... names) Get key metadata in bulk.
abstract KeyProvider.KeyVersion	getKeyVersion(String versionName) Get the key material for a specific version of the key.
abstract List<KeyProvider.KeyVersion>	getKeyVersions(String name) Get the key material for all versions of a specific key name.
abstract KeyProvider.Metadata	getMetadata(String name) Get metadata about the key.
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.
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.
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(String name) Roll a new version of the given key generating the material for it.
abstract KeyProvider.KeyVersion	rollNewVersion(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 String DEFAULT_CIPHER_NAME

See Also:

Constant Field Values

DEFAULT_CIPHER

public static final String DEFAULT_CIPHER

See Also:

Constant Field Values

DEFAULT_BITLENGTH_NAME

public static final 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 String JCEKS_KEY_SERIALFILTER_DEFAULT

See Also:

Constant Field Values

JCEKS_KEY_SERIAL_FILTER

public static final 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(String versionName)
                                              throws 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:

IOException

getKeys

public abstract List<String> getKeys()
                              throws IOException

Get the key names for all keys.

Returns:

the list of key names

Throws:

IOException

getKeysMetadata

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

Get key metadata in bulk.

Parameters:

names - the names of the keys to get

Throws:

IOException

getKeyVersions

public abstract List<KeyProvider.KeyVersion> getKeyVersions(String name)
                                                     throws IOException

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

Returns:

the list of key material

Throws:

IOException

getCurrentKey

public KeyProvider.KeyVersion getCurrentKey(String name)
                                     throws 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:

IOException

getMetadata

public abstract KeyProvider.Metadata getMetadata(String name)
                                          throws 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:

IOException

createKey

public abstract KeyProvider.KeyVersion createKey(String name,
                               byte[] material,
                               KeyProvider.Options options)
                                          throws 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:

IOException

generateKey

protected byte[] generateKey(int size,
                 String algorithm)
                      throws NoSuchAlgorithmException

Generates a key material.

Parameters:

size - length of the key.

algorithm - algorithm to use for generating the key.

Returns:

the generated key.

Throws:

NoSuchAlgorithmException

createKey

public KeyProvider.KeyVersion createKey(String name,
                               KeyProvider.Options options)
                                 throws NoSuchAlgorithmException,
                                        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:

IOException

NoSuchAlgorithmException

deleteKey

public abstract void deleteKey(String name)
                        throws IOException

Delete the given key.

Parameters:

name - the name of the key to delete

Throws:

IOException

rollNewVersion

public abstract KeyProvider.KeyVersion rollNewVersion(String name,
                                    byte[] material)
                                               throws 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:

IOException

close

public void close()
           throws IOException

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

Throws:

IOException

rollNewVersion

public KeyProvider.KeyVersion rollNewVersion(String name)
                                      throws NoSuchAlgorithmException,
                                             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:

IOException

NoSuchAlgorithmException

flush

public abstract void flush()
                    throws IOException

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

Throws:

IOException

getBaseName

public static String getBaseName(String versionName)
                          throws 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:

IOException

buildVersionName

protected static String buildVersionName(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(List<KeyProvider> providerList,
                       String keyName)
                                throws 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:

IOException

needsPassword

public boolean needsPassword()
                      throws 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:

IOException

noPasswordWarning

public 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 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