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

Package org.apache.hadoop.crypto.key.kms

# Class LoadBalancingKMSClientProvider

java.lang.Object
org.apache.hadoop.crypto.key.KeyProvider
org.apache.hadoop.crypto.key.kms.LoadBalancingKMSClientProvider

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`, `KeyProviderCryptoExtension.CryptoExtension`, `KeyProviderDelegationTokenExtension.DelegationTokenExtension`, `KeyProviderExtension.Extension`, `DelegationTokenIssuer`

public class LoadBalancingKMSClientProvider extends KeyProvider implements KeyProviderCryptoExtension.CryptoExtension, KeyProviderDelegationTokenExtension.DelegationTokenExtension
A simple LoadBalancing KMSClientProvider that round-robins requests across a provided array of KMSClientProviders. It also retries failed requests on the next available provider in the load balancer group. It only retries failed requests that result in an IOException, sending back all other Exceptions to the caller without retry.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.hadoop.crypto.key.KeyProvider

  `KeyProvider.KeyVersion, KeyProvider.Metadata, KeyProvider.Options`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static org.slf4j.Logger`
  `LOG`

  ### Fields inherited from class org.apache.hadoop.crypto.key.KeyProvider

  `DEFAULT_BITLENGTH, DEFAULT_BITLENGTH_NAME, DEFAULT_CIPHER, DEFAULT_CIPHER_NAME, JCEKS_KEY_SERIAL_FILTER, JCEKS_KEY_SERIALFILTER_DEFAULT`

  ### Fields inherited from interface org.apache.hadoop.security.token.DelegationTokenIssuer

  `TOKEN_LOG`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LoadBalancingKMSClientProvider(URI providerUri, KMSClientProvider[] providers, Configuration conf)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Void`
  `cancelDelegationToken(Token<?> token)`
  Cancels the given token.
  `void`
  `close()`
  Can be used by implementing classes to close any resources that require closing
  `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.
  `KeyProvider.KeyVersion`
  `decryptEncryptedKey(KeyProviderCryptoExtension.EncryptedKeyVersion encryptedKeyVersion)`
  Decrypts an encrypted byte[] key material using the given key version name and initialization vector.
  `void`
  `deleteKey(String name)`
  Delete the given key.
  `void`
  `drain(String keyName)`
  Drains the Queue for the provided key.
  `void`
  `flush()`
  Ensures that any changes to the keys are written to persistent store.
  `KeyProviderCryptoExtension.EncryptedKeyVersion`
  `generateEncryptedKey(String encryptionKeyName)`
  Generates a key material and encrypts it using the given key name.
  `String`
  `getCanonicalServiceName()`
  The service name used as the alias for the token in the credential token map.
  `KeyProvider.KeyVersion`
  `getCurrentKey(String name)`
  Get the current version of the key, which should be used for encrypting new data.
  `Token<?>`
  `getDelegationToken(String renewer)`
  Unconditionally get a new token with the optional renewer.
  `List<String>`
  `getKeys()`
  Get the key names for all keys.
  `KeyProvider.Metadata[]`
  `getKeysMetadata(String... names)`
  Get key metadata in bulk.
  `KeyProvider.KeyVersion`
  `getKeyVersion(String versionName)`
  Get the key material for a specific version of the key.
  `List<KeyProvider.KeyVersion>`
  `getKeyVersions(String name)`
  Get the key material for all versions of a specific key name.
  `KeyProvider.Metadata`
  `getMetadata(String name)`
  Get metadata about the key.
  `KMSClientProvider[]`
  `getProviders()`
  `void`
  `invalidateCache(String keyName)`
  Can be used by implementing classes to invalidate the caches.
  `KeyProviderCryptoExtension.EncryptedKeyVersion`
  `reencryptEncryptedKey(KeyProviderCryptoExtension.EncryptedKeyVersion ekv)`
  Re-encrypts an encrypted key version, using its initialization vector and key material, but with the latest key version name of its key name in the key provider.
  `void`
  `reencryptEncryptedKeys(List<KeyProviderCryptoExtension.EncryptedKeyVersion> ekvs)`
  Batched version of `KeyProviderCryptoExtension.CryptoExtension.reencryptEncryptedKey(EncryptedKeyVersion)`.
  `long`
  `renewDelegationToken(Token<?> token)`
  Renews the given token.
  `KeyProvider.KeyVersion`
  `rollNewVersion(String name)`
  Roll a new version of the given key generating the material for it.
  `KeyProvider.KeyVersion`
  `rollNewVersion(String name, byte[] material)`
  Roll a new version of the given key.
  `Token<? extends TokenIdentifier>`
  `selectDelegationToken(Credentials creds)`
  `void`
  `warmUpEncryptedKeys(String... keyNames)`
  Calls to this method allows the underlying KeyProvider to warm-up any implementation specific caches used to store the Encrypted Keys.

  ### Methods inherited from class org.apache.hadoop.crypto.key.KeyProvider

  `buildVersionName, findProvider, generateKey, getBaseName, getConf, isTransient, needsPassword, noPasswordError, noPasswordWarning, options`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface org.apache.hadoop.security.token.DelegationTokenIssuer

  `addDelegationTokens, getAdditionalTokenIssuers`

