org.owasp.esapi.reference.crypto

Class JavaEncryptor

java.lang.Object

org.owasp.esapi.reference.crypto.JavaEncryptor

All Implemented Interfaces:

Encryptor

public final class JavaEncryptor
extends java.lang.Object
implements Encryptor

Reference implementation of the Encryptor interface. This implementation layers on the JCE provided cryptographic package. Algorithms used are configurable in the ESAPI.properties file. The main property controlling the selection of this class is ESAPI.Encryptor. Most of the other encryption related properties have property names that start with the string "Encryptor.".

Since:

June 1, 2007; some methods since ESAPI Java 2.0

See Also:

Encryptor

Field Summary

Fields

Modifier and Type	Field and Description
private static int	decryptCounter
private static java.lang.String	DECRYPTION_FAILED
private static java.lang.String	encoding
private static java.lang.String	encryptAlgorithm
private static int	encryptCounter
private static int	encryptionKeyLength
private static java.lang.String	hashAlgorithm
private static int	hashIterations
private static boolean	initialized
private static int	logEveryNthUse
private static Logger	logger
private static int	N_SECS
private static java.security.PrivateKey	privateKey
private static java.security.PublicKey	publicKey
private static java.lang.String	randomAlgorithm
private static javax.crypto.spec.SecretKeySpec	secretKeySpec
private static java.lang.String	signatureAlgorithm
private static int	signatureKeyLength
private static Encryptor	singletonInstance

Constructor Summary

Constructors

Modifier	Constructor and Description
private	JavaEncryptor() Private CTOR for JavaEncryptor, called by getInstance().

Method Summary

Modifier and Type	Method and Description
private javax.crypto.SecretKey	computeDerivedKey(int kdfVersion, KeyDerivationFunction.PRF_ALGORITHMS prf, javax.crypto.SecretKey kdk, int keySize, java.lang.String purpose)
PlainText	decrypt(CipherText ciphertext) Decrypts the provided CipherText using the information from it and the master encryption key as specified by the property Encryptor.MasterKey as defined in the ESAPI.properties file.
PlainText	decrypt(javax.crypto.SecretKey key, CipherText ciphertext) Decrypts the provided CipherText using the information from it and the specified secret key.
CipherText	encrypt(PlainText plaintext) Encrypts the provided plaintext bytes using the cipher transformation specified by the property Encryptor.CipherTransformation and the master encryption key as specified by the property Encryptor.MasterKey as defined in the ESAPI.properties file.
CipherText	encrypt(javax.crypto.SecretKey key, PlainText plain) Encrypts the provided plaintext bytes using the cipher transformation specified by the property Encryptor.CipherTransformation as defined in the ESAPI.properties file and the specified secret key.
private KeyDerivationFunction.PRF_ALGORITHMS	getDefaultPRF()
static Encryptor	getInstance()
private KeyDerivationFunction.PRF_ALGORITHMS	getPRF(java.lang.String name)
long	getRelativeTimeStamp(long offset) Gets an absolute timestamp representing an offset from the current time to be used by other functions in the library.
long	getTimeStamp() Gets a timestamp representing the current date and time to be used by other functions in the library.
private PlainText	handleDecryption(javax.crypto.SecretKey key, CipherText ciphertext)
java.lang.String	hash(java.lang.String plaintext, java.lang.String salt) Returns a string representation of the hash of the provided plaintext and salt.
java.lang.String	hash(java.lang.String plaintext, java.lang.String salt, int iterations) Returns a string representation of the hash of the provided plaintext and salt.
private static void	initKeyPair(java.security.SecureRandom prng)
private void	logWarning(java.lang.String where, java.lang.String msg) Log a security warning every Nth time one of the deprecated encrypt or decrypt methods are called.
static void	main(java.lang.String[] args) Generates a new strongly random secret key and salt that can be copy and pasted in the ESAPI.properties file.
java.lang.String	seal(java.lang.String data, long expiration) Creates a seal that binds a set of data and includes an expiration timestamp.
private static void	setupAlgorithms()
java.lang.String	sign(java.lang.String data) Create a digital signature for the provided data and return it in a string.
java.lang.String	unseal(java.lang.String seal) Unseals data (created with the seal method) and throws an exception describing any of the various problems that could exist with a seal, such as an invalid seal format, expired timestamp, or decryption error.
boolean	verifySeal(java.lang.String seal) Verifies a seal (created with the seal method) and throws an exception describing any of the various problems that could exist with a seal, such as an invalid seal format, expired timestamp, or data mismatch.
boolean	verifySignature(java.lang.String signature, java.lang.String data) Verifies a digital signature (created with the sign method) and returns the boolean result.

