org.apache.accumulo.core.security.crypto

Class CryptoModuleParameters

java.lang.Object

org.apache.accumulo.core.security.crypto.CryptoModuleParameters

public class CryptoModuleParameters
extends Object

This class defines several parameters needed by by a module providing cryptographic stream support in Accumulo. The following Javadoc details which parameters are used for which operations (encryption vs. decryption), which ones return values (i.e. are "out" parameters from the CryptoModule), and which ones are required versus optional in certain situations. Most of the time, these classes can be constructed using CryptoModuleFactory.createParamsObjectFromAccumuloConfiguration(org.apache.accumulo.core.conf.AccumuloConfiguration).

Constructor Summary

Constructors

Constructor and Description
CryptoModuleParameters()

Method Summary

Methods

Modifier and Type	Method and Description
String	getAlgorithmName() Gets the name of the symmetric algorithm to use for encryption.
Map<String,String>	getAllOptions() Gets the overall set of options for the CryptoModule.
int	getBlockStreamSize() Gets the size of the buffering stream that sits above the cipher stream
Cipher	getCipher() Gets the initialized cipher object.
boolean	getCloseUnderylingStreamAfterCryptoStreamClose() Gets the flag that indicates whether or not to close the underlying stream when the cipher stream is closed.
InputStream	getEncryptedInputStream() Gets the encrypted input stream to wrap for decryption.
byte[]	getEncryptedKey() Gets the encrypted version of the plaintext key.
OutputStream	getEncryptedOutputStream() Gets the encrypted output stream, which is nearly always a wrapped version of the output stream from getPlaintextOutputStream().
String	getEncryptionMode() Gets the name of the encryption mode to use for encryption.
byte[]	getInitializationVector() Gets the initialization vector to use for this crypto module.
String	getKeyEncryptionStrategyClass() Gets the key encryption strategy class.
int	getKeyLength() Gets the length of the secret key.
String	getOpaqueKeyEncryptionKeyID() Gets the opaque ID associated with the encrypted version of the plaintext key.
boolean	getOverrideStreamsSecretKeyEncryptionStrategy() Gets the flag that indicates if the underlying stream's key encryption strategy should be overridden by the currently configured key encryption strategy.
String	getPadding() Gets the name of the padding type to use for encryption.
InputStream	getPlaintextInputStream() Gets the plaintext input stream, which is nearly always a wrapped version of the output from getEncryptedInputStream().
byte[]	getPlaintextKey() Gets the plaintext secret key.
OutputStream	getPlaintextOutputStream() Gets the plaintext output stream to wrap for encryption.
String	getRandomNumberGenerator() Gets the random number generator name.
String	getRandomNumberGeneratorProvider() Gets the random number generator provider name.
boolean	getRecordParametersToStream() Gets the flag that indicates whether or not the module should record its cryptographic parameters to the stream automatically, or rely on the calling code to do so.
SecureRandom	getSecureRandom() Gets the initialized secure random object.
void	setAlgorithmName(String algorithmName) Sets the name of the symmetric algorithm to use for an encryption stream.
void	setAllOptions(Map<String,String> allOptions) Sets the overall set of options for the CryptoModule.
void	setBlockStreamSize(int blockStreamSize) Sets the size of the buffering stream that sits above the cipher stream
void	setCipher(Cipher cipher) Sets the initialized cipher object.
void	setCloseUnderylingStreamAfterCryptoStreamClose(boolean closeUnderylingStreamAfterCryptoStreamClose) Sets the flag that indicates whether or not to close the underlying stream when the cipher stream is closed.
void	setEncryptedInputStream(InputStream encryptedInputStream) Sets the encrypted input stream to wrap for decryption.
void	setEncryptedKey(byte[] encryptedKey) Sets the encrypted version of the plaintext key (getPlaintextKey()).
void	setEncryptedOutputStream(OutputStream encryptedOutputStream) Sets the encrypted output stream.
void	setEncryptionMode(String encryptionMode) Sets the name of the encryption mode to use for an encryption stream.
void	setInitializationVector(byte[] initializationVector) Sets the initialization vector to use for this crypto module.
void	setKeyEncryptionStrategyClass(String keyEncryptionStrategyClass) Sets the class name of the key encryption strategy class.
void	setKeyLength(int keyLength) Sets the length of the secret key that will be used to encrypt and decrypt bytes.
void	setOpaqueKeyEncryptionKeyID(String opaqueKeyEncryptionKeyID) Sets an opaque ID assocaited with the encrypted version of the plaintext key.
void	setOverrideStreamsSecretKeyEncryptionStrategy(boolean overrideStreamsSecretKeyEncryptionStrategy) Sets the flag that indicates if the underlying stream's key encryption strategy should be overridden by the currently configured key encryption strategy.
void	setPadding(String padding) Sets the name of the padding type to use for an encryption stream.
void	setPlaintextInputStream(InputStream plaintextInputStream) Sets the plaintext input stream, which is nearly always a wrapped version of the output from getEncryptedInputStream().
void	setPlaintextKey(byte[] plaintextKey) Sets the plaintext secret key that will be used to encrypt and decrypt bytes.
void	setPlaintextOutputStream(OutputStream plaintextOutputStream) Sets the plaintext output stream to wrap for encryption.
void	setRandomNumberGenerator(String randomNumberGenerator) Sets the name of the random number generator to use.
void	setRandomNumberGeneratorProvider(String randomNumberGeneratorProvider) Sets the name of the random number generator provider to use.
void	setRecordParametersToStream(boolean recordParametersToStream) Gets the flag that indicates whether or not the module should record its cryptographic parameters to the stream automatically, or rely on the calling code to do so.
void	setSecureRandom(SecureRandom secureRandom) Sets the initialized secure random object.

