org.cumulus4j.crypto
Class CryptoRegistry

java.lang.Object
  org.cumulus4j.crypto.CryptoRegistry

public final class CryptoRegistry
extends Object

Entry to the unified crypto API.

This registry can be used for various cryptography-related tasks. For example to create a cipher or to create a key-pair-generator.

Author:

Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de

Method Summary

Cipher	createCipher(String transformation) Create a Cipher instance according to the given transformation.
AsymmetricCipherKeyPairGenerator	createKeyPairGenerator(String algorithmName, boolean initWithDefaults) Create a key pair generator for the given asymmetric encryption algorithm.
MACCalculator	createMACCalculator(String algorithmName, boolean initWithDefaults) Create a MAC calculator.
SecretKeyGenerator	createSecretKeyGenerator(String algorithmName, boolean initWithDefaults) Create a new SecretKeyGenerator.
CipherParameters	decodePrivateKey(byte[] privateKeyData) Decode (deserialise) a private key, that was previously encoded (serialised) by encodePrivateKey(CipherParameters).
CipherParameters	decodePublicKey(byte[] publicKeyData) Decode (deserialise) a public key, that was previously encoded (serialised) by encodePublicKey(CipherParameters).
byte[]	encodePrivateKey(CipherParameters privateKey) Encode (serialise) a private key in order to store it or transport it over a network.
byte[]	encodePublicKey(CipherParameters publicKey) Encode (serialise) a public key in order to store it or transport it over a network.
Set<String>	getSupportedCipherEngines(CipherEngineType cipherEngineType) Get all supported cipher engines.
Set<String>	getSupportedCipherModes(String cipherEngine) Get all supported modes for the given cipher engine (a raw encryption algorithm).
Set<String>	getSupportedCipherPaddings(CipherEngineType cipherEngineType) Get all supported paddings for the given CipherEngineType.
Set<String>	getSupportedCipherPaddings(String cipherEngine, String cipherMode) Get all supported paddings for the given cipher engine (a raw encryption algorithm) and mode.
Set<String>	getSupportedCipherTransformations(CipherEngineType cipherEngineType) Get all supported cipher transformations.
Set<String>	getSupportedMACAlgorithms() Get all supported MAC algorithms.
static CryptoRegistry	sharedInstance() Get the shared instance of this registry.
static String[]	splitTransformation(String transformation) Split the transformation-String into its parts.

Methods inherited from class java.lang.Object

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

Method Detail

sharedInstance

public static CryptoRegistry sharedInstance()

Get the shared instance of this registry.

Returns:

the shared instance.

getSupportedCipherEngines

public Set<String> getSupportedCipherEngines(CipherEngineType cipherEngineType)

Get all supported cipher engines. A cipher engine implements a raw encryption algorithm; 'raw' means without any additional transformation like block mode or padding.

Parameters:

cipherEngineType - the type of the cipher engine or null to list all.

Returns:

all supported cipher engines for the (optionally) given criteria.

See Also:

createCipher(String)

getSupportedCipherModes

public Set<String> getSupportedCipherModes(String cipherEngine)

Get all supported modes for the given cipher engine (a raw encryption algorithm). The cipherEngine can be null to not restrict the result by this criterion.

See Supported algorithms for a list of supported algorithms or use getSupportedCipherEngines(CipherEngineType) to query them.

Parameters:

cipherEngine - the name of the encryption algorithm for which to look up supported modes or null to list all.

Returns:

all supported modes for the (optionally) given criteria.

See Also:

createCipher(String)

getSupportedCipherPaddings

public Set<String> getSupportedCipherPaddings(CipherEngineType cipherEngineType)

Get all supported paddings for the given CipherEngineType. If there is no cipher-engine-type given, all supported paddings for all engine types are returned.

Parameters:

cipherEngineType - the type of the cipher engine or null to ignore this criterion.

Returns:

all supported paddings for the (optionally) given criteria.

See Also:

createCipher(String)

getSupportedCipherPaddings

public Set<String> getSupportedCipherPaddings(String cipherEngine,
                                              String cipherMode)

