|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.owasp.esapi.reference.crypto.JavaEncryptor
public final class JavaEncryptor
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.".
Encryptor
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 b64IVCiphertext)
Deprecated. |
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. |
java.lang.String |
encrypt(java.lang.String plaintext)
Deprecated. |
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. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
---|
public static Encryptor getInstance() throws EncryptionException
EncryptionException
public static void main(java.lang.String[] args) throws java.lang.Exception
args
- Set first argument to "-print" to display available algorithms on standard output.
java.lang.Exception
- To cover a multitude of sins, mostly in configuring ESAPI.properties.public java.lang.String hash(java.lang.String plaintext, java.lang.String salt) throws EncryptionException
hash
in interface Encryptor
plaintext
- the plaintext String to encryptsalt
- the salt to add to the plaintext String before hashing
EncryptionException
- if the specified hash algorithm could not be found or another problem exists with
the hashing of 'plaintext'public java.lang.String hash(java.lang.String plaintext, java.lang.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 hash
EncryptionException
- if the specified hash algorithm could not be found or another problem exists with
the hashing of 'plaintext'@Deprecated public java.lang.String encrypt(java.lang.String plaintext) throws EncryptionException
Encryptor.MasterKey
property
in ESAPI.properties
.
encrypt
in interface Encryptor
plaintext
- A String to be encrypted
EncryptionException
- Thrown when something goes wrong with the
encryption.Encryptor.encrypt(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.
This method is preferred over Encryptor.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).
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(javax.crypto.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)
@Deprecated public java.lang.String decrypt(java.lang.String b64IVCiphertext) throws EncryptionException
Encryptor.MasterKey
property
in ESAPI.properties
.
decrypt
in interface Encryptor
b64IVCiphertext
- A base64-encoded representation of the
IV + raw ciphertext string to be decrypted with
the default master key.
EncryptionException
- When something fails with the decryption.Encryptor.decrypt(CipherText)
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.
This decrypt method is to be preferred over the deprecated
Encryptor.decrypt(String)
method because this method can handle plaintext
bytes that were encrypted with cipher modes requiring IVs, such as CBC.
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(javax.crypto.SecretKey key, CipherText ciphertext) throws EncryptionException, java.lang.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.
java.lang.IllegalArgumentException
Encryptor.decrypt(CipherText)
public java.lang.String sign(java.lang.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 sign
EncryptionException
- if the specified signature algorithm cannot be foundpublic boolean verifySignature(java.lang.String signature, java.lang.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 java.lang.String seal(java.lang.String data, long expiration) throws IntegrityException
seal
in interface Encryptor
expiration
- data
- the data to seal
IntegrityException
public java.lang.String unseal(java.lang.String seal) throws EncryptionException
unseal
in interface Encryptor
seal
- the sealed data
EncryptionException
- if the unsealed data cannot be retrieved for any reasonpublic boolean verifySeal(java.lang.String seal)
verifySeal
in interface Encryptor
seal
- the seal to verify
public long getTimeStamp()
getTimeStamp
in interface Encryptor
public long getRelativeTimeStamp(long offset)
getRelativeTimeStamp
in interface Encryptor
offset
- the offset to add to the current time
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |