/**
* If a Message Authentication Code (MAC) is required for the specified
* {@code CipherText} object, then attempt to validate the MAC that
* should be embedded within the {@code CipherText} object by using a
* derived key based on the specified {@code SecretKey}.
*
* @param secretKey The {@code SecretKey} used to derived a key to check
* the authenticity via the MAC.
* @param cipherText The {@code CipherText} that we are checking for a
* valid MAC.
*
* @return True is returned if a MAC is required and it is valid as
* verified using a key derived from the specified
* {@code SecretKey} or a MAC is not required. False is returned
* otherwise.
*/
bool CryptoHelper::isCipherTextMACvalid(const SecretKey& secretKey, const CipherText& cipherText)
{
ASSERT(secretKey.getEncoded().length() > 0);
ASSERT(!cipherText.empty());
ASSERT(0);
return false;
}
/**
* The ESAPI Key Derivation Function (KDF) that computes a derived key from
* the {@code keyDerivationKey} for either encryption, decryption, or authentication.
* <p>
* <b>CAUTION:</b> If this algorithm for computing derived keys from the key derivation key
* is <i>ever</i> 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!!!
* <p>
* <b>NOTE:</b> This method is generally not intended to be called separately.
* It is used by ESAPI's reference crypto implementation class {@code 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.
*
* @param 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
* {@link #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.
* @param keyBits The cipher's key size (in bits) for the {@code keyDerivationKey}.
* Must have a minimum size of 56 bits and be an integral multiple of 8-bits.
* <b>Note:</b> The derived key will have the same size as this.
* @param purpose The purpose or use 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.
* Note that the parameter "purpose" serves the same function as "labe"
* in section 5.1 of NIST SP 800-108.
* @return The derived {@code SecretKey} to be used according
* to the specified purpose.
* @deprecated Use{@code KeyDerivationFunction} instead. This method will be removed as of
* ESAPI release 2.1 so if you are using this, please change your code.
*/
SecretKey CryptoHelper::computeDerivedKey(const SecretKey& keyDerivationKey, unsigned int keyBits, const NarrowString& purpose)
{
// Shamelessly ripped from KeyDerivationFunction.cpp
ASSERT( keyDerivationKey.getEncoded().length() > 0 );
ASSERT( keyBits >= 56 );
ASSERT( (keyBits % 8) == 0 );
ASSERT( purpose == "authenticity" || purpose == "encryption" );
return KeyDerivationFunction::computeDerivedKey(keyDerivationKey, keyBits, purpose);
}
