com.github.davidcarboni.cryptolite

Class Keys

java.lang.Object

com.github.davidcarboni.cryptolite.Keys

public class Keys
extends Object

This class generates cryptographic keys. The following key types are available:

• Deterministic Symmetric "AES" keys of length symmetricKeySize, based on a password
• Random Symmetric "AES" keys of length symmetricKeySize
• Asymmetric "RSA" keys of length 3072

Deterministic keys: these are the easiest to manage as they don't need to be stored. So long as you pass in the same password each time, the same key will be generated every time. The drawback is that if you want to generate more than one key you'll need more than one password. However, if you do only need one key, this approach can be ideal as you can use the user's plaintext password to generate the key. Since you never store a user's plaintext password (see Password.hash(String)) the key can only be regenerated using the correct password. Bear in mind however that if the user changes (or resets) their password this will result in a different key, so you'll need a plan for recovering data encrypted with the old key and re-encrypting it with the new one. Random keys: these are simple to generate, but need to be stored because it's effectively impossible to regenerate the key. To store a key you should use KeyWrapper.wrapSecretKey(SecretKey). This produces an encrypted version of the key which can safely be stored in, for example, a database or properties file. The benefit of the KeyWrapper approach is that when a user changes their password you'll only need to re-encrypt the stored keys using a KeyWrapper initialised with the new password, rather than have to re-encrypt all data encrypted with the key. In both cases when a user changes their password you will have the old and the new plaintext passwords, meaning you can decrypt with the old an re-encrypt with the new. The difficulty comes when you need to reset a password, because it's not possible to recover the old password. In this case you either need a secondary password, such as a security question, or you need to be clear that data cannot be recovered. Whatever your solution, remember that storing someone's password in any recoverable form is a clear security no-no, so you'll need to put some thought into the recovery process.

Author:

David Carboni

Field Summary

Fields

Modifier and Type	Field and Description
static String	ASYMMETRIC_ALGORITHM The asymmetric encryption algorithm: "RSA".
static int	ASYMMETRIC_KEY_SIZE The key size for asymmetric keys: 3072.
static String	SYMMETRIC_ALGORITHM The symmetric encryption algorithm: "AES".
static int	SYMMETRIC_KEY_SIZE_STANDARD By default, the JVM will only allow "AES" up to 128 bit keys.
static int	SYMMETRIC_KEY_SIZE_UNLIMITED If the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" are correctly installed for your JVM, it's possible to use 256 bit keys.
static String	SYMMETRIC_PASSWORD_ALGORITHM The algorithm to use to generate password-based secret keys: "PBKDF2WithHmacSHA1".
static int	SYMMETRIC_PASSWORD_ITERATIONS The number of iterations to use for password-based key derivation: 1024.

Constructor Summary

Constructors

Constructor and Description
Keys()

Method Summary

Modifier and Type	Method and Description
static boolean	canUseStrongKeys() Tests whether the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" are correctly installed.
static SecretKey	generateSecretKey(String password, String salt) This method generates a new secret (or symmetric) key for the "AES" algorithm, using the given password and salt values.
static int	getSymmetricKeySize()
static KeyPair	newKeyPair() This method generates a new public-private (or asymmetric) key pair, using the "RSA" algorithm and a key size of 3072 bits.
static SecretKey	newSecretKey() This method generates a new secret (or symmetric) key for the "AES" algorithm with a key size of symmetricKeySize bits.
static void	setSymmetricKeySize(int newSymmetricKeySize) Sets the key size for symmetric keys.

Methods inherited from class java.lang.Object

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

Field Detail

SYMMETRIC_ALGORITHM

public static final String SYMMETRIC_ALGORITHM

The symmetric encryption algorithm: "AES".

See Also:

Constant Field Values

SYMMETRIC_KEY_SIZE_STANDARD

public static final int SYMMETRIC_KEY_SIZE_STANDARD

