public final class JavaEncryptor extends java.lang.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 | Field and Description |
|---|---|
private static int |
decryptCounter |
private static java.lang.String |
DECRYPTION_FAILED |
private static java.lang.String |
encoding |
private static java.lang.String |
encryptAlgorithm |
private static int |
encryptCounter |
private static int |
encryptionKeyLength |
private static java.lang.String |
hashAlgorithm |
private static int |
hashIterations |
private static boolean |
initialized |
private static int |
logEveryNthUse |
private static Logger |
logger |
private static int |
N_SECS |
private static java.security.PrivateKey |
privateKey |
private static java.security.PublicKey |
publicKey |
private static java.lang.String |
randomAlgorithm |
private static javax.crypto.spec.SecretKeySpec |
secretKeySpec |
private static java.lang.String |
signatureAlgorithm |
private static int |
signatureKeyLength |
private static Encryptor |
singletonInstance |
| Modifier | Constructor and Description |
|---|---|
private |
JavaEncryptor()
Private CTOR for
JavaEncryptor, called by getInstance(). |
| Modifier and Type | Method and Description |
|---|---|
private javax.crypto.SecretKey |
computeDerivedKey(int kdfVersion,
KeyDerivationFunction.PRF_ALGORITHMS prf,
javax.crypto.SecretKey kdk,
int keySize,
java.lang.String purpose) |
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. |
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. |
private KeyDerivationFunction.PRF_ALGORITHMS |
getDefaultPRF() |
static Encryptor |
getInstance() |
private KeyDerivationFunction.PRF_ALGORITHMS |
getPRF(java.lang.String name) |
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.
|
private PlainText |
handleDecryption(javax.crypto.SecretKey key,
CipherText ciphertext) |
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.
|
private static void |
initKeyPair(java.security.SecureRandom prng) |
private void |
logWarning(java.lang.String where,
java.lang.String msg)
Log a security warning every Nth time one of the deprecated encrypt or
decrypt methods are called.
|
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.
|
private static void |
setupAlgorithms() |
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.
|
private static volatile Encryptor singletonInstance
private static boolean initialized
private static javax.crypto.spec.SecretKeySpec secretKeySpec
private static java.lang.String encryptAlgorithm
private static java.lang.String encoding
private static int encryptionKeyLength
private static java.security.PrivateKey privateKey
private static java.security.PublicKey publicKey
private static java.lang.String signatureAlgorithm
private static java.lang.String randomAlgorithm
private static int signatureKeyLength
private static java.lang.String hashAlgorithm
private static int hashIterations
private static Logger logger
private static int encryptCounter
private static int decryptCounter
private static final int logEveryNthUse
private static final java.lang.String DECRYPTION_FAILED
private static int N_SECS
private JavaEncryptor()
throws EncryptionException
JavaEncryptor, called by getInstance().EncryptionException - if can't construct this object for some reason.
Original exception will be attached as the 'cause'.public static Encryptor getInstance() throws EncryptionException
EncryptionExceptionpublic 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 Encryptorplaintext - 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 java.lang.String hash(java.lang.String plaintext,
java.lang.String salt,
int iterations)
throws EncryptionException
hash in interface Encryptorplaintext - 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 Encryptorplaintext - 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 Encryptorkey - 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 Encryptorciphertext - 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 Encryptorkey - 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.IllegalArgumentExceptionEncryptor.decrypt(CipherText)private PlainText handleDecryption(javax.crypto.SecretKey key, CipherText ciphertext) throws EncryptionException
EncryptionExceptionpublic 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 Encryptordata - the data to signEncryptionException - 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 Encryptorsignature - 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 Encryptorexpiration - data - the data to sealIntegrityExceptionpublic java.lang.String unseal(java.lang.String seal)
throws EncryptionException
unseal in interface Encryptorseal - the sealed dataEncryptionException - if the unsealed data cannot be retrieved for any reasonpublic boolean verifySeal(java.lang.String seal)
verifySeal in interface Encryptorseal - the seal to verifypublic long getTimeStamp()
getTimeStamp in interface Encryptorpublic long getRelativeTimeStamp(long offset)
getRelativeTimeStamp in interface Encryptoroffset - the offset to add to the current timeprivate void logWarning(java.lang.String where,
java.lang.String msg)
ESAPI.Encryptor.warnEveryNthUse.) In other words, we nag
them until the give in and change it. ;-)where - The string "encrypt" or "decrypt", corresponding to the
method that is being logged.msg - The message to log.private KeyDerivationFunction.PRF_ALGORITHMS getPRF(java.lang.String name)
private KeyDerivationFunction.PRF_ALGORITHMS getDefaultPRF()
private javax.crypto.SecretKey computeDerivedKey(int kdfVersion,
KeyDerivationFunction.PRF_ALGORITHMS prf,
javax.crypto.SecretKey kdk,
int keySize,
java.lang.String purpose)
throws java.security.NoSuchAlgorithmException,
java.security.InvalidKeyException,
EncryptionException
java.security.NoSuchAlgorithmExceptionjava.security.InvalidKeyExceptionEncryptionExceptionprivate static void setupAlgorithms()
private static void initKeyPair(java.security.SecureRandom prng)
throws java.security.NoSuchAlgorithmException
java.security.NoSuchAlgorithmException