public class CryptoHelper extends Object
All the cryptographic operations use the default cryptographic properties; e.g., default cipher transformation, default key size, default IV type (where applicable), etc.
Modifier and Type | Method and Description |
---|---|
static boolean |
arrayCompare(byte[] b1,
byte[] b2)
Deprecated.
Use java.security.MessageDigest#isEqual(byte[], byte[]) instead.
|
static SecretKey |
computeDerivedKey(SecretKey keyDerivationKey,
int keySize,
String purpose)
Deprecated.
Use same method in
KeyDerivationFunction instead. This method will be removed as of
ESAPI release 2.3 so if you are using this, please CHANGE YOUR CODE. Note that the replacement
is not a static method, so create your own wrapper if you wish, but this will soon disappear. |
static void |
copyByteArray(byte[] src,
byte[] dest)
Same as
copyByteArray(src, dest, src.length) . |
static void |
copyByteArray(byte[] src,
byte[] dest,
int length)
Same as
System.arraycopy(src, 0, dest, 0, length) . |
static SecretKey |
generateSecretKey(String alg,
int keySize)
Generate a random secret key appropriate to the specified cipher algorithm
and key size.
|
static boolean |
isAllowedCipherMode(String cipherMode)
Return true if specified cipher mode is one that may be used for
encryption / decryption operations via
Encryptor . |
static boolean |
isCipherTextMACvalid(SecretKey sk,
CipherText ct)
If a Message Authentication Code (MAC) is required for the specified
CipherText object, then attempt to validate the MAC that
should be embedded within the CipherText object by using a
derived key based on the specified SecretKey . |
static boolean |
isCombinedCipherMode(String cipherMode)
Return true if specified cipher mode is one of those specified in the
ESAPI.properties file that supports both confidentiality
and authenticity (i.e., a "combined cipher mode" as NIST refers
to it). |
static boolean |
isMACRequired(CipherText ct)
Check to see if a Message Authentication Code (MAC) is required
for a given
CipherText object and the current ESAPI.property
settings. |
static boolean |
isValidKDFVersion(int kdfVers,
boolean restrictToCurrent,
boolean throwIfError)
Is this particular KDF version number one that is sane? For that, we
just make sure it is inbounds of the valid range which is:
|
static void |
overwrite(byte[] bytes)
Overwrite a byte array with the byte containing '*'.
|
static void |
overwrite(byte[] bytes,
byte x)
Overwrite a byte array with a specified byte.
|
public static SecretKey generateSecretKey(String alg, int keySize) throws EncryptionException
alg
- The cipher algorithm or cipher transformation. (If the latter is
passed, the cipher algorithm is determined from it.) Cannot be
null or empty.keySize
- The key size, in bits.SecretKey
is returned.EncryptionException
- Thrown if cannot create secret key conforming to
requested algorithm with requested size. Typically this is caused by
specifying an unavailable algorithm or invalid key size.@Deprecated public static SecretKey computeDerivedKey(SecretKey keyDerivationKey, int keySize, String purpose) throws NoSuchAlgorithmException, InvalidKeyException, EncryptionException
KeyDerivationFunction
instead. This method will be removed as of
ESAPI release 2.3 so if you are using this, please CHANGE YOUR CODE. Note that the replacement
is not a static method, so create your own wrapper if you wish, but this will soon disappear.keyDerivationKey
for either
encryption / decryption or for authentication.
CAUTION: If this algorithm for computing derived keys from the key derivation key is ever changed, we risk breaking backward compatibility of being able to decrypt data previously encrypted with earlier / different versions of this method. Therefore, do not change this unless you are 100% certain that what you are doing will NOT change either of the derived keys for ANY "key derivation key" AT ALL!!!
NOTE: This method is generally not intended to be called separately.
It is used by ESAPI's reference crypto implementation class JavaEncryptor
and might be useful for someone implementing their own replacement class, but
generally it is not something that is useful to application client code.
keyDerivationKey
- A key used as an input to a key derivation function
to derive other keys. This is the key that generally
is created using some key generation mechanism such as
generateSecretKey(String, int)
. The
"input" key from which the other keys are derived.
The derived key will have the same algorithm type
as this key.keySize
- The cipher's key size (in bits) for the keyDerivationKey
.
Must have a minimum size of 56 bits and be an integral multiple of 8-bits.
Note: The derived key will have the same size as this.purpose
- The purpose for the derived key. Must be either the
string "encryption" or "authenticity". Use "encryption" for
creating a derived key to use for confidentiality, and "authenticity"
for a derived key to use with a MAC to ensure message authenticity.SecretKey
to be used according
to the specified purpose. Note that this serves the same purpose
as "label" in section 5.1 of NIST SP 800-108.NoSuchAlgorithmException
- The keyDerivationKey
has an unsupported
encryption algorithm or no current JCE provider supports
"HmacSHA1".EncryptionException
- If "UTF-8" is not supported as an encoding, then
this is thrown with the original UnsupportedEncodingException
as the cause. (NOTE: This should never happen as "UTF-8" is supposed to
be a common encoding supported by all Java implementations. Support
for it is usually in rt.jar.) This exception is also thrown if the
requested keySize
parameter exceeds the length of the number of
bytes provded in the keyDerivationKey
parameter.InvalidKeyException
- Likely indicates a coding error. Should not happen.EncryptionException
- Throw for some precondition violations.public static boolean isCombinedCipherMode(String cipherMode)
ESAPI.properties
file that supports both confidentiality
and authenticity (i.e., a "combined cipher mode" as NIST refers
to it).cipherMode
- The specified cipher mode to be used for the encryption
or decryption operation.SecurityConfiguration.getCombinedCipherModes()
public static boolean isAllowedCipherMode(String cipherMode)
Encryptor
.cipherMode
- The specified cipher mode to be used for the encryption
or decryption operation.isCombinedCipherMode(String)
,
SecurityConfiguration.getCombinedCipherModes()
,
SecurityConfiguration.getAdditionalAllowedCipherModes()
public static boolean isMACRequired(CipherText ct)
CipherText
object and the current ESAPI.property
settings. A MAC is considered "required" if the specified
CipherText
was not encrypted by one of the preferred
"combined" cipher modes (e.g., CCM or GCM) and the setting of the
current ESAPI properties for the property
Encryptor.CipherText.useMAC
is set to true
. (Normally,
the setting for Encryptor.CipherText.useMAC
should be set to
true
unless FIPS 140-2 compliance is required. See
User Guide for Symmetric Encryption in ESAPI 2.0 and the section
on using ESAPI with FIPS for further details.ct
- The specified CipherText
object to check to see if
it requires a MAC.public static boolean isCipherTextMACvalid(SecretKey sk, CipherText ct)
CipherText
object, then attempt to validate the MAC that
should be embedded within the CipherText
object by using a
derived key based on the specified SecretKey
.sk
- The SecretKey
used to derived a key to check
the authenticity via the MAC.ct
- The CipherText
that we are checking for a
valid MAC.SecretKey
or a MAC is not required. False is returned
otherwise.public static void overwrite(byte[] bytes, byte x)
bytes
- The byte array to be overwritten.x
- The byte array bytes
is overwritten with this byte.public static void overwrite(byte[] bytes)
overwrite(bytes, (byte)'*');
bytes
- The byte array to be overwritten.public static void copyByteArray(byte[] src, byte[] dest, int length)
System.arraycopy(src, 0, dest, 0, length)
.src
- the source array.dest
- the destination array.length
- the number of array elements to be copied.IndexOutOfBoundsException
- if copying would cause
access of data outside array bounds.NullPointerException
- if either src
or
dest
is null
.public static void copyByteArray(byte[] src, byte[] dest)
copyByteArray(src, dest, src.length)
.src
- the source array.dest
- the destination array.IndexOutOfBoundsException
- if copying would cause
access of data outside array bounds.NullPointerException
- if either src
or
dest
is null
.@Deprecated public static boolean arrayCompare(byte[] b1, byte[] b2)
b1
- A byte array to compare.b2
- A second byte array to compare.true
if both byte arrays are null or if both byte
arrays are identical or have the same value; otherwise
false
is returned.public static boolean isValidKDFVersion(int kdfVers, boolean restrictToCurrent, boolean throwIfError) throws IllegalArgumentException
[20110203, 99991231]
kdfVers
- KDF version # that we are checking. Generally this is
extracted from the serialized CipherText
.restrictToCurrent
- If this is set, we do an additional check
to see if the KDF version is a later version than the
one that this current ESAPI version supports.throwIfError
- Instead of returning false
in the case of
an error, throw an IllegalArgumentException
throwIfError
is true.}IllegalArgumentException
Copyright © 2021 The Open Web Application Security Project (OWASP). All rights reserved.