Methods inherited from class java.lang.Object

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

Constructor Detail

CryptoModuleParameters

public CryptoModuleParameters()

Method Detail

getAlgorithmName

public String getAlgorithmName()

Gets the name of the symmetric algorithm to use for encryption.

See Also:

setAlgorithmName(String)

setAlgorithmName

public void setAlgorithmName(String algorithmName)

Sets the name of the symmetric algorithm to use for an encryption stream.

Valid names are names recognized by your cryptographic engine provider. For the default Java provider, valid names would include things like "AES", "RC4", "DESede", etc.

For encryption, this value is required and is always used. Its value should be prepended or otherwise included with the ciphertext for future decryption.
For decryption, this value is often disregarded in favor of the value encoded with the ciphertext.

Parameters:

algorithmName - the name of the cryptographic algorithm to use.

See Also:

Standard Algorithm Names in JCE

getEncryptionMode

public String getEncryptionMode()

Gets the name of the encryption mode to use for encryption.

See Also:

setEncryptionMode(String)

setEncryptionMode

public void setEncryptionMode(String encryptionMode)

Sets the name of the encryption mode to use for an encryption stream.

Valid names are names recognized by your cryptographic engine provider. For the default Java provider, valid names would include things like "EBC", "CBC", "CFB", etc.

For encryption, this value is required and is always used. Its value should be prepended or otherwise included with the ciphertext for future decryption.
For decryption, this value is often disregarded in favor of the value encoded with the ciphertext.

Parameters:

encryptionMode - the name of the encryption mode to use.

See Also:

Standard Mode Names in JCE

getPadding

public String getPadding()

Gets the name of the padding type to use for encryption.

See Also:

setPadding(String)

setPadding

public void setPadding(String padding)

Sets the name of the padding type to use for an encryption stream.

Valid names are names recognized by your cryptographic engine provider. For the default Java provider, valid names would include things like "NoPadding", "None", etc.

For encryption, this value is required and is always used. Its value should be prepended or otherwise included with the ciphertext for future decryption.
For decryption, this value is often disregarded in favor of the value encoded with the ciphertext.

Parameters:

padding - the name of the padding type to use.

See Also:

Standard Padding Names in JCE

getPlaintextKey

public byte[] getPlaintextKey()

Gets the plaintext secret key.

For decryption, this value is often the out parameter of using a secret key encryption strategy to decrypt an encrypted version of this secret key. (See setKeyEncryptionStrategyClass(String).)

See Also:

setPlaintextKey(byte[])

setPlaintextKey

public void setPlaintextKey(byte[] plaintextKey)

Sets the plaintext secret key that will be used to encrypt and decrypt bytes.

Valid values and lengths for this secret key depend entirely on the algorithm type. Refer to the documentation about the algorithm for further information.

For encryption, this value is optional. If it is not provided, it will be automatically generated by the underlying cryptographic module.
For decryption, this value is often obtained from the underlying cipher stream, or derived from the encrypted version of the key (see setEncryptedKey(byte[])).

Parameters:

plaintextKey - the value of the plaintext secret key

getKeyLength

public int getKeyLength()

Gets the length of the secret key.

See Also:

setKeyLength(int)

setKeyLength

public void setKeyLength(int keyLength)

Sets the length of the secret key that will be used to encrypt and decrypt bytes.

Valid lengths depend entirely on the algorithm type. Refer to the documentation about the algorithm for further information. (For example, AES may use either 128 or 256 bit keys in the default Java cryptography provider.)

For encryption, this value is required if the secret key is not set.
For decryption, this value is often obtained from the underlying cipher stream, or derived from the encrypted version of the key (see setEncryptedKey(byte[])).

Parameters:

keyLength - the length of the secret key to be generated

getRandomNumberGenerator

public String getRandomNumberGenerator()

Gets the random number generator name.

See Also:

setRandomNumberGenerator(String)

setRandomNumberGenerator

public void setRandomNumberGenerator(String randomNumberGenerator)

Sets the name of the random number generator to use. The default for this for the baseline JCE implementation is "SHA1PRNG".

For encryption, this value is required.
For decryption, this value is often obtained from the underlying cipher stream.

Parameters:

randomNumberGenerator - the name of the random number generator to use

getRandomNumberGeneratorProvider

public String getRandomNumberGeneratorProvider()

Gets the random number generator provider name.

See Also:

setRandomNumberGeneratorProvider(String)

setRandomNumberGeneratorProvider

public void setRandomNumberGeneratorProvider(String randomNumberGeneratorProvider)

Sets the name of the random number generator provider to use. The default for this for the baseline JCE implementation is "SUN".

The provider, as the name implies, provides the RNG implementation specified by getRandomNumberGenerator().

For encryption, this value is required.
For decryption, this value is often obtained from the underlying cipher stream.

Parameters:

randomNumberGeneratorProvider - the name of the provider to use

getKeyEncryptionStrategyClass

public String getKeyEncryptionStrategyClass()

Gets the key encryption strategy class.

See Also:

setKeyEncryptionStrategyClass(String)

setKeyEncryptionStrategyClass

public void setKeyEncryptionStrategyClass(String keyEncryptionStrategyClass)

Sets the class name of the key encryption strategy class. The class obeys the SecretKeyEncryptionStrategy interface. It instructs the DefaultCryptoModule on how to encrypt the keys it uses to secure the streams.

The default implementation of this interface, CachingHDFSSecretKeyEncryptionStrategy, creates a random key encryption key (KEK) as another symmetric key and places the KEK into HDFS. This is not really very secure. Users of the crypto modules are encouraged to either safeguard that KEK carefully or to obtain and use another SecretKeyEncryptionStrategy class.

For encryption, this value is optional. If it is not specified, then it assumed that the secret keys used for encrypting files will not be encrypted. This is not a secure approach, thus setting this is highly recommended.
For decryption, this value is often obtained from the underlying cipher stream. However, the underlying stream's value can be overridden (at least when using DefaultCryptoModule) by setting the setOverrideStreamsSecretKeyEncryptionStrategy(boolean) to true.

Parameters:

keyEncryptionStrategyClass - the name of the key encryption strategy class to use

getEncryptedKey

public byte[] getEncryptedKey()

Gets the encrypted version of the plaintext key. This parameter is generally either obtained from an underlying stream or computed in the process of employed the getKeyEncryptionStrategyClass().

See Also:

setEncryptedKey(byte[])

setEncryptedKey

public void setEncryptedKey(byte[] encryptedKey)

Sets the encrypted version of the plaintext key (getPlaintextKey()). Generally this operation will be done either by:

• the code reading an encrypted stream and coming across the encrypted version of one of these keys, OR
• the getKeyEncryptionStrategyClass() that encrypted the plaintext key (see getPlaintextKey()).

For encryption, this value is generally not required, but is usually set by the underlying module during encryption.
For decryption, this value is usually required.

Parameters:

encryptedKey - the encrypted value of the plaintext key

getOpaqueKeyEncryptionKeyID

public String getOpaqueKeyEncryptionKeyID()

Gets the opaque ID associated with the encrypted version of the plaintext key.

See Also:

setOpaqueKeyEncryptionKeyID(String)