- ## Field Details

  - ### LOG

    public static org.slf4j.Logger LOG

- ## Constructor Details

  - ### LoadBalancingKMSClientProvider

    public LoadBalancingKMSClientProvider(URI providerUri, KMSClientProvider[] providers, Configuration conf)

- ## Method Details

  - ### getProviders

    @VisibleForTesting public KMSClientProvider[] getProviders()

  - ### selectDelegationToken

    public Token<? extends TokenIdentifier> selectDelegationToken(Credentials creds)
    Specified by:
      `selectDelegationToken` in interface `KeyProviderDelegationTokenExtension.DelegationTokenExtension`

  - ### getCanonicalServiceName

    public String getCanonicalServiceName()
    Description copied from interface: `DelegationTokenIssuer`
    The service name used as the alias for the token in the credential token map. addDelegationTokens will use this to determine if a token exists, and if not, add a new token with this alias.
    Specified by:
      `getCanonicalServiceName` in interface `DelegationTokenIssuer`
    Returns:
      the token.

  - ### getDelegationToken

    public Token<?> getDelegationToken(String renewer) throws IOException
    Description copied from interface: `DelegationTokenIssuer`
    Unconditionally get a new token with the optional renewer. Returning null indicates the service does not issue tokens.
    Specified by:
      `getDelegationToken` in interface `DelegationTokenIssuer`
    Parameters:
      `renewer` - renewer.
    Returns:
      the token.
    Throws:
      `IOException` - raised on errors performing I/O.

  - ### renewDelegationToken

    public long renewDelegationToken(Token<?> token) throws IOException
    Description copied from interface: `KeyProviderDelegationTokenExtension.DelegationTokenExtension`
    Renews the given token.
    Specified by:
      `renewDelegationToken` in interface `KeyProviderDelegationTokenExtension.DelegationTokenExtension`
    Parameters:
      `token` - The token to be renewed.
    Returns:
      The token's lifetime after renewal, or 0 if it can't be renewed.
    Throws:
      `IOException` - raised on errors performing I/O.

  - ### cancelDelegationToken

    public Void cancelDelegationToken(Token<?> token) throws IOException
    Description copied from interface: `KeyProviderDelegationTokenExtension.DelegationTokenExtension`
    Cancels the given token.
    Specified by:
      `cancelDelegationToken` in interface `KeyProviderDelegationTokenExtension.DelegationTokenExtension`
    Parameters:
      `token` - The token to be cancelled.
    Throws:
      `IOException` - raised on errors performing I/O.

  - ### warmUpEncryptedKeys

    public void warmUpEncryptedKeys(String... keyNames) throws IOException
    Description copied from interface: `KeyProviderCryptoExtension.CryptoExtension`
    Calls to this method allows the underlying KeyProvider to warm-up any implementation specific caches used to store the Encrypted Keys.
    Specified by:
      `warmUpEncryptedKeys` in interface `KeyProviderCryptoExtension.CryptoExtension`
    Parameters:
      `keyNames` - Array of Key Names
    Throws:
      `IOException` - thrown if the key material could not be encrypted.

  - ### drain

    public void drain(String keyName)
    Description copied from interface: `KeyProviderCryptoExtension.CryptoExtension`
    Drains the Queue for the provided key.
    Specified by:
      `drain` in interface `KeyProviderCryptoExtension.CryptoExtension`
    Parameters:
      `keyName` - the key to drain the Queue for

  - ### invalidateCache

    public void invalidateCache(String keyName) throws IOException
    Description copied from class: `KeyProvider`
    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.
    Overrides:
      `invalidateCache` in class `KeyProvider`
    Parameters:
      `keyName` - the basename of the key
    Throws:
      `IOException` - raised on errors performing I/O.

  - ### generateEncryptedKey

    public KeyProviderCryptoExtension.EncryptedKeyVersion generateEncryptedKey(String encryptionKeyName) throws IOException, GeneralSecurityException
    Description copied from interface: `KeyProviderCryptoExtension.CryptoExtension`
    Generates a key material and encrypts it using the given key name. The generated key material is of the same length as the `KeyVersion` material of the latest key version of the key and is encrypted using the same cipher.

    NOTE: The generated key is not stored by the `KeyProvider`

    Specified by:
      `generateEncryptedKey` in interface `KeyProviderCryptoExtension.CryptoExtension`
    Parameters:
      `encryptionKeyName` - The latest KeyVersion of this key's material will be encrypted.
    Returns:
      EncryptedKeyVersion with the generated key material, the version name is 'EEK' (for Encrypted Encryption Key)
    Throws:
      `IOException` - thrown if the key material could not be generated
      `GeneralSecurityException` - thrown if the key material could not be encrypted because of a cryptographic issue.

  - ### decryptEncryptedKey

    public KeyProvider.KeyVersion decryptEncryptedKey(KeyProviderCryptoExtension.EncryptedKeyVersion encryptedKeyVersion) throws IOException, GeneralSecurityException
    Description copied from interface: `KeyProviderCryptoExtension.CryptoExtension`
    Decrypts an encrypted byte[] key material using the given key version name and initialization vector.
    Specified by:
      `decryptEncryptedKey` in interface `KeyProviderCryptoExtension.CryptoExtension`
    Parameters:
      `encryptedKeyVersion` - contains keyVersionName and IV to decrypt the encrypted key material
    Returns:
      a KeyVersion with the decrypted key material, the version name is 'EK' (For Encryption Key)
    Throws:
      `IOException` - thrown if the key material could not be decrypted
      `GeneralSecurityException` - thrown if the key material could not be decrypted because of a cryptographic issue.

  - ### reencryptEncryptedKey

    public KeyProviderCryptoExtension.EncryptedKeyVersion reencryptEncryptedKey(KeyProviderCryptoExtension.EncryptedKeyVersion ekv) throws IOException, GeneralSecurityException
    Description copied from interface: `KeyProviderCryptoExtension.CryptoExtension`
    Re-encrypts an encrypted key version, using its initialization vector and key material, but with the latest key version name of its key name in the key provider.

    If the latest key version name in the provider is the same as the one encrypted the passed-in encrypted key version, the same encrypted key version is returned.

    NOTE: The generated key is not stored by the `KeyProvider`

    Specified by:
      `reencryptEncryptedKey` in interface `KeyProviderCryptoExtension.CryptoExtension`
    Parameters:
      `ekv` - The EncryptedKeyVersion containing keyVersionName and IV.
    Returns:
      The re-encrypted EncryptedKeyVersion.
    Throws:
      `IOException` - If the key material could not be re-encrypted.
      `GeneralSecurityException` - If the key material could not be re-encrypted because of a cryptographic issue.

  - ### reencryptEncryptedKeys

    public void reencryptEncryptedKeys(List<KeyProviderCryptoExtension.EncryptedKeyVersion> ekvs) throws IOException, GeneralSecurityException
    Description copied from interface: `KeyProviderCryptoExtension.CryptoExtension`
    Batched version of `KeyProviderCryptoExtension.CryptoExtension.reencryptEncryptedKey(EncryptedKeyVersion)`.

    For each encrypted key version, re-encrypts an encrypted key version, using its initialization vector and key material, but with the latest key version name of its key name. If the latest key version name in the provider is the same as the one encrypted the passed-in encrypted key version, the same encrypted key version is returned.

    NOTE: The generated key is not stored by the `KeyProvider`

    Specified by:
      `reencryptEncryptedKeys` in interface `KeyProviderCryptoExtension.CryptoExtension`
    Parameters:
      `ekvs` - List containing the EncryptedKeyVersion's
    Throws:
      `IOException` - If any EncryptedKeyVersion could not be re-encrypted
      `GeneralSecurityException` - If any EncryptedKeyVersion could not be re-encrypted because of a cryptographic issue.

  - ### getKeyVersion

    public KeyProvider.KeyVersion getKeyVersion(String versionName) throws IOException
    Description copied from class: `KeyProvider`
    Get the key material for a specific version of the key. This method is used when decrypting data.
    Specified by:
      `getKeyVersion` in class `KeyProvider`
    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 List<String> getKeys() throws IOException
    Description copied from class: `KeyProvider`
    Get the key names for all keys.
    Specified by:
      `getKeys` in class `KeyProvider`
    Returns:
      the list of key names
    Throws:
      `IOException` - raised on errors performing I/O.

  - ### getKeysMetadata

    public KeyProvider.Metadata[] getKeysMetadata(String... names) throws IOException
    Description copied from class: `KeyProvider`
    Get key metadata in bulk.
    Overrides:
      `getKeysMetadata` in class `KeyProvider`
    Parameters:
      `names` - the names of the keys to get
    Returns:
      Metadata Array.
    Throws:
      `IOException` - raised on errors performing I/O.

  - ### getKeyVersions

    public List<KeyProvider.KeyVersion> getKeyVersions(String name) throws IOException
    Description copied from class: `KeyProvider`
    Get the key material for all versions of a specific key name.
    Specified by:
      `getKeyVersions` in class `KeyProvider`
    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
    Description copied from class: `KeyProvider`
    Get the current version of the key, which should be used for encrypting new data.
    Overrides:
      `getCurrentKey` in class `KeyProvider`
    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 KeyProvider.Metadata getMetadata(String name) throws IOException
    Description copied from class: `KeyProvider`
    Get metadata about the key.
    Specified by:
      `getMetadata` in class `KeyProvider`
    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 KeyProvider.KeyVersion createKey(String name, byte[] material, KeyProvider.Options options) throws IOException
    Description copied from class: `KeyProvider`
    Create a new key. The given key must not already exist.
    Specified by:
      `createKey` in class `KeyProvider`
    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.

  - ### createKey

    public KeyProvider.KeyVersion createKey(String name, KeyProvider.Options options) throws NoSuchAlgorithmException, IOException
    Description copied from class: `KeyProvider`
    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 `KeyProvider.createKey(String, byte[], Options)` method.

    Overrides:
      `createKey` in class `KeyProvider`
    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:
      `NoSuchAlgorithmException` - no such algorithm exception.
      `IOException` - raised on errors performing I/O.

  - ### deleteKey

    public void deleteKey(String name) throws IOException
    Description copied from class: `KeyProvider`
    Delete the given key.
    Specified by:
      `deleteKey` in class `KeyProvider`
    Parameters:
      `name` - the name of the key to delete
    Throws:
      `IOException` - raised on errors performing I/O.

  - ### rollNewVersion

    public KeyProvider.KeyVersion rollNewVersion(String name, byte[] material) throws IOException
    Description copied from class: `KeyProvider`
    Roll a new version of the given key.
    Specified by:
      `rollNewVersion` in class `KeyProvider`
    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.

  - ### rollNewVersion

    public KeyProvider.KeyVersion rollNewVersion(String name) throws NoSuchAlgorithmException, IOException
    Description copied from class: `KeyProvider`
    Roll a new version of the given key generating the material for it.

    This implementation generates the key material and calls the `KeyProvider.rollNewVersion(String, byte[])` method.

    Overrides:
      `rollNewVersion` in class `KeyProvider`
    Parameters:
      `name` - the basename of the key
    Returns:
      the name of the new version of the key
    Throws:
      `NoSuchAlgorithmException` - This exception is thrown when a particular cryptographic algorithm is requested but is not available in the environment.
      `IOException` - raised on errors performing I/O.

  - ### close

    public void close() throws IOException
    Description copied from class: `KeyProvider`
    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`
    Overrides:
      `close` in class `KeyProvider`
    Throws:
      `IOException`

  - ### flush

    public void flush() throws IOException
    Description copied from class: `KeyProvider`
    Ensures that any changes to the keys are written to persistent store.
    Specified by:
      `flush` in class `KeyProvider`
    Throws:
      `IOException` - raised on errors performing I/O.