Methods inherited from class java.lang.Object

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

Field Detail

singletonInstance

private static volatile Encryptor singletonInstance

initialized

private static boolean initialized

secretKeySpec

private static javax.crypto.spec.SecretKeySpec secretKeySpec

encryptAlgorithm

private static java.lang.String encryptAlgorithm

encoding

private static java.lang.String encoding

encryptionKeyLength

private static int encryptionKeyLength

privateKey

private static java.security.PrivateKey privateKey

publicKey

private static java.security.PublicKey publicKey

signatureAlgorithm

private static java.lang.String signatureAlgorithm

randomAlgorithm

private static java.lang.String randomAlgorithm

signatureKeyLength

private static int signatureKeyLength

hashAlgorithm

private static java.lang.String hashAlgorithm

hashIterations

private static int hashIterations

logger

private static Logger logger

encryptCounter

private static int encryptCounter

decryptCounter

private static int decryptCounter

logEveryNthUse

private static final int logEveryNthUse

See Also:

Constant Field Values

DECRYPTION_FAILED

private static final java.lang.String DECRYPTION_FAILED

See Also:

Constant Field Values

N_SECS

private static int N_SECS

Constructor Detail

JavaEncryptor

private JavaEncryptor()
               throws EncryptionException

Private CTOR for JavaEncryptor, called by getInstance().

Throws:

EncryptionException - if can't construct this object for some reason. Original exception will be attached as the 'cause'.

Method Detail

getInstance

public static Encryptor getInstance()
                             throws EncryptionException

Throws:

EncryptionException

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Generates a new strongly random secret key and salt that can be copy and pasted in the ESAPI.properties file.

Parameters:

args - Set first argument to "-print" to display available algorithms on standard output.

Throws:

java.lang.Exception - To cover a multitude of sins, mostly in configuring ESAPI.properties.

hash

public java.lang.String hash(java.lang.String plaintext,
                             java.lang.String salt)
                      throws EncryptionException

Returns a string representation of the hash of the provided plaintext and salt. The salt helps to protect against a rainbow table attack by mixing in some extra data with the plaintext. Some good choices for a salt might be an account name or some other string that is known to the application but not to an attacker. See this article for more information about hashing as it pertains to password schemes. Hashes the data with the supplied salt and the number of iterations specified in the ESAPI SecurityConfiguration.

Specified by:

hash in interface Encryptor

Parameters:

plaintext - the plaintext String to encrypt

salt - the salt to add to the plaintext String before hashing

Returns:

the encrypted hash of 'plaintext' stored as a String

Throws:

EncryptionException - if the specified hash algorithm could not be found or another problem exists with the hashing of 'plaintext'

hash

public java.lang.String hash(java.lang.String plaintext,
                             java.lang.String salt,
                             int iterations)
                      throws EncryptionException

Returns a string representation of the hash of the provided plaintext and salt. The salt helps to protect against a rainbow table attack by mixing in some extra data with the plaintext. Some good choices for a salt might be an account name or some other string that is known to the application but not to an attacker. See this article for more information about hashing as it pertains to password schemes. Hashes the data using the specified algorithm and the Java MessageDigest class. This method first adds the salt, a separator (":"), and the data, and then rehashes the specified number of iterations in order to help strengthen weak passwords.

Specified by:

hash in interface Encryptor

Parameters:

plaintext - the plaintext String to encrypt

salt - the salt to add to the plaintext String before hashing

iterations - the number of times to iterate the hash

Returns:

the encrypted hash of 'plaintext' stored as a String

Throws:

EncryptionException - if the specified hash algorithm could not be found or another problem exists with the hashing of 'plaintext'

encrypt

public CipherText encrypt(PlainText plaintext)
                   throws EncryptionException

Encrypts the provided plaintext bytes using the cipher transformation specified by the property Encryptor.CipherTransformation and the master encryption key as specified by the property Encryptor.MasterKey as defined in the ESAPI.properties file.