setOpaqueKeyEncryptionKeyID

public void setOpaqueKeyEncryptionKeyID(String opaqueKeyEncryptionKeyID)

Sets an opaque ID assocaited with the encrypted version of the plaintext key.

Often, implementors of the SecretKeyEncryptionStrategy will need to record some information about how they encrypted a particular plaintext key. For example, if the strategy employs several keys for its encryption, it will want to record which key it used. The caller should not have to worry about the format or contents of this internal ID; thus, the strategy class will encode whatever information it needs into this string. It is then beholden to the calling code to record this opqaue string properly to the underlying cryptographically-encoded stream, and then set the opaque ID back into this parameter object upon reading.

For encryption, this value is generally not required, but will be typically generated and set by the SecretKeyEncryptionStrategy class (see getKeyEncryptionStrategyClass()).
For decryption, this value is required, though it will typically be read from the underlying stream.

Parameters:

opaqueKeyEncryptionKeyID - the opaque ID assoicated with the encrypted version of the plaintext key (see getEncryptedKey()).

getRecordParametersToStream

public boolean getRecordParametersToStream()

Gets the flag that indicates whether or not the module should record its cryptographic parameters to the stream automatically, or rely on the calling code to do so.

See Also:

setRecordParametersToStream(boolean)

setRecordParametersToStream

public void setRecordParametersToStream(boolean recordParametersToStream)

Gets the flag that indicates whether or not the module should record its cryptographic parameters to the stream automatically, or rely on the calling code to do so.

If this is set to true, then the stream passed to CryptoModule.getEncryptingOutputStream(CryptoModuleParameters) will be written to by the module before it is returned to the caller. There are situations where it is easier to let the crypto module do this writing on behalf of the caller, and other times where it is not appropriate (if the format of the underlying stream must be carefully maintained, for instance).

Parameters:

recordParametersToStream - whether or not to require the module to record its parameters to the stream by itself

getCloseUnderylingStreamAfterCryptoStreamClose

public boolean getCloseUnderylingStreamAfterCryptoStreamClose()

Gets the flag that indicates whether or not to close the underlying stream when the cipher stream is closed.

See Also:

setCloseUnderylingStreamAfterCryptoStreamClose(boolean)

setCloseUnderylingStreamAfterCryptoStreamClose

public void setCloseUnderylingStreamAfterCryptoStreamClose(boolean closeUnderylingStreamAfterCryptoStreamClose)

Sets the flag that indicates whether or not to close the underlying stream when the cipher stream is closed.

CipherOutputStream will only output its padding bytes when its CipherOutputStream.close() method is called. However, there are times when a caller doesn't want its underlying stream closed at the time that the CipherOutputStream is closed. This flag indicates that the CryptoModule should wrap the underlying stream in a basic FilterOutputStream which will swallow any close() calls and prevent them from propogating to the underlying stream.

Parameters:

closeUnderylingStreamAfterCryptoStreamClose - the flag that indicates whether or not to close the underlying stream when the cipher stream is closed

getOverrideStreamsSecretKeyEncryptionStrategy

public boolean getOverrideStreamsSecretKeyEncryptionStrategy()

Gets the flag that indicates if the underlying stream's key encryption strategy should be overridden by the currently configured key encryption strategy.

See Also:

setOverrideStreamsSecretKeyEncryptionStrategy(boolean)

setOverrideStreamsSecretKeyEncryptionStrategy

public void setOverrideStreamsSecretKeyEncryptionStrategy(boolean overrideStreamsSecretKeyEncryptionStrategy)

Sets the flag that indicates if the underlying stream's key encryption strategy should be overridden by the currently configured key encryption strategy.

So, why is this important? Say you started out with the default secret key encryption strategy. So, now you have a secret key in HDFS that encrypts all the other secret keys. Then you deploy a key management solution. You want to move that secret key up to the key management server. Great! No problem. Except, all your encrypted files now contain a setting that says "hey I was encrypted by the default strategy, so find decrypt my key using that, not the key management server". This setting signals the CryptoModule that it should ignore the setting in the file and prefer the one from the configuration.

Parameters:

overrideStreamsSecretKeyEncryptionStrategy - the flag that indicates if the underlying stream's key encryption strategy should be overridden by the currently configured key encryption strategy

getPlaintextOutputStream

public OutputStream getPlaintextOutputStream()

