|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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(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 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. |
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. |
String |
seal(String data,
long timestamp)
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. |
Method Detail |
---|
String hash(String plaintext, String salt) throws EncryptionException
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'String hash(String plaintext, String salt, int iterations) throws EncryptionException
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'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.
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.encrypt(SecretKey, PlainText)
CipherText encrypt(SecretKey key, PlainText plaintext) throws EncryptionException
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.
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")
.
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.encrypt(PlainText)
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.
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.decrypt(SecretKey, CipherText)
PlainText decrypt(SecretKey key, CipherText ciphertext) throws EncryptionException
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.
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.decrypt(CipherText)
String sign(String data) throws EncryptionException
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.
data
- the data to sign
EncryptionException
- if the specified signature algorithm cannot be foundboolean verifySignature(String signature, String data)
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.
signature
- the signature to verify against 'data'data
- the data to verify against 'signature'
String seal(String data, long timestamp) throws IntegrityException
data
- the data to sealtimestamp
- the absolute expiration date of the data, expressed as seconds since the epoch
IntegrityException
String unseal(String seal) throws EncryptionException
seal
- the sealed data
EncryptionException
- if the unsealed data cannot be retrieved for any reasonboolean verifySeal(String seal)
seal
- the seal to verify
long getRelativeTimeStamp(long offset)
offset
- the offset to add to the current time
long getTimeStamp()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |