public final class JavaEncryptor extends Object implements Encryptor
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.".Encryptor
Modifier and Type | Method and Description |
---|---|
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(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(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. |
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.
|
String |
hash(String plaintext,
String salt)
Returns a string representation of the hash of the provided plaintext and
salt.
|
String |
hash(String plaintext,
String salt,
int iterations)
Returns a string representation of the hash of the provided plaintext and
salt.
|
static void |
main(String[] args)
Generates a new strongly random secret key and salt that can be
copy and pasted in the ESAPI.properties file.
|
String |
seal(String data,
long expiration)
Creates a seal that binds a set of data and includes an expiration timestamp.
|
String |
sign(String data)
Create a digital signature for the provided data and return it in a
string.
|
String |
unseal(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(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(String signature,
String data)
Verifies a digital signature (created with the sign method) and returns
the boolean result.
|
public static Encryptor getInstance() throws EncryptionException
EncryptionException
public static void main(String[] args) throws Exception
args
- Set first argument to "-print" to display available algorithms on standard output.Exception
- To cover a multitude of sins, mostly in configuring ESAPI.properties.public String hash(String plaintext, String salt) throws EncryptionException
hash
in interface Encryptor
plaintext
- the plaintext String to encryptsalt
- the salt to add to the plaintext String before hashingEncryptionException
- if the specified hash algorithm could not be found or another problem exists with
the hashing of 'plaintext'public String hash(String plaintext, String salt, int iterations) throws EncryptionException
hash
in interface Encryptor
plaintext
- the plaintext String to encryptsalt
- the salt to add to the plaintext String before hashingiterations
- the number of times to iterate the hashEncryptionException
- if the specified hash algorithm could not be found or another problem exists with
the hashing of 'plaintext'public CipherText encrypt(PlainText plaintext) throws EncryptionException
Encryptor.CipherTransformation
and the master encryption key as specified by the property
Encryptor.MasterKey
as defined in the ESAPI.properties
file.
encrypt
in interface Encryptor
plaintext
- The PlainText
to be encrypted.CipherText
object from which the raw ciphertext, the
IV, the cipher transformation, and many other aspects about
the encryption detail may be extracted.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.Encryptor.encrypt(SecretKey, PlainText)
public CipherText encrypt(SecretKey key, PlainText plain) throws EncryptionException
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.
encrypt
in interface Encryptor
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")
.CipherText
object from which the raw ciphertext, the
IV, the cipher transformation, and many other aspects about
the encryption detail may be extracted.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.Encryptor.encrypt(PlainText)
public PlainText decrypt(CipherText ciphertext) throws EncryptionException
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.
decrypt
in interface Encryptor
ciphertext
- The CipherText
object to be decrypted.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.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.Encryptor.decrypt(SecretKey, CipherText)
public PlainText decrypt(SecretKey key, CipherText ciphertext) throws EncryptionException, IllegalArgumentException
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.
decrypt
in interface Encryptor
key
- The SecretKey
to use for encrypting the plaintext.ciphertext
- The CipherText
object to be decrypted.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.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.IllegalArgumentException
Encryptor.decrypt(CipherText)
public String sign(String data) throws EncryptionException
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.
sign
in interface Encryptor
data
- the data to signEncryptionException
- if the specified signature algorithm cannot be foundpublic boolean verifySignature(String signature, String data)
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.
verifySignature
in interface Encryptor
signature
- the signature to verify against 'data'data
- the data to verify against 'signature'public String seal(String data, long expiration) throws IntegrityException
seal
in interface Encryptor
expiration
- data
- the data to sealIntegrityException
public String unseal(String seal) throws EncryptionException
unseal
in interface Encryptor
seal
- the sealed dataEncryptionException
- if the unsealed data cannot be retrieved for any reasonpublic boolean verifySeal(String seal)
verifySeal
in interface Encryptor
seal
- the seal to verifypublic long getTimeStamp()
getTimeStamp
in interface Encryptor
public long getRelativeTimeStamp(long offset)
getRelativeTimeStamp
in interface Encryptor
offset
- the offset to add to the current timeCopyright © 2023 The Open Web Application Security Project (OWASP). All rights reserved.