Specified by:

encrypt in interface Encryptor

Parameters:

plaintext - The PlainText to be encrypted.

Returns:

the CipherText object from which the raw ciphertext, the IV, the cipher transformation, and many other aspects about the encryption detail may be extracted.

Throws:

EncryptionException - Thrown if something should go wrong such as the JCE provider cannot be found, the cipher algorithm, cipher mode, or padding scheme not being supported, specifying an unsupported key size, specifying an IV of incorrect length, etc.

See Also:

Encryptor.encrypt(SecretKey, PlainText)

encrypt

public CipherText encrypt(javax.crypto.SecretKey key,
                          PlainText plain)
                   throws EncryptionException

Encrypts the provided plaintext bytes using the cipher transformation specified by the property Encryptor.CipherTransformation as defined in the ESAPI.properties file and the specified secret key.

This method is similar to Encryptor.encrypt(PlainText) except that it permits a specific SecretKey to be used for encryption.

Specified by:

encrypt in interface Encryptor

Parameters:

key - The SecretKey to use for encrypting the plaintext.

plain - The byte stream to be encrypted. Note if a Java String is to be encrypted, it should be converted using "some string".getBytes("UTF-8").

Returns:

the CipherText object from which the raw ciphertext, the IV, the cipher transformation, and many other aspects about the encryption detail may be extracted.

Throws:

EncryptionException - Thrown if something should go wrong such as the JCE provider cannot be found, the cipher algorithm, cipher mode, or padding scheme not being supported, specifying an unsupported key size, specifying an IV of incorrect length, etc.

See Also:

Encryptor.encrypt(PlainText)

decrypt

public PlainText decrypt(CipherText ciphertext)
                  throws EncryptionException

Decrypts the provided CipherText using the information from it and the master encryption key as specified by the property Encryptor.MasterKey as defined in the ESAPI.properties file.

Specified by:

decrypt in interface Encryptor

Parameters:

ciphertext - The CipherText object to be decrypted.

Returns:

The PlainText object resulting from decrypting the specified ciphertext. Note that it it is desired to convert the returned plaintext byte array to a Java String is should be done using new String(byte[], "UTF-8"); rather than simply using new String(byte[]); which uses native encoding and may not be portable across hardware and/or OS platforms.

Throws:

EncryptionException - Thrown if something should go wrong such as the JCE provider cannot be found, the cipher algorithm, cipher mode, or padding scheme not being supported, specifying an unsupported key size, or incorrect encryption key was specified or a PaddingException occurs.

See Also:

Encryptor.decrypt(SecretKey, CipherText)

decrypt

public PlainText decrypt(javax.crypto.SecretKey key,
                         CipherText ciphertext)
                  throws EncryptionException,
                         java.lang.IllegalArgumentException

Decrypts the provided CipherText using the information from it and the specified secret key.

This decrypt method is similar to Encryptor.decrypt(CipherText) except that it allows decrypting with a secret key other than the master secret key.

Specified by:

decrypt in interface Encryptor

Parameters:

key - The SecretKey to use for encrypting the plaintext.

ciphertext - The CipherText object to be decrypted.

Returns:

The PlainText object resulting from decrypting the specified ciphertext. Note that it it is desired to convert the returned plaintext byte array to a Java String is should be done using new String(byte[], "UTF-8"); rather than simply using new String(byte[]); which uses native encoding and may not be portable across hardware and/or OS platforms.

Throws:

EncryptionException - Thrown if something should go wrong such as the JCE provider cannot be found, the cipher algorithm, cipher mode, or padding scheme not being supported, specifying an unsupported key size, or incorrect encryption key was specified or a PaddingException occurs.

java.lang.IllegalArgumentException

See Also:

Encryptor.decrypt(CipherText)

handleDecryption

private PlainText handleDecryption(javax.crypto.SecretKey key,
                                   CipherText ciphertext)
                            throws EncryptionException

Throws:

EncryptionException

sign

public java.lang.String sign(java.lang.String data)
                      throws EncryptionException

Create a digital signature for the provided data and return it in a string.

