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, org.apache.hadoop.security.token.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 and 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 and Description
LoadBalancingKMSClientProvider(URI providerUri, org.apache.hadoop.crypto.key.kms.KMSClientProvider[] providers, Configuration conf)

Method Summary

Modifier and Type	Method and 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.
org.apache.hadoop.crypto.key.kms.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.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 Detail

LOG

public static org.slf4j.Logger LOG

Constructor Detail

LoadBalancingKMSClientProvider

public LoadBalancingKMSClientProvider(URI providerUri,
                                      org.apache.hadoop.crypto.key.kms.KMSClientProvider[] providers,
                                      Configuration conf)

Method Detail

getProviders

@VisibleForTesting
public org.apache.hadoop.crypto.key.kms.KMSClientProvider[] getProviders()

selectDelegationToken

public Token<? extends TokenIdentifier> selectDelegationToken(Credentials creds)

getCanonicalServiceName

public String getCanonicalServiceName()

Description copied from interface: org.apache.hadoop.security.token.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 org.apache.hadoop.security.token.DelegationTokenIssuer

Returns:

the token.

getDelegationToken

public Token<?> getDelegationToken(String renewer)
                            throws IOException

Description copied from interface: org.apache.hadoop.security.token.DelegationTokenIssuer

Unconditionally get a new token with the optional renewer. Returning null indicates the service does not issue tokens.

Specified by:

getDelegationToken in interface org.apache.hadoop.security.token.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.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 Closeable

Specified by:

close in interface AutoCloseable

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.