KeyProvider (Apache Hadoop Common 3.5.0 API)
Description: declaration: package: org.apache.hadoop.crypto.key, class: KeyProvider

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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  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
  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 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?
  `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 Details

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