cz.d1x.dxcrypto.encryption

Class SymmetricAlgorithmBuilder

java.lang.Object

cz.d1x.dxcrypto.encryption.SymmetricAlgorithmBuilder

public final class SymmetricAlgorithmBuilder
extends Object

Base builder for symmetric key algorithms based on GenericEncryptionAlgorithm. For all supported symmetric ciphers we use initialization vector so we have it also in this builder even if symmetric ciphers can be without IV by definition. If we would support other ciphers that does not have IV, this builder should be refactored into two different classes.

Author:

Zdenek Obst, zdenek.obst-at-gmail.com

See Also:

GenericEncryptionAlgorithm

Constructor Summary

Constructors

Constructor and Description
SymmetricAlgorithmBuilder(EncryptionFactories factories, SymmetricEncryptionEngineFactory<ByteArray> engineFactory, int keySize, int blockSize) Creates a new builder.

Method Summary

Modifier and Type	Method and Description
StreamingEncryptionAlgorithm	build() Builds a new instance of encryption algorithm.
SymmetricAlgorithmBuilder	bytesRepresentation(BytesRepresentation bytesRepresentation) Sets how byte arrays will be represented in strings.
SymmetricAlgorithmBuilder	encoding(String encoding) Sets encoding for strings in input and output.
SymmetricAlgorithmBuilder	engineFactory(SymmetricEncryptionEngineFactory<ByteArray> engineFactory) Sets factory for encryption engine.
SymmetricAlgorithmBuilder	ivAndOutputCombining(CombiningSplitting ivOutputCombining) Sets algorithm combining initialization vector and cipher text in output during encryption and splitting from input during decryption.
SymmetricAlgorithmBuilder	ivFactory(ByteArrayFactory ivFactory) Sets algorithm for generation of initialization vector for every message.
SymmetricAlgorithmBuilder	key(byte[] key) Set custom key.
SymmetricAlgorithmBuilder	keyDerivation(byte[] keyPassword, byte[] keySalt, int keyHashIterations) Sets all parameters for key derivation function.
SymmetricAlgorithmBuilder	keyFactory(EncryptionKeyFactory<ByteArray,DerivedKeyParams> keyFactory) Sets a custom key factory.
SymmetricAlgorithmBuilder	keyHashIterations(int keyHashIterations) Sets number of iterations of hashing for key derivation.
SymmetricAlgorithmBuilder	keyPassword(byte[] keyPassword) Sets a key password for key derivation.
SymmetricAlgorithmBuilder	keyPassword(String keyPassword) Sets a key password for key derivation.
SymmetricAlgorithmBuilder	keySalt(byte[] keySalt) Sets salt for key derivation.
SymmetricAlgorithmBuilder	keySalt(String keySalt) Sets salt for key derivation.

Methods inherited from class java.lang.Object

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

Constructor Detail

SymmetricAlgorithmBuilder

public SymmetricAlgorithmBuilder(EncryptionFactories factories,
                                 SymmetricEncryptionEngineFactory<ByteArray> engineFactory,
                                 int keySize,
                                 int blockSize)

Creates a new builder.

Parameters:

factories - factories for engines

engineFactory - factory for encryption engine

keySize - size of the key (in bits)

blockSize - size of the block (in bits)

Method Detail

engineFactory

public SymmetricAlgorithmBuilder engineFactory(SymmetricEncryptionEngineFactory<ByteArray> engineFactory)
                                        throws IllegalArgumentException

Sets factory for encryption engine.

Parameters:

engineFactory - factory for encryption engine

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed factory is null

key

public SymmetricAlgorithmBuilder key(byte[] key)
                              throws IllegalArgumentException

Set custom key. Note that client is responsible for correct key size. If passed key size is invalid, IllegalArgumentException is thrown.

Note that if you use this method, it overrides previous setting of keyFactory(EncryptionKeyFactory) and keyPassword(byte[]).

Parameters:

key - key to be set

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed key is null or key size is invalid

keyPassword

