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 theEncryptor
interface. This implementation layers on the JCE provided cryptographic package. Algorithms used are configurable in theESAPI.properties
file. The main property controlling the selection of this class isESAPI.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
- Author:
- Jeff Williams (jeff.williams .at. aspectsecurity.com) Aspect Security, kevin.w.wall@gmail.com, Chris Schmidt (chrisisbeef .at. gmail.com)
- See Also:
Encryptor
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description PlainText
decrypt(javax.crypto.SecretKey key, CipherText ciphertext)
Decrypts the providedCipherText
using the information from it and the specified secret key.PlainText
decrypt(CipherText ciphertext)
Decrypts the providedCipherText
using the information from it and the master encryption key as specified by the propertyEncryptor.MasterKey
as defined in theESAPI.properties
file.CipherText
encrypt(javax.crypto.SecretKey key, PlainText plain)
Encrypts the provided plaintext bytes using the cipher transformation specified by the propertyEncryptor.CipherTransformation
as defined in theESAPI.properties
file and the specified secret key.CipherText
encrypt(PlainText plaintext)
Encrypts the provided plaintext bytes using the cipher transformation specified by the propertyEncryptor.CipherTransformation
and the master encryption key as specified by the propertyEncryptor.MasterKey
as defined in theESAPI.properties
file.static Encryptor
getInstance()
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.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.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
-
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 interfaceEncryptor
- Parameters:
plaintext
- the plaintext String to encryptsalt
- 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 interfaceEncryptor
- Parameters:
plaintext
- the plaintext String to encryptsalt
- the salt to add to the plaintext String before hashingiterations
- 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 propertyEncryptor.CipherTransformation
and the master encryption key as specified by the propertyEncryptor.MasterKey
as defined in theESAPI.properties
file.- Specified by:
encrypt
in interfaceEncryptor
- Parameters:
plaintext
- ThePlainText
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 propertyEncryptor.CipherTransformation
as defined in theESAPI.properties
file and the specified secret key.This method is similar to
Encryptor.encrypt(PlainText)
except that it permits a specificSecretKey
to be used for encryption.- Specified by:
encrypt
in interfaceEncryptor
- Parameters:
key
- TheSecretKey
to use for encrypting the plaintext.plain
- The byte stream to be encrypted. Note if a JavaString
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 providedCipherText
using the information from it and the master encryption key as specified by the propertyEncryptor.MasterKey
as defined in theESAPI.properties
file.- Specified by:
decrypt
in interfaceEncryptor
- Parameters:
ciphertext
- TheCipherText
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 usingnew String(byte[], "UTF-8");
rather than simply usingnew 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 aPaddingException
occurs.- See Also:
Encryptor.decrypt(SecretKey, CipherText)
-
decrypt
public PlainText decrypt(javax.crypto.SecretKey key, CipherText ciphertext) throws EncryptionException, java.lang.IllegalArgumentException
Decrypts the providedCipherText
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 interfaceEncryptor
- Parameters:
key
- TheSecretKey
to use for encrypting the plaintext.ciphertext
- TheCipherText
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 usingnew String(byte[], "UTF-8");
rather than simply usingnew 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 aPaddingException
occurs.java.lang.IllegalArgumentException
- See Also:
Encryptor.decrypt(CipherText)
-
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 correspondingEncryptor.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 interfaceEncryptor
- 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 correspondingEncryptor.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 interfaceEncryptor
- 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 interfaceEncryptor
- 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 interfaceEncryptor
- 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 interfaceEncryptor
- 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 interfaceEncryptor
- 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 interfaceEncryptor
- Parameters:
offset
- the offset to add to the current time- Returns:
- the absolute timestamp
-
-