org.apache.hadoop.crypto.key
Class KeyProvider

java.lang.Object
  extended by 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
static int DEFAULT_BITLENGTH
           
static String DEFAULT_BITLENGTH_NAME
           
static String DEFAULT_CIPHER
           
static String DEFAULT_CIPHER_NAME
           
 
Constructor Summary
KeyProvider(Configuration conf)
          Constructor.
 
Method Summary
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.
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


Copyright © 2014 Apache Software Foundation. All Rights Reserved.