public SymmetricAlgorithmBuilder keyPassword(byte[] keyPassword)
                                      throws IllegalArgumentException

Sets a key password for key derivation.

Note that if you use this method, it overrides previous setting of key(byte[]).

Parameters:

keyPassword - key password for key derivation

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed key password is null

keyPassword

public SymmetricAlgorithmBuilder keyPassword(String keyPassword)
                                      throws IllegalArgumentException

Sets a key password for key derivation.

Note that if you use this method, it overrides previous setting of key(byte[]).

Parameters:

keyPassword - key password for key derivation

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed key password is null

keySalt

public SymmetricAlgorithmBuilder keySalt(byte[] keySalt)
                                  throws IllegalArgumentException

Sets salt for key derivation. Recommended length is at least 8 bytes.

Parameters:

keySalt - salt to be set

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed key salt is null

keySalt

public SymmetricAlgorithmBuilder keySalt(String keySalt)
                                  throws IllegalArgumentException

Sets salt for key derivation. Recommended length is at least 8 bytes.

Parameters:

keySalt - salt to be set

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed key salt is null

keyHashIterations

public SymmetricAlgorithmBuilder keyHashIterations(int keyHashIterations)
                                            throws IllegalArgumentException

Sets number of iterations of hashing for key derivation. Recommended count is at least 1000.

Parameters:

keyHashIterations - number of hash iterations

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed iterations are lower than 1

keyDerivation

public SymmetricAlgorithmBuilder keyDerivation(byte[] keyPassword,
                                               byte[] keySalt,
                                               int keyHashIterations)
                                        throws IllegalArgumentException

Sets all parameters for key derivation function.

Note that if you use this method, it overrides previous setting of key(byte[]).

Parameters:

keyPassword - key password for key derivation

keySalt - salt for key derivation

keyHashIterations - number of hash iterations

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed key password is null

keyFactory

public SymmetricAlgorithmBuilder keyFactory(EncryptionKeyFactory<ByteArray,DerivedKeyParams> keyFactory)
                                     throws IllegalArgumentException

Sets a custom key factory.

Note that if you use this method, it overrides previous setting of key(byte[]).

Parameters:

keyFactory - factory to be set

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed factory is null

ivFactory

public SymmetricAlgorithmBuilder ivFactory(ByteArrayFactory ivFactory)
                                    throws IllegalArgumentException

Sets algorithm for generation of initialization vector for every message. This is used only for algorithms that use it (typically CBC-based algorithms like AES, 3DES...). Note that it is recommended to have unique initialization vector for every message that is later combined with encrypted output via ivAndOutputCombining(CombiningSplitting) into the final output.

Parameters:

ivFactory - factory for initialization vector

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed ByteArrayFactory is null

ivAndOutputCombining

public SymmetricAlgorithmBuilder ivAndOutputCombining(CombiningSplitting ivOutputCombining)
                                               throws IllegalArgumentException

Sets algorithm combining initialization vector and cipher text in output during encryption and splitting from input during decryption.

Parameters:

ivOutputCombining - combine/split algorithm for IV and cipher text

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed CombiningSplitting is null

bytesRepresentation

public SymmetricAlgorithmBuilder bytesRepresentation(BytesRepresentation bytesRepresentation)
                                              throws IllegalArgumentException

Sets how byte arrays will be represented in strings. By default HexRepresentation is used.

Parameters:

bytesRepresentation - byte array representation strategy

Returns:

this instance

Throws:

IllegalArgumentException - exception if passed BytesRepresentation is null

encoding

public SymmetricAlgorithmBuilder encoding(String encoding)
                                   throws IllegalArgumentException

Sets encoding for strings in input and output.

Parameters:

encoding - encoding to be set

Returns:

this instance

Throws:

IllegalArgumentException - exception if given encoding is null or not supported

build

public StreamingEncryptionAlgorithm build()
                                   throws IllegalArgumentException

Builds a new instance of encryption algorithm.

Returns:

algorithm instance

Throws:

IllegalArgumentException