Get all supported paddings for the given cipher engine (a raw encryption algorithm) and mode. Each of the parameters can be null to not restrict the result by this criterion.

See Supported algorithms for a list of supported algorithms or use getSupportedCipherEngines(CipherEngineType) and getSupportedCipherModes(String) to query them.

Parameters:

cipherEngine - the cipher engine for which to get the supported paddings or null to list all.

cipherMode - the mode to restrict the result or null to list all (for the given cipher-engine).

Returns:

all supported paddings for the (optionally) given criteria.

See Also:

createCipher(String)

getSupportedCipherTransformations

public Set<String> getSupportedCipherTransformations(CipherEngineType cipherEngineType)

Get all supported cipher transformations.

Every element of the resulting Set can be passed to createCipher(String) and will return a usable Cipher instance. However, not everything that is supported makes sense! It might not even be secure in certain situations! This is just a listing of what you theoretically could pass to createCipher(String).

Parameters:

cipherEngineType - the type of the cipher engine or null to list all.

Returns:

all supported cipher transformations for the (optionally) given criteria.

See Also:

createCipher(String)

createCipher

public Cipher createCipher(String transformation)
                    throws NoSuchAlgorithmException,
                           NoSuchPaddingException

Create a Cipher instance according to the given transformation. The transformation is a chain of algorithms containing 1 to 3 elements:

• encryption algorithm (required)
• mode (optional)
• padding (optional)

For example:

• "AES"
• "AES/CBC/PKCS5Padding"
• "Twofish/CFB/NoPadding"
• "RSA"
• "RSA/ECB/OAEPWITHSHA1ANDMGF1PADDING"
• "RSA//OAEPWITHSHA1ANDMGF1PADDING"

"ECB" and "NoPadding" are equivalent to an empty String.

See Supported algorithms for a list of supported algorithms or use getSupportedCipherTransformations(CipherEngineType) to query them. Additionally, you can use getSupportedCipherEngines(CipherEngineType), getSupportedCipherModes(String) and getSupportedCipherPaddings(String, String) to query the individual parts of the supported transformations.

Parameters:

transformation - the transformation. This is case-INsensitive. It must not be null.

Returns:

a new Cipher instance.

Throws:

NoSuchAlgorithmException - if there is no encryption engine or no mode registered to suit the given transformation.

NoSuchPaddingException - if there is no padding registered to suit the given transformation.

See Also:

getSupportedCipherTransformations(CipherEngineType), getSupportedCipherEngines(CipherEngineType), getSupportedCipherModes(String), getSupportedCipherPaddings(CipherEngineType), getSupportedCipherPaddings(String, String)

splitTransformation

public static String[] splitTransformation(String transformation)
                                    throws IllegalArgumentException

Split the transformation-String into its parts. The transformation is what you would normally pass to createCipher(String), i.e. a chain of operations usually starting with an encryption algorithm and then optionally followed by a block-cipher-mode (e.g. "CBC") and a padding (e.g. "PKCS5Padding").

Parameters:

transformation - the transformation-String.

Returns:

a String-array with exactly 3 elements. None of these is ever null. If parts are missing in the transformation, the corresponding elements are an empty string.

Throws:

IllegalArgumentException - if the given transformation is null or contains more than 3 parts (i.e. more than 2 slashes).

createSecretKeyGenerator

public SecretKeyGenerator createSecretKeyGenerator(String algorithmName,
                                                   boolean initWithDefaults)
                                            throws NoSuchAlgorithmException

Create a new SecretKeyGenerator.

Parameters:

algorithmName - the encryption algorithm for which the generated keys will be used. This is the first element of a transformation, i.e. you can pass a transformation to splitTransformation(String) and use element 0 of its result. See Supported algorithms for a list of supported algorithms.

initWithDefaults - whether to initialise the secret key generator with default values.

Returns:

an instance of SecretKeyGenerator. If initWithDefaults == true, it can directly be used to generate keys, i.e. it is already initialised with some default values. If initWithDefaults == false, you still have to initialise the key generator before you can use it.

