org.apache.hadoop.crypto.key

Class KeyProvider

java.lang.Object

org.apache.hadoop.crypto.key.KeyProvider

@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.

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

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

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

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

Throws:

IOException

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.

Returns:

the list of key material

Throws:

IOException

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

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

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

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

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

close

public void close()
           throws IOException

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

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

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