org.apache.hadoop.hbase.io.crypto

Class Encryption

java.lang.Object

org.apache.hadoop.hbase.io.crypto.Encryption

@InterfaceAudience.Public
public final class Encryption
extends Object

A facade for encryption algorithms and related support.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Encryption.Context Crypto context

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	CRYPTO_ENABLED_CONF_DEFAULT Default value for globally enable / disable column family encryption (set to "true" for backward compatibility)
static String	CRYPTO_ENABLED_CONF_KEY Configuration key for globally enable / disable column family encryption
static boolean	CRYPTO_KEY_FAIL_ON_ALGORITHM_MISMATCH_CONF_DEFAULT Default behaviour is not to fail if the hash algorithm configured differs from the one used in the HFile.
static String	CRYPTO_KEY_FAIL_ON_ALGORITHM_MISMATCH_CONF_KEY Configuration key for specifying the behaviour if the configured hash algorithm differs from the one used for generating key hash in encrypted HFiles currently being read.
static String	CRYPTO_KEY_HASH_ALGORITHM_CONF_DEFAULT Default hash algorithm used for generating key hash in encrypted HFiles.
static String	CRYPTO_KEY_HASH_ALGORITHM_CONF_KEY Configuration key for the hash algorithm used for generating key hash in encrypted HFiles.
(package private) static Map<Pair<String,String>,KeyProvider>	keyProviderCache
private static org.slf4j.Logger	LOG

Constructor Summary

Constructors

Modifier	Constructor and Description
private	Encryption()

Method Summary

Modifier and Type	Method and Description
static byte[]	computeCryptoKeyHash(org.apache.hadoop.conf.Configuration conf, byte[] arg) Returns the hash of the supplied argument, using the hash algorithm specified in the given config.
static void	decrypt(byte[] dest, int destOffset, InputStream in, int destSize, Decryptor d) Decrypt a block of ciphertext read in from a stream with the given cipher and context
static void	decrypt(byte[] dest, int destOffset, InputStream in, int destSize, Encryption.Context context, byte[] iv) Decrypt a block of ciphertext from a stream given a context and IV
static void	decrypt(OutputStream out, InputStream in, int outLen, Decryptor d) Decrypt a stream of ciphertext given a decryptor
static void	decrypt(OutputStream out, InputStream in, int outLen, Encryption.Context context, byte[] iv) Decrypt a stream of ciphertext given a context and IV
static void	decryptWithSubjectKey(OutputStream out, InputStream in, int outLen, String subject, org.apache.hadoop.conf.Configuration conf, Cipher cipher, byte[] iv) Decrypts a block of ciphertext with the symmetric key resolved for the given subject
static void	encrypt(OutputStream out, byte[] src, int offset, int length, Encryption.Context context, byte[] iv) Encrypt a block of plaintext
static void	encrypt(OutputStream out, byte[] src, int offset, int length, Encryptor e) Encrypt a block of plaintext
static void	encrypt(OutputStream out, InputStream in, Encryption.Context context, byte[] iv) Encrypt a stream of plaintext given a context and IV
static void	encrypt(OutputStream out, InputStream in, Encryptor e) Encrypt a stream of plaintext given an encryptor
static void	encryptWithSubjectKey(OutputStream out, InputStream in, String subject, org.apache.hadoop.conf.Configuration conf, Cipher cipher, byte[] iv) Encrypts a block of plaintext with the symmetric key resolved for the given subject
static boolean	failOnHashAlgorithmMismatch(org.apache.hadoop.conf.Configuration conf) Returns the Hash Algorithm mismatch behaviour defined in the crypto configuration.
static byte[]	generateSecretKey(org.apache.hadoop.conf.Configuration conf, String cypherAlg, byte[]... args) Return a key derived from the concatenation of the supplied arguments using PBKDF2WithHmacSHA384 key derivation algorithm at 10,000 iterations.
static byte[]	generateSecretKey(org.apache.hadoop.conf.Configuration conf, String cypherAlg, String... args) Return a key derived from the concatenation of the supplied arguments using PBKDF2WithHmacSHA384 key derivation algorithm at 10,000 iterations.
private static byte[]	generateSecretKey(String algorithm, int keyLengthBytes, char[] password) Return a key (byte array) derived from the supplied password argument using the given algorithm with a random salt at 10,000 iterations.
static Cipher	getCipher(org.apache.hadoop.conf.Configuration conf, String name) Get an cipher given a name
static CipherProvider	getCipherProvider(org.apache.hadoop.conf.Configuration conf)
private static ClassLoader	getClassLoaderForClass(Class<?> c)
static String	getConfiguredHashAlgorithm(org.apache.hadoop.conf.Configuration conf) Returns the Hash Algorithm defined in the crypto configuration.
static KeyProvider	getKeyProvider(org.apache.hadoop.conf.Configuration conf)
static Key	getSecretKeyForSubject(String subject, org.apache.hadoop.conf.Configuration conf) Resolves a key for the given subject
static String[]	getSupportedCiphers() Get names of supported encryption algorithms
static String[]	getSupportedCiphers(org.apache.hadoop.conf.Configuration conf) Get names of supported encryption algorithms
static byte[]	hash128(byte[]... args) Return the MD5 digest of the concatenation of the supplied arguments.
static byte[]	hash128(String... args) Return the MD5 digest of the concatenation of the supplied arguments.
static byte[]	hash256(byte[]... args) Return the SHA-256 digest of the concatenation of the supplied arguments.
static byte[]	hash256(String... args) Return the SHA-256 digest of the concatenation of the supplied arguments.
static byte[]	hashWithAlg(String algorithm, byte[]... args) Return the hash of the concatenation of the supplied arguments, using the hash algorithm provided.
static void	incrementIv(byte[] iv)
static void	incrementIv(byte[] iv, int v)
static boolean	isEncryptionEnabled(org.apache.hadoop.conf.Configuration conf) Returns true if the column family encryption feature is enabled globally.
static Encryption.Context	newContext()
static Encryption.Context	newContext(org.apache.hadoop.conf.Configuration conf)
static byte[]	pbkdf128(byte[]... args) Return a 128 bit key derived from the concatenation of the supplied arguments using PBKDF2WithHmacSHA1 at 10,000 iterations.
static byte[]	pbkdf128(String... args) Return a 128 bit key derived from the concatenation of the supplied arguments using PBKDF2WithHmacSHA1 at 10,000 iterations.