By default, the JVM will only allow "AES" up to 128 bit keys. This is the default value used by this class.

See Also:

Constant Field Values

SYMMETRIC_KEY_SIZE_UNLIMITED

public static final int SYMMETRIC_KEY_SIZE_UNLIMITED

If the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" are correctly installed for your JVM, it's possible to use 256 bit keys. Pass this constant to the setSymmetricKeySize(int) method to enable unlimited-strength cryptography.

See Also:

Constant Field Values

SYMMETRIC_PASSWORD_ALGORITHM

public static final String SYMMETRIC_PASSWORD_ALGORITHM

The algorithm to use to generate password-based secret keys: "PBKDF2WithHmacSHA1".

See Also:

Constant Field Values

SYMMETRIC_PASSWORD_ITERATIONS

public static final int SYMMETRIC_PASSWORD_ITERATIONS

The number of iterations to use for password-based key derivation: 1024.

See Also:

Constant Field Values

ASYMMETRIC_ALGORITHM

public static final String ASYMMETRIC_ALGORITHM

The asymmetric encryption algorithm: "RSA".

See Also:

Constant Field Values

ASYMMETRIC_KEY_SIZE

public static final int ASYMMETRIC_KEY_SIZE

The key size for asymmetric keys: 3072.

See Also:

Constant Field Values

Constructor Detail

Keys

public Keys()

Method Detail

newSecretKey

public static SecretKey newSecretKey()

This method generates a new secret (or symmetric) key for the "AES" algorithm with a key size of symmetricKeySize bits.

Returns:

A new, randomly generated SecretKey.

generateSecretKey

public static SecretKey generateSecretKey(String password,
                                          String salt)

This method generates a new secret (or symmetric) key for the "AES" algorithm, using the given password and salt values. Given the same password and salt, this method will (re)generate the same key. Note that this method may or may not handle blank passwords. This seems to be related to the implementation of the "PBKDF2WithHmacSHA1" algorithm in different Java and/or BouncyCastle provider versions.

Parameters:

password - The starting point to use in generating the key. This can be a password, or any suitably secret string. It's worth noting that, if a user's plaintext password is used, this makes key derivation secure, but means the key can never be recovered if a user forgets their password. If a different value, such as a password hash is used, this is not really secure, but does mean the key can be recovered if a user forgets their password. It's a trade-off, right?

salt - A value for this parameter can be generated by calling Random.salt(). You'll need to store the salt value (this is ok to do because salt isn't particularly sensitive) and use the same salt each time in order to always generate the same key. Using salt is good practice as it ensures that keys generated from the same password will be different - i.e. if two users use the password "password", having a salt value avoids the generated keys being identical which, for example, might give away someone's password.

Returns:

A deterministic SecretKey, defined by the given password and salt

newKeyPair

public static KeyPair newKeyPair()

This method generates a new public-private (or asymmetric) key pair, using the "RSA" algorithm and a key size of 3072 bits. BouncyCastle will automatically generate a "Chinese Remainder Theorem" or CRT key, which makes using a symmetric encryption significantly faster.

Returns:

A new, randomly generated asymmetric KeyPair.

getSymmetricKeySize

public static int getSymmetricKeySize()

Returns:

the symmetricKeySize

setSymmetricKeySize

public static void setSymmetricKeySize(int newSymmetricKeySize)

Sets the key size for symmetric keys. This defaults to 128 bit ( SYMMETRIC_KEY_SIZE_STANDARD) but can be changed to 256 bit by setting this field using the SYMMETRIC_KEY_SIZE_UNLIMITED constant. Note that whilst it's possible to generate a 256 bit key in any environment, you will need the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" installed in your JVM in order to use it. To test this, you can use the canUseStrongKeys() method.

Parameters:

newSymmetricKeySize - the symmetricKeySize to set

canUseStrongKeys

public static boolean canUseStrongKeys()

Tests whether the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" are correctly installed.

Returns:

If strong keys can be used, true, otherwise false.