Throws:

NoSuchAlgorithmException

createKeyPairGenerator

public AsymmetricCipherKeyPairGenerator createKeyPairGenerator(String algorithmName,
                                                               boolean initWithDefaults)
                                                        throws NoSuchAlgorithmException

Create a key pair generator for the given asymmetric encryption algorithm. If initWithDefaults is specified with value true, the returned generator is ready to be used and doesn't require any further initialisation.

Parameters:

algorithmName - the name of the asymmetric encryption algorithm. This is the first element of a transformation, i.e. you can pass a transformation to splitTransformation(String) and use element 0 of its result. See Supported algorithms for a list of supported algorithms.

initWithDefaults - whether to initialise the key pair generator with default values.

Returns:

an instance of AsymmetricCipherKeyPairGenerator. If initWithDefaults == true, it can directly be used to generate key pairs, i.e. it is already initialised with some default values. If initWithDefaults == false, you still have to initialise the key pair generator before you can use it.

Throws:

NoSuchAlgorithmException - if there is no generator available for the given algorithmName.

decodePublicKey

public CipherParameters decodePublicKey(byte[] publicKeyData)
                                 throws IOException

Decode (deserialise) a public key, that was previously encoded (serialised) by encodePublicKey(CipherParameters).

Parameters:

publicKeyData - the serialised public key.

Returns:

the public key (as previously passed to encodePublicKey(CipherParameters)).

Throws:

IOException - if parsing the serialised public key fails.

See Also:

encodePublicKey(CipherParameters), decodePrivateKey(byte[])

encodePublicKey

public byte[] encodePublicKey(CipherParameters publicKey)

Encode (serialise) a public key in order to store it or transport it over a network.

Parameters:

publicKey - the public key to be encoded; must not be null.

Returns:

the encoded (serialised) form of the public key. Can be passed to decodePublicKey(byte[]) to reverse this method.

See Also:

decodePublicKey(byte[]), encodePrivateKey(CipherParameters)

decodePrivateKey

public CipherParameters decodePrivateKey(byte[] privateKeyData)
                                  throws IOException

Decode (deserialise) a private key, that was previously encoded (serialised) by encodePrivateKey(CipherParameters).

Parameters:

privateKeyData - the serialised private key.

Returns:

the private key (as previously passed to encodePrivateKey(CipherParameters)).

Throws:

IOException - if parsing the serialised private key fails.

See Also:

encodePrivateKey(CipherParameters), decodePublicKey(byte[])

encodePrivateKey

public byte[] encodePrivateKey(CipherParameters privateKey)

Encode (serialise) a private key in order to store it or transport it over a network.

Important: You should keep your private key secret! Thus, you might want to encrypt the result before storing it to a file or sending it somewhere!

Parameters:

privateKey - the private key to be encoded; must not be null.

Returns:

the encoded (serialised) form of the private key. Can be passed to decodePrivateKey(byte[]) to reverse this method.

See Also:

decodePrivateKey(byte[]), encodePublicKey(CipherParameters)

createMACCalculator

public MACCalculator createMACCalculator(String algorithmName,
                                         boolean initWithDefaults)
                                  throws NoSuchAlgorithmException

Create a MAC calculator.

Parameters:

algorithmName - the name of the MAC algorithm. See Supported algorithms for a list of supported algorithms or use getSupportedMACAlgorithms() to query them.

initWithDefaults - whether to initialise the MACCalculator with default values so that it can be used immediately as-is.

Returns:

a new instance of MACCalculator (iff initWithDefaults==true ready-to-use; otherwise requiring initialisation before it can be used).

Throws:

NoSuchAlgorithmException - if there is no MACCalculatorFactory registered to suit the given algorithmName.

See Also:

getSupportedMACAlgorithms()

getSupportedMACAlgorithms

public Set<String> getSupportedMACAlgorithms()

Get all supported MAC algorithms. createMACCalculator(String, boolean) should be able to return a MACCalculator for each of them.

Returns:

all supported MAC algorithms.

See Also:

createMACCalculator(String, boolean)