Methods inherited from class java.lang.Object

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

Field Detail

LOG

private static final org.slf4j.Logger LOG

CRYPTO_ENABLED_CONF_KEY

public static final String CRYPTO_ENABLED_CONF_KEY

Configuration key for globally enable / disable column family encryption

See Also:

Constant Field Values

CRYPTO_ENABLED_CONF_DEFAULT

public static final boolean CRYPTO_ENABLED_CONF_DEFAULT

Default value for globally enable / disable column family encryption (set to "true" for backward compatibility)

See Also:

Constant Field Values

CRYPTO_KEY_HASH_ALGORITHM_CONF_KEY

public static final String CRYPTO_KEY_HASH_ALGORITHM_CONF_KEY

Configuration key for the hash algorithm used for generating key hash in encrypted HFiles. This is a MessageDigest algorithm identifier string, like "MD5", "SHA-256" or "SHA-384". (default: "MD5" for backward compatibility reasons)

See Also:

Constant Field Values

CRYPTO_KEY_HASH_ALGORITHM_CONF_DEFAULT

public static final String CRYPTO_KEY_HASH_ALGORITHM_CONF_DEFAULT

Default hash algorithm used for generating key hash in encrypted HFiles. (we use "MD5" for backward compatibility reasons)

See Also:

Constant Field Values

CRYPTO_KEY_FAIL_ON_ALGORITHM_MISMATCH_CONF_KEY

public static final String CRYPTO_KEY_FAIL_ON_ALGORITHM_MISMATCH_CONF_KEY

Configuration key for specifying the behaviour if the configured hash algorithm differs from the one used for generating key hash in encrypted HFiles currently being read. - "false" (default): we won't fail but use the hash algorithm stored in the HFile - "true": we throw an exception (this can be useful if regulations are enforcing the usage of certain algorithms, e.g. on FIPS compliant clusters)

See Also:

Constant Field Values

CRYPTO_KEY_FAIL_ON_ALGORITHM_MISMATCH_CONF_DEFAULT

public static final boolean CRYPTO_KEY_FAIL_ON_ALGORITHM_MISMATCH_CONF_DEFAULT

Default behaviour is not to fail if the hash algorithm configured differs from the one used in the HFile. (this is the more fail-safe approach, allowing us to read encrypted HFiles written using a different encryption key hash algorithm)

See Also:

Constant Field Values

keyProviderCache

static final Map<Pair<String,String>,KeyProvider> keyProviderCache