Limitations: A new public/private key pair used for ESAPI 2.0 digital signatures with this method and Encryptor.verifySignature(String, String) are dynamically created when the default reference implementation class, JavaEncryptor is first created. Because this key pair is not persisted nor is the public key shared, this method and the corresponding Encryptor.verifySignature(String, String) can not be used with expected results across JVM instances. This limitation will be addressed in ESAPI 2.1.

Specified by:

sign in interface Encryptor

Parameters:

data - the data to sign

Returns:

the digital signature stored as a String

Throws:

EncryptionException - if the specified signature algorithm cannot be found

verifySignature

public boolean verifySignature(java.lang.String signature,
                               java.lang.String data)

Verifies a digital signature (created with the sign method) and returns the boolean result.

Limitations: A new public/private key pair used for ESAPI 2.0 digital signatures with this method and Encryptor.sign(String) are dynamically created when the default reference implementation class, JavaEncryptor is first created. Because this key pair is not persisted nor is the public key shared, this method and the corresponding Encryptor.sign(String) can not be used with expected results across JVM instances. This limitation will be addressed in ESAPI 2.1.

Specified by:

verifySignature in interface Encryptor

Parameters:

signature - the signature to verify against 'data'

data - the data to verify against 'signature'

Returns:

true, if the signature is verified, false otherwise

seal

public java.lang.String seal(java.lang.String data,
                             long expiration)
                      throws IntegrityException

Creates a seal that binds a set of data and includes an expiration timestamp.

Specified by:

seal in interface Encryptor

Parameters:

expiration -

data - the data to seal

Returns:

the seal

Throws:

IntegrityException

unseal

public java.lang.String unseal(java.lang.String seal)
                        throws EncryptionException

Unseals data (created with the seal method) and throws an exception describing any of the various problems that could exist with a seal, such as an invalid seal format, expired timestamp, or decryption error.

Specified by:

unseal in interface Encryptor

Parameters:

seal - the sealed data

Returns:

the original (unsealed) data

Throws:

EncryptionException - if the unsealed data cannot be retrieved for any reason

verifySeal

public boolean verifySeal(java.lang.String seal)

Verifies a seal (created with the seal method) and throws an exception describing any of the various problems that could exist with a seal, such as an invalid seal format, expired timestamp, or data mismatch.

Specified by:

verifySeal in interface Encryptor

Parameters:

seal - the seal to verify

Returns:

true, if the seal is valid. False otherwise

getTimeStamp

public long getTimeStamp()

Gets a timestamp representing the current date and time to be used by other functions in the library.

Specified by:

getTimeStamp in interface Encryptor

Returns:

a timestamp representing the current time

getRelativeTimeStamp

public long getRelativeTimeStamp(long offset)

Gets an absolute timestamp representing an offset from the current time to be used by other functions in the library.

Specified by:

getRelativeTimeStamp in interface Encryptor

Parameters:

offset - the offset to add to the current time

Returns:

the absolute timestamp

logWarning

private void logWarning(java.lang.String where,
                        java.lang.String msg)

Log a security warning every Nth time one of the deprecated encrypt or decrypt methods are called. ('N' is hard-coded to be 25 by default, but may be changed via the system property ESAPI.Encryptor.warnEveryNthUse.) In other words, we nag them until the give in and change it. ;-)

Parameters:

where - The string "encrypt" or "decrypt", corresponding to the method that is being logged.

msg - The message to log.

getPRF

private KeyDerivationFunction.PRF_ALGORITHMS getPRF(java.lang.String name)

getDefaultPRF

private KeyDerivationFunction.PRF_ALGORITHMS getDefaultPRF()

computeDerivedKey

private javax.crypto.SecretKey computeDerivedKey(int kdfVersion,
                                                 KeyDerivationFunction.PRF_ALGORITHMS prf,
                                                 javax.crypto.SecretKey kdk,
                                                 int keySize,
                                                 java.lang.String purpose)
                                          throws java.security.NoSuchAlgorithmException,
                                                 java.security.InvalidKeyException,
                                                 EncryptionException

Throws:

java.security.NoSuchAlgorithmException

java.security.InvalidKeyException

EncryptionException

setupAlgorithms

private static void setupAlgorithms()

initKeyPair

private static void initKeyPair(java.security.SecureRandom prng)
                         throws java.security.NoSuchAlgorithmException

Throws:

java.security.NoSuchAlgorithmException