net.sourceforge.stripes.util
Class CryptoUtil

java.lang.Object
  extended by net.sourceforge.stripes.util.CryptoUtil

public class CryptoUtil
extends Object

Cryptographic utility that can encrypt and decrypt Strings using a key stored in HttpSession. Strings are encrypted by default using a 168bit DEDede (triple DES) key and then Base 64 encoded in a way that is compatible with being inserte into web pages.

A single encryption key is used to encrypt values for all sessions in the web application. The key can come from multiple sources. Without any configuration the key will be generated using a SecureRandom the first time it is needed. Note: this will result in encrypted values that are not decryptable across application restarts or across nodes in a cluster. Alternatively specific key material can be specified using the configuration parameter Stripes.EncryptionKey in web.xml. This key is text that is used to generate a secret key, and ideally should be quite long (at least 20 characters). If a key is configured this way the same key will be used across all nodes in a cluster and across restarts.

Finally a key can be specified by calling setSecretKey(javax.crypto.SecretKey) and providing your own SecretKey instance. This method allows the specification of any key from any source. In addition the provided key can be for any algorithm supported by the JVM in which it is constructed. CryptoUtil will then use the algorithm returned by Key.getAlgorithm(). If using this method, the key should be set before any requests are made, e.g. in a ServletContextListener.

Two additional measures are taken to improve security. Firstly a nonce value is prepended to the input during encryption. This is a value generated each time using a SecureRandom. Doing this ensures that the same value is not encrypted the same way each time and leads to increased unpredictability of the encrypted values. Secondly a "magic number" is also prepended to the input (after the nonce). The magic number is verified at decryption time to ensure that the value passed in was encrypted using the same key as was used for decryption.

Since:
Stripes 1.2
Author:
Tim Fennell

Field Summary
static String ALGORITHM
          The algorithm that is used to encrypt values.
static String CONFIG_ENCRYPTION_KEY
          Key used to look up the location of a secret key.
 
Constructor Summary
CryptoUtil()
           
 
Method Summary
protected static boolean checkHashCode(byte[] value)
          Checks the hash code in the first bytes of the value to make sure it is correct.
static String decrypt(String input)
          Takes in a base64 encoded and encrypted String that was generated by a call to encrypt(String) and decrypts it.
static String decrypt(String input, HttpServletRequest request)
          Deprecated. use decrypt(String) instead
static String encrypt(String input)
          Takes in a String, encrypts it and then base64 encodes the resulting byte[] so that it can be transmitted and stored as a String.
static String encrypt(String input, HttpServletRequest request)
          Deprecated. use encrypt(String) instead
protected static byte[] generateHashCode(byte[]... byteses)
          Generates and returns a hash code from the given byte arrays
protected static Cipher getCipher(int mode)
          Gets the secret key that should be used to encrypt and decrypt values for the current request.
protected static byte[] getKeyMaterialFromConfig()
          Attempts to load material from which to manufacture a secret key from the Stripes Configuration.
protected static SecretKey getSecretKey()
          Returns the secret key to be used to encrypt and decrypt values.
protected static byte[] nextNonce()
          Generates a nonce value using a secure random.
static void setSecretKey(SecretKey key)
          Sets the secret key that will be used by the CryptoUtil to perform encryption and decryption.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ALGORITHM

public static final String ALGORITHM
The algorithm that is used to encrypt values.

See Also:
Constant Field Values

CONFIG_ENCRYPTION_KEY

public static final String CONFIG_ENCRYPTION_KEY
Key used to look up the location of a secret key.

See Also:
Constant Field Values
Constructor Detail

CryptoUtil

public CryptoUtil()
Method Detail

encrypt

@Deprecated
public static String encrypt(String input,
                                        HttpServletRequest request)
Deprecated. use encrypt(String) instead

Takes in a String, encrypts it and then base64 encodes the resulting byte[] so that it can be transmitted and stored as a String. Can be decrypted by a subsequent call to decrypt(String, HttpServletRequest) in the same session.

Parameters:
input - the String to encrypt and encode
request - NO LONGER USED
Returns:
the encrypted, base64 encoded String

encrypt

public static String encrypt(String input)
Takes in a String, encrypts it and then base64 encodes the resulting byte[] so that it can be transmitted and stored as a String. Can be decrypted by a subsequent call to decrypt(String). Because, null and "" are equivalent to the Stripes binding engine, if input is null, then it will be encrypted as if it were "".

Parameters:
input - the String to encrypt and encode
Returns:
the encrypted, base64 encoded String

decrypt

@Deprecated
public static String decrypt(String input,
                                        HttpServletRequest request)
Deprecated. use decrypt(String) instead

Takes in a base64 encoded and encrypted String that was generated by a call to encrypt(String, HttpServletRequest) and decrypts it.

Parameters:
input - the base64 String to decode and decrypt
request - NO LONGER USED
Returns:
the decrypted String

decrypt

public static String decrypt(String input)
Takes in a base64 encoded and encrypted String that was generated by a call to encrypt(String) and decrypts it. If input is null, then null will be returned.

Parameters:
input - the base64 String to decode and decrypt
Returns:
the decrypted String

getCipher

protected static Cipher getCipher(int mode)
Gets the secret key that should be used to encrypt and decrypt values for the current request. If a key does not already exist in Session, one is created and then deposited there for use later.

Returns:
a SecretKey that can be used to manufacture Ciphers

getSecretKey

protected static SecretKey getSecretKey()
Returns the secret key to be used to encrypt and decrypt values. The key will be generated the first time it is requested. Will look for source material for the key in config and use that if found. Otherwise will generate key material using a SecureRandom and then manufacture the key. Once the key is created it is cached locally and the same key instance will be returned until the application is shutdown or restarted.

Returns:
SecretKey the secret key used to encrypt and decrypt values

getKeyMaterialFromConfig

protected static byte[] getKeyMaterialFromConfig()
Attempts to load material from which to manufacture a secret key from the Stripes Configuration. If config is unavailable or there is no material configured null will be returned.

Returns:
a byte[] of key material, or null

setSecretKey

public static void setSecretKey(SecretKey key)
Sets the secret key that will be used by the CryptoUtil to perform encryption and decryption. In general the use of the config property (Stripes.EncryptionKey) should be preferred, but if specific encryption methods are required, this method allows the caller to set a SecretKey suitable to any symmetric encryption algorithm available in the JVM.

Parameters:
key - the secret key to be used to encrypt and decrypt values going forward

nextNonce

protected static byte[] nextNonce()
Generates a nonce value using a secure random.


generateHashCode

protected static byte[] generateHashCode(byte[]... byteses)
Generates and returns a hash code from the given byte arrays


checkHashCode

protected static boolean checkHashCode(byte[] value)
Checks the hash code in the first bytes of the value to make sure it is correct.

Parameters:
value - byte array that contains the hash code and the bytes from which the hash code was generated
Returns:
true if the hash code is valid; otherwise, false


? Copyright 2005-2006, Stripes Development Team.