Package org.apache.hadoop.crypto.key

Class KeyProvider

java.lang.Object
org.apache.hadoop.crypto.key.KeyProvider
All Implemented Interfaces:
Closeable, AutoCloseable
Direct Known Subclasses:
JavaKeyStoreProvider, KeyProviderExtension, KMSClientProvider, LoadBalancingKMSClientProvider, UserProvider
@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.

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