|
||||||||||
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.
Possible future enhancements (depending on feedback) might include:
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 |
---|
java.lang.String hash(java.lang.String plaintext, java.lang.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'java.lang.String hash(java.lang.String plaintext, java.lang.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'@Deprecated java.lang.String encrypt(java.lang.String plaintext) throws EncryptionException
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.
Compatibility with earlier ESAPI versions: Unlike ESAPI 1.4 version of this method which used the Electronic Code Book (ECB) cipher mode to encrypt, this method uses the default cipher transformation and IV type (which by default is AES/CBC/PKCS5Padding and a random IV). ECB mode is not secure for general use and usually should be avoided. If you must use ECB mode for backward compatibility, you should do so by specifying
ESAPI.Encryptor=org.owasp.esapi.reference.LegacyJavaEncryptorin your ESAPI.properties file rather than changing the default cipher transformation. That will make this method and the
decrypt(String)
method use ECB mode in a manner that is compatible
with ESAPI 1.4 and earlier but not affect the newer encryption / decryption
methods. However, this should only be used for backward compatibility. You
should use it to decrypt data that was previous encrypted using ESAPI 1.4 or
earlier use a newer method that uses the stronger CBC cipher mode
to re-encrypt it. Once all the previously encrypted data has been re-encrypted
using this legacy class, you should stop using this legacy class and start
using the default reference class, as per:
ESAPI.Encryptor=org.owasp.esapi.reference.LegacyJavaEncryptorin your ESAPI.properties file.
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.
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.
EncryptionException
- if the specified encryption algorithm could not be found or another problem exists with
the encryption of 'plaintext'encrypt(PlainText)
,
encrypt(SecretKey, 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.
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).
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(javax.crypto.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)
@Deprecated java.lang.String decrypt(java.lang.String ciphertext) throws EncryptionException
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.
Compatibility with earlier ESAPI versions: Unlike ESAPI 1.4 version of this method which used the Electronic Code Book (ECB) cipher mode to encrypt, this method uses the default cipher transformation and IV type (which by default is AES/CBC/PKCS5Padding and a random IV). ECB mode is not secure for general use and usually should be avoided. If you must use ECB mode for backward compatibility, you should do so by specifying
ESAPI.Encryptor=org.owasp.esapi.reference.LegacyJavaEncryptorin your ESAPI.properties file rather than changing the default cipher transformation. That will make this method and the
decrypt(String)
method use ECB mode in a manner that is compatible
with ESAPI 1.4 and earlier but not affect the newer encryption / decryption
methods. However, this should only be used for backward compatibility. You
should use it to decrypt data that was previous encrypted using ESAPI 1.4 or
earlier use a newer method that uses the stronger CBC cipher mode
to re-encrypt it. Once all the previously encrypted data has been re-encrypted
using this legacy class, you should stop using this legacy class and start
using the default reference class, as per:
ESAPI.Encryptor=org.owasp.esapi.reference.LegacyJavaEncryptorin your ESAPI.properties file.
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.
ciphertext
- the ciphertext (the encrypted plaintext) that resulted from
encrypting using the method encrypt(String)
.
EncryptionException
- if the specified encryption algorithm could not be found or another problem exists with
the decryption of '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.
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.
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(javax.crypto.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)
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 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(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 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'
java.lang.String seal(java.lang.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
java.lang.String unseal(java.lang.String seal) throws EncryptionException
seal
- the sealed data
EncryptionException
- if the unsealed data cannot be retrieved for any reasonboolean verifySeal(java.lang.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 |