org.apache.accumulo.core.security.crypto
public class CryptoModuleParameters extends Object
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 and Description |
---|
CryptoModuleParameters() |
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.
|
public String getAlgorithmName()
setAlgorithmName(String)
public void setAlgorithmName(String algorithmName)
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.
algorithmName
- the name of the cryptographic algorithm to use.public String getEncryptionMode()
setEncryptionMode(String)
public void setEncryptionMode(String encryptionMode)
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.
encryptionMode
- the name of the encryption mode to use.public String getPadding()
setPadding(String)
public void setPadding(String padding)
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.
padding
- the name of the padding type to use.public byte[] getPlaintextKey()
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)
.)
setPlaintextKey(byte[])
public void setPlaintextKey(byte[] plaintextKey)
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[])
).
plaintextKey
- the value of the plaintext secret keypublic int getKeyLength()
setKeyLength(int)
public void setKeyLength(int keyLength)
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[])
).
keyLength
- the length of the secret key to be generatedpublic String getRandomNumberGenerator()
setRandomNumberGenerator(String)
public void setRandomNumberGenerator(String randomNumberGenerator)
For encryption, this value is required.
For decryption, this value is often obtained from the underlying cipher stream.
randomNumberGenerator
- the name of the random number generator to usepublic String getRandomNumberGeneratorProvider()
public void setRandomNumberGeneratorProvider(String randomNumberGeneratorProvider)
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.
randomNumberGeneratorProvider
- the name of the provider to usepublic String getKeyEncryptionStrategyClass()
public void setKeyEncryptionStrategyClass(String keyEncryptionStrategyClass)
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.
keyEncryptionStrategyClass
- the name of the key encryption strategy class to usepublic byte[] getEncryptedKey()
getKeyEncryptionStrategyClass()
.setEncryptedKey(byte[])
public void setEncryptedKey(byte[] encryptedKey)
getPlaintextKey()
). Generally this operation will be done either by:
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.
encryptedKey
- the encrypted value of the plaintext keypublic String getOpaqueKeyEncryptionKeyID()
setOpaqueKeyEncryptionKeyID(String)
public void setOpaqueKeyEncryptionKeyID(String opaqueKeyEncryptionKeyID)
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.
opaqueKeyEncryptionKeyID
- the opaque ID assoicated with the encrypted version of the plaintext key (see getEncryptedKey()
).public boolean getRecordParametersToStream()
setRecordParametersToStream(boolean)
public void setRecordParametersToStream(boolean recordParametersToStream)
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).
recordParametersToStream
- whether or not to require the module to record its parameters to the stream by itselfpublic boolean getCloseUnderylingStreamAfterCryptoStreamClose()
public void setCloseUnderylingStreamAfterCryptoStreamClose(boolean closeUnderylingStreamAfterCryptoStreamClose)
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.
closeUnderylingStreamAfterCryptoStreamClose
- the flag that indicates whether or not to close the underlying stream when the cipher stream is closedpublic boolean getOverrideStreamsSecretKeyEncryptionStrategy()
public void setOverrideStreamsSecretKeyEncryptionStrategy(boolean overrideStreamsSecretKeyEncryptionStrategy)
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.
overrideStreamsSecretKeyEncryptionStrategy
- the flag that indicates if the underlying stream's key encryption strategy should be overridden by the currently configured key encryption
strategypublic OutputStream getPlaintextOutputStream()
public void setPlaintextOutputStream(OutputStream plaintextOutputStream)
For encryption, this parameter is required.
For decryption, this parameter is ignored.
public OutputStream getEncryptedOutputStream()
getPlaintextOutputStream()
.
Generally this method is used by CryptoModule
classes as an out parameter from calling
CryptoModule.getEncryptingOutputStream(CryptoModuleParameters)
.
public void setEncryptedOutputStream(OutputStream encryptedOutputStream)
CryptoModule
implementations unless something very unusual is going
on.encryptedOutputStream
- the encrypted version of the stream from output stream from getPlaintextOutputStream()
.public InputStream getPlaintextInputStream()
getEncryptedInputStream()
.
Generally this method is used by CryptoModule
classes as an out parameter from calling
CryptoModule.getDecryptingInputStream(CryptoModuleParameters)
.
setPlaintextInputStream(InputStream)
public void setPlaintextInputStream(InputStream plaintextInputStream)
getEncryptedInputStream()
.
This method should really only be called by CryptoModule
implementations.
public InputStream getEncryptedInputStream()
setEncryptedInputStream(InputStream)
public void setEncryptedInputStream(InputStream encryptedInputStream)
public Cipher getCipher()
setCipher(Cipher)
public void setCipher(Cipher cipher)
cipher
- the cipher objectpublic SecureRandom getSecureRandom()
setSecureRandom(SecureRandom)
public void setSecureRandom(SecureRandom secureRandom)
secureRandom
- the SecureRandom
objectpublic byte[] getInitializationVector()
setInitializationVector(byte[])
public void setInitializationVector(byte[] initializationVector)
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.
initializationVector
- the initialization vector to use for this crypto operation.public int getBlockStreamSize()
public void setBlockStreamSize(int blockStreamSize)
public Map<String,String> getAllOptions()
CryptoModule
.setAllOptions(Map)
public void setAllOptions(Map<String,String> allOptions)
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.
allOptions
- the set of key/value pairs that confiure a module, based on a configuration fileCopyright © 2011–2015 The Apache Software Foundation. All rights reserved.