org.apache.hadoop.crypto.key

Class KeyProvider

java.lang.Object

org.apache.hadoop.crypto.key.KeyProvider

All Implemented Interfaces:

Closeable, AutoCloseable

@InterfaceAudience.Public
 @InterfaceStability.Stable
public abstract class KeyProvider
extends Object
implements 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.

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

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 org.apache.hadoop.crypto.key.KeyProvider.KeyVersion	createKey(String name, byte[] material, org.apache.hadoop.crypto.key.KeyProvider.Options options) Create a new key.
org.apache.hadoop.crypto.key.KeyProvider.KeyVersion	createKey(String name, org.apache.hadoop.crypto.key.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.
org.apache.hadoop.crypto.key.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.
org.apache.hadoop.crypto.key.KeyProvider.Metadata[]	getKeysMetadata(String... names) Get key metadata in bulk.
abstract org.apache.hadoop.crypto.key.KeyProvider.KeyVersion	getKeyVersion(String versionName) Get the key material for a specific version of the key.
abstract List<org.apache.hadoop.crypto.key.KeyProvider.KeyVersion>	getKeyVersions(String name) Get the key material for all versions of a specific key name.
abstract org.apache.hadoop.crypto.key.KeyProvider.Metadata	getMetadata(String name) Get metadata about the key.
void	invalidateCache(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.
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 org.apache.hadoop.crypto.key.KeyProvider.Options	options(Configuration conf) A helper function to create an options object.
org.apache.hadoop.crypto.key.KeyProvider.KeyVersion	rollNewVersion(String name) Roll a new version of the given key generating the material for it.
abstract org.apache.hadoop.crypto.key.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 org.apache.hadoop.crypto.key.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 org.apache.hadoop.crypto.key.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 - raised on errors performing I/O.

getKeys

public abstract List<String> getKeys()
                              throws IOException

Get the key names for all keys.

Returns:

the list of key names

Throws:

IOException - raised on errors performing I/O.

getKeysMetadata

public org.apache.hadoop.crypto.key.KeyProvider.Metadata[] getKeysMetadata(String... names)
                                                                    throws IOException

Get key metadata in bulk.

Parameters:

names - the names of the keys to get

Returns:

Metadata Array.

Throws:

IOException - raised on errors performing I/O.

getKeyVersions

public abstract List<org.apache.hadoop.crypto.key.KeyProvider.KeyVersion> getKeyVersions(String name)
                                                                                  throws 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:

IOException - raised on errors performing I/O.

getCurrentKey

public org.apache.hadoop.crypto.key.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 - raised on errors performing I/O.

getMetadata

public abstract org.apache.hadoop.crypto.key.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 - raised on errors performing I/O.

createKey

public abstract org.apache.hadoop.crypto.key.KeyProvider.KeyVersion createKey(String name,
                                                                              byte[] material,
                                                                              org.apache.hadoop.crypto.key.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 - raised on errors performing I/O.

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 - no such algorithm exception.

createKey

public org.apache.hadoop.crypto.key.KeyProvider.KeyVersion createKey(String name,
                                                                     org.apache.hadoop.crypto.key.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 - raised on errors performing I/O.

NoSuchAlgorithmException - no such algorithm exception.

deleteKey

public abstract void deleteKey(String name)
                        throws IOException

Delete the given key.

Parameters:

name - the name of the key to delete

Throws:

IOException - raised on errors performing I/O.

rollNewVersion

public abstract org.apache.hadoop.crypto.key.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 - raised on errors performing I/O.

close

public void close()
           throws IOException

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

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

rollNewVersion

public org.apache.hadoop.crypto.key.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 - raised on errors performing I/O.

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

invalidateCache

public void invalidateCache(String name)
                     throws 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:

IOException - raised on errors performing I/O.

flush

public abstract void flush()
                    throws IOException

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

Throws:

IOException - raised on errors performing I/O.

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 - raised on errors performing I/O.

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 - raised on errors performing I/O.

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 - raised on errors performing I/O.

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