Gets the plaintext output stream to wrap for encryption.

See Also:

setPlaintextOutputStream(OutputStream)

setPlaintextOutputStream

public void setPlaintextOutputStream(OutputStream plaintextOutputStream)

Sets the plaintext output stream to wrap for encryption.

For encryption, this parameter is required.
For decryption, this parameter is ignored.

getEncryptedOutputStream

public OutputStream getEncryptedOutputStream()

Gets the encrypted output stream, which is nearly always a wrapped version of the output stream from getPlaintextOutputStream().

Generally this method is used by CryptoModule classes as an out parameter from calling CryptoModule.getEncryptingOutputStream(CryptoModuleParameters).

See Also:

setEncryptedOutputStream(OutputStream)

setEncryptedOutputStream

public void setEncryptedOutputStream(OutputStream encryptedOutputStream)

Sets the encrypted output stream. This method should really only be called by CryptoModule implementations unless something very unusual is going on.

Parameters:

encryptedOutputStream - the encrypted version of the stream from output stream from getPlaintextOutputStream().

getPlaintextInputStream

public InputStream getPlaintextInputStream()

Gets the plaintext input stream, which is nearly always a wrapped version of the output from getEncryptedInputStream().

Generally this method is used by CryptoModule classes as an out parameter from calling CryptoModule.getDecryptingInputStream(CryptoModuleParameters).

See Also:

setPlaintextInputStream(InputStream)

setPlaintextInputStream

public void setPlaintextInputStream(InputStream plaintextInputStream)

Sets the plaintext input stream, which is nearly always a wrapped version of the output from getEncryptedInputStream().

This method should really only be called by CryptoModule implementations.

getEncryptedInputStream

public InputStream getEncryptedInputStream()

Gets the encrypted input stream to wrap for decryption.

See Also:

setEncryptedInputStream(InputStream)

setEncryptedInputStream

public void setEncryptedInputStream(InputStream encryptedInputStream)

Sets the encrypted input stream to wrap for decryption.

getCipher

public Cipher getCipher()

Gets the initialized cipher object.

See Also:

setCipher(Cipher)

setCipher

public void setCipher(Cipher cipher)

Sets the initialized cipher object. Generally speaking, callers do not have to create and set this object. There may be circumstances where the cipher object is created outside of the module (to determine IV lengths, for one). If it is created and you want the module to use the cipher you already initialized, set it here.

Parameters:

cipher - the cipher object

getSecureRandom

public SecureRandom getSecureRandom()

Gets the initialized secure random object.

See Also:

setSecureRandom(SecureRandom)

setSecureRandom

public void setSecureRandom(SecureRandom secureRandom)

Sets the initialized secure random object. Generally speaking, callers do not have to create and set this object. There may be circumstances where the random object is created outside of the module (for instance, to create a random secret key). If it is created outside the module and you want the module to use the random object you already created, set it here.

Parameters:

secureRandom - the SecureRandom object

getInitializationVector

public byte[] getInitializationVector()

Gets the initialization vector to use for this crypto module.

See Also:

setInitializationVector(byte[])

setInitializationVector

public void setInitializationVector(byte[] initializationVector)

Sets the initialization vector to use for this crypto module.

For encryption, this parameter is optional. If the initialization vector is created by the caller, for whatever reasons, it can be set here and the crypto module will use it.
For decryption, this parameter is required. It should be read from the underlying stream that contains the encrypted data.

Parameters:

initializationVector - the initialization vector to use for this crypto operation.

getBlockStreamSize

public int getBlockStreamSize()

Gets the size of the buffering stream that sits above the cipher stream

setBlockStreamSize

public void setBlockStreamSize(int blockStreamSize)

Sets the size of the buffering stream that sits above the cipher stream

getAllOptions

public Map<String,String> getAllOptions()

Gets the overall set of options for the CryptoModule.

See Also:

setAllOptions(Map)

setAllOptions

public void setAllOptions(Map<String,String> allOptions)

Sets the overall set of options for the CryptoModule.

Often, options for the cryptographic modules will be encoded as key/value pairs in a configuration file. This map represents those values. It may include some of the parameters already called out as members of this class. It may contain any number of additional parameters which may be required by different module or key encryption strategy implementations.

Parameters:

allOptions - the set of key/value pairs that confiure a module, based on a configuration file