With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero. With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by the two parties intending to share the shared secret. With the key derivation function CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some data shared by the two parties intending to share the shared secret. Otherwise, pOtherInfo must be NULL and ulOtherInfoLen must be zero.
CK_X9_42_DH1_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_DH1_DERIVE_PARAMS.
· CK_X9_42_DH2_DERIVE_PARAMS, CK_X9_42_DH2_DERIVE_PARAMS_PTR
CK_X9_42_DH2_DERIVE_PARAMS is a structure that provides the parameters to the CKM_X9_42_DH_HYBRID_DERIVE and CKM_X9_42_MQV_DERIVE key derivation mechanisms, where each party contributes two key pairs. The structure is defined as follows:
typedef struct CK_X9_42_DH2_DERIVE_PARAMS {
CK_X9_42_DH_KDF_TYPE kdf;
CK_ULONG ulOtherInfoLen;
CK_BYTE_PTR pOtherInfo;
CK_ULONG ulPublicDataLen;
CK_BYTE_PTR pPublicData;
CK_ULONG ulPrivateDataLen;
CK_OBJECT_HANDLE hPrivateData;
CK_ULONG ulPublicDataLen2;
CK_BYTE_PTR pPublicData2;
} CK_X9_42_DH2_DERIVE_PARAMS;
The fields of the structure have the following meanings:
kdf key derivation function used on the shared secret value
ulOtherInfoLen the length in bytes of the other info
pOtherInfo some data shared between the two parties
ulPublicDataLen the length in bytes of the other party’s first X9.42 Diffie-Hellman public key
pPublicData pointer to other party’s first X9.42 Diffie-Hellman public key value
ulPrivateDataLen the length in bytes of the second X9.42 Diffie-Hellman private key
hPrivateData key handle for second X9.42 Diffie-Hellman private key value
ulPublicDataLen2 the length in bytes of the other party’s second X9.42 Diffie-Hellman public key
pPublicData2 pointer to other party’s second X9.42 Diffie-Hellman public key value
With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero. With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by the two parties intending to share the shared secret. With the key derivation function CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some data shared by the two parties intending to share the shared secret. Otherwise, pOtherInfo must be NULL and ulOtherInfoLen must be zero.
CK_X9_42_DH2_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_DH2_DERIVE_PARAMS.
· CK_X9_42_MQV_DERIVE_PARAMS, CK_X9_42_MQV_DERIVE_PARAMS_PTR
CK_X9_42_MQV_DERIVE_PARAMS is a structure that provides the parameters to the CKM_X9_42_MQV_DERIVE key derivation mechanism, where each party contributes two key pairs. The structure is defined as follows:
typedef struct CK_X9_42_MQV_DERIVE_PARAMS {
CK_X9_42_DH_KDF_TYPE kdf;
CK_ULONG ulOtherInfoLen;
CK_BYTE_PTR pOtherInfo;
CK_ULONG ulPublicDataLen;
CK_BYTE_PTR pPublicData;
CK_ULONG ulPrivateDataLen;
CK_OBJECT_HANDLE hPrivateData;
CK_ULONG ulPublicDataLen2;
CK_BYTE_PTR pPublicData2;
CK_OBJECT_HANDLE publicKey;
} CK_X9_42_MQV_DERIVE_PARAMS;
The fields of the structure have the following meanings:
kdf key derivation function used on the shared secret value
ulOtherInfoLen the length in bytes of the other info
pOtherInfo some data shared between the two parties
ulPublicDataLen the length in bytes of the other party’s first X9.42 Diffie-Hellman public key
pPublicData pointer to other party’s first X9.42 Diffie-Hellman public key value
ulPrivateDataLen the length in bytes of the second X9.42 Diffie-Hellman private key
hPrivateData key handle for second X9.42 Diffie-Hellman private key value
ulPublicDataLen2 the length in bytes of the other party’s second X9.42 Diffie-Hellman public key
pPublicData2 pointer to other party’s second X9.42 Diffie-Hellman public key value
publicKey Handle to the first party’s ephemeral public key
With the key derivation function CKD_NULL, pOtherInfo must be NULL and ulOtherInfoLen must be zero. With the key derivation function CKD_SHA1_KDF_ASN1, pOtherInfo must be supplied, which contains an octet string, specified in ASN.1 DER encoding, consisting of mandatory and optional data shared by the two parties intending to share the shared secret. With the key derivation function CKD_SHA1_KDF_CONCATENATE, an optional pOtherInfo may be supplied, which consists of some data shared by the two parties intending to share the shared secret. Otherwise, pOtherInfo must be NULL and ulOtherInfoLen must be zero.
CK_X9_42_MQV_DERIVE_PARAMS_PTR is a pointer to a CK_X9_42_MQV_DERIVE_PARAMS.
The X9.42 Diffie-Hellman key pair generation mechanism, denoted CKM_X9_42_DH_KEY_PAIR_GEN, is a key pair generation mechanism based on Diffie-Hellman key agreement, as defined in the ANSI X9.42 standard.
It does not have a parameter.
The mechanism generates X9.42 Diffie-Hellman public/private key pairs with a particular prime, base and subprime, as specified in the CKA_PRIME, CKA_BASE and CKA_SUBPRIME attributes of the template for the public key.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, CKA_SUBPRIME, and CKA_VALUE attributes to the new private key; other attributes required by the X9.42 Diffie-Hellman public and private key types must be specified in the templates.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.
The X9.42 Diffie-Hellman domain parameter generation mechanism, denoted CKM_X9_42_DH_PARAMETER_GEN, is a domain parameters generation mechanism based on X9.42 Diffie-Hellman key agreement, as defined in the ANSI X9.42 standard.
It does not have a parameter.
The mechanism generates X9.42 Diffie-Hellman domain parameters with particular prime and subprime length in bits, as specified in the CKA_PRIME_BITS and CKA_SUBPRIME_BITS attributes of the template for the domain parameters.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_BASE, CKA_SUBPRIME, CKA_PRIME_BITS and CKA_SUBPRIME_BITS attributes to the new object. Other attributes supported by the X9.42 Diffie-Hellman domain parameter types may also be specified in the template for the domain parameters, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits.
The X9.42 Diffie-Hellman key derivation mechanism, denoted CKM_X9_42_DH_DERIVE, is a mechanism for key derivation based on the Diffie-Hellman key agreement scheme, as defined in the ANSI X9.42 standard, where each party contributes one key pair, all using the same X9.42 Diffie-Hellman domain parameters.
It has a parameter, a CK_X9_42_DH1_DERIVE_PARAMS structure.
This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. Note that in order to validate this mechanism it may be required to use the CKA_VALUE attribute as the key of a general-length MAC mechanism (e.g. CKM_SHA_1_HMAC_GENERAL) over some test data.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.
The X9.42 Diffie-Hellman hybrid key derivation mechanism, denoted CKM_X9_42_DH_HYBRID_DERIVE, is a mechanism for key derivation based on the Diffie-Hellman hybrid key agreement scheme, as defined in the ANSI X9.42 standard, where each party contributes two key pair, all using the same X9.42 Diffie-Hellman domain parameters.
It has a parameter, a CK_X9_42_DH2_DERIVE_PARAMS structure.
This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. Note that in order to validate this mechanism it may be required to use the CKA_VALUE attribute as the key of a general-length MAC mechanism (e.g. CKM_SHA_1_HMAC_GENERAL) over some test data.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.
The X9.42 Diffie-Hellman Menezes-Qu-Vanstone (MQV) key derivation mechanism, denoted CKM_X9_42_MQV_DERIVE, is a mechanism for key derivation based the MQV scheme, as defined in the ANSI X9.42 standard, where each party contributes two key pairs, all using the same X9.42 Diffie-Hellman domain parameters.
It has a parameter, a CK_X9_42_MQV_DERIVE_PARAMS structure.
This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. Note that in order to validate this mechanism it may be required to use the CKA_VALUE attribute as the key of a general-length MAC mechanism (e.g. CKM_SHA_1_HMAC_GENERAL) over some test data.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of X9.42 Diffie-Hellman prime sizes, in bits, for the CKA_PRIME attribute.
Cryptoki Versions 2.01 and up allow the use of secret keys for wrapping and unwrapping RSA private keys, Diffie-Hellman private keys, X9.42 Diffie-Hellman private keys, EC (also related to ECDSA) private keys and DSA private keys. For wrapping, a private key is BER-encoded according to PKCS #8’s PrivateKeyInfo ASN.1 type. PKCS #8 requires an algorithm identifier for the type of the private key. The object identifiers for the required algorithm identifiers are as follows:
rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1 }
dhKeyAgreement OBJECT IDENTIFIER ::= { pkcs-3 1 }
dhpublicnumber OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) ansi-x942(10046) number-type(2) 1 }
id-ecPublicKey OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) ansi-x9-62(10045) publicKeyType(2) 1 }
id-dsa OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) x9-57(10040) x9cm(4) 1 }
where
pkcs-1 OBJECT IDENTIFIER ::= {
iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 1 }
pkcs-3 OBJECT IDENTIFIER ::= {
iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 3 }
These parameters for the algorithm identifiers have the following types, respectively:
NULL
DHParameter ::= SEQUENCE {
prime INTEGER, -- p
base INTEGER, -- g
privateValueLength INTEGER OPTIONAL
}
DomainParameters ::= SEQUENCE {
prime INTEGER, -- p
base INTEGER, -- g
subprime INTEGER, -- q
cofactor INTEGER OPTIONAL, -- j
validationParms ValidationParms OPTIONAL
}
ValidationParms ::= SEQUENCE {
Seed BIT STRING, -- seed
PGenCounter INTEGER -- parameter verification
}
Parameters ::= CHOICE {
ecParameters ECParameters,
namedCurve CURVES.&id({CurveNames}),
implicitlyCA NULL
}
Dss-Parms ::= SEQUENCE {
p INTEGER,
q INTEGER,
g INTEGER
}
For the X9.42 Diffie-Hellman domain parameters, the cofactor and the validationParms optional fields should not be used when wrapping or unwrapping X9.42 Diffie-Hellman private keys since their values are not stored within the token.
For the EC domain parameters, the use of namedCurve is recommended over the choice ecParameters. The choice implicitlyCA must not be used in Cryptoki.
Within the PrivateKeyInfo type:
· RSA private keys are BER-encoded according to PKCS #1’s RSAPrivateKey ASN.1 type. This type requires values to be present for all the attributes specific to Cryptoki’s RSA private key objects. In other words, if a Cryptoki library does not have values for an RSA private key’s CKA_MODULUS, CKA_PUBLIC_EXPONENT, CKA_PRIVATE_EXPONENT, CKA_PRIME_1, CKA_PRIME_2, CKA_EXPONENT_1, CKA_EXPONENT2, and CKA_COEFFICIENT values, it must not create an RSAPrivateKey BER-encoding of the key, and so it must not prepare it for wrapping.
· Diffie-Hellman private keys are represented as BER-encoded ASN.1 type INTEGER.
· X9.42 Diffie-Hellman private keys are represented as BER-encoded ASN.1 type INTEGER.
· EC (also related with ECDSA) private keys are BER-encoded according to SECG SEC 1 ECPrivateKey ASN.1 type:
ECPrivateKey ::= SEQUENCE {
Version INTEGER { ecPrivkeyVer1(1) } (ecPrivkeyVer1),
privateKey OCTET STRING,
parameters [0] Parameters OPTIONAL,
publicKey [1] BIT STRING OPTIONAL
}
Since the EC domain parameters are placed in the PKCS #8’s privateKeyAlgorithm field, the optional parameters field in an ECPrivateKey must be omitted. A Cryptoki application must be able to unwrap an ECPrivateKey that contains the optional publicKey field; however, what is done with this publicKey field is outside the scope of Cryptoki.
· DSA private keys are represented as BER-encoded ASN.1 type INTEGER.
Once a private key has been BER-encoded as a PrivateKeyInfo type, the resulting string of bytes is encrypted with the secret key. This encryption must be done in CBC mode with PKCS padding.
Unwrapping a wrapped private key undoes the above procedure. The CBC-encrypted ciphertext is decrypted, and the PKCS padding is removed. The data thereby obtained are parsed as a PrivateKeyInfo type, and the wrapped key is produced. An error will result if the original wrapped key does not decrypt properly, or if the decrypted unpadded data does not parse properly, or its type does not match the key type specified in the template for the new key. The unwrapping mechanism contributes only those attributes specified in the PrivateKeyInfo type to the newly-unwrapped key; other attributes must be specified in the template, or will take their default values.
Earlier drafts of PKCS #11 Version 2.0 and Version 2.01 used the object identifier
DSA OBJECT IDENTIFIER ::= { algorithm 12 }
algorithm OBJECT IDENTIFIER ::= {
iso(1) identifier-organization(3) oiw(14) secsig(3) algorithm(2) }
with associated parameters
DSAParameters ::= SEQUENCE {
prime1 INTEGER, -- modulus p
prime2 INTEGER, -- modulus q
base INTEGER -- base g
}
for wrapping DSA private keys. Note that although the two structures for holding DSA domain parameters appear identical when instances of them are encoded, the two corresponding object identifiers are different.
Table 44, Generic Secret Key Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_GENERIC_SECRET_KEY_GEN |
|
|
|
|
ü |
|
|
This section defines the key type “CKK_GENERIC_SECRET” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.
Mechanisms:
CKM_GENERIC_SECRET_KEY_GEN
Generic secret key objects (object class CKO_SECRET_KEY, key type CKK_GENERIC_SECRET) hold generic secret keys. These keys do not support encryption or decryption; however, other keys can be derived from them and they can be used in HMAC operations. The following table defines the generic secret key object attributes, in addition to the common attributes defined for this object class:
These key types are used in several of the mechanisms described in this section.
Table 45, Generic Secret Key Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_VALUE1,4,6,7 |
Byte array |
Key value (arbitrary length) |
|
CKA_VALUE_LEN2,3 |
CK_ULONG |
Length in bytes of key value |
- Refer to [PKCS #11-Base] table 10 for footnotes
The following is a sample template for creating a generic secret key object:
CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_GENERIC_SECRET;
CK_UTF8CHAR label[] = “A generic secret key object”;
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_DERIVE, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};
CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three bytes of the SHA-1 hash of the generic secret key object’s CKA_VALUE attribute.
The generic secret key generation mechanism, denoted CKM_GENERIC_SECRET_KEY_GEN, is used to generate generic secret keys. The generated keys take on any attributes provided in the template passed to the C_GenerateKey call, and the CKA_VALUE_LEN attribute specifies the length of the key to be generated.
It does not have a parameter.
The template supplied must specify a value for the CKA_VALUE_LEN attribute. If the template specifies an object type and a class, they must have the following values:
CK_OBJECT_CLASS = CKO_SECRET_KEY;
CK_KEY_TYPE = CKK_GENERIC_SECRET;
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of key sizes, in bits.
Refer to RFC2104 and FIPS 198 for HMAC algorithm description.. The HMAC secret key shall correspond to the PKCS11 generic secret key type or the mechanism specific key types (see mechanism definition). Such keys, for use with HMAC operations can be created using C_CreateObject or C_GenerateKey.
The RFC also specifies test vectors for the various hash function based HMAC mechanisms described in the respective hash mechanism descriptions. The RFC should be consulted to obtain these test vectors.
For the Advanced Encryption Standard (AES) see [FIPS PUB 197].
Table 46, AES Mechanisms vs. Functions
This section defines the key type “CKK_AES” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.
Mechanisms:
CKM_AES_KEY_GEN
CKM_AES_ECB
CKM_AES_CBC
CKM_AES_MAC
CKM_AES_MAC_GENERAL
CKM_AES_CBC_PAD
CKM_AES_OFB
CKM_AES_CFB64
CKM_AES_CFB8
CKM_AES_CFB128
CKM_AES_CFB1
CKM_AES_XCBC_MAC
CKM_AES_XCBC_MAC_96
AES secret key objects (object class CKO_SECRET_KEY, key type CKK_AES) hold AES keys. The following table defines the AES secret key object attributes, in addition to the common attributes defined for this object class:
Table 47, AES Secret Key Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_VALUE1,4,6,7 |
Byte array |
Key value (16, 24, or 32 bytes) |
|
CKA_VALUE_LEN2,3,6 |
CK_ULONG |
Length in bytes of key value |
- Refer to [PKCS #11-Base] table 10 for footnotes
The following is a sample template for creating an AES secret key object:
CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_AES;
CK_UTF8CHAR label[] = “An AES secret key object”;
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};
CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three bytes of the ECB encryption of a single block of null (0x00) bytes, using the default cipher associated with the key type of the secret key object.
The AES key generation mechanism, denoted CKM_AES_KEY_GEN, is a key generation mechanism for NIST’s Advanced Encryption Standard.
It does not have a parameter.
The mechanism generates AES keys with a particular length in bytes, as specified in the CKA_VALUE_LEN attribute of the template for the key.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key. Other attributes supported by the AES key type (specifically, the flags indicating which functions the key supports) may be specified in the template for the key, or else are assigned default initial values.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.
AES-ECB, denoted CKM_AES_ECB, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on NIST Advanced Encryption Standard and electronic codebook mode.
It does not have a parameter.
This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to wrap/unwrap every secret key that it supports. For wrapping, the mechanism encrypts the value of the CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus one null bytes so that the resulting length is a multiple of the block size. The output data is the same length as the padded input data. It does not wrap the key type, key length, or any other information about the key; the application must convey these separately.
For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.
Constraints on key types and the length of data are summarized in the following table:
Table 48, AES-ECB: Key And Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
AES |
multiple of block size |
same as input length |
no final part |
|
C_Decrypt |
AES |
multiple of block size |
same as input length |
no final part |
|
C_WrapKey |
AES |
any |
input length rounded up to multiple of block size |
|
|
C_UnwrapKey |
AES |
multiple of block size |
determined by type of key being unwrapped or CKA_VALUE_LEN |
|
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.
AES-CBC, denoted CKM_AES_CBC, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on NIST’s Advanced Encryption Standard and cipher-block chaining mode.
It has a parameter, a 16-byte initialization vector.
This mechanism can wrap and unwrap any secret key. Of course, a particular token may not be able to wrap/unwrap every secret key that it supports. For wrapping, the mechanism encrypts the value of the CKA_VALUE attribute of the key that is wrapped, padded on the trailing end with up to block size minus one null bytes so that the resulting length is a multiple of the block size. The output data is the same length as the padded input data. It does not wrap the key type, key length, or any other information about the key; the application must convey these separately.
For unwrapping, the mechanism decrypts the wrapped key, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one, and the key type supports it, the CKA_VALUE_LEN attribute of the template. The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template.
Constraints on key types and the length of data are summarized in the following table:
Table 49, AES-CBC: Key And Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
AES |
multiple of block size |
same as input length |
no final part |
|
C_Decrypt |
AES |
multiple of block size |
same as input length |
no final part |
|
C_WrapKey |
AES |
any |
input length rounded up to multiple of the block size |
|
|
C_UnwrapKey |
AES |
multiple of block size |
determined by type of key being unwrapped or CKA_VALUE_LEN |
|
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.
AES-CBC with PKCS padding, denoted CKM_AES_CBC_PAD, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on NIST’s Advanced Encryption Standard; cipher-block chaining mode; and the block cipher padding method detailed in PKCS #7.
It has a parameter, a 16-byte initialization vector.
The PKCS padding in this mechanism allows the length of the plaintext value to be recovered from the ciphertext value. Therefore, when unwrapping keys with this mechanism, no value should be specified for the CKA_VALUE_LEN attribute.
In addition to being able to wrap and unwrap secret keys, this mechanism can wrap and unwrap RSA, Diffie-Hellman, X9.42 Diffie-Hellman, EC (also related to ECDSA) and DSA private keys (see Section 2.5 for details). The entries in the table below for data length constraints when wrapping and unwrapping keys do not apply to wrapping and unwrapping private keys.
Constraints on key types and the length of data are summarized in the following table:
Table 50, AES-CBC with PKCS Padding: Key And Data Length
|
Function |
Key type |
Input length |
Output length |
|
C_Encrypt |
AES |
any |
input length rounded up to multiple of the block size |
|
C_Decrypt |
AES |
multiple of block size |
between 1 and block size bytes shorter than input length |
|
C_WrapKey |
AES |
any |
input length rounded up to multiple of the block size |
|
C_UnwrapKey |
AES |
multiple of block size |
between 1 and block length bytes shorter than input length |
AES-OFB, denoted CKM_AES_OFB. It is a mechanism for single and multiple-part encryption and decryption with AES. AES-OFB mode is described in [NIST sp800-38a].
It has a parameter, an initialization vector for this mode.
The initialization vector has the same length as the block size.
Constraints on key types and the length of data are summarized in the following
table:
Table 51, AES-OFB: Key And Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
AES |
any |
same as input length |
no final part |
|
C_Decrypt |
AES |
any |
same as input length |
no final part |
For this mechanism the CK_MECHANISM_INFO structure is as specified for CBC mode.
Cipher AES has a cipher feedback mode, AES-CFB, denoted CKM_AES_CFB8, CKM_AES_CFB64, and CKM_AES_CFB128. It is a mechanism for single and multiple-part encryption and decryption with AES. AES-OFB mode is described [NIST sp800-38a].
It has a parameter, an initialization vector for this mode.
The initialization vector has the same length as the block size.
Constraints on key types and the length of data are summarized in the following
table:
Table 52, AES-CFB: Key And Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
AES |
any |
same as input length |
no final part |
|
C_Decrypt |
AES |
any |
same as input length |
no final part |
For this mechanism the CK_MECHANISM_INFO structure is as specified for CBC mode.
General-length AES-MAC, denoted CKM_AES_MAC_GENERAL, is a mechanism for single- and multiple-part signatures and verification, based on NIST Advanced Encryption Standard as defined in FIPS PUB 197 and data authentication as defined in FIPS PUB 113.
It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length desired from the mechanism.
The output bytes from this mechanism are taken from the start of the final AES cipher block produced in the MACing process.
Constraints on key types and the length of data are summarized in the following table:
Table 53, General-length AES-MAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
AES |
any |
0-block size, as specified in parameters |
|
C_Verify |
AES |
any |
0-block size, as specified in parameters |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.
AES-MAC, denoted by CKM_AES_MAC, is a special case of the general-length AES-MAC mechanism. AES-MAC always produces and verifies MACs that are half the block size in length.
It does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 54, AES-MAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
AES |
Any |
½ block size (8 bytes) |
|
C_Verify |
AES |
Any |
½ block size (8 bytes) |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.
AES-XCBC-MAC, denoted CKM_AES_XCBC_MAC, is a mechanism for single and multiple part signatures and verification; based on NIST’s Advanced Encryption Standard and [RFC 3566].
It does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 55, AES-XCBC-MAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
AES |
Any |
16 bytes |
|
C_Verify |
AES |
Any |
16 bytes |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.
AES-XCBC-MAC-96, denoted CKM_AES_XCBC_MAC-_96,
is a mechanism for single and multiple part signatures and verification; based
on NIST’s Advanced Encryption Standard and [RFC 3566].
It does not have a parameter.
Constraints on key types and the length of data are summarized in the following table:
Table 56, AES-XCBC-MAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
AES |
Any |
12 bytes |
|
C_Verify |
AES |
Any |
12 bytes |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.
Table 57, AES with Counter Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_AES_CTR |
ü |
|
|
|
|
ü |
|
Mechanisms:
CKM_AES_CTR
¨ CK_AES_CTR_PARAMS; CK_AES_CTR_PARAMS_PTR
CK_AES_CTR_PARAMS is a structure that provides the parameters to the CKM_AES_CTR mechanism. It is defined as follows:
typedef struct CK_AES_CTR_PARAMS {
CK_ULONG ulCounterBits;
CK_BYTE cb[16];
} CK_AES_CTR_PARAMS;
ulCounterBits specifies the number of bits in the counter block (cb) that shall be incremented. This number shall be such that 0 < ulCounterBits <= 128. For any values outside this range the mechanism shall return CKR_MECHANISM_PARAM_INVALID.
It's up to the caller to initialize all of the bits in the counter block including the counter bits. The counter bits are the least significant bits of the counter block (cb). They are a big-endian value usually starting with 1. The rest of ‘cb’ is for the nonce, and maybe an optional IV.
E.g. as defined in [RFC 3686]:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Nonce |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Initialization Vector (IV) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Block Counter |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This construction permits each packet to consist of up to 232-1 blocks = 4,294,967,295 blocks = 68,719,476,720 octets.
CK_AES_CTR_PARAMS_PTR is a pointer to a CK_AES_CTR_PARAMS.
Generic AES counter mode is described in NIST Special Publication 800-38A and in RFC 3686. These describe encryption using a counter block which may include a nonce to guarantee uniqueness of the counter block. Since the nonce is not incremented, the mechanism parameter must specify the number of counter bits in the counter block.
The block counter is incremented by 1 after each block of plaintext is processed. There is no support for any other increment functions in this mechanism.
If an attempt to encrypt/decrypt is made which will cause an overflow of the counter block’s counter bits, then the mechanism shall return CKR_DATA_LEN_RANGE. Note that the mechanism should allow the final post increment of the counter to overflow (if it implements it this way) but not allow any further processing after this point. E.g. if ulCounterBits = 2 and the counter bits start as 1 then only 3 blocks of data can be processed.
Ref [NIST AES CTS]
This mode allows unpadded data that has length that is not a multiple of the block size to be encrypted to the same length of cipher text.
Table 58, AES CBC with Cipher Text Stealing CTS Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_AES_CTS |
ü |
|
|
|
|
ü |
|
Mechanisms:
CKM_AES_CTS
It has a parameter, a 16-byte initialization vector.
Table 59, AES-CTS: Key And Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
AES |
Any, ≥ block size (16 bytes) |
same as input length |
no final part |
|
C_Decrypt |
AES |
any, ≥ block size (16 bytes) |
same as input length |
no final part |
Table 60, Additional AES Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_AES_GCM |
ü |
|
|
|
|
ü |
|
|
CKM_AES_CCM |
ü |
|
|
|
|
ü |
|
|
CKM_AES_GMAC |
|
ü |
|
|
|
|
ü |
Mechanisms:
CKM_AES_GCM
CKM_AES_CCM
CKM_AES_GMAC
Generic GCM mode is described in [GCM]. To set up for AES-GCM use the following process, where K (key) and AAD (additional authenticated data) are as described in [GCM].
Encrypt:
Decrypt:
In pIv the least significant bit of the initialization vector is the rightmost bit. ulIvLen is the length of the initialization vector in bytes.
The tag is appended to the cipher text and the least significant bit of the tag is the rightmost bit and the tag bits are the rightmost ulTagBits bits.
The key type for K must be compatible with CKM_AES_ECB and the C_EncryptInit/C_DecryptInit calls shall behave, with respect to K, as if they were called directly with CKM_AES_ECB, K and NULL parameters.
For IPsec (RFC 4309) and also for use in ZFS encryption. Generic CCM mode is described in [RFC 3610].
To set up for AES-CCM use the following process, where K (key), nonce and additional authenticated data are as described in [RFC 3610].
Encrypt:
Decrypt:
The key type for K must be compatible with CKM_AES_ECB and the C_EncryptInit/C_DecryptInit calls shall behave, with respect to K, as if they were called directly with CKM_AES_ECB, K and NULL parameters.
AES-GMAC, denoted CKM_AES_GMAC, is a mechanism for single and multiple-part signatures and verification. It is described in NIST Special Publication 800-38D [GMAC]. GMAC is a special case of GCM that authenticates only the Additional Authenticated Data (AAD) part of the GCM mechanism parameters. When HMAC is used with C_Sign or C_Verify, pData points to the AAD. HMAC does not use plaintext or ciphertext.
The signature produced by HMAC, also referred to as a Tag, is 16 bytes long.
Its single mechanism parameter is a 12 byte initialization vector (IV).
Constraints on key types and the length of data are summarized in the following table:
Table 61, AES-GMAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_AES |
< 2^64 |
16 bytes |
|
C_Verify |
CKK_AES |
< 2^64 |
16 bytes |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.
¨ CK_GCM_PARAMS; CK_GCM_PARAMS_PTR
CK_GCM_PARAMS is a structure that provides the parameters to the CKM_AES_GCM mechanism. It is defined as follows:
typedef struct CK_GCM_PARAMS {
CK_BYTE_PTR pIv;
CK_ULONG ulIvLen;
CK_BYTE_PTR pAAD;
CK_ULONG ulAADLen;
CK_ULONG ulTagBits;
} CK_GCM_PARAMS;
The fields of the structure have the following meanings:
pIv pointer to initialization vector
ulIvLen length of initialization vector in bytes. The length of the initialization vector can be any number between 1 and 256. 96-bit (12 byte) IV values can be processed more efficiently, so that length is recommended for situations in which efficiency is critical.
pAAD pointer to additional authentication data. This data is authenticated but not encrypted.
ulAADLen length of pAAD in bytes.
ulTagBits length of authentication tag (output following cipher text) in bits. Can be any value between 0 and 128.
CK_GCM_PARAMS_PTR is a pointer to a CK_GCM_PARAMS.
¨ CK_CCM_PARAMS; CK_CCM_PARAMS_PTR
CK_CCM_PARAMS is a structure that provides the parameters to the CKM_AES_CCM mechanism. It is defined as follows:
typedef struct CK_CCM_PARAMS {
CK_ULONG ulDataLen; /*plaintext or ciphertext*/
CK_BYTE_PTR pNonce;
CK_ULONG ulNonceLen;
CK_BYTE_PTR pAAD;
CK_ULONG ulAADLen;
CK_ULONG ulMACLen;
} CK_CCM_PARAMS;
The fields of the structure have the following meanings, where L is the size in bytes of the data length’s length (2 < L < 8):
ulDataLen length of the data where 0 <= ulDataLen < 28L.
pNonce the nonce.
ulNonceLen length of pNonce (<= 15-L) in bytes.
pAAD Additional authentication data. This data is authenticated but not encrypted.
ulAADLen length of pAuthData in bytes.
ulMACLen length of the MAC (output following cipher text) in bytes. Valid values are 4, 6, 8, 10, 12, 14, and 16.
CK_CCM_PARAMS_PTR is a pointer to a CK_CCM_PARAMS.
Generic GCM mode is described in [GCM]. To set up for AES-GCM use the following process, where K (key) and AAD (additional authenticated data) are as described in [GCM].
Encrypt:
Decrypt:
In pIv the least significant bit of the initialization vector is the rightmost bit. ulIvLen is the length of the initialization vector in bytes.
The tag is appended to the cipher text and the least significant bit of the tag is the rightmost bit and the tag bits are the rightmost ulTagBits bits.
The key type for K must be compatible with CKM_AES_ECB and the C_EncryptInit/C_DecryptInit calls shall behave, with respect to K, as if they were called directly with CKM_AES_ECB, K and NULL parameters.
For IPsec (RFC 4309) and also for use in ZFS encryption. Generic CCM mode is described in [RFC 3610].
To set up for AES-CCM use the following process, where K (key), nonce and additional authenticated data are as described in [RFC 3610].
Encrypt:
Decrypt:
The key type for K must be compatible with CKM_AES_ECB and the C_EncryptInit/C_DecryptInit calls shall behave, with respect to K, as if they were called directly with CKM_AES_ECB, K and NULL parameters.
Table 62, Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_AES_CMAC_GENERAL |
|
ü |
|
|
|
|
|
|
CKM_AES_CMAC |
|
ü |
|
|
|
|
|
1 SR = SignRecover, VR = VerifyRecover.
Mechanisms:
CKM_AES_CMAC_GENERAL
CKM_AES_CMAC
CKM_AES_CMAC_GENERAL uses the existing CK_MAC_GENERAL_PARAMS structure. CKM_AES_CMAC does not use a mechanism parameter.
General-length AES-CMAC, denoted CKM_AES_CMAC_GENERAL, is a mechanism for single- and multiple-part signatures and verification, based on [NIST SP800-38B] and [RFC 4493].
It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length desired from the mechanism.
The output bytes from this mechanism are taken from the start of the final AES cipher block produced in the MACing process.
Constraints on key types and the length of data are summarized in the following table:
Table 63, General-length AES-CMAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_AES |
any |
0-block size, as specified in parameters |
|
C_Verify |
CKK_AES |
any |
0-block size, as specified in parameters |
References [NIST SP800-38B] and [RFC 4493] recommend that the output MAC is not truncated to less than 64 bits. The MAC length must be specified before the communication starts, and must not be changed during the lifetime of the key. It is the caller’s responsibility to follow these rules.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.
AES-CMAC, denoted CKM_AES_CMAC, is a special case of the general-length AES-CMAC mechanism. AES-MAC always produces and verifies MACs that are a full block size in length, the default output length specified by [RFC 4493].
Constraints on key types and the length of data are summarized in the following table:
Table 64, AES-CMAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_AES |
any |
Block size (16 bytes) |
|
C_Verify |
CKK_AES |
any |
Block size (16 bytes) |
References [NIST SP800-38B] and [RFC 4493] recommend that the output MAC is not truncated to less than 64 bits. The MAC length must be specified before the communication starts, and must not be changed during the lifetime of the key. It is the caller’s responsibility to follow these rules.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of AES key sizes, in bytes.
Table 65, AES Key Wrap Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_AES_KEY_WRAP |
|
|
|
|
|
ü |
|
|
CKM_AES_KEY_WRAP_PAD |
ü |
|
|
|
|
|
|
|
1SR = SignRecover, VR = VerifyRecover |
Mechanisms:
CKM_AES_KEY_WRAP
CKM_AES_KEY_WRAP_PAD
The mechanisms will accept an optional mechanism parameter as the Initialization vector which, if present, must be a fixed size array of 8 bytes, and, if NULL, will use the default initial value defined in Section <IP_ADDRESS> of [AES KEYWRAP].
The type of this parameter is CK_BYTE_PTR and the pointer points to the array of 8 bytes to be used as the initial value. The length shall be either 0 and the pointer NULL, or 8, and the pointer non-NULL.
The mechanisms support only single-part operations, single part wrapping and unwrapping, and single-part encryption and decryption.
The CKM_AES_KEY_WRAP mechanism can wrap a key of any length. A key whose length is not a multiple of the AES Key Wrap block size (8 bytes) will be zero padded to fit. The CKM_AES_KEY_WRAP mechanism can only encrypt a block of data whose size is an exact multiple of the AES Key Wrap algorithm block size.
The CKM_AES_KEY_WRAP_PAD mechanism can wrap a key or block of data of any length. It does the usual padding of inputs (keys or data blocks) that are not multiples of the AES Key Wrap algorithm block size, always producing wrapped output that is larger than the input key/data to be wrapped. This padding is done by the token before being passed to the AES key wrap algorithm, which adds an 8 byte AES Key Wrap algorithm block of data.
These mechanisms allow derivation of keys using the result of an encryption operation as the key value. They are for use with the C_DeriveKey function.
Table 66, Key derivation by data encryption Mechanisms vs. Functions
Mechanisms:
CKM_DES_ECB_ENCRYPT_DATA
CKM_DES_CBC_ENCRYPT_DATA
CKM_DES3_ECB_ENCRYPT_DATA
CKM_DES3_CBC_ENCRYPT_DATA
CKM_AES_ECB_ENCRYPT_DATA
CKM_AES_CBC_ENCRYPT_DATA
typedef struct CK_DES_CBC_ENCRYPT_DATA_PARAMS {
CK_BYTE iv[8];
CK_BYTE_PTR pData;
CK_ULONG length;
} CK_DES_CBC_ENCRYPT_DATA_PARAMS;
typedef CK_DES_CBC_ENCRYPT_DATA_PARAMS CK_PTR CK_DES_CBC_ENCRYPT_DATA_PARAMS_PTR;
typedef struct CK_AES_CBC_ENCRYPT_DATA_PARAMS {
CK_BYTE iv[16];
CK_BYTE_PTR pData;
CK_ULONG length;
} CK_AES_CBC_ENCRYPT_DATA_PARAMS;
typedef CK_AES_CBC_ENCRYPT_DATA_PARAMS CK_PTR
CK_AES_CBC_ENCRYPT_DATA_PARAMS_PTR;
Uses CK_KEY_DERIVATION_STRING_DATA as defined in section 2.31.2
Table 67, Mechanism Parameters
|
CKM_DES_ECB_ENCRYPT_DATA |
Uses CK_KEY_DERIVATION_STRING_DATA structure. Parameter is the data to be encrypted and must be a multiple of 8 bytes long. |
|
CKM_AES_ECB_ENCRYPT_DATA |
Uses CK_KEY_DERIVATION_STRING_DATA structure. Parameter is the data to be encrypted and must be a multiple of 16 long. |
|
CKM_DES_CBC_ENCRYPT_DATA CKM_DES3_CBC_ENCRYPT_DATA |
Uses CK_DES_CBC_ENCRYPT_DATA_PARAMS. Parameter is an 8 byte IV value followed by the data. The data value part must be a multiple of 8 bytes long. |
|
CKM_AES_CBC_ENCRYPT_DATA |
Uses CK_AES_CBC_ENCRYPT_DATA_PARAMS. Parameter is an 16 byte IV value followed by the data. The data value part must be a multiple of 16 bytes long. |
The mechanisms will function by performing the encryption over the data provided using the base key. The resulting cipher text shall be used to create the key value of the resulting key. If not all the cipher text is used then the part discarded will be from the trailing end (least significant bytes) of the cipher text data. The derived key shall be defined by the attribute template supplied but constrained by the length of cipher text available for the key value and other normal PKCS11 derivation constraints.
Attribute template handling, attribute defaulting and key value preparation will operate as per the SHA-1 Key Derivation mechanism in section 2.18.5.
If the data is too short to make the requested key then the mechanism returns CKR_DATA_LEN_RANGE.
Table 68, Double and Triple-Length DES Mechanisms vs. Functions
This section defines the key type “CKK_DES2” and “CKK_DES3” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.
Mechanisms:
CKM_DES2_KEY_GEN
CKM_DES3_KEY_GEN
CKM_DES3_ECB
CKM_DES3_CBC
CKM_DES3_MAC
CKM_DES3_MAC_GENERAL
CKM_DES3_CBC_PAD
DES2 secret key objects (object class CKO_SECRET_KEY, key type CKK_DES2) hold double-length DES keys. The following table defines the DES2 secret key object attributes, in addition to the common attributes defined for this object class:
Table 69, DES2 Secret Key Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_VALUE1,4,6,7 |
Byte array |
Key value (always 16 bytes long) |
- Refer to [PKCS #11-Base] table 10 for footnotes
DES2 keys must always have their parity bits properly set as described in FIPS PUB 46-3 (i.e., each of the DES keys comprising a DES2 key must have its parity bits properly set). Attempting to create or unwrap a DES2 key with incorrect parity will return an error.
The following is a sample template for creating a double-length DES secret key object:
CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_DES2;
CK_UTF8CHAR label[] = “A DES2 secret key object”;
CK_BYTE value[16] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};
CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three bytes of the ECB encryption of a single block of null (0x00) bytes, using the default cipher associated with the key type of the secret key object.
DES3 secret key objects (object class CKO_SECRET_KEY, key type CKK_DES3) hold triple-length DES keys. The following table defines the DES3 secret key object attributes, in addition to the common attributes defined for this object class:
Table 70, DES3 Secret Key Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_VALUE1,4,6,7 |
Byte array |
Key value (always 24 bytes long) |
- Refer to [PKCS #11-Base] table 10 for footnotes
DES3 keys must always have their parity bits properly set as described in FIPS PUB 46-3 (i.e., each of the DES keys comprising a DES3 key must have its parity bits properly set). Attempting to create or unwrap a DES3 key with incorrect parity will return an error.
The following is a sample template for creating a triple-length DES secret key object:
CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_DES3;
CK_UTF8CHAR label[] = “A DES3 secret key object”;
CK_BYTE value[24] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_ENCRYPT, &true, sizeof(true)},
{CKA_VALUE, value, sizeof(value)}
};
CKA_CHECK_VALUE: The value of this attribute is derived from the key object by taking the first three bytes of the ECB encryption of a single block of null (0x00) bytes, using the default cipher associated with the key type of the secret key object.
The double-length DES key generation mechanism, denoted CKM_DES2_KEY_GEN, is a key generation mechanism for double-length DES keys. The DES keys making up a double-length DES key both have their parity bits set properly, as specified in FIPS PUB 46-3.
It does not have a parameter.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key. Other attributes supported by the double-length DES key type (specifically, the flags indicating which functions the key supports) may be specified in the template for the key, or else are assigned default initial values.
Double-length DES keys can be used with all the same mechanisms as triple-DES keys: CKM_DES3_ECB, CKM_DES3_CBC, CKM_DES3_CBC_PAD, CKM_DES3_MAC_GENERAL, and CKM_DES3_MAC. Triple-DES encryption with a double-length DES key is equivalent to encryption with a triple-length DES key with K1=K3 as specified in FIPS PUB 46-3.
When double-length DES keys are generated, it is token-dependent whether or not it is possible for either of the component DES keys to be “weak” or “semi-weak” keys.
Triple-length DES encryptions are carried out as specified in FIPS PUB 46-3: encrypt, decrypt, encrypt. Decryptions are carried out with the opposite three steps: decrypt, encrypt, decrypt. The mathematical representations of the encrypt and decrypt operations are as follows:
DES3-E({K1,K2,K3}, P) = E(K3, D(K2, E(K1, P)))
DES3-D({K1,K2,K3}, C) = D(K1, E(K2, D(K3, P)))
Triple-length DES operations in CBC mode, with double or triple-length keys, are performed using outer CBC as defined in X9.52. X9.52 describes this mode as TCBC. The mathematical representations of the CBC encrypt and decrypt operations are as follows:
DES3-CBC-E({K1,K2,K3}, P) = E(K3, D(K2, E(K1, P + I)))
DES3-CBC-D({K1,K2,K3}, C) = D(K1, E(K2, D(K3, P))) + I
The value I is either an 8-byte initialization vector or the previous block of cipher text that is added to the current input block. The addition operation is used is addition modulo-2 (XOR).
Table 71, DES and Triple Length DES in OFB Mode Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_DES_OFB64 |
ü |
|
|
|
|
|
|
|
CKM_DES_OFB8 |
ü |
|
|
|
|
|
|
|
CKM_DES_CFB64 |
ü |
|
|
|
|
|
|
|
CKM_DES_CFB8 |
ü |
|
|
|
|
|
|
Cipher DES has a output feedback mode, DES-OFB, denoted CKM_DES_OFB8 and CKM_DES_OFB64. It is a mechanism for single and multiple-part encryption and decryption with DES.
It has a parameter, an initialization vector for this mode. The initialization vector has the same length as the block size.
Constraints on key types and the length of data are summarized in the following table:
Table 72, OFB: Key And Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
CKK_DES, CKK_DES2, CKK_DES3 |
any |
same as input length |
no final part |
|
C_Decrypt |
CKK_DES, CKK_DES2, CKK_DES3 |
any |
same as input length |
no final part |
For this mechanism the CK_MECHANISM_INFO structure is as specified for CBC mode.
Cipher DES has a cipher feedback mode, DES-CFB, denoted CKM_DES_CFB8 and CKM_DES_CFB64. It is a mechanism for single and multiple-part encryption and decryption with DES.
It has a parameter, an initialization vector for this mode. The initialization vector has the same length as the block size.
Constraints on key types and the length of data are summarized in the following table:
Table 73, CFB: Key And Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
CKK_DES, CKK_DES2, CKK_DES3 |
any |
same as input length |
no final part |
|
C_Decrypt |
CKK_DES, CKK_DES2, CKK_DES3 |
any |
same as input length |
no final part |
For this mechanism the CK_MECHANISM_INFO structure is as specified for CBC mode.
Table 74, Double and Triple-length DES CMAC Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_DES3_CMAC_GENERAL |
|
ü |
|
|
|
|
|
|
CKM_DES3_CMAC |
|
ü |
|
|
|
|
|
1 SR = SignRecover, VR = VerifyRecover.
The following additional DES3 mechanisms have been added.
Mechanisms:
CKM_DES3_CMAC_GENERAL
CKM_DES3_CMAC
CKM_DES3_CMAC_GENERAL uses the existing CK_MAC_GENERAL_PARAMS structure. CKM_DES3_CMAC does not use a mechanism parameter.
General-length DES3-CMAC, denoted CKM_DES3_CMAC_GENERAL, is a mechanism for single- and multiple-part signatures and verification with DES3 or DES2 keys, based on [NIST sp800-38b].
It has a parameter, a CK_MAC_GENERAL_PARAMS structure, which specifies the output length desired from the mechanism.
The output bytes from this mechanism are taken from the start of the final DES3 cipher block produced in the MACing process.
Constraints on key types and the length of data are summarized in the following table:
Table 75, General-length DES3-CMAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_DES3 |
any |
0-block size, as specified in parameters |
|
C_Verify |
CKK_DES3 |
any |
0-block size, as specified in parameters |
Reference [NIST sp800-38b] recommends that the output MAC is not truncated to less than 64 bits (which means using the entire block for DES). The MAC length must be specified before the communication starts, and must not be changed during the lifetime of the key. It is the caller’s responsibility to follow these rules.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure are not used
DES3-CMAC, denoted CKM_DES3_CMAC, is a special case of the general-length DES3-CMAC mechanism. DES3-MAC always produces and verifies MACs that are a full block size in length, since the DES3 block length is the minimum output length recommended by [NIST sp800-38b].
Constraints on key types and the length of data are summarized in the following table:
Table 76, DES3-CMAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_DES3 |
any |
Block size (8 bytes) |
|
C_Verify |
CKK_DES3 |
any |
Block size (8 bytes) |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure are not used.
Table 77, SHA-1 Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_SHA_1 |
|
|
|
ü |
|
|
|
|
CKM_SHA_1_HMAC_GENERAL |
|
ü |
|
|
|
|
|
|
CKM_SHA_1_HMAC |
|
ü |
|
|
|
|
|
|
CKM_SHA1_KEY_DERIVATION |
|
|
|
|
|
|
ü |
Mechanisms:
CKM_SHA_1
CKM_SHA_1_HMAC
CKM_SHA_1_HMAC_GENERAL
CKM_SHA1_KEY_DERIVATION
CKK_SHA_1_HMAC
The SHA-1 mechanism, denoted CKM_SHA_1, is a mechanism for message digesting, following the Secure Hash Algorithm with a 160-bit message digest defined in FIPS PUB 180-2.
It does not have a parameter.
Constraints on the length of input and output data are summarized in the following table. For single-part digesting, the data and the digest may begin at the same location in memory.
Table 78, SHA-1: Data Length
|
Function |
Input length |
Digest length |
|
C_Digest |
any |
20 |
The general-length SHA-1-HMAC mechanism, denoted CKM_SHA_1_HMAC_GENERAL, is a mechanism for signatures and verification. It uses the HMAC construction, based on the SHA-1 hash function. The keys it uses are generic secret keys and CKK_SHA_1_HMAC.
It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired output. This length should be in the range 0-20 (the output size of SHA-1 is 20 bytes). Signatures (MACs) produced by this mechanism will be taken from the start of the full 20-byte HMAC output.
Table 79, General-length SHA-1-HMAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
generic secret |
any |
0-20, depending on parameters |
|
C_Verify |
generic secret |
any |
0-20, depending on parameters |
The SHA-1-HMAC mechanism, denoted CKM_SHA_1_HMAC, is a special case of the general-length SHA-1-HMAC mechanism in Section 2.18.3.
It has no parameter, and always produces an output of length 20.
SHA-1 key derivation, denoted CKM_SHA1_KEY_DERIVATION, is a mechanism which provides the capability of deriving a secret key by digesting the value of another secret key with SHA-1.
The value of the base key is digested once, and the result is used to make the value of derived secret key.
· If no length or key type is provided in the template, then the key produced by this mechanism will be a generic secret key. Its length will be 20 bytes (the output size of SHA-1).
· If no key type is provided in the template, but a length is, then the key produced by this mechanism will be a generic secret key of the specified length.
· If no length was provided in the template, but a key type is, then that key type must have a well-defined length. If it does, then the key produced by this mechanism will be of the type specified in the template. If it doesn’t, an error will be returned.
· If both a key type and a length are provided in the template, the length must be compatible with that key type. The key produced by this mechanism will be of the specified type and length.
If a DES, DES2, or CDMF key is derived with this mechanism, the parity bits of the key will be set properly.
If the requested type of key requires more than 20 bytes, such as DES3, an error is generated.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
Table 80, SHA-224 Mechanisms vs. Functions
Mechanisms:
CKM_SHA224
CKM_SHA224_HMAC
CKM_SHA224_HMAC_GENERAL
CKM_SHA224_KEY_DERIVATION
CKK_SHA224_HMAC
The SHA-224 mechanism, denoted CKM_SHA224, is a mechanism for message digesting, following the Secure Hash Algorithm with a 224-bit message digest defined in 0.
It does not have a parameter.
Constraints on the length of input and output data are summarized in the following table. For single-part digesting, the data and the digest may begin at the same location in memory.
Table 81, SHA-224: Data Length
|
Function |
Input length |
Digest length |
|
C_Digest |
any |
28 |
The general-length SHA-224-HMAC mechanism, denoted CKM_SHA224_HMAC_GENERAL, is the same as the general-length SHA-1-HMAC mechanism except that it uses the HMAC construction based on the SHA-224 hash function and length of the output should be in the range 0-28. The keys it uses are generic secret keys and CKK_SHA224_HMAC. FIPS-198 compliant tokens may require the key length to be at least 14 bytes; that is, half the size of the SHA-224 hash output.
It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired output. This length should be in the range 0-28 (the output size of SHA-224 is 28 bytes). FIPS-198 compliant tokens may constrain the output length to be at least 4 or 14 (half the maximum length). Signatures (MACs) produced by this mechanism will be taken from the start of the full 28-byte HMAC output.
Table 82, General-length SHA-224-HMAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
generic secret |
Any |
0-28, depending on parameters |
|
C_Verify |
generic secret |
Any |
0-28, depending on parameters |
The SHA-224-HMAC mechanism, denoted CKM_SHA224_HMAC, is a special case of the general-length SHA-224-HMAC mechanism.
It has no parameter, and always produces an output of length 28.
SHA-224 key derivation, denoted CKM_SHA224_KEY_DERIVATION, is the same as the SHA-1 key derivation mechanism in Section 12.21.5 except that it uses the SHA-224 hash function and the relevant length is 28 bytes.
Table 83, SHA-256 Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_SHA256 |
|
|
|
ü |
|
|
|
|
CKM_SHA256_HMAC_GENERAL |
|
ü |
|
|
|
|
|
|
CKM_SHA256_HMAC |
|
ü |
|
|
|
|
|
|
CKM_SHA256_KEY_DERIVATION |
|
|
|
|
|
|
ü |
Mechanisms:
CKM_SHA256
CKM_SHA256_HMAC
CKM_SHA256_HMAC_GENERAL
CKM_SHA256_KEY_DERIVATION
CKK_SHA256_HMAC
The SHA-256 mechanism, denoted CKM_SHA256, is a mechanism for message digesting, following the Secure Hash Algorithm with a 256-bit message digest defined in FIPS PUB 180-2.
It does not have a parameter.
Constraints on the length of input and output data are summarized in the following table. For single-part digesting, the data and the digest may begin at the same location in memory.
Table 84, SHA-256: Data Length
|
Function |
Input length |
Digest length |
|
C_Digest |
any |
32 |
The general-length SHA-256-HMAC mechanism, denoted CKM_SHA256_HMAC_GENERAL, is the same as the general-length SHA-1-HMAC mechanism in Section 2.18.3, except that it uses the HMAC construction based on the SHA-256 hash function and length of the output should be in the range 0-32. The keys it uses are generic secret keys and CKK_SHA256_HMAC. FIPS-198 compliant tokens may require the key length to be at least 16 bytes; that is, half the size of the SHA-256 hash output.
It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired output. This length should be in the range 0-32 (the output size of SHA-256 is 32 bytes). FIPS-198 compliant tokens may constrain the output length to be at least 4 or 16 (half the maximum length). Signatures (MACs) produced by this mechanism will be taken from the start of the full 32-byte HMAC output.
Table 85, General-length SHA-256-HMAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
generic secret |
Any |
0-32, depending on parameters |
|
C_Verify |
generic secret |
Any |
0-32, depending on parameters |
The SHA-256-HMAC mechanism, denoted CKM_SHA256_HMAC, is a special case of the general-length SHA-256-HMAC mechanism in Section 2.20.3.
It has no parameter, and always produces an output of length 32.
SHA-256 key derivation, denoted CKM_SHA256_KEY_DERIVATION, is the same as the SHA-1 key derivation mechanism in Section 2.18.5, except that it uses the SHA-256 hash function and the relevant length is 32 bytes.
Table 86, SHA-384 Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_SHA384 |
|
|
|
ü |
|
|
|
|
CKM_SHA384_HMAC_GENERAL |
|
ü |
|
|
|
|
|
|
CKM_SHA384_HMAC |
|
ü |
|
|
|
|
|
|
CKM_SHA384_KEY_DERIVATION |
|
|
|
|
|
|
ü |
CKM_SHA384
CKM_SHA384_HMAC
CKM_SHA384_HMAC_GENERAL
CKM_SHA384_KEY_DERIVATION
CKK_SHA384_HMAC
The SHA-384 mechanism, denoted CKM_SHA384, is a mechanism for message digesting, following the Secure Hash Algorithm with a 384-bit message digest defined in FIPS PUB 180-2.
It does not have a parameter.
Constraints on the length of input and output data are summarized in the following table. For single-part digesting, the data and the digest may begin at the same location in memory.
Table 87, SHA-384: Data Length
|
Function |
Input length |
Digest length |
|
C_Digest |
any |
48 |
The general-length SHA-384-HMAC mechanism, denoted CKM_SHA384_HMAC_GENERAL, is the same as the general-length SHA-1-HMAC mechanism in Section 2.18.3, except that it uses the HMAC construction based on the SHA-384 hash function and length of the output should be in the range 0-48.
The SHA-384-HMAC mechanism, denoted CKM_SHA384_HMAC, is a special case of the general-length SHA-384-HMAC mechanism.
It has no parameter, and always produces an output of length 48.
SHA-384 key derivation, denoted CKM_SHA384_KEY_DERIVATION, is the same as the SHA-1 key derivation mechanism in Section 2.18.5, except that it uses the SHA-384 hash function and the relevant length is 48 bytes.
Table 88, SHA-512 Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_SHA512 |
|
|
|
ü |
|
|
|
|
CKM_SHA512_HMAC_GENERAL |
|
ü |
|
|
|
|
|
|
CKM_SHA512_HMAC |
|
ü |
|
|
|
|
|
|
CKM_SHA512_KEY_DERIVATION |
|
|
|
|
|
|
ü |
CKM_SHA512
CKM_SHA512_HMAC
CKM_SHA512_HMAC_GENERAL
CKM_SHA512_KEY_DERIVATION
CKK_SHA512_HMAC
The SHA-512 mechanism, denoted CKM_SHA512, is a mechanism for message digesting, following the Secure Hash Algorithm with a 512-bit message digest defined in FIPS PUB 180-2.
It does not have a parameter.
Constraints on the length of input and output data are summarized in the following table. For single-part digesting, the data and the digest may begin at the same location in memory.
Table 89, SHA-512: Data Length
|
Function |
Input length |
Digest length |
|
C_Digest |
any |
64 |
The general-length SHA-512-HMAC mechanism, denoted CKM_SHA512_HMAC_GENERAL, is the same as the general-length SHA-1-HMAC mechanism in Section 2.18.3, except that it uses the HMAC construction based on the SHA-512 hash function and length of the output should be in the range 0-64.
The SHA-512-HMAC mechanism, denoted CKM_SHA512_HMAC, is a special case of the general-length SHA-512-HMAC mechanism.
It has no parameter, and always produces an output of length 64.
SHA-512 key derivation, denoted CKM_SHA512_KEY_DERIVATION, is the same as the SHA-1 key derivation mechanism in Section 2.18.5, except that it uses the SHA-512 hash function and the relevant length is 64 bytes.
Table 90, SHA-512/224 Mechanisms vs. Functions
|
Mechanism |
Functions |
||||||
|
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
|
CKM_SHA512_224 |
|
|
|
ü |
|
|
|
|
CKM_SHA512_224_HMAC_GENERAL |
|
ü |
|
|
|
|
|
|
CKM_SHA512_224_HMAC |
|
ü |
|
|
|
|
|
|
CKM_SHA512_224_KEY_DERIVATION |
|
|
|
|
|
|
ü |
CKM_SHA512_224
CKM_SHA512_224_HMAC
CKM_SHA512_224_HMAC_GENERAL
CKM_SHA512_224_KEY_DERIVATION
CKK_SHA512_224_HMAC
The SHA-512/224 mechanism, denoted CKM_SHA512_224, is a mechanism for message digesting, following the Secure Hash Algorithm defined in FIPS PUB 180-4, section 5.3.6. It is based on a 512-bit message digest with a distinct initial hash value and truncated to 224 bits. CKM_SHA512_224 is the same as CKM_SHA512_T with a parameter value of 224.
It does not have a parameter.
Constraints on the length of input and output data are summarized in the following table. For single-part digesting, the data and the digest may begin at the same location in memory.
Table 91, SHA-512/224: Data Length
|
Function |
Input length |
Digest length |
|
C_Digest |
any |
28 |
The general-length SHA-512/224-HMAC mechanism, denoted CKM_SHA512_224_HMAC_GENERAL, is the same as the general-length SHA-1-HMAC mechanism in Section 2.18.3, except that it uses the HMAC construction based on the SHA-512/224 hash function and length of the output should be in the range 0-28.
The SHA-512-HMAC mechanism, denoted CKM_SHA512_224_HMAC, is a special case of the general-length SHA-512/224-HMAC mechanism.
It has no parameter, and always produces an output of length 28.
The SHA-512/224 key derivation, denoted CKM_SHA512_224_KEY_DERIVATION, is the same as the SHA-512 key derivation mechanism in section 2.25.5, except that it uses the SHA-512/224 hash function and the relevant length is 28 bytes.
Table 92, SHA-512/256 Mechanisms vs. Functions
|
Mechanism |
Functions |
||||||
|
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
|
CKM_SHA512_256 |
|
|
|
ü |
|
|
|
|
CKM_SHA512_256_HMAC_GENERAL |
|
ü |
|
|
|
|
|
|
CKM_SHA512_256_HMAC |
|
ü |
|
|
|
|
|
|
CKM_SHA512_256_KEY_DERIVATION |
|
|
|
|
|
|
ü |
CKM_SHA512_256
CKM_SHA512_256_HMAC
CKM_SHA512_256_HMAC_GENERAL
CKM_SHA512_256_KEY_DERIVATION
CKK_SHA512_256_HMAC
The SHA-512/256 mechanism, denoted CKM_SHA512_256, is a mechanism for message digesting, following the Secure Hash Algorithm defined in FIPS PUB 180-4, section 5.3.6. It is based on a 512-bit message digest with a distinct initial hash value and truncated to 256 bits. CKM_SHA512_256 is the same as CKM_SHA512_T with a parameter value of 256.
It does not have a parameter.
Constraints on the length of input and output data are summarized in the following table. For single-part digesting, the data and the digest may begin at the same location in memory.
Table 93, SHA-512/256: Data Length
|
Function |
Input length |
Digest length |
|
C_Digest |
any |
32 |
The general-length SHA-512/256-HMAC mechanism, denoted CKM_SHA512_256_HMAC_GENERAL, is the same as the general-length SHA-1-HMAC mechanism in Section 2.18.3, except that it uses the HMAC construction based on the SHA-512/256 hash function and length of the output should be in the range 0-32.
The SHA-512-HMAC mechanism, denoted CKM_SHA512_256_HMAC, is a special case of the general-length SHA-512/256-HMAC mechanism.
It has no parameter, and always produces an output of length 32.
The SHA-512/256 key derivation, denoted CKM_SHA512_256_KEY_DERIVATION, is the same as the SHA-512 key derivation mechanism in section 2.25.5, except that it uses the SHA-512/256 hash function and the relevant length is 32 bytes.
Table 94, SHA-512 / t Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_SHA512_T |
|
|
|
ü |
|
|
|
|
CKM_SHA512_T_HMAC_GENERAL |
|
ü |
|
|
|
|
|
|
CKM_SHA512_T_HMAC |
|
ü |
|
|
|
|
|
|
CKM_SHA512_T_KEY_DERIVATION |
|
|
|
|
|
|
ü |
CKM_SHA512_T
CKM_SHA512_T_HMAC
CKM_SHA512_T_HMAC_GENERAL
CKM_SHA512_T_KEY_DERIVATION
CKK_SHA512_T_HMAC
The SHA-512/t mechanism, denoted CKM_SHA512_T, is a mechanism for message digesting, following the Secure Hash Algorithm defined in FIPS PUB 180-4, section 5.3.6. It is based on a 512-bit message digest with a distinct initial hash value and truncated to t bits.
It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the value of t in bits. The length in bytes of the desired output should be in the range of 0-⌈ t/8⌉, where 0 < t < 512, and t <> 384.
Constraints on the length of input and output data are summarized in the following table. For single-part digesting, the data and the digest may begin at the same location in memory.
Table 95, SHA-512/256: Data Length
|
Function |
Input length |
Digest length |
|
C_Digest |
any |
⌈t/8⌉, where 0 < t < 512, and t <> 384 |
The general-length SHA-512/256-HMAC mechanism, denoted CKM_SHA512_T_HMAC_GENERAL, is the same as the general-length SHA-1-HMAC mechanism in Section 2.18.3, except that it uses the HMAC construction based on the SHA-512/t hash function and length of the output should be in the range 0 – ⌈t/8⌉, where 0 < t < 512, and t <> 384.
The SHA-512-HMAC mechanism, denoted CKM_SHA512_T_HMAC, is a special case of the general-length SHA-512/256-HMAC mechanism.
It has a parameter, a CK_MAC_GENERAL_PARAMS, which holds the value of t in bits. The length in bytes of the desired output should be in the range of 0-⌈t/8⌉, where 0 < t < 512, and t <> 384.
The SHA-512/256 key derivation, denoted CKM_SHA512_T_KEY_DERIVATION, is the same as the SHA-512 key derivation mechanism in section 2.25.5, except that it uses the SHA-512/256 hash function and the relevant length is ⌈t/8⌉ bytes, where 0 < t < 512, and t <> 384.
The mechanisms in this section are for generating keys and IVs for performing password-based encryption. The method used to generate keys and IVs is specified in PKCS #5.
Table 96, PKCS 5 Mechanisms vs. Functions
Mechanisms:
CKM_PBE_SHA1_DES3_EDE_CBC
CKM_PBE_SHA1_DES2_EDE_CBC
CKM_PKCS5_PBKD2
CKM_PBA_SHA1_WITH_SHA1_HMAC
¨ CK_PBE_PARAMS; CK_PBE_PARAMS_PTR
CK_PBE_PARAMS is a structure which provides all of the necessary information required by the CKM_PBE mechanisms (see PKCS #5 and PKCS #12 for information on the PBE generation mechanisms) and the CKM_PBA_SHA1_WITH_SHA1_HMAC mechanism. It is defined as follows:
typedef struct CK_PBE_PARAMS {
CK_BYTE_PTR pInitVector;
CK_UTF8CHAR_PTR pPassword;
CK_ULONG ulPasswordLen;
CK_BYTE_PTR pSalt;
CK_ULONG ulSaltLen;
CK_ULONG ulIteration;
} CK_PBE_PARAMS;
The fields of the structure have the following meanings:
pInitVector pointer to the location that receives the 8-byte initialization vector (IV), if an IV is required;
pPassword points to the password to be used in the PBE key generation;
ulPasswordLen length in bytes of the password information;
pSalt points to the salt to be used in the PBE key generation;
ulSaltLen length in bytes of the salt information;
ulIteration number of iterations required for the generation.
CK_PBE_PARAMS_PTR is a pointer to a CK_PBE_PARAMS.
¨ CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE; CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE_PTR
CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE is used to indicate the Pseudo-Random Function (PRF) used to generate key bits using PKCS #5 PBKDF2. It is defined as follows:
typedef CK_ULONG CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE;
The following PRFs are defined in PKCS #5 v2.1. The following table lists the defined functions.
Table 97, PKCS #5 PBKDF2 Key Generation: Pseudo-random functions
|
PRF Identifier |
Value |
Parameter Type |
|
CKP_PKCS5_PBKD2_HMAC_SHA1 |
0x00000001UL |
No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. |
|
CKP_PKCS5_PBKD2_HMAC_GOSTR3411
|
0x00000002UL
|
This PRF uses GOST R34.11-94 hash to produce secret key value. pPrfData should point to DER-encoded OID, indicating GOSTR34.11-94 parameters. ulPrfDataLen holds encoded OID length in bytes. If pPrfData is set to NULL_PTR, then id-GostR3411-94-CryptoProParamSet parameters will be used (RFC 4357, 11.2), and ulPrfDataLen must be 0. |
|
CKP_PKCS5_PBKD2_HMAC_SHA224 |
0x00000003UL |
No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. |
|
CKP_PKCS5_PBKD2_HMAC_SHA256 |
0x00000004UL |
No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. |
|
CKP_PKCS5_PBKD2_HMAC_SHA384 |
0x00000005UL |
No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. |
|
CKP_PKCS5_PBKD2_HMAC_SHA512 |
0x00000006UL |
No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. |
|
CKP_PKCS5_PBKD2_HMAC_SHA512_224 |
0x00000007UL |
No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. |
|
CKP_PKCS5_PBKD2_HMAC_SHA512_256 |
0x00000008UL |
No Parameter. pPrfData must be NULL and ulPrfDataLen must be zero. |
CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE_PTR is a pointer to a CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE.
¨ CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE; CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE_PTR
CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE is used to indicate the source of the salt value when deriving a key using PKCS #5 PBKDF2. It is defined as follows:
typedef CK_ULONG CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE;
The following salt value sources are defined in PKCS #5
v2.1. The following table lists the defined sources along with the
corresponding data type for the pSaltSourceData field in the CK_PKCS5_PBKD2_PARAMPARAMS2
structure defined below.
Table 98, PKCS #5 PBKDF2 Key Generation: Salt sources
|
Source Identifier |
Value |
Data Type |
|
CKZ_SALT_SPECIFIED |
0x00000001 |
Array of CK_BYTE containing the value of the salt value. |
CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE_PTR is a pointer to a CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE.
¨
CK_PKCS5_PBKD2_PARAMSPARAMS2; CK_PKCS5_PBKD2_PARAMSPARAMS2_PTR
CK_PKCS5_PBKD2_PARAMSPARAMS2 is a structure
that provides the parameters to the CKM_PKCS5_PBKD2 mechanism. The
structure is defined as follows:
typedef struct CK_PKCS5_PBKD2_PARAMSPARAMS2 {
CK_PKCS5_PBKDF2_SALT_SOURCE_TYPE saltSource;
CK_VOID_PTR pSaltSourceData;
CK_ULONG ulSaltSourceDataLen;
CK_ULONG iterations;
CK_PKCS5_PBKD2_PSEUDO_RANDOM_FUNCTION_TYPE prf;
CK_VOID_PTR pPrfData;
CK_ULONG ulPrfDataLen;
CK_UTF8CHAR_PTR pPassword;
CK_ULONG_PTRulPasswordLen;
} CK_PKCS5_PBKD2_PARAMSPARAMS2;
The fields of the structure have the following meanings:
saltSource source of the salt value
pSaltSourceData data used as the input for the salt source
ulSaltSourceDataLen length of the salt source input
iterations number of iterations to perform when generating each block of random data
prf pseudo-random function used to generate the key
pPrfData data used as the input for PRF in addition to the salt value
ulPrfDataLen length of the input data for the PRF
pPassword points to the password to be used in the PBE key generation
ulPasswordLen length in bytes of the password information
CK_PKCS5_PBKD2_PARAMSPARAMS2_PTR is a pointer to a CK_PKCS5_PBKD2_PARAMSPARAMS2.
PKCS #5 PBKDF2 key generation, denoted CKM_PKCS5_PBKD2, is a mechanism used for generating a secret key from a password and a salt value. This functionality is defined in PKCS#5 as PBKDF2.
It has a parameter, a CK_PKCS5_PBKD2_PARAMSPARAMS2 structure.
The parameter specifies the salt value source, pseudo-random function, and
iteration count used to generate the new key.
Since this mechanism can be used to generate any type of secret key, new key templates must contain the CKA_KEY_TYPE and CKA_VALUE_LEN attributes. If the key type has a fixed length the CKA_VALUE_LEN attribute may be omitted.
The mechanisms in this section are for generating keys and IVs for performing password-based encryption or authentication. The method used to generate keys and IVs is based on a method that was specified in PKCS #12.
We specify here a general method for producing various types of pseudo-random bits from a password, p; a string of salt bits, s; and an iteration count, c. The “type” of pseudo-random bits to be produced is identified by an identification byte, ID, the meaning of which will be discussed later.
Let H be a hash function built around a compression function f: Z2u ´ Z2v ® Z2u (that is, H has a chaining variable and output of length u bits, and the message input to the compression function of H is v bits). For MD2 and MD5, u=128 and v=512; for SHA-1, u=160 and v=512.
We assume here that u and v are both multiples of 8, as are the lengths in bits of the password and salt strings and the number n of pseudo-random bits required.
1. Construct a string, D (the “diversifier”), by concatenating v/8 copies of ID.
2. Concatenate copies of the salt together to create a string S of length v×és/vù bits (the final copy of the salt may be truncated to create S). Note that if the salt is the empty string, then so is S.
3. Concatenate copies of the password together to create a string P of length v×ép/vù bits (the final copy of the password may be truncated to create P). Note that if the password is the empty string, then so is P.
4. Set I=S||P to be the concatenation of S and P.
5. Set j=én/uù.
6. For i=1, 2, …, j, do the following:
a. Set Ai=Hc(D||I), the cth hash of D||I. That is, compute the hash of D||I; compute the hash of that hash; etc.; continue in this fashion until a total of c hashes have been computed, each on the result of the previous hash.
b. Concatenate copies of Ai to create a string B of length v bits (the final copy of Ai may be truncated to create B).
c. Treating I as a concatenation I0, I1, …, Ik-1 of v-bit blocks, where k=és/vù+ép/vù, modify I by setting Ij=(Ij+B+1) mod 2v for each j. To perform this addition, treat each v-bit block as a binary number represented most-significant bit first.
7. Concatenate A1, A2, …, Aj together to form a pseudo-random bit string, A.
8. Use the first n bits of A as the output of this entire process.
When the password-based encryption mechanisms presented in this section are used to generate a key and IV (if needed) from a password, salt, and an iteration count, the above algorithm is used. To generate a key, the identifier byte ID is set to the value 1; to generate an IV, the identifier byte ID is set to the value 2.
When the password based authentication mechanism presented in this section is used to generate a key from a password, salt, and an iteration count, the above algorithm is used. The identifier byte ID is set to the value 3.
SHA-1-PBE for 3-key triple-DES-CBC, denoted CKM_PBE_SHA1_DES3_EDE_CBC, is a mechanism used for generating a 3-key triple-DES secret key and IV from a password and a salt value by using the SHA-1 digest algorithm and an iteration count. The method used to generate the key and IV is described above. Each byte of the key produced will have its low-order bit adjusted, if necessary, so that a valid 3-key triple-DES key with proper parity bits is obtained.
It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the key generation process and the location of the application-supplied buffer which will receive the 8-byte IV generated by the mechanism.
SHA-1-PBE for 2-key triple-DES-CBC, denoted CKM_PBE_SHA1_DES2_EDE_CBC, is a mechanism used for generating a 2-key triple-DES secret key and IV from a password and a salt value by using the SHA-1 digest algorithm and an iteration count. The method used to generate the key and IV is described above. Each byte of the key produced will have its low-order bit adjusted, if necessary, so that a valid 2-key triple-DES key with proper parity bits is obtained.
It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the key generation process and the location of the application-supplied buffer which will receive the 8-byte IV generated by the mechanism.
SHA-1-PBA for SHA-1-HMAC, denoted CKM_PBA_SHA1_WITH_SHA1_HMAC, is a mechanism used for generating a 160-bit generic secret key from a password and a salt value by using the SHA-1 digest algorithm and an iteration count. The method used to generate the key is described above.
It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the key generation process. The parameter also has a field to hold the location of an application-supplied buffer which will receive an IV; for this mechanism, the contents of this field are ignored, since authentication with SHA-1-HMAC does not require an IV.
The key generated by this mechanism will typically be used for computing a SHA-1 HMAC to perform password-based authentication (not password-based encryption). At the time of this writing, this is primarily done to ensure the integrity of a PKCS #12 PDU.
Table 99,SSL Mechanisms vs. Functions
|
Mechanism |
Functions |
||||||
|
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
|
CKM_SSL3_PRE_MASTER_KEY_GEN |
|
|
|
|
ü |
|
|
|
CKM_SSL3_MASTER_KEY_DERIVE |
|
|
|
|
|
|
ü |
|
CKM_SSL3_MASTER_KEY_DERIVE_DH |
|
|
|
|
|
|
ü |
|
CKM_SSL3_KEY_AND_MAC_DERIVE |
|
|
|
|
|
|
ü |
|
CKM_SSL3_MD5_MAC |
|
ü |
|
|
|
|
|
|
CKM_SSL3_SHA1_MAC |
|
ü |
|
|
|
|
|
Mechanisms:
CKM_SSL3_PRE_MASTER_KEY_GEN
CKM_SSL3_MASTER_KEY_DERIVE
CKM_SSL3_KEY_AND_MAC_DERIVE
CKM_SSL3_MASTER_KEY_DERIVE_DH
CKM_SSL3_MD5_MAC
CKM_SSL3_SHA1_MAC
¨ CK_SSL3_RANDOM_DATA
CK_SSL3_RANDOM_DATA is a structure which provides information about the random data of a client and a server in an SSL context. This structure is used by both the CKM_SSL3_MASTER_KEY_DERIVE and the CKM_SSL3_KEY_AND_MAC_DERIVE mechanisms. It is defined as follows:
typedef struct CK_SSL3_RANDOM_DATA {
CK_BYTE_PTR pClientRandom;
CK_ULONG ulClientRandomLen;
CK_BYTE_PTR pServerRandom;
CK_ULONG ulServerRandomLen;
} CK_SSL3_RANDOM_DATA;
The fields of the structure have the following meanings:
pClientRandom pointer to the client’s random data
ulClientRandomLen length in bytes of the client’s random data
pServerRandom pointer to the server’s random data
ulServerRandomLen length in bytes of the server’s random data
¨ CK_SSL3_MASTER_KEY_DERIVE_PARAMS; CK_SSL3_MASTER_KEY_DERIVE_PARAMS_PTR
CK_SSL3_MASTER_KEY_DERIVE_PARAMS is a structure that provides the parameters to the CKM_SSL3_MASTER_KEY_DERIVE mechanism. It is defined as follows:
typedef struct CK_SSL3_MASTER_KEY_DERIVE_PARAMS {
CK_SSL3_RANDOM_DATA RandomInfo;
CK_VERSION_PTR pVersion;
} CK_SSL3_MASTER_KEY_DERIVE_PARAMS;
The fields of the structure have the following meanings:
RandomInfo client’s and server’s random data information.
pVersion pointer to a CK_VERSION structure which receives the SSL protocol version information
CK_SSL3_MASTER_KEY_DERIVE_PARAMS_PTR is a pointer to a CK_SSL3_MASTER_KEY_DERIVE_PARAMS.
¨ CK_SSL3_KEY_MAT_OUT; CK_SSL3_KEY_MAT_OUT_PTR
CK_SSL3_KEY_MAT_OUT is a structure that contains the resulting key handles and initialization vectors after performing a C_DeriveKey function with the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. It is defined as follows:
typedef struct CK_SSL3_KEY_MAT_OUT {
CK_OBJECT_HANDLE hClientMacSecret;
CK_OBJECT_HANDLE hServerMacSecret;
CK_OBJECT_HANDLE hClientKey;
CK_OBJECT_HANDLE hServerKey;
CK_BYTE_PTR pIVClient;
CK_BYTE_PTR pIVServer;
} CK_SSL3_KEY_MAT_OUT;
The fields of the structure have the following meanings:
hClientMacSecret key handle for the resulting Client MAC Secret key
hServerMacSecret key handle for the resulting Server MAC Secret key
hClientKey key handle for the resulting Client Secret key
hServerKey key handle for the resulting Server Secret key
pIVClient pointer to a location which receives the initialization vector (IV) created for the client (if any)
pIVServer pointer to a location which receives the initialization vector (IV) created for the server (if any)
CK_SSL3_KEY_MAT_OUT_PTR is a pointer to a CK_SSL3_KEY_MAT_OUT.
¨ CK_SSL3_KEY_MAT_PARAMS; CK_SSL3_KEY_MAT_PARAMS_PTR
CK_SSL3_KEY_MAT_PARAMS is a structure that provides the parameters to the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. It is defined as follows:
typedef struct CK_SSL3_KEY_MAT_PARAMS {
CK_ULONG ulMacSizeInBits;
CK_ULONG ulKeySizeInBits;
CK_ULONG ulIVSizeInBits;
CK_BBOOL bIsExport;
CK_SSL3_RANDOM_DATA RandomInfo;
CK_SSL3_KEY_MAT_OUT_PTR pReturnedKeyMaterial;
} CK_SSL3_KEY_MAT_PARAMS;
The fields of the structure have the following meanings:
ulMacSizeInBits the length (in bits) of the MACing keys agreed upon during the protocol handshake phase
ulKeySizeInBits the length (in bits) of the secret keys agreed upon during the protocol handshake phase
ulIVSizeInBits the length (in bits) of the IV agreed upon during the protocol handshake phase. If no IV is required, the length should be set to 0
bIsExport a Boolean value which indicates whether the keys have to be derived for an export version of the protocol
RandomInfo client’s and server’s random data information.
pReturnedKeyMaterial points to a CK_SSL3_KEY_MAT_OUT structures which receives the handles for the keys generated and the IVs
CK_SSL3_KEY_MAT_PARAMS_PTR is a pointer to a CK_SSL3_KEY_MAT_PARAMS.
Pre-master key generation in SSL 3.0, denoted CKM_SSL3_PRE_MASTER_KEY_GEN, is a mechanism which generates a 48-byte generic secret key. It is used to produce the "pre_master" key used in SSL version 3.0 for RSA-like cipher suites.
It has one parameter, a CK_VERSION structure, which provides the client’s SSL version number.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may be specified in the template, or else are assigned default values.
The template sent along with this mechanism during a C_GenerateKey call may indicate that the object class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to specify any of them.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure both indicate 48 bytes.
Master key derivation in SSL 3.0, denoted CKM_SSL3_MASTER_KEY_DERIVE, is a mechanism used to derive one 48-byte generic secret key from another 48-byte generic secret key. It is used to produce the "master_secret" key used in the SSL protocol from the "pre_master" key. This mechanism returns the value of the client version, which is built into the "pre_master" key as well as a handle to the derived "master_secret" key.
It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the passing of random data to the token as well as the returning of the protocol version number which is part of the pre-master key. This structure is defined in Section 2.28.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may be specified in the template; otherwise they are assigned default values.
The template sent along with this mechanism during a C_DeriveKey call may indicate that the object class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to specify any of them.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure both indicate 48 bytes.
Note that the CK_VERSION structure pointed to by the CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure’s pVersion field will be modified by the C_DeriveKey call. In particular, when the call returns, this structure will hold the SSL version associated with the supplied pre_master key.
Note that this mechanism is only useable for cipher suites that use a 48-byte “pre_master” secret with an embedded version number. This includes the RSA cipher suites, but excludes the Diffie-Hellman cipher suites.
Master key derivation for Diffie-Hellman in SSL 3.0, denoted CKM_SSL3_MASTER_KEY_DERIVE_DH, is a mechanism used to derive one 48-byte generic secret key from another arbitrary length generic secret key. It is used to produce the "master_secret" key used in the SSL protocol from the "pre_master" key.
It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the passing of random data to the token. This structure is defined in Section 2.28. The pVersion field of the structure must be set to NULL_PTR since the version number is not embedded in the "pre_master" key as it is for RSA-like cipher suites.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may be specified in the template, or else are assigned default values.
The template sent along with this mechanism during a C_DeriveKey call may indicate that the object class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to specify any of them.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure both indicate 48 bytes.
Note that this mechanism is only useable for cipher suites that do not use a fixed length 48-byte “pre_master” secret with an embedded version number. This includes the Diffie-Hellman cipher suites, but excludes the RSA cipher suites.
Key, MAC and IV derivation in SSL 3.0, denoted CKM_SSL3_KEY_AND_MAC_DERIVE, is a mechanism used to derive the appropriate cryptographic keying material used by a "CipherSuite" from the "master_secret" key and random data. This mechanism returns the key handles for the keys generated in the process, as well as the IVs created.
It has a parameter, a CK_SSL3_KEY_MAT_PARAMS structure, which allows for the passing of random data as well as the characteristic of the cryptographic material for the given CipherSuite and a pointer to a structure which receives the handles and IVs which were generated. This structure is defined in Section 2.28.
This mechanism contributes to the creation of four distinct keys on the token and returns two IVs (if IVs are requested by the caller) back to the caller. The keys are all given an object class of CKO_SECRET_KEY.
The two MACing keys ("client_write_MAC_secret" and "server_write_MAC_secret") are always given a type of CKK_GENERIC_SECRET. They are flagged as valid for signing, verification, and derivation operations.
The other two keys ("client_write_key" and "server_write_key") are typed according to information found in the template sent along with this mechanism during a C_DeriveKey function call. By default, they are flagged as valid for encryption, decryption, and derivation operations.
IVs will be generated and returned if the ulIVSizeInBits field of the CK_SSL3_KEY_MAT_PARAMS field has a nonzero value. If they are generated, their length in bits will agree with the value in the ulIVSizeInBits field.
All four keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template provided to C_DeriveKey may not specify values for any of these attributes which differ from those held by the base key.
Note that the CK_SSL3_KEY_MAT_OUT structure pointed to by the CK_SSL3_KEY_MAT_PARAMS structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the four key handle fields in the CK_SSL3_KEY_MAT_OUT structure will be modified to hold handles to the newly-created keys; in addition, the buffers pointed to by the CK_SSL3_KEY_MAT_OUT structure’s pIVClient and pIVServer fields will have IVs returned in them (if IVs are requested by the caller). Therefore, these two fields must point to buffers with sufficient space to hold any IVs that will be returned.
This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result of a successful completion. However, since the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism returns all of its key handles in the CK_SSL3_KEY_MAT_OUT structure pointed to by the CK_SSL3_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey passed to C_DeriveKey is unnecessary, and should be a NULL_PTR.
If a call to C_DeriveKey with this mechanism fails, then none of the four keys will be created on the token.
MD5 MACing in SSL3.0, denoted CKM_SSL3_MD5_MAC, is a mechanism for single- and multiple-part signatures (data authentication) and verification using MD5, based on the SSL 3.0 protocol. This technique is very similar to the HMAC technique.
It has a parameter, a CK_MAC_GENERAL_PARAMS, which specifies the length in bytes of the signatures produced by this mechanism.
Constraints on key types and the length of input and output data are summarized in the following table:
Table 100, MD5 MACing in SSL 3.0: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
generic secret |
any |
4-8, depending on parameters |
|
C_Verify |
generic secret |
any |
4-8, depending on parameters |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of generic secret key sizes, in bits.
SHA-1 MACing in SSL3.0, denoted CKM_SSL3_SHA1_MAC, is a mechanism for single- and multiple-part signatures (data authentication) and verification using SHA-1, based on the SSL 3.0 protocol. This technique is very similar to the HMAC technique.
It has a parameter, a CK_MAC_GENERAL_PARAMS, which specifies the length in bytes of the signatures produced by this mechanism.
Constraints on key types and the length of input and output data are summarized in the following table:
Table 101, SHA-1 MACing in SSL 3.0: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
generic secret |
any |
4-8, depending on parameters |
|
C_Verify |
generic secret |
any |
4-8, depending on parameters |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of generic secret key sizes, in bits.
Details for TLS 1.2 and its key derivation and MAC mechanisms can be found in [TLS 1.2]. TLS 1.2 mechanisms differ from TLS 1.0 and 1.1 mechanisms in that the base hash used in the underlying TLS PRF (pseudo-random function) can be negotiated. Therefore each mechanism parameter for the TLS 1.2 mechanisms contains a new value in the parameters structure to specify the hash function.
This section also specifies CKM_TLS_MAC which should be used in place of CKM_TLS_PRF to calculate the verify_data in the TLS "finished" message.
This section also specifies CKM_TLS_KDF that can be used in place of CKM_TLS_PRF to implement key material exporters.
 It is defined as follows:
typedef struct CK_TLS12_MASTER_KEY_DERIVE_PARAMS {
CK_SSL3_RANDOM_DATA RandomInfo;
CK_VERSION_PTR pVersion;
CK_MECHANISM_TYPE prfHashMechanism;
} CK_TLS12_MASTER_KEY_DERIVE_PARAMS;
The fields of the structure have the following meanings:
RandomInfo client’s and server’s random data information.
pVersion pointer to a CK_VERSION structure which receives the SSL protocol version information
prfHashMechanism base hash used in the underlying TLS1.2 PRF operation used to derive the master key.
CK_TLS12_MASTER_KEY_DERIVE_PARAMS_PTR is a pointer to a CK_TLS12_MASTER_KEY_DERIVE_PARAMS.
¨ CK_TLS12_KEY_MAT_PARAMS; CK_TLS12_KEY_MAT_PARAMS_PTR
CK_TLS12_KEY_MAT_PARAMS is a structure that provides the parameters to the CKM_TLS12_KEY_AND_MAC_DERIVE mechanism. It is defined as follows:
typedef struct CK_TLS12_KEY_MAT_PARAMS {
CK_ULONG ulMacSizeInBits;
CK_ULONG ulKeySizeInBits;
CK_ULONG ulIVSizeInBits;
CK_BBOOL bIsExport;
CK_SSL3_RANDOM_DATA RandomInfo;
CK_SSL3_KEY_MAT_OUT_PTR pReturnedKeyMaterial;
CK_MECHANISM_TYPE prfHashMechanism;
} CK_TLS12_KEY_MAT_PARAMS;
The fields of the structure have the following meanings:
ulMacSizeInBits the length (in bits) of the MACing keys agreed upon during the protocol handshake phase. If no MAC key is required, the length should be set to 0.
ulKeySizeInBits the length (in bits) of the secret keys agreed upon during the protocol handshake phase
ulIVSizeInBits the length (in bits) of the IV agreed upon during the protocol handshake phase. If no IV is required, the length should be set to 0
bIsExport must be set to CK_FALSE because export cipher suites must not be used in TLS 1.1 and later.
RandomInfo client’s and server’s random data information.
pReturnedKeyMaterial points to a CK_SSL3_KEY_MAT_OUT structures which receives the handles for the keys generated and the IVs
prfHashMechanism base hash used in the underlying TLS1.2 PRF operation used to derive the master key.
CK_TLS12_KEY_MAT_PARAMS_PTR is a pointer to a CK_TLS12_KEY_MAT_PARAMS.
¨ CK_TLS_KDF_PARAMS; CK_TLS_KDF_PARAMS_PTR
CK_TLS_KDF_PARAMS is a structure that provides the parameters to the CKM_TLS_KDF mechanism. It is defined as follows:
typedef struct CK_TLS_KDF_PARAMS {
CK_MECHANISM_TYPE prfMechanism;
CK_BYTE_PTR pLabel;
CK_ULONG ulLabelLength;
CK_SSL3_RANDOM_DATA RandomInfo;
CK_BYTE_PTR pContextData;
CK_ULONG ulContextDataLength;
} CK_TLS_KDF_PARAMS;
The fields of the structure have the following meanings:
prfMechanism the hash mechanism used in the TLS1.2 PRF construct or CKM_TLS_PRF to use with the TLS1.0 and 1.1 PRF construct.
pLabel a pointer to the label for this key derivation
ulLabelLength length of the label in bytes
RandomInfo the random data for the key derivation
pContextData a pointer to the context data for this key derivation. NULL_PTR if not present
ulContextDataLength length of the context data in bytes. 0 if not present.
¨ CK_TLS_MAC_PARAMS; CK_TLS_MAC_PARAMS_PTR
CK_TLS_MAC_PARAMS is a structure that provides the parameters to the CKM_TLS_MAC mechanism. It is defined as follows:
typedef struct CK_TLS_MAC_PARAMS {
CK_MECHANISM_TYPE prfMechanism;
CK_ULONG ulMacLength;
CK_ULONG ulServerOrClient;
} CK_TLS_MAC_PARAMS;
The fields of the structure have the following meanings:
prfMechanism the hash mechanism used in the TLS12 PRF construct or CKM_TLS_PRF to use with the TLS1.0 and 1.1 PRF construct.
ulMacLength the length of the MAC tag required or offered. Always 12 octets in TLS 1.0 and 1.1. Generally 12 octets, but may be negotiated to a longer value in TLS1.2.
ulServerOrClient 1 to use the label "server finished", 2 to use the label "client finished". All other values are invalid.
CK_TLS_MAC_PARAMS_PTR is a pointer to a CK_TLS_MAC_PARAMS.
The TLS MAC mechanism is used to generate integrity tags for the TLS "finished" message. It replaces the use of the CKM_TLS_PRF function for TLS1.0 and 1.1 and that mechanism is deprecated.
CKM_TLS_MAC takes a parameter of CK_TLS_MAC_PARAMS. To use this mechanism with TLS1.0 and TLS1.1, use CKM_TLS_PRF as the value for prfMechanism in place of a hash mechanism. Note: Although CKM_TLS_PRF is deprecated as a mechanism for C_DeriveKey, the manifest value is retained for use with this mechanism to indicate the use of the TLS1.0/1.1 pseudo-random function.
In TLS1.0 and 1.1 the "finished" message verify_data (i.e. the output signature from the MAC mechanism) is always 12 bytes. In TLS1.2 the "finished" message verify_data is a minimum of 12 bytes, defaults to 12 bytes, but may be negotiated to longer length.
Table 103, General-length TLS MAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
generic secret |
any |
>=12 bytes |
|
C_Verify |
generic secret |
any |
>=12 bytes |
Master key derivation in TLS 1.0, denoted CKM_TLS_MASTER_KEY_DERIVE, is a mechanism used to derive one 48-byte generic secret key from another 48-byte generic secret key. It is used to produce the "master_secret" key used in the TLS protocol from the "pre_master" key. This mechanism returns the value of the client version, which is built into the "pre_master" key as well as a handle to the derived "master_secret" key.
It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the passing of random data to the token as well as the returning of the protocol version number which is part of the pre-master key. This structure is defined in Section 2.28.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may be specified in the template, or else are assigned default values.
The mechanism also contributes the CKA_ALLOWED_MECHANISMS attribute consisting only of CKM_TLS12_KEY_AND_MAC_DERIVE, CKM_TLS12_KEY_SAFE_DERIVE, CKM_TLS12_KDF and CKM_TLS12_MAC.
The template sent along with this mechanism during a C_DeriveKey call may indicate that the object class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to specify any of them.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure both indicate 48 bytes.
Note that the CK_VERSION structure pointed to by the CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure’s pVersion field will be modified by the C_DeriveKey call. In particular, when the call returns, this structure will hold the SSL version associated with the supplied pre_master key.
Note that this mechanism is only useable for cipher suites that use a 48-byte “pre_master” secret with an embedded version number. This includes the RSA cipher suites, but excludes the Diffie-Hellman cipher suites.
Master key derivation for Diffie-Hellman in TLS 1.0, denoted CKM_TLS_MASTER_KEY_DERIVE_DH, is a mechanism used to derive one 48-byte generic secret key from another arbitrary length generic secret key. It is used to produce the "master_secret" key used in the TLS protocol from the "pre_master" key.
It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the passing of random data to the token. This structure is defined in Section 2.28. The pVersion field of the structure must be set to NULL_PTR since the version number is not embedded in the "pre_master" key as it is for RSA-like cipher suites.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may be specified in the template, or else are assigned default values.
The mechanism also contributes the CKA_ALLOWED_MECHANISMS attribute consisting only of CKM_TLS12_KEY_AND_MAC_DERIVE, CKM_TLS12_KEY_SAFE_DERIVE, CKM_TLS12_KDF and CKM_TLS12_MAC.
The template sent along with this mechanism during a C_DeriveKey call may indicate that the object class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to specify any of them.
This mechanism has the following rules about key sensitivity and extractability:
· The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.
· If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, then the derived key will as well. If the base key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE, then the derived key has its CKA_ALWAYS_SENSITIVE attribute set to the same value as its CKA_SENSITIVE attribute.
· Similarly, if the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE, then the derived key will, too. If the base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE, then the derived key has its CKA_NEVER_EXTRACTABLE attribute set to the opposite value from its CKA_EXTRACTABLE attribute.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure both indicate 48 bytes.
Note that this mechanism is only useable for cipher suites that do not use a fixed length 48-byte “pre_master” secret with an embedded version number. This includes the Diffie-Hellman cipher suites, but excludes the RSA cipher suites.
Key, MAC and IV derivation in TLS 1.0, denoted CKM_TLS_KEY_AND_MAC_DERIVE, is a mechanism used to derive the appropriate cryptographic keying material used by a "CipherSuite" from the "master_secret" key and random data. This mechanism returns the key handles for the keys generated in the process, as well as the IVs created.
It has a parameter, a CK_SSL3_KEY_MAT_PARAMS structure, which allows for the passing of random data as well as the characteristic of the cryptographic material for the given CipherSuite and a pointer to a structure which receives the handles and IVs which were generated. This structure is defined in Section 2.28.
This mechanism contributes to the creation of four distinct keys on the token and returns two IVs (if IVs are requested by the caller) back to the caller. The keys are all given an object class of CKO_SECRET_KEY.
The two MACing keys ("client_write_MAC_secret" and "server_write_MAC_secret") (if present) are always given a type of CKK_GENERIC_SECRET. They are flagged as valid for signing and verification.
The other two keys ("client_write_key" and "server_write_key") are typed according to information found in the template sent along with this mechanism during a C_DeriveKey function call. By default, they are flagged as valid for encryption, decryption, and derivation operations.
For CKM_TLS12_KEY_AND_MAC_DERIVE, IVs will be generated and returned if the ulIVSizeInBits field of the CK_SSL3_KEY_MAT_PARAMS field has a nonzero value. If they are generated, their length in bits will agree with the value in the ulIVSizeInBits field.
Note Well: CKM_TLS12_KEY_AND_MAC_DERIVE produces both private (key) and public (IV) data. It is possible to "leak" private data by the simple expedient of decreasing the length of private data requested. E.g. Setting ulMacSizeInBits and ulKeySizeInBits to 0 (or other lengths less than the key size) will result in the private key data being placed in the destination designated for the IV's. Repeated calls with the same master key and same RandomInfo but with differing lengths for the private key material will result in different data being leaked.<
All four keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template provided to C_DeriveKey may not specify values for any of these attributes which differ from those held by the base key.
Note that the CK_SSL3_KEY_MAT_OUT structure pointed to by the CK_SSL3_KEY_MAT_PARAMS structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the four key handle fields in the CK_SSL3_KEY_MAT_OUT structure will be modified to hold handles to the newly-created keys; in addition, the buffers pointed to by the CK_SSL3_KEY_MAT_OUT structure’s pIVClient and pIVServer fields will have IVs returned in them (if IVs are requested by the caller). Therefore, these two fields must point to buffers with sufficient space to hold any IVs that will be returned.
This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. For most key-derivation mechanisms, C_DeriveKey returns a single key handle as a result of a successful completion. However, since the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism returns all of its key handles in the CK_SSL3_KEY_MAT_OUT structure pointed to by the CK_SSL3_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey passed to C_DeriveKey is unnecessary, and should be a NULL_PTR.
If a call to C_DeriveKey with this mechanism fails, then none of the four keys will be created on the token.
CKM_TLS12_KEY_SAFE_DERIVE is identical to CKM_TLS12_KEY_AND_MAC_DERIVE except that it shall never produce IV data, and the ulIvSizeInBits field of CK_TLS12_KEY_MAT_PARAMS is ignored and treated as 0.
CKM_TLS12_KEY_SAFE_DERIVE is provided as a separate mechanism to allow a client to control the export of IV material (and possible leaking of key material) through the use of the CKA_ALLOWED_MECHANISMS key attribute.
CKM_TLS_KDF is the mechanism defined in RFC5705. It uses the TLS key material and TLS PRF function to produce additional key material for protocols that want to leverage the TLS key negotiation mechanism. CKM_TLS_KDF has a parameter of CK_TLS_KDF_PARAMS. If the protocol using this mechanism does not use context information, the pContextData field shall be set to NULL_PTR and the ulContextDataLength field shall be set to 0.
To use this mechanism with TLS1.0 and TLS1.1, use CKM_TLS_PRF as the value for prfMechanism in place of a hash mechanism. Note: Although CKM_TLS_PRF is deprecated as a mechanism for C_DeriveKey, the manifest value is retained for use with this mechanism to indicate the use of the TLS1.0/1.1 Pseudo-random function.
This mechanism can be used to derive multiple keys (e.g. similar to CKM_TLS12_KEY_AND_MAC_DERIVE) by first deriving the key stream as a CKK_GENERIC_SECRET of the necessary length and doing subsequent derives against that derived key stream using the CKM_EXTRACT_KEY_FROM_KEY mechanism to split the key stream into the actual operational keys.
The mechanism should not be used with the labels defined for use with TLS, but the token does not enforce this behavior.
This mechanism has the following rules about key sensitivity and extractability:
· If the original key has its CKA_SENSITIVE attribute set to CK_TRUE, so does the derived key. If not, then the derived key’s CKA_SENSITIVE attribute is set either from the supplied template or from the original key.
· Similarly, if the original key has its CKA_EXTRACTABLE attribute set to CK_FALSE, so does the derived key. If not, then the derived key’s CKA_EXTRACTABLE attribute is set either from the supplied template or from the original key.
· The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the original key has its CKA_ALWAYS_SENSITIVE attribute set to CK_TRUE.
· Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if the original key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
Details can be found in [WTLS].
When comparing the existing TLS mechanisms with these extensions to support WTLS one could argue that there would be no need to have distinct handling of the client and server side of the handshake. However, since in WTLS the server and client use different sequence numbers, there could be instances (e.g. when WTLS is used to protect asynchronous protocols) where sequence numbers on the client and server side differ, and hence this motivates the introduced split.
Table 104, WTLS Mechanisms vs. Functions
|
Mechanism |
Functions |
||||||
|
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
|
CKM_WTLS_PRE_MASTER_KEY_GEN |
|
|
|
|
ü |
|
|
|
CKM_WTLS_MASTER_KEY_DERIVE |
|
|
|
|
|
|
ü |
|
CKM_WTLS_MASTER_KEY_DERIVE_DH_ECC |
|
|
|
|
|
|
ü |
|
CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE |
|
|
|
|
|
|
ü |
|
CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE |
|
|
|
|
|
|
ü |
|
CKM_WTLS_PRF |
|
|
|
|
|
|
ü |
Mechanisms:
CKM_WTLS_PRE_MASTER_KEY_GEN
CKM_WTLS_MASTER_KEY_DERIVE
CKM_WTLS_MASTER_KEY_DERIVE_DH_ECC
CKM_WTLS_PRF
CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE
CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE
¨ CK_WTLS_RANDOM_DATA; CK_WTLS_RANDOM_DATA_PTR
CK_WTLS_RANDOM_DATA is a structure, which provides information about the random data of a client and a server in a WTLS context. This structure is used by the CKM_WTLS_MASTER_KEY_DERIVE mechanism. It is defined as follows:
typedef struct CK_WTLS_RANDOM_DATA {
CK_BYTE_PTR pClientRandom;
CK_ULONG ulClientRandomLen;
CK_BYTE_PTR pServerRandom;
CK_ULONG ulServerRandomLen;
} CK_WTLS_RANDOM_DATA;
The fields of the structure have the following meanings:
pClientRandom pointer to the client’s random data
pClientRandomLen length in bytes of the client’s random data
pServerRaondom pointer to the server’s random data
ulServerRandomLen length in bytes of the server’s random data
CK_WTLS_RANDOM_DATA_PTR is a pointer to a CK_WTLS_RANDOM_DATA.
¨ CK_WTLS_MASTER_KEY_DERIVE_PARAMS; CK_WTLS_MASTER_KEY_DERIVE_PARAMS _PTR
CK_WTLS_MASTER_KEY_DERIVE_PARAMS is a structure, which provides the parameters to the CKM_WTLS_MASTER_KEY_DERIVE mechanism. It is defined as follows:
typedef struct CK_WTLS_MASTER_KEY_DERIVE_PARAMS {
CK_MECHANISM_TYPE DigestMechanism;
CK_WTLS_RANDOM_DATA RandomInfo;
CK_BYTE_PTR pVersion;
} CK_WTLS_MASTER_KEY_DERIVE_PARAMS;
The fields of the structure have the following meanings:
DigestMechanism the mechanism type of the digest mechanism to be used (possible types can be found in [WTLS])
RandomInfo Client’s and server’s random data information
pVersion pointer to a CK_BYTE which receives the WTLS protocol version information
CK_WTLS_MASTER_KEY_DERIVE_PARAMS_PTR is a pointer to a CK_WTLS_MASTER_KEY_DERIVE_PARAMS.
¨ CK_WTLS_PRF_PARAMS; CK_WTLS_PRF_PARAMS_PTR
CK_WTLS_PRF_PARAMS is a structure, which provides the parameters to the CKM_WTLS_PRF mechanism. It is defined as follows:
typedef struct CK_WTLS_PRF_PARAMS {
CK_MECHANISM_TYPE DigestMechanism;
CK_BYTE_PTR pSeed;
CK_ULONG ulSeedLen;
CK_BYTE_PTR pLabel;
CK_ULONG ulLabelLen;
CK_BYTE_PTR pOutput;
CK_ULONG_PTR pulOutputLen;
} CK_WTLS_PRF_PARAMS;
The fields of the structure have the following meanings:
Digest Mechanism the mechanism type of the digest mechanism to be used (possible types can be found in [WTLS])
pSeed pointer to the input seed
ulSeedLen length in bytes of the input seed
pLabel pointer to the identifying label
ulLabelLen length in bytes of the identifying label
pOutput pointer receiving the output of the operation
pulOutputLen pointer to the length in bytes that the output to be created shall have, has to hold the desired length as input and will receive the calculated length as output
CK_WTLS_PRF_PARAMS_PTR is a pointer to a CK_WTLS_PRF_PARAMS.
¨ CK_WTLS_KEY_MAT_OUT; CK_WTLS_KEY_MAT_OUT_PTR
CK_WTLS_KEY_MAT_OUT is a structure that contains the resulting key handles and initialization vectors after performing a C_DeriveKey function with the CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE or with the CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE mechanism. It is defined as follows:
typedef struct CK_WTLS_KEY_MAT_OUT {
CK_OBJECT_HANDLE hMacSecret;
CK_OBJECT_HANDLE hKey;
CK_BYTE_PTR pIV;
} CK_WTLS_KEY_MAT_OUT;
The fields of the structure have the following meanings:
hMacSecret Key handle for the resulting MAC secret key
hKey Key handle for the resulting secret key
pIV Pointer to a location which receives the initialization vector (IV) created (if any)
CK_WTLS_KEY_MAT_OUT _PTR is a pointer to a CK_WTLS_KEY_MAT_OUT.
¨ CK_WTLS_KEY_MAT_PARAMS; CK_WTLS_KEY_MAT_PARAMS_PTR
CK_WTLS_KEY_MAT_PARAMS is a structure that provides the parameters to the CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE and the CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE mechanisms. It is defined as follows:
typedef struct CK_WTLS_KEY_MAT_PARAMS {
CK_MECHANISM_TYPE DigestMechanism;
CK_ULONG ulMacSizeInBits;
CK_ULONG ulKeySizeInBits;
CK_ULONG ulIVSizeInBits;
CK_ULONG ulSequenceNumber;
CK_BBOOL bIsExport;
CK_WTLS_RANDOM_DATA RandomInfo;
CK_WTLS_KEY_MAT_OUT_PTR pReturnedKeyMaterial;
} CK_WTLS_KEY_MAT_PARAMS;
The fields of the structure have the following meanings:
Digest Mechanism the mechanism type of the digest mechanism to be used (possible types can be found in [WTLS])
ulMaxSizeInBits the length (in bits) of the MACing key agreed upon during the protocol handshake phase
ulKeySizeInBits the length (in bits) of the secret key agreed upon during the handshake phase
ulIVSizeInBits the length (in bits) of the IV agreed upon during the handshake phase. If no IV is required, the length should be set to 0.
ulSequenceNumber the current sequence number used for records sent by the client and server respectively
bIsExport a boolean value which indicates whether the keys have to be derives for an export version of the protocol. If this value is true (i.e., the keys are exportable) then ulKeySizeInBits is the length of the key in bits before expansion. The length of the key after expansion is determined by the information found in the template sent along with this mechanism during a C_DeriveKey function call (either the CKA_KEY_TYPE or the CKA_VALUE_LEN attribute).
RandomInfo client’s and server’s random data information
pReturnedKeyMaterial points to a CK_WTLS_KEY_MAT_OUT structure which receives the handles for the keys generated and the IV
CK_WTLS_KEY_MAT_PARAMS_PTR is a pointer to a CK_WTLS_KEY_MAT_PARAMS.
Pre master secret key generation for the RSA key exchange suite in WTLS denoted CKM_WTLS_PRE_MASTER_KEY_GEN, is a mechanism, which generates a variable length secret key. It is used to produce the pre master secret key for RSA key exchange suite used in WTLS. This mechanism returns a handle to the pre master secret key.
It has one parameter, a CK_BYTE, which provides the client’s WTLS version.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE and CKA_VALUE attributes to the new key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may be specified in the template, or else are assigned default values.
The template sent along with this mechanism during a C_GenerateKey call may indicate that the object class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN attribute indicates the length of the pre master secret key.
For this mechanism, the ulMinKeySize field of the CK_MECHANISM_INFO structure shall indicate 20 bytes.
Master secret derivation in WTLS, denoted CKM_WTLS_MASTER_KEY_DERIVE, is a mechanism used to derive a 20 byte generic secret key from variable length secret key. It is used to produce the master secret key used in WTLS from the pre master secret key. This mechanism returns the value of the client version, which is built into the pre master secret key as well as a handle to the derived master secret key.
It has a parameter, a CK_WTLS_MASTER_KEY_DERIVE_PARAMS structure, which allows for passing the mechanism type of the digest mechanism to be used as well as the passing of random data to the token as well as the returning of the protocol version number which is part of the pre master secret key.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may be specified in the template, or else are assigned default values.
The template sent along with this mechanism during a C_DeriveKey call may indicate that the object class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN attribute has value 20. However, since these facts are all implicit in the mechanism, there is no need to specify any of them.
This mechanism has the following rules about key sensitivity and extractability:
The CKA_SENSITIVE and CKA_EXTRACTABLE attributes in the template for the new key can both be specified to be either CK_TRUE or CK_FALSE. If omitted, these attributes each take on some default value.