Constructor Detail

Encryption

private Encryption()

Method Detail

newContext

public static Encryption.Context newContext()

newContext

public static Encryption.Context newContext(org.apache.hadoop.conf.Configuration conf)

isEncryptionEnabled

public static boolean isEncryptionEnabled(org.apache.hadoop.conf.Configuration conf)

Returns true if the column family encryption feature is enabled globally.

getCipher

public static Cipher getCipher(org.apache.hadoop.conf.Configuration conf,
                               String name)

Get an cipher given a name

Parameters:

name - the cipher name

Returns:

the cipher, or null if a suitable one could not be found

getSupportedCiphers

public static String[] getSupportedCiphers()

Get names of supported encryption algorithms

Returns:

Array of strings, each represents a supported encryption algorithm

getSupportedCiphers

public static String[] getSupportedCiphers(org.apache.hadoop.conf.Configuration conf)

Get names of supported encryption algorithms

Returns:

Array of strings, each represents a supported encryption algorithm

getConfiguredHashAlgorithm

public static String getConfiguredHashAlgorithm(org.apache.hadoop.conf.Configuration conf)

Returns the Hash Algorithm defined in the crypto configuration.

failOnHashAlgorithmMismatch

public static boolean failOnHashAlgorithmMismatch(org.apache.hadoop.conf.Configuration conf)

Returns the Hash Algorithm mismatch behaviour defined in the crypto configuration.

computeCryptoKeyHash

public static byte[] computeCryptoKeyHash(org.apache.hadoop.conf.Configuration conf,
                                          byte[] arg)

Returns the hash of the supplied argument, using the hash algorithm specified in the given config.

hash128

public static byte[] hash128(String... args)

Return the MD5 digest of the concatenation of the supplied arguments.

hash128

public static byte[] hash128(byte[]... args)

Return the MD5 digest of the concatenation of the supplied arguments.

hash256

public static byte[] hash256(String... args)

Return the SHA-256 digest of the concatenation of the supplied arguments.

hash256

public static byte[] hash256(byte[]... args)

Return the SHA-256 digest of the concatenation of the supplied arguments.

pbkdf128

public static byte[] pbkdf128(String... args)

Return a 128 bit key derived from the concatenation of the supplied arguments using PBKDF2WithHmacSHA1 at 10,000 iterations.

pbkdf128

public static byte[] pbkdf128(byte[]... args)

Return a 128 bit key derived from the concatenation of the supplied arguments using PBKDF2WithHmacSHA1 at 10,000 iterations.

generateSecretKey

public static byte[] generateSecretKey(org.apache.hadoop.conf.Configuration conf,
                                       String cypherAlg,
                                       String... args)

Return a key derived from the concatenation of the supplied arguments using PBKDF2WithHmacSHA384 key derivation algorithm at 10,000 iterations. The length of the returned key is determined based on the need of the cypher algorithm. E.g. for the default "AES" we will need a 128 bit long key, while if the user is using a custom cipher, we might generate keys with other length. This key generation method is used currently e.g. in the HBase Shell (admin.rb) to generate a column family data encryption key, if the user provided an ENCRYPTION_KEY parameter.

generateSecretKey

public static byte[] generateSecretKey(org.apache.hadoop.conf.Configuration conf,
                                       String cypherAlg,
                                       byte[]... args)

Return a key derived from the concatenation of the supplied arguments using PBKDF2WithHmacSHA384 key derivation algorithm at 10,000 iterations. The length of the returned key is determined based on the need of the cypher algorithm. E.g. for the default "AES" we will need a 128 bit long key, while if the user is using a custom cipher, we might generate keys with other length. This key generation method is used currently e.g. in the HBase Shell (admin.rb) to generate a column family data encryption key, if the user provided an ENCRYPTION_KEY parameter.

generateSecretKey

private static byte[] generateSecretKey(String algorithm,
                                        int keyLengthBytes,
                                        char[] password)

Return a key (byte array) derived from the supplied password argument using the given algorithm with a random salt at 10,000 iterations.

Parameters:

algorithm - the secret key generation algorithm to use

keyLengthBytes - the length of the key to be derived (in bytes, not in bits)

password - char array to use as password for the key generation algorithm

Returns:

secret key encoded as a byte array

encrypt

public static void encrypt(OutputStream out,
                           byte[] src,
                           int offset,
                           int length,
                           Encryptor e)
                    throws IOException

Encrypt a block of plaintext

