org.apache.hadoop.crypto.key

## Class KeyProvider

- java.lang.Object
- - org.apache.hadoop.crypto.key.KeyProvider

- All Implemented Interfaces:
    Closeable, AutoCloseable
  Direct Known Subclasses:
    KeyProviderExtension, LoadBalancingKMSClientProvider

      @InterfaceAudience.Public
       @InterfaceStability.Unstable
      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 and Description
    --- | ---
    `static class` | `KeyProvider.KeyVersion` The combination of both the key version name and the key material.
    `static class` | `KeyProvider.Metadata` Key metadata that is associated with the key.
    `static class` | `KeyProvider.Options` Options when creating key objects.

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

    All Methods Static Methods Instance Methods Abstract Methods Concrete 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 KeyProvider.KeyVersion` | `createKey(String name, byte[] material, KeyProvider.Options options)` Create a new key.
    `KeyProvider.KeyVersion` | `createKey(String name, 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.
    `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.
    `KeyProvider.Metadata[]` | `getKeysMetadata(String... names)` Get key metadata in bulk.
    `abstract KeyProvider.KeyVersion` | `getKeyVersion(String versionName)` Get the key material for a specific version of the key.
    `abstract List<KeyProvider.KeyVersion>` | `getKeyVersions(String name)` Get the key material for all versions of a specific key name.
    `abstract 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 KeyProvider.Options` | `options(Configuration conf)` A helper function to create an options object.
    `KeyProvider.KeyVersion` | `rollNewVersion(String name)` Roll a new version of the given key generating the material for it.
    `abstract 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 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`

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

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

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

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

Copyright © 2008–2022 Apache Software Foundation. All rights reserved.