Package org.apache.hadoop.crypto.key

Class KeyProvider

java.lang.Object
org.apache.hadoop.crypto.key.KeyProvider
All Implemented Interfaces:
Closeable, AutoCloseable
@Public @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.

  • Nested Class Summary

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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_BITLENGTH
     
    static final String
    DEFAULT_BITLENGTH_NAME
     
    static final String
    DEFAULT_CIPHER
     
    static final String
    DEFAULT_CIPHER_NAME
     
    static final String
    JCEKS_KEY_SERIAL_FILTER
     
    static final String
    JCEKS_KEY_SERIALFILTER_DEFAULT
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    KeyProvider(Configuration conf)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    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?
    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 Details

  • Constructor Details

    • KeyProvider

      public KeyProvider(Configuration conf)
      Constructor.
      Parameters:
      conf - configuration for the provider

  • Method Details

    • 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 AutoCloseable
      Specified by:
      close in interface Closeable
      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