com.github.davidcarboni.cryptolite

Class KeyWrapper

java.lang.Object

com.github.davidcarboni.cryptolite.KeyWrapper

All Implemented Interfaces:

Serializable

public class KeyWrapper
extends Object
implements Serializable

This class provides secure "wrapping" of keys. Wrapping a key is important if you need to store it in, for example, a database. It is not safe to store a raw key as this could be compromised, so you need to wrap a key before storing it. The wrapping process encrypts the key, so that it can be safely stored. Great! However the wrapping encryption process requires a further key! The question therefore arises - how does one safely store the wrapping key? The answer is to use a "password-based key derivation function" (PBKDF for short). This provides a way to generate the same key repeatedly, from a password (or some other secret string). There is one last problem to be overcome, which is that if two people use identical passwords, the generated keys will be identical. This could perhaps give away someone's password. The answer is therefore to use a "salt value" (which can be generated by calling Random.salt()). The salt adds randomness to the process so that two people using the same password will still get different keys. This does means you'll need to store the salt value for each person and use it each time in order to ensure you can regenerate the key. This is considered acceptable as the salt is not a particularly sensitive value - all it does is add a little randomness. The cryptographic algorithms used in this class are those indicated in the "Beginning Cryptography with Java" book. See: http://p2p.wrox.com/book-beginning -cryptography-java/67710-wrapping-rsa-keys.html

Author:

David Carboni

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	PBKD_ITERATIONS The number of iterations to perform when doing the password-based key derivation to generate the wrapping key: 1024.

Constructor Summary

Constructors

Constructor and Description
KeyWrapper(SecretKey wrapKey) This constructor sets the wrap key directly, rather than generating it from a password and salt as KeyWrapper(String, String) does.
KeyWrapper(String password, String salt) This is the constructor you should typically use.

Method Summary

Methods

Modifier and Type	Method and Description
static PublicKey	decodePublicKey(String encodedKey) Decodes the given encoded PublicKey.
static String	encodePublicKey(PublicKey key) Encodes the given PublicKey without wrapping.
PrivateKey	unwrapPrivateKey(String wrappedKey) Unwraps the given encoded PrivateKey, using WRAP_ALGORITHM_ASYMMETRIC.
SecretKey	unwrapSecretKey(String wrappedKey) Unwraps the given encoded SecretKey, using WRAP_ALGORITHM_SYMMETRIC.
String	wrapPrivateKey(PrivateKey key) Wraps the given SecretKey using .
String	wrapSecretKey(SecretKey key) Wraps the given SecretKey using .

Methods inherited from class java.lang.Object

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

Field Detail

PBKD_ITERATIONS

public static final int PBKD_ITERATIONS

The number of iterations to perform when doing the password-based key derivation to generate the wrapping key: 1024.

See Also:

Constant Field Values

Constructor Detail

KeyWrapper

public KeyWrapper(String password,
          String salt)

This is the constructor you should typically use. It initialises the instance with a wrap key based on the given password and salt values.

Parameters:

password - The password to use as the basis for wrapping keys.

salt - A value for this can be obtained from Random.salt(). You need to store a salt value for each password and ensure the matching one is passed in each time this constructor is invoked.

KeyWrapper

public KeyWrapper(SecretKey wrapKey)

This constructor sets the wrap key directly, rather than generating it from a password and salt as KeyWrapper(String, String) does. The wrap key must be an WRAP_KEY_ALGORITHM key. Both Keys.newSecretKey() and Keys.generateSecretKey(String, String) can be used to generate the right type of key.

Parameters:

wrapKey - The key which will be used for wrapping other keys.

Method Detail

wrapSecretKey

public String wrapSecretKey(SecretKey key)

Wraps the given SecretKey using .

Parameters:

key - The SecretKey to be wrapped. This method internally just calls wrap(Key, String), but this provides a clear naming match with unwrapSecretKey(String).

Returns:

A String representation (base64-encoded) of the wrapped SecretKey, for ease of storage.

wrapPrivateKey

public String wrapPrivateKey(PrivateKey key)

Wraps the given SecretKey using .

Parameters:

key - The PrivateKey to be wrapped. This method internally just calls wrap(Key, String), but this provides a clear naming match with unwrapPrivateKey(String).

Returns:

A String representation (base64-encoded) of the wrapped PrivateKey, for ease of storage.

encodePublicKey

public static String encodePublicKey(PublicKey key)

Encodes the given PublicKey without wrapping. Since a public key is public, this is a convenience method provided to convert it to a String for unprotected storage. This method internally calls ByteArray.toBase64String(byte[]), passing the value of Key.getEncoded().

Parameters:

key - The PublicKey to be encoded.

Returns:

A String representation (base64-encoded) of the raw PublicKey, for ease of storage.

unwrapSecretKey

public SecretKey unwrapSecretKey(String wrappedKey)

Unwraps the given encoded SecretKey, using WRAP_ALGORITHM_SYMMETRIC.

Parameters:

wrappedKey - The wrapped key, base-64 encoded, as returned by wrapSecretKey(SecretKey) .

Returns:

The unwrapped SecretKey.

unwrapPrivateKey

public PrivateKey unwrapPrivateKey(String wrappedKey)

Unwraps the given encoded PrivateKey, using WRAP_ALGORITHM_ASYMMETRIC.

Parameters:

wrappedKey - The wrapped key, base-64 encoded, as returned by wrapPrivateKey(PrivateKey) .

Returns:

The unwrapped PrivateKey.

decodePublicKey

public static PublicKey decodePublicKey(String encodedKey)

Decodes the given encoded PublicKey. See: http://stackoverflow.com/questions/2411096/how-to-recover-a-rsa-public -key-from-a-byte- array

Parameters:

encodedKey - The public key, base-64 encoded, as returned by encodePublicKey(PublicKey) .

Returns:

The unwrapped PublicKey.