public class KeyDerivationFunction extends Object
Acknowledgments:
ESAPI's KDF is patterned after suggestions first made by cryptographer
Dr. David A. Wagner and later extended to follow KDF in counter mode
as specified by section 5.1 of NIST SP 800-108. Jeffrey Walton and the NSA
also made valuable suggestions regarding the modeling of the method,
computeDerivedKey(SecretKey, int, String)
.
Modifier and Type | Class and Description |
---|---|
static class |
KeyDerivationFunction.PRF_ALGORITHMS |
Modifier and Type | Field and Description |
---|---|
static int |
kdfVersion |
static int |
originalVersion
Used to support backward compatibility.
|
Constructor and Description |
---|
KeyDerivationFunction()
Construct a
KeyDerivationFunction based on the
ESAPI.property property, Encryptor.KDF.PRF . |
KeyDerivationFunction(KeyDerivationFunction.PRF_ALGORITHMS prfAlg)
Construct a
KeyDerivationFunction . |
Modifier and Type | Method and Description |
---|---|
SecretKey |
computeDerivedKey(SecretKey keyDerivationKey,
int keySize,
String purpose)
The method is ESAPI's Key Derivation Function (KDF) that computes a
derived key from the
keyDerivationKey for either
encryption / decryption or for authentication. |
static KeyDerivationFunction.PRF_ALGORITHMS |
convertIntToPRF(int selection) |
static KeyDerivationFunction.PRF_ALGORITHMS |
convertNameToPRF(String prfAlgName) |
String |
getContext()
Return the optional 'context' that typically contains information
related to the keying material, such as the identities of the message
sender and recipient.
|
String |
getPRFAlgName()
Return the name of the algorithm for the Pseudo Random Function (PRF)
that is being used.
|
int |
getVersion()
Return the version used for backward compatibility.
|
static boolean |
isValidPRF(String prfAlgName)
Check if specified algorithm name is a valid PRF that can be used.
|
static void |
main(String[] args)
Print list of ESAPI supported pseudo-random functions for KDF and
KDF version information.
|
void |
setContext(String context)
Set the 'context' as specified by NIST Special Publication 800-108.
|
void |
setVersion(int version)
Set version so backward compatibility can be supported.
|
public static final int originalVersion
kdfVersion
is used as the
version for the serialized encrypted ciphertext on all the "encrypt"
operations. This static field should be the same as
CipherText.cipherTextVersion
and
CipherTextSerializer.cipherTextSerializerVersion
to make sure
that these classes are all kept in-sync in order to support backward
compatibility of previously encrypted data.
Previous versions: 20110203 - Original version (ESAPI releases 2.0 & 2.0.1) 20130830 - Fix to issue #306 (release 2.1.0)
public static final int kdfVersion
public KeyDerivationFunction(KeyDerivationFunction.PRF_ALGORITHMS prfAlg)
KeyDerivationFunction
.prfAlg
- Specifies a supported algorithm.public KeyDerivationFunction()
KeyDerivationFunction
based on the
ESAPI.property property, Encryptor.KDF.PRF
.public String getPRFAlgName()
public void setVersion(int version) throws IllegalArgumentException
version
- Date as a integer, in format of YYYYMMDD. Maximum
version date is 99991231 (December 31, 9999).IllegalArgumentException
- If version
is not within
the valid range of [20110203, 99991231].public int getVersion()
public void setContext(String context)
"Derived keying material should be bound to all relying entities and other information to identify the derived keying material. This is called context binding. In particular, the identity (or identifier, as the term is defined in [NIST SP 800-56A , sic] and [NIST SP 800-56B , sic]) of each entity that will access (meaning derive, hold, use, and/or distribute) any segment of the keying material should be included in the Context string input to the KDF, provided that this information is known by each entity who derives the keying material."The ISO/IEC's KDF2 uses a similar construction for their KDF and there 'context' data is not specified at all. Therefore, ESAPI 2.0's reference implementation,
JavaEncryptor
, chooses not to use
'context' at all.context
- Optional binary string containing information related to
the derived keying material. By default (if this method
is never called), the empty string is used. May have any
value but null
.public String getContext()
setContext(String)
public SecretKey computeDerivedKey(SecretKey keyDerivationKey, int keySize, String purpose) throws NoSuchAlgorithmException, InvalidKeyException, EncryptionException
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
CryptoHelper.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. This KDK cannot be null.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. IMPORTANT: For the ESAPI reference implementation,
JavaEncryptor
, this must be either the string "encryption" or
"authenticity", where "encryption" is used for creating a derived key to use
for confidentiality, and "authenticity" is used for creating a derived key to
use with a MAC to ensure message authenticity. However, since parameter serves
the same purpose as the "Label" in section 5.1 of NIST SP 800-108, it really can
be set to anything other than null
or an empty string when called outside
of ESAPI's JavaEncryptor
reference implementation (but you must consistent).SecretKey
to be used according
to the specified purpose.NoSuchAlgorithmException
- The keyDerivationKey
has an unsupported
encryption algorithm or no current JCE provider supports requested
Hmac algorithrm used for the PRF for key generation.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 isValidPRF(String prfAlgName)
prfAlgName
- Name of the PRF algorithm; e.g., "HmacSHA1", "HmacSHA384", etc.prfAlgName
is supported, otherwise false.public static KeyDerivationFunction.PRF_ALGORITHMS convertNameToPRF(String prfAlgName)
public static KeyDerivationFunction.PRF_ALGORITHMS convertIntToPRF(int selection)
public static final void main(String[] args)
args
- Required, but not used.Copyright © 2021 The Open Web Application Security Project (OWASP). All rights reserved.