org.owasp.esapi.crypto

Class CryptoHelper

java.lang.Object

org.owasp.esapi.crypto.CryptoHelper

public class CryptoHelper
extends java.lang.Object

Class to provide some convenience methods for encryption, decryption, etc.

All the cryptographic operations use the default cryptographic properties; e.g., default cipher transformation, default key size, default IV type (where applicable), etc.

Since:

2.0

Field Summary

Fields

Modifier and Type	Field and Description
private static Logger	logger

Constructor Summary

Constructors

Modifier	Constructor and Description
private	CryptoHelper() Prevent public, no-argument CTOR from being auto-generated.

Method Summary

Modifier and Type	Method and Description
static boolean	arrayCompare(byte[] b1, byte[] b2) A "safe" array comparison that is not vulnerable to side-channel "timing attacks".
static javax.crypto.SecretKey	computeDerivedKey(javax.crypto.SecretKey keyDerivationKey, int keySize, java.lang.String purpose) Deprecated. UseKeyDerivationFunction instead. This method will be removed as of ESAPI release 2.1 so if you are using this, please change your code.
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 javax.crypto.SecretKey	generateSecretKey(java.lang.String alg, int keySize) Generate a random secret key appropriate to the specified cipher algorithm and key size.
static boolean	isAllowedCipherMode(java.lang.String cipherMode) Return true if specified cipher mode is one that may be used for encryption / decryption operations via Encryptor.
static boolean	isCipherTextMACvalid(javax.crypto.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(java.lang.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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

private static final Logger logger

Constructor Detail

CryptoHelper

private CryptoHelper()

Prevent public, no-argument CTOR from being auto-generated. Public CTOR is not needed as all methods are static.

Method Detail

generateSecretKey

public static javax.crypto.SecretKey generateSecretKey(java.lang.String alg,
                                                       int keySize)
                                                throws EncryptionException

Generate a random secret key appropriate to the specified cipher algorithm and key size.

Parameters:

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.

Returns:

A random SecretKey is returned.

Throws:

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.

computeDerivedKey

public static javax.crypto.SecretKey computeDerivedKey(javax.crypto.SecretKey keyDerivationKey,
                                                       int keySize,
                                                       java.lang.String purpose)
                                                throws java.security.NoSuchAlgorithmException,
                                                       java.security.InvalidKeyException,
                                                       EncryptionException

Deprecated. UseKeyDerivationFunction instead. This method will be removed as of ESAPI release 2.1 so if you are using this, please change your code.

The method is ESAPI's Key Derivation Function (KDF) that computes a derived key from the 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.

Parameters:

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.

Returns:

The derived 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.

Throws:

java.security.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.)

java.security.InvalidKeyException - Likely indicates a coding error. Should not happen.

EncryptionException - Throw for some precondition violations.

isCombinedCipherMode

public static boolean isCombinedCipherMode(java.lang.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).

Parameters:

cipherMode - The specified cipher mode to be used for the encryption or decryption operation.

Returns:

true if the specified cipher mode is in the comma-separated list of cipher modes supporting both confidentiality and authenticity; otherwise false.

See Also:

SecurityConfiguration.getCombinedCipherModes()

isAllowedCipherMode

public static boolean isAllowedCipherMode(java.lang.String cipherMode)

Return true if specified cipher mode is one that may be used for encryption / decryption operations via Encryptor.

Parameters:

cipherMode - The specified cipher mode to be used for the encryption or decryption operation.

Returns:

true if the specified cipher mode is in the comma-separated list of cipher modes supporting both confidentiality and authenticity; otherwise false.

See Also:

isCombinedCipherMode(String), SecurityConfiguration.getCombinedCipherModes(), SecurityConfiguration.getAdditionalAllowedCipherModes()

isMACRequired

public 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. 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.

Parameters:

ct - The specified CipherText object to check to see if it requires a MAC.

Returns:

True if a MAC is required, false if it is not required.

isCipherTextMACvalid

public static boolean isCipherTextMACvalid(javax.crypto.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.

Parameters:

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.

Returns:

True is returned if a MAC is required and it is valid as verified using a key derived from the specified SecretKey or a MAC is not required. False is returned otherwise.

overwrite

public static void overwrite(byte[] bytes,
                             byte x)

Overwrite a byte array with a specified byte. This is frequently done to a plaintext byte array so the sensitive data is not lying around exposed in memory.

Parameters:

bytes - The byte array to be overwritten.

x - The byte array bytes is overwritten with this byte.

overwrite

public static void overwrite(byte[] bytes)

Overwrite a byte array with the byte containing '*'. That is, call

                overwrite(bytes, (byte)'*');
 

Parameters:

bytes - The byte array to be overwritten.

copyByteArray

public static void copyByteArray(byte[] src,
                                 byte[] dest,
                                 int length)

Same as System.arraycopy(src, 0, dest, 0, length).

Parameters:

src - the source array.

dest - the destination array.

length - the number of array elements to be copied.

Throws:

java.lang.IndexOutOfBoundsException - if copying would cause access of data outside array bounds.

java.lang.NullPointerException - if either src or dest is null.

copyByteArray

public static void copyByteArray(byte[] src,
                                 byte[] dest)

Same as copyByteArray(src, dest, src.length).

Parameters:

src - the source array.

dest - the destination array.

Throws:

java.lang.IndexOutOfBoundsException - if copying would cause access of data outside array bounds.

java.lang.NullPointerException - if either src or dest is null.

arrayCompare

public static boolean arrayCompare(byte[] b1,
                                   byte[] b2)

A "safe" array comparison that is not vulnerable to side-channel "timing attacks". All comparisons of non-null, equal length bytes should take same amount of time. We use this for cryptographic comparisons.

Parameters:

b1 - A byte array to compare.

b2 - A second byte array to compare.

Returns:

true if both byte arrays are null or if both byte arrays are identical or have the same value; otherwise false is returned.

isValidKDFVersion

public static boolean isValidKDFVersion(int kdfVers,
                                        boolean restrictToCurrent,
                                        boolean throwIfError)
                                 throws java.lang.IllegalArgumentException

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:

     [20110203, 99991231]
 

Parameters:

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

Returns:

True if in range, false otherwise (except if throwIfError is true.}

Throws:

java.lang.IllegalArgumentException