Cryptographic Token Interface Standard

PKCS#11


CK_SSL3_KEY_MAT_PARAMS Reference

CK_SSL3_KEY_MAT_PARAMS

CK_SSL3_KEY_MAT_PARAMS is a structure that provides the parameters to the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. More...


Data Fields

CK_ULONG ulMacSizeInBits
 establishes the length (in bits) of the MACing keys agreed upon during the protocol handshake phase (see SSL 3.0 for details). More...

CK_ULONG ulKeySizeInBits
 establishes the length (in bits) of the secret keys agreed upon during the protocol handshake phase (see SSL 3.0 for details). More...

CK_ULONG ulIVSizeInBits
 establishes the length (in bits) of the IV agreed upon during the protocol handshake phase. More...

CK_BBOOL bIsExport
 a boolean value which indicates whether the keys have to be derived for an export version of the protocol (see SSL 3.0 for details). More...

CK_SSL3_RANDOM_DATA RandomInfo
 client's and server's random data information. More...

CK_SSL3_KEY_MAT_OUT_PTR pReturnedKeyMaterial
 points to a '''CK_SSL3_KEY_MAT_OUT''' structures which receives the handles for the keys generated, as well as the IVs when required (see SSL 3.0 for details). More...


Detailed Description

CK_SSL3_KEY_MAT_PARAMS

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:
ulMacSizeInBits establishes the length (in bits) of the MACing keys agreed upon during the protocol handshake phase (see SSL 3.0 for details)
ulKeySizeInBits establishes the length (in bits) of the secret keys agreed upon during the protocol handshake phase (see SSL 3.0 for details)
ulIVSizeInBits establishes 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 (see SSL 3.0 for details)
bIsExport a boolean value which indicates whether the keys have to be derived for an export version of the protocol (see SSL 3.0 for details)
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, as well as the IVs when required (see SSL 3.0 for details)

CK_SSL3_KEY_MAT_PARAMS_PTR

CK_SSL3_KEY_MAT_PARAMS_PTR points to a CK_SSL3_KEY_MAT_PARAMS structure. It is implementation-dependent.

SSL mechanisms

Pre_master key generation

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.

It has one parameter, a CK_VERSION structure, which provides the client's SSL version number.

The mechanism contributes to 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

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 found in 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 .

The mechanism contributes to 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.

This mechanism has the following rules about key sensitivity and extractability:

Key and MAC derivation

Key, MAC and IV derivation in SSL 3.0, denoted CKM_SSL3_KEY_AND_MAC_DERIVE, is a mechanism is 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 initialization vectors (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 .

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 (they are used for MACing), 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.

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 by 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 other mechanisms, the C_DeriveKey function 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 SSL 3.0

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 10-50, MD5 MACing in SSL 3.0: Key And Data Length Constraints
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 SSL 3.0

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 10-51, SHA-1 MACing in SSL 3.0: Key And Data Length Constraints
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.

Parameters for miscellaneous simple key derivation mechanisms

CK_KEY_DERIVATION_STRING_DATA

CK_KEY_DERIVATION_STRING_DATA is a structure that holds a pointer to a byte string and the byte string's length. It provides the parameters for the CKM_CONCATENATE_BASE_AND_DATA, CKM_CONCATENATE_DATA_AND_BASE, and CKM_XOR_BASE_AND_DATA mechanisms. It is defined as follows:


Field Documentation

CK_ULONG ulMacSizeInBits
 

establishes the length (in bits) of the MACing keys agreed upon during the protocol handshake phase (see SSL 3.0 for details).

CK_ULONG ulKeySizeInBits
 

establishes the length (in bits) of the secret keys agreed upon during the protocol handshake phase (see SSL 3.0 for details).

CK_ULONG ulIVSizeInBits
 

establishes 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 (see SSL 3.0 for details)

CK_BBOOL bIsExport
 

a boolean value which indicates whether the keys have to be derived for an export version of the protocol (see SSL 3.0 for details).

CK_SSL3_RANDOM_DATA RandomInfo
 

client's and server's random data information.

CK_SSL3_KEY_MAT_OUT_PTR pReturnedKeyMaterial
 

points to a '''CK_SSL3_KEY_MAT_OUT''' structures which receives the handles for the keys generated, as well as the IVs when required (see SSL 3.0 for details).


RSA Security Inc. Public-Key Cryptography Standards - PKCS#11 - v200