org.owasp.esapi
Interface Encryptor

All Known Implementing Classes:

JavaEncryptor

public interface Encryptor

The Encryptor interface provides a set of methods for performing common encryption, random number, and hashing operations. Implementations should rely on a strong cryptographic implementation, such as JCE or BouncyCastle. Implementors should take care to ensure that they initialize their implementation with a strong "master key", and that they protect this secret as much as possible.

The main property controlling the selection of the implementation class is the property ESAPI.Encryptor in ESAPI.properties. Most of the the other encryption related properties have property names that start with the string "Encryptor.". These properties all you to do things such as select the encryption algorithms, the preferred JCE provider, etc.

In addition, there are two important properties (initially delivered as unset from the ESAPI download) named Encryptor.MasterKey and Encryptor.MasterSalt that must be set before using ESAPI encryption. There is a bash(1) shell script provided with the standard ESAPI distribution called 'setMasterKey.sh' that will assist you in setting these two properties. The script is in 'src/examples/scripts/setMasterKey.sh'.

Possible future enhancements (depending on feedback) are discussed in section 4 of Design Goals in OWASP ESAPI Cryptography.

Since:

June 1, 2007

Author:

Jeff Williams (jeff.williams .at. aspectsecurity.com) Aspect Security

See Also:

User Guide for Symmetric Encryption in ESAPI 2.0

Method Summary

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.
java.lang.String	decrypt(java.lang.String ciphertext) Deprecated. As of 1.4.2; use decrypt(CipherText) instead, which also ensures message authenticity. This method will be completely removed as of the next major release or point release (3.0 or 2.1, whichever comes first) as per OWASP deprecation policy.
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 plaintext) 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.
java.lang.String	encrypt(java.lang.String plaintext) Deprecated. As of 1.4.2; use encrypt(PlainText) instead, which also ensures message authenticity. This method will be completely removed as of the next major release or point release (3.0 or 2.1, whichever comes first) as per OWASP deprecation policy.
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.
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.
java.lang.String	seal(java.lang.String data, long timestamp) Creates a seal that binds a set of data and includes an expiration timestamp.
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.

Method Detail

hash

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.

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

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.

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

@Deprecated
java.lang.String encrypt(java.lang.String plaintext)
                         throws EncryptionException

Deprecated. As of 1.4.2; use encrypt(PlainText) instead, which also ensures message authenticity. This method will be completely removed as of the next major release or point release (3.0 or 2.1, whichever comes first) as per OWASP deprecation policy.

Encrypts the provided plaintext and returns a ciphertext string using the master secret key and default cipher transformation.

Compatibility with earlier ESAPI versions: The symmetric encryption in ESAPI 2.0 and later is not compatible with the encryption in ESAPI 1.4 or earlier. Not only are the interfaces slightly different, but they format of the serialized encrypted data is incompatible. Therefore, if you have encrypted data with ESAPI 1.4 or earlier, you must first encrypt it and then re-encrypt it with ESAPI 2.0. Backward compatibility with ESAPI 1.4 was proposed to both the ESAPI Developers and ESAPI Users mailing lists and voted down. More details are available in the ESAPI document Why Is OWASP Changing ESAPI Encryption?

Why this method is deprecated: Most cryptographers strongly suggest that if you are creating crypto functionality for general-purpose use, at a minimum you should ensure that it provides authenticity, integrity, and confidentiality. This method only provides confidentiality, but not authenticity or integrity. Therefore, you are encouraged to use one of the other encryption methods referenced below. Because this method provides neither authenticity nor integrity, it may be removed in some future ESAPI Java release. Note: there are some cases where authenticity / integrity are not that important. For instance, consider a case where the encrypted data is never out of your application's control. For example, if you receive data that your application is encrypting itself and then storing the encrypted data in its own database for later use (and no other applications can query or update that column of the database), providing confidentiality alone might be sufficient. However, if there are cases where your application will be sending or receiving already encrypted data over an insecure, unauthenticated channel, in such cases authenticity and integrity of the encrypted data likely is important and this method should be avoided in favor of one of the other two.

Parameters:

plaintext - the plaintext String to encrypt. Note that if you are encrypting general bytes, you should encypt that byte array to a String using "UTF-8" encoding.

