Package org.apache.accumulo.core.security.crypto

Class CryptoModuleParameters

    • 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

      • 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

      • 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

      • 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

      • 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:

        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

      • 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

      • 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.

      • 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().

      • 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.

      • setEncryptedInputStream

        public void setEncryptedInputStream​(InputStream encryptedInputStream)
        Sets the encrypted input stream to wrap for decryption.

      • 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

      • 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

      • 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