The encryptor's state will be finalized. It should be reinitialized or returned to the pool.

Parameters:

out - ciphertext

src - plaintext

offset -

length -

e -

Throws:

IOException

encrypt

public static void encrypt(OutputStream out,
                           byte[] src,
                           int offset,
                           int length,
                           Encryption.Context context,
                           byte[] iv)
                    throws IOException

Encrypt a block of plaintext

Parameters:

out - ciphertext

src - plaintext

offset -

length -

context -

iv -

Throws:

IOException

encrypt

public static void encrypt(OutputStream out,
                           InputStream in,
                           Encryptor e)
                    throws IOException

Encrypt a stream of plaintext given an encryptor

The encryptor's state will be finalized. It should be reinitialized or returned to the pool.

Parameters:

out - ciphertext

in - plaintext

e -

Throws:

IOException

encrypt

public static void encrypt(OutputStream out,
                           InputStream in,
                           Encryption.Context context,
                           byte[] iv)
                    throws IOException

Encrypt a stream of plaintext given a context and IV

Parameters:

out - ciphertext

in - plaintet

context -

iv -

Throws:

IOException

decrypt

public static void decrypt(byte[] dest,
                           int destOffset,
                           InputStream in,
                           int destSize,
                           Decryptor d)
                    throws IOException

Decrypt a block of ciphertext read in from a stream with the given cipher and context

The decryptor's state will be finalized. It should be reinitialized or returned to the pool.

Parameters:

dest -

destOffset -

in -

destSize -

d -

Throws:

IOException

decrypt

public static void decrypt(byte[] dest,
                           int destOffset,
                           InputStream in,
                           int destSize,
                           Encryption.Context context,
                           byte[] iv)
                    throws IOException

Decrypt a block of ciphertext from a stream given a context and IV

Parameters:

dest -

destOffset -

in -

destSize -

context -

iv -

Throws:

IOException

decrypt

public static void decrypt(OutputStream out,
                           InputStream in,
                           int outLen,
                           Decryptor d)
                    throws IOException

Decrypt a stream of ciphertext given a decryptor

Parameters:

out -

in -

outLen -

d -

Throws:

IOException

decrypt

public static void decrypt(OutputStream out,
                           InputStream in,
                           int outLen,
                           Encryption.Context context,
                           byte[] iv)
                    throws IOException

Decrypt a stream of ciphertext given a context and IV

Parameters:

out -

in -

outLen -

context -

iv -

Throws:

IOException

getSecretKeyForSubject

public static Key getSecretKeyForSubject(String subject,
                                         org.apache.hadoop.conf.Configuration conf)
                                  throws IOException

Resolves a key for the given subject

Parameters:

subject -

conf -

Returns:

a key for the given subject

Throws:

IOException - if the key is not found

encryptWithSubjectKey

public static void encryptWithSubjectKey(OutputStream out,
                                         InputStream in,
                                         String subject,
                                         org.apache.hadoop.conf.Configuration conf,
                                         Cipher cipher,
                                         byte[] iv)
                                  throws IOException

Encrypts a block of plaintext with the symmetric key resolved for the given subject

Parameters:

out - ciphertext

in - plaintext

conf - configuration

cipher - the encryption algorithm

iv - the initialization vector, can be null

Throws:

IOException

decryptWithSubjectKey

public static void decryptWithSubjectKey(OutputStream out,
                                         InputStream in,
                                         int outLen,
                                         String subject,
                                         org.apache.hadoop.conf.Configuration conf,
                                         Cipher cipher,
                                         byte[] iv)
                                  throws IOException

Decrypts a block of ciphertext with the symmetric key resolved for the given subject

Parameters:

out - plaintext

in - ciphertext

outLen - the expected plaintext length

subject - the subject's key alias

conf - configuration

cipher - the encryption algorithm

iv - the initialization vector, can be null

Throws:

IOException

getClassLoaderForClass

private static ClassLoader getClassLoaderForClass(Class<?> c)

getCipherProvider

public static CipherProvider getCipherProvider(org.apache.hadoop.conf.Configuration conf)

getKeyProvider

public static KeyProvider getKeyProvider(org.apache.hadoop.conf.Configuration conf)

incrementIv

public static void incrementIv(byte[] iv)

incrementIv

public static void incrementIv(byte[] iv,
                               int v)

hashWithAlg

public static byte[] hashWithAlg(String algorithm,
                                 byte[]... args)

Return the hash of the concatenation of the supplied arguments, using the hash algorithm provided.