Returns:

the encrypted, base64-encoded String representation of 'plaintext' plus the random IV used.

Throws:

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

See Also:

encrypt(PlainText), encrypt(SecretKey, PlainText)

encrypt

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.

This method is preferred over encrypt(String) because it also allows encrypting of general byte streams rather than simply strings and also because it returns a CipherText object and thus supports cipher modes that require an Initialization Vector (IV), such as Cipher Block Chaining (CBC).

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.

Since:

2.0

See Also:

encrypt(SecretKey, PlainText)

encrypt

CipherText encrypt(javax.crypto.SecretKey key,
                   PlainText plaintext)
                   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 encrypt(PlainText) except that it permits a specific SecretKey to be used for encryption.

Parameters:

key - The SecretKey to use for encrypting the plaintext.

plaintext - 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.

Since:

2.0

See Also:

encrypt(PlainText)

decrypt

@Deprecated
java.lang.String decrypt(java.lang.String ciphertext)
                         throws EncryptionException

Deprecated. As of 1.4.2; use decrypt(CipherText) instead, which also ensures message authenticity. This method will be completely removed as of the next major release or point release (3.0 or 2.1, whichever comes first) as per OWASP deprecation policy.

Decrypts the provided ciphertext and returns a plaintext string using the master secret key and default cipher transformation.

Compatibility with earlier ESAPI versions: The symmetric encryption in ESAPI 2.0 and later is not compatible with the encryption in ESAPI 1.4 or earlier. Not only are the interfaces slightly different, but they format of the serialized encrypted data is incompatible. Therefore, if you have encrypted data with ESAPI 1.4 or earlier, you must first encrypt it and then re-encrypt it with ESAPI 2.0. Backward compatibility with ESAPI 1.4 was proposed to both the ESAPI Developers and ESAPI Users mailing lists and voted down. More details are available in the ESAPI document Why Is OWASP Changing ESAPI Encryption?

Why this method is deprecated: Most cryptographers strongly suggest that if you are creating crypto functionality for general-purpose use, at a minimum you should ensure that it provides authenticity, integrity, and confidentiality. This method only provides confidentiality, but not authenticity or integrity. Therefore, you are encouraged to use one of the other encryption methods referenced below. Because this method provides neither authenticity nor integrity, it may be removed in some future ESAPI Java release. Note: there are some cases where authenticity / integrity are not that important. For instance, consider a case where the encrypted data is never out of your application's control. For example, if you receive data that your application is encrypting itself and then storing the encrypted data in its own database for later use (and no other applications can query or update that column of the database), providing confidentiality alone might be sufficient. However, if there are cases where your application will be sending or receiving already encrypted data over an insecure, unauthenticated channel, in such cases authenticity and integrity of the encrypted data likely is important and this method should be avoided in favor of one of the other two.

Parameters:

ciphertext - the ciphertext (the encrypted plaintext) that resulted from encrypting using the method encrypt(String).

Returns:

the decrypted ciphertext (i.e., the corresponding plaintext).

Throws:

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

decrypt

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.

This decrypt method is to be preferred over the deprecated decrypt(String) method because this method can handle plaintext bytes that were encrypted with cipher modes requiring IVs, such as CBC.

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:

decrypt(SecretKey, CipherText)

decrypt

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

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

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

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.

See Also:

decrypt(CipherText)

sign

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 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 verifySignature(String, String) can not be used with expected results across JVM instances. This limitation will be addressed in ESAPI 2.1.

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

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 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 sign(String) can not be used with expected results across JVM instances. This limitation will be addressed in ESAPI 2.1.

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

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

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

Parameters:

data - the data to seal

timestamp - the absolute expiration date of the data, expressed as seconds since the epoch

Returns:

the seal

Throws:

IntegrityException

unseal

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.

Parameters:

seal - the sealed data

Returns:

the original (unsealed) data

Throws:

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

verifySeal

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.

Parameters:

seal - the seal to verify

Returns:

true, if the seal is valid. False otherwise

getRelativeTimeStamp

long getRelativeTimeStamp(long offset)

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

Parameters:

offset - the offset to add to the current time

Returns:

the absolute timestamp

getTimeStamp

long getTimeStamp()

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

Returns:

a timestamp representing the current time