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 20 bytes.
Note that the CK_BYTE pointed to by the CK_WTLS_MASTER_KEY_DERIVE_PARAMS structure’s pVersion field will be modified by the C_DeriveKey call. In particular, when the call returns, this byte will hold the WTLS version associated with the supplied pre master secret key.
Note that this mechanism is only useable for key exchange suites that use a 20-byte pre master secret key with an embedded version number. This includes the RSA key exchange suites, but excludes the Diffie-Hellman and Elliptic Curve Cryptography key exchange suites.
Master secret derivation for Diffie-Hellman and Elliptic Curve Cryptography in WTLS, denoted CKM_WTLS_MASTER_KEY_DERIVE_DH_ECC, 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 a handle to the derived master secret key.
It has a parameter, a CK_WTLS_MASTER_KEY_DERIVE_PARAMS structure, which allows for the passing of the mechanism type of the digest mechanism to be used as well as random data to the token. The pVersion field of the structure must be set to NULL_PTR since the version number is not embedded in the pre master secret key as it is for RSA-like key exchange 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 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.
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 20 bytes.
Note that this mechanism is only useable for key exchange suites that do not use a fixed length 20-byte pre master secret key with an embedded version number. This includes the Diffie-Hellman and Elliptic Curve Cryptography key exchange suites, but excludes the RSA key exchange suites.
PRF (pseudo random function) in WTLS, denoted CKM_WTLS_PRF, is a mechanism used to produce a securely generated pseudo-random output of arbitrary length. The keys it uses are generic secret keys.
It has a parameter, a CK_WTLS_PRF_PARAMS structure, which allows for passing the mechanism type of the digest mechanism to be used, the passing of the input seed and its length, the passing of an identifying label and its length and the passing of the length of the output to the token and for receiving the output.
This mechanism produces securely generated pseudo-random output of the length specified in the parameter.
If a call to C_DeriveKey with this mechanism fails, then no output will be generated.
Server key, MAC and IV derivation in WTLS, denoted CKM_WTLS_SERVER_KEY_AND_MAC_DERIVE, is a mechanism used to derive the appropriate cryptographic keying material used by a cipher suite 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 IV created.
It has a parameter, a CK_WTLS_KEY_MAT_PARAMS structure, which allows for the passing of the mechanism type of the digest mechanism to be used, random data, the characteristic of the cryptographic material for the given cipher suite, and a pointer to a structure which receives the handles and IV which were generated.
This mechanism contributes to the creation of two distinct keys and returns one IV (if an IV is requested by the caller) back to the caller. The keys are all given an object class of CKO_SECRET_KEY.
The MACing key (server write MAC secret) is always given a type of CKK_GENERIC_SECRET. It is flagged as valid for signing, verification and derivation operations.
The other key (server write key) is typed according to information found in the template sent along with this mechanism during a C_DeriveKey function call. By default, it is flagged as valid for encryption, decryption, and derivation operations.
An IV (server write IV) will be generated and returned if the ulIVSizeInBits field of the CK_WTLS_KEY_MAT_PARAMS field has a nonzero value. If it is generated, its length in bits will agree with the value in the ulIVSizeInBits field
Both 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 that differ from those held by the base key.
Note that the CK_WTLS_KEY_MAT_OUT structure pointed to by the CK_WTLS_KEY_MAT_PARAMS structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the two key handle fields in the CK_WTLS_KEY_MAT_OUT structure will be modified to hold handles to the newly-created keys; in addition, the buffer pointed to by the CK_WTLS_KEY_MAT_OUT structure’s pIV field will have the IV returned in them (if an IV is requested by the caller). Therefore, this field must point to a buffer with sufficient space to hold any IV 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_WTLS_SERVER_KEY_AND_MAC_DERIVE mechanism returns all of its key handles in the CK_WTLS_KEY_MAT_OUT structure pointed to by the CK_WTLS_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 two keys will be created.
Client key, MAC and IV derivation in WTLS, denoted CKM_WTLS_CLIENT_KEY_AND_MAC_DERIVE, is a mechanism used to derive the appropriate cryptographic keying material used by a cipher suite 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 IV created.
It has a parameter, a CK_WTLS_KEY_MAT_PARAMS structure, which allows for the passing of the mechanism type of the digest mechanism to be used, random data, the characteristic of the cryptographic material for the given cipher suite, and a pointer to a structure which receives the handles and IV which were generated.
This mechanism contributes to the creation of two distinct keys and returns one IV (if an IV is requested by the caller) back to the caller. The keys are all given an object class of CKO_SECRET_KEY.
The MACing key (client write MAC secret) is always given a type of CKK_GENERIC_SECRET. It is flagged as valid for signing, verification and derivation operations.
The other key (client write key) is typed according to information found in the template sent along with this mechanism during a C_DeriveKey function call. By default, it is flagged as valid for encryption, decryption, and derivation operations.
An IV (client write IV) will be generated and returned if the ulIVSizeInBits field of the CK_WTLS_KEY_MAT_PARAMS field has a nonzero value. If it is generated, its length in bits will agree with the value in the ulIVSizeInBits field
Both 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 that differ from those held by the base key.
Note that the CK_WTLS_KEY_MAT_OUT structure pointed to by the CK_WTLS_KEY_MAT_PARAMS structure’s pReturnedKeyMaterial field will be modified by the C_DeriveKey call. In particular, the two key handle fields in the CK_WTLS_KEY_MAT_OUT structure will be modified to hold handles to the newly-created keys; in addition, the buffer pointed to by the CK_WTLS_KEY_MAT_OUT structure’s pIV field will have the IV returned in them (if an IV is requested by the caller). Therefore, this field must point to a buffer with sufficient space to hold any IV 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_WTLS_CLIENT_KEY_AND_MAC_DERIVE mechanism returns all of its key handles in the CK_WTLS_KEY_MAT_OUT structure pointed to by the CK_WTLS_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 two keys will be created.
Table 105, Miscellaneous simple key derivation Mechanisms vs. Functions
|
Mechanism |
Functions |
||||||
|
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
|
CKM_CONCATENATE_BASE_AND_KEY |
|
|
|
|
|
|
ü |
|
CKM_CONCATENATE_BASE_AND_DATA |
|
|
|
|
|
|
ü |
|
CKM_CONCATENATE_DATA_AND_BASE |
|
|
|
|
|
|
ü |
|
CKM_XOR_BASE_AND_DATA |
|
|
|
|
|
|
ü |
|
CKM_EXTRACT_KEY_FROM_KEY |
|
|
|
|
|
|
ü |
Mechanisms:
CKM_CONCATENATE_BASE_AND_DATA
CKM_CONCATENATE_DATA_AND_BASE
CKM_XOR_BASE_AND_DATA
CKM_EXTRACT_KEY_FROM_KEY
CKM_CONCATENATE_BASE_AND_KEY
¨ CK_KEY_DERIVATION_STRING_DATA; CK_KEY_DERIVATION_STRING_DATA_PTR
CK_KEY_DERIVATION_STRING_DATA 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:
typedef struct CK_KEY_DERIVATION_STRING_DATA {
CK_BYTE_PTR pData;
CK_ULONG ulLen;
} CK_KEY_DERIVATION_STRING_DATA;
The fields of the structure have the following meanings:
pData pointer to the byte string
ulLen length of the byte string
CK_KEY_DERIVATION_STRING_DATA_PTR is a pointer to a CK_KEY_DERIVATION_STRING_DATA.
¨ CK_EXTRACT_PARAMS; CK_EXTRACT_PARAMS_PTR
CK_EXTRACT_PARAMS provides the parameter to the CKM_EXTRACT_KEY_FROM_KEY mechanism. It specifies which bit of the base key should be used as the first bit of the derived key. It is defined as follows:
typedef CK_ULONG CK_EXTRACT_PARAMS;
CK_EXTRACT_PARAMS_PTR is a pointer to a CK_EXTRACT_PARAMS.
This mechanism, denoted CKM_CONCATENATE_BASE_AND_KEY, derives a secret key from the concatenation of two existing secret keys. The two keys are specified by handles; the values of the keys specified are concatenated together in a buffer.
This mechanism takes a parameter, a CK_OBJECT_HANDLE. This handle produces the key value information which is appended to the end of the base key’s value information (the base key is the key whose handle is supplied as an argument to C_DeriveKey).
For example, if the value of the base key is 0x01234567, and the value of the other key is 0x89ABCDEF, then the value of the derived key will be taken from a buffer containing the string 0x0123456789ABCDEF.
· 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 equal to the sum of the lengths of the values of the two original keys.
· 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 is 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, DES3, 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 bytes than are available by concatenating the two original keys’ values, an error is generated.
This mechanism has the following rules about key sensitivity and extractability:
· If either of the two original keys 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 a default value.
· Similarly, if either of the two original keys 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 a default value.
· The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if both of the original keys have their CKA_ALWAYS_SENSITIVE attributes set to CK_TRUE.
· Similarly, the derived key’s CKA_NEVER_EXTRACTABLE attribute is set to CK_TRUE if and only if both of the original keys have their CKA_NEVER_EXTRACTABLE attributes set to CK_TRUE.
This mechanism, denoted CKM_CONCATENATE_BASE_AND_DATA, derives a secret key by concatenating data onto the end of a specified secret key.
This mechanism takes a parameter, a CK_KEY_DERIVATION_STRING_DATA structure, which specifies the length and value of the data which will be appended to the base key to derive another key.
For example, if the value of the base key is 0x01234567, and the value of the data is 0x89ABCDEF, then the value of the derived key will be taken from a buffer containing the string 0x0123456789ABCDEF.
· 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 equal to the sum of the lengths of the value of the original key and the data.
· 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 is 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, DES3, 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 bytes than are available by concatenating the original key’s value and the data, an error is generated.
This mechanism has the following rules about key sensitivity and extractability:
· If the base 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 a default value.
· Similarly, if the base 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 a default value.
· The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the base 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 base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
This mechanism, denoted CKM_CONCATENATE_DATA_AND_BASE, derives a secret key by prepending data to the start of a specified secret key.
This mechanism takes a parameter, a CK_KEY_DERIVATION_STRING_DATA structure, which specifies the length and value of the data which will be prepended to the base key to derive another key.
For example, if the value of the base key is 0x01234567, and the value of the data is 0x89ABCDEF, then the value of the derived key will be taken from a buffer containing the string 0x89ABCDEF01234567.
· 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 equal to the sum of the lengths of the data and the value of the original key.
· 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 is 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, DES3, 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 bytes than are available by concatenating the data and the original key’s value, an error is generated.
This mechanism has the following rules about key sensitivity and extractability:
· If the base 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 a default value.
· Similarly, if the base 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 a default value.
· The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the base 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 base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
XORing key derivation, denoted CKM_XOR_BASE_AND_DATA, is a mechanism which provides the capability of deriving a secret key by performing a bit XORing of a key pointed to by a base key handle and some data.
This mechanism takes a parameter, a CK_KEY_DERIVATION_STRING_DATA structure, which specifies the data with which to XOR the original key’s value.
For example, if the value of the base key is 0x01234567, and the value of the data is 0x89ABCDEF, then the value of the derived key will be taken from a buffer containing the string 0x88888888.
· 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 equal to the minimum of the lengths of the data and the value of the original key.
· 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 is 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, DES3, 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 bytes than are available by taking the shorter of the data and the original key’s value, an error is generated.
This mechanism has the following rules about key sensitivity and extractability:
· If the base 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 a default value.
· Similarly, if the base 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 a default value.
· The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the base 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 base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
Extraction of one key from another key, denoted CKM_EXTRACT_KEY_FROM_KEY, is a mechanism which provides the capability of creating one secret key from the bits of another secret key.
This mechanism has a parameter, a CK_EXTRACT_PARAMS, which specifies which bit of the original key should be used as the first bit of the newly-derived key.
We give an example of how this mechanism works. Suppose a token has a secret key with the 4-byte value 0x329F84A9. We will derive a 2-byte secret key from this key, starting at bit position 21 (i.e., the value of the parameter to the CKM_EXTRACT_KEY_FROM_KEY mechanism is 21).
1. We write the key’s value in binary: 0011 0010 1001 1111 1000 0100 1010 1001. We regard this binary string as holding the 32 bits of the key, labeled as b0, b1, …, b31.
2. We then extract 16 consecutive bits (i.e., 2 bytes) from this binary string, starting at bit b21. We obtain the binary string 1001 0101 0010 0110.
3. The value of the new key is thus 0x9526.
Note that when constructing the value of the derived key, it is permissible to wrap around the end of the binary string representing the original key’s value.
If the original key used in this process is sensitive, then the derived key must also be sensitive for the derivation to succeed.
· If no length or key type is provided in the template, then an error will be returned.
· 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 is 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, DES3, 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 bytes than the original key has, an error is generated.
This mechanism has the following rules about key sensitivity and extractability:
· If the base 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 a default value.
· Similarly, if the base 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 a default value.
· The derived key’s CKA_ALWAYS_SENSITIVE attribute is set to CK_TRUE if and only if the base 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 base key has its CKA_NEVER_EXTRACTABLE attribute set to CK_TRUE.
Table 106, CMS Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_CMS_SIG |
|
ü |
ü |
|
|
|
|
Mechanisms:
CKM_CMS_SIG
These objects provide information relating to the CKM_CMS_SIG mechanism. CKM_CMS_SIG mechanism object attributes represent information about supported CMS signature attributes in the token. They are only present on tokens supporting the CKM_CMS_SIG mechanism, but must be present on those tokens.
Table 107, CMS Signature Mechanism Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_REQUIRED_CMS_ATTRIBUTES |
Byte array |
Attributes the token always will include in the set of CMS signed attributes |
|
CKA_DEFAULT_CMS_ATTRIBUTES |
Byte array |
Attributes the token will include in the set of CMS signed attributes in the absence of any attributes specified by the application |
|
CKA_SUPPORTED_CMS_ATTRIBUTES |
Byte array |
Attributes the token may include in the set of CMS signed attributes upon request by the application |
The contents of each byte array will be a DER-encoded list of CMS Attributes with optional accompanying values. Any attributes in the list shall be identified with its object identifier, and any values shall be DER-encoded. The list of attributes is defined in ASN.1 as:
Attributes ::= SET SIZE (1..MAX) OF Attribute
Attribute ::= SEQUENCE {
attrType OBJECT IDENTIFIER,
attrValues SET OF ANY DEFINED BY OBJECT IDENTIFIER OPTIONAL
}
The client may not set any of the attributes.
· CK_CMS_SIG_PARAMS, CK_CMS_SIG_PARAMS_PTR
CK_CMS_SIG_PARAMS is a structure that provides the parameters to the CKM_CMS_SIG mechanism. It is defined as follows:
typedef struct CK_CMS_SIG_PARAMS {
CK_OBJECT_HANDLE certificateHandle;
CK_MECHANISM_PTR pSigningMechanism;
CK_MECHANISM_PTR pDigestMechanism;
CK_UTF8CHAR_PTR pContentType;
CK_BYTE_PTR pRequestedAttributes;
CK_ULONG ulRequestedAttributesLen;
CK_BYTE_PTR pRequiredAttributes;
CK_ULONG ulRequiredAttributesLen;
} CK_CMS_SIG_PARAMS;
The fields of the structure have the following meanings:
certificateHandle Object handle for a certificate associated with the signing key. The token may use information from this certificate to identify the signer in the SignerInfo result value. CertificateHandle may be NULL_PTR if the certificate is not available as a PKCS #11 object or if the calling application leaves the choice of certificate completely to the token.
pSigningMechanism Mechanism to use when signing a constructed CMS SignedAttributes value. E.g. CKM_SHA1_RSA_PKCS.
pDigestMechanism Mechanism to use when digesting the data. Value shall be NULL_PTR when the digest mechanism to use follows from the pSigningMechanism parameter.
pContentType NULL-terminated string indicating complete MIME Content-type of message to be signed; or the value NULL_PTR if the message is a MIME object (which the token can parse to determine its MIME Content-type if required). Use the value “application/octet-stream“ if the MIME type for the message is unknown or undefined. Note that the pContentType string shall conform to the syntax specified in RFC 2045, i.e. any parameters needed for correct presentation of the content by the token (such as, for example, a non-default “charset”) must be present. The token must follow rules and procedures defined in RFC 2045 when presenting the content.
pRequestedAttributes Pointer to DER-encoded list of CMS Attributes the caller requests to be included in the signed attributes. Token may freely ignore this list or modify any supplied values.
ulRequestedAttributesLen Length in bytes of the value pointed to by pRequestedAttributes
pRequiredAttributes Pointer to DER-encoded list of CMS Attributes (with accompanying values) required to be included in the resulting signed attributes. Token must not modify any supplied values. If the token does not support one or more of the attributes, or does not accept provided values, the signature operation will fail. The token will use its own default attributes when signing if both the pRequestedAttributes and pRequiredAttributes field are set to NULL_PTR.
ulRequiredAttributesLen Length in bytes, of the value pointed to by pRequiredAttributes.
The CMS mechanism, denoted CKM_CMS_SIG, is a multi-purpose mechanism based on the structures defined in PKCS #7 and RFC 2630. It supports single- or multiple-part signatures with and without message recovery. The mechanism is intended for use with, e.g., PTDs (see MeT-PTD) or other capable tokens. The token will construct a CMS SignedAttributes value and compute a signature on this value. The content of the SignedAttributes value is decided by the token, however the caller can suggest some attributes in the parameter pRequestedAttributes. The caller can also require some attributes to be present through the parameters pRequiredAttributes. The signature is computed in accordance with the parameter pSigningMechanism.
When this mechanism is used in successful calls to C_Sign or C_SignFinal, the pSignature return value will point to a DER-encoded value of type SignerInfo. SignerInfo is defined in ASN.1 as follows (for a complete definition of all fields and types, see RFC 2630):
SignerInfo ::= SEQUENCE {
version CMSVersion,
sid SignerIdentifier,
digestAlgorithm DigestAlgorithmIdentifier,
signedAttrs [0] IMPLICIT SignedAttributes OPTIONAL,
signatureAlgorithm SignatureAlgorithmIdentifier,
signature SignatureValue,
unsignedAttrs [1] IMPLICIT UnsignedAttributes OPTIONAL }
The certificateHandle parameter, when set, helps the token populate the sid field of the SignerInfo value. If certificateHandle is NULL_PTR the choice of a suitable certificate reference in the SignerInfo result value is left to the token (the token could, e.g., interact with the user).
This mechanism shall not be used in calls to C_Verify or C_VerifyFinal (use the pSigningMechanism mechanism instead).
For the pRequiredAttributes field, the token may have to interact with the user to find out whether to accept a proposed value or not. The token should never accept any proposed attribute values without some kind of confirmation from its owner (but this could be through, e.g., configuration or policy settings and not direct interaction). If a user rejects proposed values, or the signature request as such, the value CKR_FUNCTION_REJECTED shall be returned.
When possible, applications should use the CKM_CMS_SIG mechanism when generating CMS-compatible signatures rather than lower-level mechanisms such as CKM_SHA1_RSA_PKCS. This is especially true when the signatures are to be made on content that the token is able to present to a user. Exceptions may include those cases where the token does not support a particular signing attribute. Note however that the token may refuse usage of a particular signature key unless the content to be signed is known (i.e. the CKM_CMS_SIG mechanism is used).
When a token does not have presentation capabilities, the PKCS #11-aware application may avoid sending the whole message to the token by electing to use a suitable signature mechanism (e.g. CKM_RSA_PKCS) as the pSigningMechanism value in the CK_CMS_SIG_PARAMS structure, and digesting the message itself before passing it to the token.
PKCS #11-aware applications making use of tokens with presentation capabilities, should attempt to provide messages to be signed by the token in a format possible for the token to present to the user. Tokens that receive multipart MIME-messages for which only certain parts are possible to present may fail the signature operation with a return value of CKR_DATA_INVALID, but may also choose to add a signing attribute indicating which parts of the message were possible to present.
Blowfish, a secret-key block cipher. It is a Feistel network, iterating a simple encryption function 16 times. The block size is 64 bits, and the key can be any length up to 448 bits. Although there is a complex initialization phase required before any encryption can take place, the actual encryption of data is very efficient on large microprocessors.
Table 108, Blowfish Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_BLOWFISH_CBC |
✓ |
|
|
|
|
✓ |
|
|
CKM_BLOWFISH_CBC_PAD |
✓ |
|
|
|
|
✓ |
|
This section defines the key type “CKK_BLOWFISH” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.
Mechanisms:
CKM_BLOWFISH_KEY_GEN
CKM_BLOWFISH_CBC
Blowfish secret key objects (object class CKO_SECRET_KEY, key type CKK_BLOWFISH) hold Blowfish keys. The following table defines the Blowfish secret key object attributes, in addition to the common attributes defined for this object class:
Table 109, BLOWFISH Secret Key Object
|
Attribute |
Data type |
Meaning |
|
CKA_VALUE1,4,6,7 |
Byte array |
Key value the key can be any length up to 448 bits. Bit length restricted to a byte array. |
|
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 an Blowfish secret key object:
CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_BLOWFISH;
CK_UTF8CHAR label[] = “A blowfish 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)}
};
The Blowfish key generation mechanism, denoted CKM_BLOWFISH_KEY_GEN, is a key generation mechanism Blowfish.
It does not have a parameter.
The mechanism generates Blowfish keys with a particular length, 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 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 key sizes in bytes.
Blowfish-CBC, denoted CKM_BLOWFISH_CBC, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping.
It has a parameter, a 8-byte initialization vector.
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 110, BLOWFISH-CBC: Key and Data Length
|
Function |
Key type |
Input Length |
Output Length |
|
C_Encrypt |
BLOWFISH |
Multiple of block size |
Same as input length |
|
C_Decrypt |
BLOWFISH |
Multiple of block size |
Same as input length |
|
C_WrapKey |
BLOWFISH |
Any |
Input length rounded up to multiple of the block size |
|
C_UnwrapKey |
BLOWFISH |
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 BLOWFISH key sizes, in bytes.
Blowfish-CBC-PAD, denoted CKM_BLOWFISH_CBC_PAD, is a mechanism for single- and multiple-part encryption and decryption, key wrapping and key unwrapping, cipher-block chaining mode and the block cipher padding method detailed in PKCS #7.
It has a parameter, a 8-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.
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 111, BLOWFISH-CBC with PKCS Padding: Key and Data Length
|
Function |
Key type |
Input Length |
Output Length |
|
C_Encrypt |
BLOWFISH |
Any |
Input length rounded up to multiple of the block size |
|
C_Decrypt |
BLOWFISH |
Multiple of block size |
Between 1 and block length block size bytes shorter than input length |
|
C_WrapKey |
BLOWFISH |
Any |
Input length rounded up to multiple of the block size |
|
C_UnwrapKey |
BLOWFISH |
Multiple of block size |
Between 1 and block length block size bytes shorter than input length |
Ref. https://www.schneier.com/twofish.html
This section defines the key type “CKK_TWOFISH” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.
Mechanisms:
CKM_TWOFISH_KEY_GEN
CKM_TWOFISH_CBC
CKM_TWOFISH_CBC_PAD
Twofish secret key objects (object class CKO_SECRET_KEY, key type CKK_TWOFISH) hold Twofish keys. The following table defines the Twofish secret key object attributes, in addition to the common attributes defined for this object class:
Table 112, Twofish Secret Key Object
|
Attribute |
Data type |
Meaning |
|
CKA_VALUE1,4,6,7 |
Byte array |
Key value 128-, 192-, or 256-bit key |
|
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 an TWOFISH secret key object:
CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_TWOFISH;
CK_UTF8CHAR label[] = “A twofish 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)}
};
The Twofish key generation mechanism, denoted CKM_TWOFISH_KEY_GEN, is a key generation mechanism Twofish.
It does not have a parameter.
The mechanism generates Blowfish keys with a particular length, 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 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 key sizes, in bytes.
Twofish-CBC, denoted CKM_TWOFISH_CBC, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping.
It has a parameter, a 16-byte initialization vector.
Twofish-CBC-PAD, denoted CKM_TWOFISH_CBC_PAD, is a mechanism for single- and multiple-part encryption and decryption, key wrapping and key unwrapping, 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.
Camellia is a block cipher with 128-bit block size and 128-, 192-, and 256-bit keys, similar to AES. Camellia is described e.g. in IETF RFC 3713.
Table 113, Camellia Mechanisms vs. Functions
|
Mechanism |
Functions |
||||||
|
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
|
CKM_CAMELLIA_KEY_GEN |
|
|
|
|
ü |
|
|
|
CKM_CAMELLIA_ECB |
ü |
|
|
|
|
ü |
|
|
CKM_CAMELLIA_CBC |
ü |
|
|
|
|
ü |
|
|
CKM_CAMELLIA_CBC_PAD |
ü |
|
|
|
|
ü |
|
|
CKM_CAMELLIA_MAC_GENERAL |
|
ü |
|
|
|
|
|
|
CKM_CAMELLIA_MAC |
|
ü |
|
|
|
|
|
|
CKM_CAMELLIA_ECB_ENCRYPT_DATA |
|
|
|
|
|
|
ü |
|
CKM_CAMELLIA_CBC_ENCRYPT_DATA |
|
|
|
|
|
|
ü |
This section defines the key type “CKK_CAMELLIA” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.
Mechanisms:
CKM_CAMELLIA_KEY_GEN
CKM_CAMELLIA_ECB
CKM_CAMELLIA_CBC
CKM_CAMELLIA_MAC
CKM_CAMELLIA_MAC_GENERAL
CKM_CAMELLIA_CBC_PAD
Camellia secret key objects (object class CKO_SECRET_KEY, key type CKK_CAMELLIA) hold Camellia keys. The following table defines the Camellia secret key object attributes, in addition to the common attributes defined for this object class:
Table 114, Camellia 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 a Camellia secret key object:
CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_CAMELLIA;
CK_UTF8CHAR label[] = “A Camellia 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)}
};
The Camellia key generation mechanism, denoted CKM_CAMELLIA_KEY_GEN, is a key generation mechanism for Camellia.
It does not have a parameter.
The mechanism generates Camellia 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 Camellia 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 Camellia key sizes, in bytes.
Camellia-ECB, denoted CKM_CAMELLIA_ECB, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on Camellia 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 115, Camellia-ECB: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
CKK_CAMELLIA |
multiple of block size |
same as input length |
no final part |
|
C_Decrypt |
CKK_CAMELLIA |
multiple of block size |
same as input length |
no final part |
|
C_WrapKey |
CKK_CAMELLIA |
any |
input length rounded up to multiple of block size |
|
|
C_UnwrapKey |
CKK_CAMELLIA |
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 Camellia key sizes, in bytes.
Camellia-CBC, denoted CKM_CAMELLIA_CBC, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on Camellia 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 116, Camellia-CBC: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
CKK_CAMELLIA |
multiple of block size |
same as input length |
no final part |
|
C_Decrypt |
CKK_CAMELLIA |
multiple of block size |
same as input length |
no final part |
|
C_WrapKey |
CKK_CAMELLIA |
any |
input length rounded up to multiple of the block size |
|
|
C_UnwrapKey |
CKK_CAMELLIA |
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 Camellia key sizes, in bytes.
Camellia-CBC with PKCS padding, denoted CKM_CAMELLIA_CBC_PAD, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on Camellia; 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 TBA 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 117, Camellia-CBC with PKCS Padding: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
|
C_Encrypt |
CKK_CAMELLIA |
any |
input length rounded up to multiple of the block size |
|
C_Decrypt |
CKK_CAMELLIA |
multiple of block size |
between 1 and block size bytes shorter than input length |
|
C_WrapKey |
CKK_CAMELLIA |
any |
input length rounded up to multiple of the block size |
|
C_UnwrapKey |
CKK_CAMELLIA |
multiple of block size |
between 1 and block length bytes shorter than input length |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of Camellia key sizes, in bytes.
General-length Camellia -MAC, denoted CKM_CAMELLIA_MAC_GENERAL, is a mechanism for single- and multiple-part signatures and verification, based on Camellia and data authentication as defined in.[CAMELLIA]
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 Camellia cipher block produced in the MACing process.
Constraints on key types and the length of data are summarized in the following table:
Table 118, General-length Camellia-MAC: Key and Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_CAMELLIA |
any |
0-block size, as specified in parameters |
|
C_Verify |
CKK_CAMELLIA |
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 Camellia key sizes, in bytes.
Camellia-MAC, denoted by CKM_CAMELLIA_MAC, is a special case of the general-length Camellia-MAC mechanism. Camellia-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 119, Camellia-MAC: Key and Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_CAMELLIA |
any |
½ block size (8 bytes) |
|
C_Verify |
CKK_CAMELLIA |
any |
½ block size (8 bytes) |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of Camellia key sizes, in bytes.
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.
Mechanisms:
CKM_CAMELLIA_ECB_ENCRYPT_DATA
CKM_CAMELLIA_CBC_ENCRYPT_DATA
typedef struct CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS {
CK_BYTE iv[16];
CK_BYTE_PTR pData;
CK_ULONG length;
} CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS;
typedef CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS CK_PTR
CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS_PTR;
Uses CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS, and CK_KEY_DERIVATION_STRING_DATA.
Table 120, Mechanism Parameters for Camellia-based key derivation
|
CKM_CAMELLIA_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_CAMELLIA_CBC_ENCRYPT_DATA |
Uses CK_CAMELLIA_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. |
ARIA is a block cipher with 128-bit block size and 128-, 192-, and 256-bit keys, similar to AES. ARIA is described in NSRI “Specification of ARIA”.
Table 121, ARIA Mechanisms vs. Functions
This section defines the key type “CKK_ARIA” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.
Mechanisms:
CKM_ARIA_KEY_GEN
CKM_ARIA_ECB
CKM_ARIA_CBC
CKM_ARIA_MAC
CKM_ARIA_MAC_GENERAL
CKM_ARIA_CBC_PAD
ARIA secret key objects (object class CKO_SECRET_KEY, key type CKK_ARIA) hold ARIA keys. The following table defines the ARIA secret key object attributes, in addition to the common attributes defined for this object class:
Table 122, ARIA 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 ARIA secret key object:
CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_ARIA;
CK_UTF8CHAR label[] = “An ARIA 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)}
};
The ARIA key generation mechanism, denoted CKM_ARIA_KEY_GEN, is a key generation mechanism for Aria.
It does not have a parameter.
The mechanism generates ARIA 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 ARIA 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 ARIA key sizes, in bytes.
ARIA-ECB, denoted CKM_ARIA_ECB, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on Aria 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 123, ARIA-ECB: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
CKK_ARIA |
multiple of block size |
same as input length |
no final part |
|
C_Decrypt |
CKK_ARIA |
multiple of block size |
same as input length |
no final part |
|
C_WrapKey |
CKK_ARIA |
any |
input length rounded up to multiple of block size |
|
|
C_UnwrapKey |
CKK_ARIA |
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 ARIA key sizes, in bytes.
ARIA-CBC, denoted CKM_ARIA_CBC, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on ARIA 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 124, ARIA-CBC: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
Comments |
|
C_Encrypt |
CKK_ARIA |
multiple of block size |
same as input length |
no final part |
|
C_Decrypt |
CKK_ARIA |
multiple of block size |
same as input length |
no final part |
|
C_WrapKey |
CKK_ARIA |
any |
input length rounded up to multiple of the block size |
|
|
C_UnwrapKey |
CKK_ARIA |
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 Aria key sizes, in bytes.
ARIA-CBC with PKCS padding, denoted CKM_ARIA_CBC_PAD, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on ARIA; 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 TBA 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 125, ARIA-CBC with PKCS Padding: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
|
C_Encrypt |
CKK_ARIA |
any |
input length rounded up to multiple of the block size |
|
C_Decrypt |
CKK_ARIA |
multiple of block size |
between 1 and block size bytes shorter than input length |
|
C_WrapKey |
CKK_ARIA |
any |
input length rounded up to multiple of the block size |
|
C_UnwrapKey |
CKK_ARIA |
multiple of block size |
between 1 and block length bytes shorter than input length |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of ARIA key sizes, in bytes.
General-length ARIA -MAC, denoted CKM_ARIA_MAC_GENERAL, is a mechanism for single- and multiple-part signatures and verification, based on ARIA and data authentication as defined in [FIPS 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 ARIA cipher block produced in the MACing process.
Constraints on key types and the length of data are summarized in the following table:
Table 126, General-length ARIA-MAC: Key and Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_ARIA |
any |
0-block size, as specified in parameters |
|
C_Verify |
CKK_ARIA |
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 ARIA key sizes, in bytes.
ARIA-MAC, denoted by CKM_ARIA_MAC, is a special case of the general-length ARIA-MAC mechanism. ARIA-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 127, ARIA-MAC: Key and Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_ARIA |
any |
½ block size (8 bytes) |
|
C_Verify |
CKK_ARIA |
any |
½ block size (8 bytes) |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of ARIA key sizes, in bytes.
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.
Mechanisms:
CKM_ARIA_ECB_ENCRYPT_DATA
CKM_ARIA_CBC_ENCRYPT_DATA
typedef struct CK_ARIA_CBC_ENCRYPT_DATA_PARAMS {
CK_BYTE iv[16];
CK_BYTE_PTR pData;
CK_ULONG length;
} CK_ARIA_CBC_ENCRYPT_DATA_PARAMS;
typedef CK_ARIA_CBC_ENCRYPT_DATA_PARAMS CK_PTR
CK_ARIA_CBC_ENCRYPT_DATA_PARAMS_PTR;
Uses CK_ARIA_CBC_ENCRYPT_DATA_PARAMS, and CK_KEY_DERIVATION_STRING_DATA.
Table 128, Mechanism Parameters for Aria-based key derivation
|
CKM_ARIA_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_ARIA_CBC_ENCRYPT_DATA |
Uses CK_ARIA_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. |
SEED is a symmetric block cipher developed by the South Korean Information Security Agency (KISA). It has a 128-bit key size and a 128-bit block size.
Its specification has been published as Internet [RFC 4269].
RFCs have been published defining the use of SEED in
TLS ftp://ftp.rfc-editor.org/in-notes/rfc4162.txt
IPsec ftp://ftp.rfc-editor.org/in-notes/rfc4196.txt
CMS ftp://ftp.rfc-editor.org/in-notes/rfc4010.txt
TLS cipher suites that use SEED include:
CipherSuite TLS_RSA_WITH_SEED_CBC_SHA = { 0x00, 0x96};
CipherSuite TLS_DH_DSS_WITH_SEED_CBC_SHA = { 0x00, 0x97};
CipherSuite TLS_DH_RSA_WITH_SEED_CBC_SHA = { 0x00, 0x98};
CipherSuite TLS_DHE_DSS_WITH_SEED_CBC_SHA = { 0x00, 0x99};
CipherSuite TLS_DHE_RSA_WITH_SEED_CBC_SHA = { 0x00, 0x9A};
CipherSuite TLS_DH_anon_WITH_SEED_CBC_SHA = { 0x00, 0x9B};
As with any block cipher, it can be used in the ECB, CBC, OFB and CFB modes of operation, as well as in a MAC algorithm such as HMAC.
OIDs have been published for all these uses. A list may be seen at http://www.alvestrand.no/objectid/1.2.410.200004.1.html
Table 129, SEED Mechanisms vs. Functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_SEED_KEY_GEN |
|
|
|
|
ü |
|
|
|
CKM_SEED_ECB |
|
|
ü |
|
|
|
|
|
CKM_SEED_CBC |
|
|
ü |
|
|
|
|
|
CKM_SEED_CBC_PAD |
ü |
|
|
|
|
ü |
|
|
CKM_SEED_MAC_GENERAL |
|
|
ü |
|
|
|
|
|
CKM_SEED_MAC |
|
|
|
ü |
|
|
|
|
CKM_SEED_ECB_ENCRYPT_DATA |
|
|
|
|
|
|
ü |
|
CKM_SEED_CBC_ENCRYPT_DATA |
|
|
|
|
|
|
ü |
This section defines the key type “CKK_SEED” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects.
Mechanisms:
CKM_SEED_KEY_GEN
CKM_SEED_ECB
CKM_SEED_CBC
CKM_SEED_MAC
CKM_SEED_MAC_GENERAL
CKM_SEED_CBC_PAD
For all of these mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO are always 16.
SEED secret key objects (object class CKO_SECRET_KEY, key type CKK_SEED) hold SEED keys. The following table defines the secret key object attributes, in addition to the common attributes defined for this object class:
Table 130, SEED 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.
The following is a sample template for creating a SEED secret key object:
CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_SEED;
CK_UTF8CHAR label[] = “A SEED 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)}
};
The SEED key generation mechanism, denoted CKM_SEED_KEY_GEN, is a key generation mechanism for SEED.
It does not have a parameter.
The mechanism generates SEED keys.
The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key. Other attributes supported by the SEED 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.
SEED-ECB, denoted CKM_SEED_ECB, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on SEED and electronic codebook mode.
It does not have a parameter.
SEED-CBC, denoted CKM_SEED_CBC, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on SEED and cipher-block chaining mode.
It has a parameter, a 16-byte initialization vector.
SEED-CBC with PKCS padding, denoted CKM_SEED_CBC_PAD, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on SEED; cipher-block chaining mode; and the block cipher padding method detailed in PKCS #7.
It has a parameter, a 16-byte initialization vector.
General-length SEED-MAC, denoted CKM_SEED_MAC_GENERAL, is a mechanism for single- and multiple-part signatures and verification, based on SEED and data authentication as defined in 0.
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 cipher block produced in the MACing process.
SEED-MAC, denoted by CKM_SEED_MAC, is a special case of the general-length SEED-MAC mechanism. SEED-MAC always produces and verifies MACs that are half the block size in length.
It does not have a parameter.
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.
Mechanisms:
CKM_SEED_ECB_ENCRYPT_DATA
CKM_SEED_CBC_ENCRYPT_DATA
typedef struct CK_SEED_CBC_ENCRYPT_DATA_PARAMSCK_CBC_ENCRYPT_DATA_PARAMS;{
typedefCK_BYTE iv[16];
CK_BYTE_PTR pData;
CK_ULONG length;
} CK_SEED_CBC_ENCRYPT_DATA_PARAMSCK_PTR;
typedef CK_SEED_CBC_ENCRYPT_DATA_PARAMS CK_PTR;CK_SEED_CBC_ENCRYPT_DATA_PARAMS_PTR;
Table 131, Mechanism Parameters for SEED-based key derivation
|
CKM_SEED_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_SEED_CBC_ENCRYPT_DATA |
Uses CK_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. |
OTP tokens represented as PKCS #11 mechanisms may be used in a variety of ways. The usage cases can be categorized according to the type of sought functionality.
.
Figure 1: Retrieving OTP values through C_Sign
Figure 1 shows an integration of PKCS #11 into an application that needs to authenticate users holding OTP tokens. In this particular example, a connected hardware token is used, but a software token is equally possible. The application invokes C_Sign to retrieve the OTP value from the token. In the example, the application then passes the retrieved OTP value to a client API that sends it via the network to an authentication server. The client API may implement a standard authentication protocol such as RADIUS [RFC 2865] or EAP [RFC 3748], or a proprietary protocol such as that used by RSA Security's ACE/Agent® software.
Figure 2: Server-side verification of OTP values
Figure 2 illustrates the server-side equivalent of the scenario depicted in Figure 1. In this case, a server application invokes C_Verify with the received OTP value as the signature value to be verified.
Figure 3: Generation of an OTP key
Figure 3 shows an integration of PKCS #11 into an application that generates OTP keys. The application invokes C_GenerateKey to generate an OTP key of a particular type on the token. The key may subsequently be used as a basis to generate OTP values.
OTP key objects (object class CKO_OTP_KEY) hold secret keys used by OTP tokens. The following table defines the attributes common to all OTP keys, in addition to the attributes defined for secret keys, all of which are inherited by this class:
Table 132: Common OTP key attributes
|
Attribute |
Data type |
Meaning |
|
CKA_OTP_FORMAT |
CK_ULONG |
Format of OTP values produced with this key: CK_OTP_FORMAT_DECIMAL = Decimal (default) (UTF8-encoded) CK_OTP_FORMAT_HEXADECIMAL = Hexadecimal (UTF8-encoded) CK_OTP_FORMAT_ALPHANUMERIC = Alphanumeric (UTF8-encoded) CK_OTP_FORMAT_BINARY = Only binary values. |
|
CKA_OTP_LENGTH9 |
CK_ULONG |
Default length of OTP values (in the CKA_OTP_FORMAT) produced with this key. |
|
CKA_OTP_USER_FRIENDLY_MODE9 |
CK_BBOOL |
Set to CK_TRUE when the token is capable of returning OTPs suitable for human consumption. See the description of CKF_USER_FRIENDLY_OTP below. |
|
CKA_OTP _CHALLENGE_REQUIREMENT9 |
CK_ULONG |
Parameter requirements when generating or verifying OTP values with this key: CK_OTP_PARAM_MANDATORY = A challenge must be supplied. CK_OTP_PARAM_OPTIONAL = A challenge may be supplied but need not be. CK_OTP_PARAM_IGNORED = A challenge, if supplied, will be ignored. |
|
CKA_OTP_TIME_REQUIREMENT9 |
CK_ULONG |
Parameter requirements when generating or verifying OTP values with this key: CK_OTP_PARAM_MANDATORY = A time value must be supplied. CK_OTP_PARAM_OPTIONAL = A time value may be supplied but need not be. CK_OTP_PARAM_IGNORED = A time value, if supplied, will be ignored. |
|
CKA_OTP_COUNTER_REQUIREMENT9 |
CK_ULONG |
Parameter requirements when generating or verifying OTP values with this key: CK_OTP_PARAM_MANDATORY = A counter value must be supplied. CK_OTP_PARAM_OPTIONAL = A counter value may be supplied but need not be. CK_OTP_PARAM_IGNORED = A counter value, if supplied, will be ignored. |
|
CKA_OTP_PIN_REQUIREMENT9 |
CK_ULONG |
Parameter requirements when generating or verifying OTP values with this key: CK_OTP_PARAM_MANDATORY = A PIN value must be supplied. CK_OTP_PARAM_OPTIONAL = A PIN value may be supplied but need not be (if not supplied, then library will be responsible for collecting it) CK_OTP_PARAM_IGNORED = A PIN value, if supplied, will be ignored. |
|
CKA_OTP_COUNTER |
Byte array |
Value of the associated internal counter. Default value is empty (i.e. ulValueLen = 0). |
|
CKA_OTP_TIME |
RFC 2279 string |
Value of the associated internal UTC time in the form YYYYMMDDhhmmss. Default value is empty (i.e. ulValueLen= 0). |
|
CKA_OTP_USER_IDENTIFIER |
RFC 2279 string |
Text string that identifies a user associated with the OTP key (may be used to enhance the user experience). Default value is empty (i.e. ulValueLen = 0). |
|
CKA_OTP_SERVICE_IDENTIFIER |
RFC 2279 string |
Text string that identifies a service that may validate OTPs generated by this key. Default value is empty (i.e. ulValueLen = 0). |
|
CKA_OTP_SERVICE_LOGO |
Byte array |
Logotype image that identifies a service that may validate OTPs generated by this key. Default value is empty (i.e. ulValueLen = 0). |
|
CKA_OTP_SERVICE_LOGO_TYPE |
RFC 2279 string |
MIME type of the CKA_OTP_SERVICE_LOGO attribute value. Default value is empty (i.e. ulValueLen = 0). |
|
CKA_VALUE1, 4, 6, 7 |
Byte array |
Value of the key. |
|
CKA_VALUE_LEN2, 3 |
CK_ULONG |
Length in bytes of key value. |
Refer to [PKCS #11-Base] table 10 for footnotes.
Note: A Cryptoki library may support PIN-code caching in order to reduce user interactions. An OTP-PKCS #11 application should therefore always consult the state of the CKA_OTP_PIN_REQUIREMENT attribute before each call to C_SignInit, as the value of this attribute may change dynamically.
For OTP tokens with multiple keys, the keys may be enumerated using C_FindObjects. The CKA_OTP_SERVICE_IDENTIFIER and/or the CKA_OTP_SERVICE_LOGO attribute may be used to distinguish between keys. The actual choice of key for a particular operation is however application-specific and beyond the scope of this document.
For all OTP keys, the CKA_ALLOWED_MECHANISMS attribute should be set as required.
This document extends the set of defined notifications as follows:
CKN_OTP_CHANGED Cryptoki is informing the application that the OTP for a key on a connected token just changed. This notification is particularly useful when applications wish to display the current OTP value for time-based mechanisms.
The following table shows, for the OTP mechanisms defined in this document, their support by different cryptographic operations. For any particular token, of course, a particular operation may well support only a subset of the mechanisms listed. There is also no guarantee that a token that supports one mechanism for some operation supports any other mechanism for any other operation (or even supports that same mechanism for any other operation).
Table 133: OTP mechanisms vs. applicable functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_SECURID_KEY_GEN |
|
|
|
|
ü |
|
|
|
CKM_SECURID |
|
ü |
|
|
|
|
|
|
CKM_HOTP_KEY_GEN |
|
|
|
|
ü |
|
|
|
CKM_HOTP |
|
ü |
|
|
|
|
|
|
CKM_ACTI_KEY_GEN |
|
|
|
|
ü |
|
|
|
CKM_ACTI |
|
ü |
|
|
|
|
|
The remainder of this section will present in detail the OTP mechanisms and the parameters that are supplied to them.
¨ CK_OTP_PARAM_TYPE
CK_OTP_PARAM_TYPE is a value that identifies an OTP parameter type. It is defined as follows:
typedef CK_ULONG CK_OTP_PARAM_TYPE;
The following CK_OTP_PARAM_TYPE types are defined:
Table 134, OTP parameter types
|
Parameter |
Data type |
Meaning |
|
CK_OTP_PIN |
RFC 2279 string |
A UTF8 string containing a PIN for use when computing or verifying PIN-based OTP values. |
|
CK_OTP_CHALLENGE |
Byte array |
Challenge to use when computing or verifying challenge-based OTP values. |
|
CK_OTP_TIME |
RFC 2279 string |
UTC time value in the form YYYYMMDDhhmmss to use when computing or verifying time-based OTP values. |
|
CK_OTP_COUNTER |
Byte array |
Counter value to use when computing or verifying counter-based OTP values. |
|
CK_OTP_FLAGS |
CK_FLAGS |
Bit flags indicating the characteristics of the sought OTP as defined below. |
|
CK_OTP_OUTPUT_LENGTH |
CK_ULONG |
Desired output length (overrides any default value). A Cryptoki library will return CKR_MECHANISM_PARAM_INVALID if a provided length value is not supported. |
|
CK_OTP_OUTPUT_FORMAT |
CK_ULONG |
Returned OTP format (allowed values are the same as for CKA_OTP_FORMAT). This parameter is only intended for C_Sign output, see paragraphs below. When not present, the returned OTP format will be the same as the value of the CKA_OTP_FORMAT attribute for the key in question. |
|
CK_OTP_VALUE |
Byte array |
An actual OTP value. This parameter type is intended for C_Sign output, see paragraphs below. |
The following table defines the possible values for the CK_OTP_FLAGS type:
Table 135: OTP Mechanism Flags
|
Bit flag |
Mask |
Meaning |
|
CKF_NEXT_OTP |
0x00000001 |
True (i.e. set) if the OTP computation shall be for the next OTP, rather than the current one (current being interpreted in the context of the algorithm, e.g. for the current counter value or current time window). A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if the CKF_NEXT_OTP flag is set and the OTP mechanism in question does not support the concept of “next” OTP or the library is not capable of generating the next OTP[5]. |
|
CKF_EXCLUDE_TIME |
0x00000002 |
True (i.e. set) if the OTP computation must not include a time value. Will have an effect only on mechanisms that do include a time value in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed. |
|
CKF_EXCLUDE_COUNTER |
0x00000004 |
True (i.e. set) if the OTP computation must not include a counter value. Will have an effect only on mechanisms that do include a counter value in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed. |
|
CKF_EXCLUDE_CHALLENGE |
0x00000008 |
True (i.e. set) if the OTP computation must not include a challenge. Will have an effect only on mechanisms that do include a challenge in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed. |
|
CKF_EXCLUDE_PIN |
0x00000010 |
True (i.e. set) if the OTP computation must not include a PIN value. Will have an effect only on mechanisms that do include a PIN in the OTP computation and then only if the mechanism (and token) allows exclusion of this value. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if exclusion of the value is not allowed. |
|
CKF_USER_FRIENDLY_OTP |
0x00000020 |
True (i.e. set) if the OTP returned shall be in a form suitable for human consumption. If this flag is set, and the call is successful, then the returned CK_OTP_VALUE shall be a UTF8-encoded printable string. A Cryptoki library shall return CKR_MECHANISM_PARAM_INVALID if this flag is set when CKA_OTP_USER_FRIENDLY_MODE for the key in question is CK_FALSE. |
Note: Even if CKA_OTP_FORMAT is not set to CK_OTP_FORMAT_BINARY, then there may still be value in setting the CKF_USER_FRIENDLY_OTP flag (assuming CKA_OTP_USER_FRIENDLY_MODE is CK_TRUE, of course) if the intent is for a human to read the generated OTP value, since it may become shorter or otherwise better suited for a user. Applications that do not intend to provide a returned OTP value to a user should not set the CKF_USER_FRIENDLY_OTP flag.
¨ CK_OTP_PARAM; CK_OTP_PARAM_PTR
CK_OTP_PARAM is a structure that includes the type, value, and length of an OTP parameter. It is defined as follows:
typedef struct CK_OTP_PARAM {
CK_OTP_PARAM_TYPE type;
CK_VOID_PTR pValue;
CK_ULONG ulValueLen;
} CK_OTP_PARAM;
The fields of the structure have the following meanings:
type the parameter type
pValue pointer to the value of the parameter
ulValueLen length in bytes of the value
If a parameter has no value, then ulValueLen = 0, and the value of pValue is irrelevant. Note that pValue is a “void” pointer, facilitating the passing of arbitrary values. Both the application and the Cryptoki library must ensure that the pointer can be safely cast to the expected type (i.e., without word-alignment errors).
CK_OTP_PARAM_PTR is a pointer to a CK_OTP_PARAM.
CK_OTP_PARAMS; CK_OTP_PARAMS_PTR
CK_OTP_PARAMS is a structure that is used to provide parameters for OTP mechanisms in a generic fashion. It is defined as follows:
typedef struct CK_OTP_PARAMS {
CK_OTP_PARAM_PTR pParams;
CK_ULONG ulCount;
} CK_OTP_PARAMS;
The fields of the structure have the following meanings:
pParams pointer to an array of OTP parameters
ulCount the number of parameters in the array
CK_OTP_PARAMS_PTR is a pointer to a CK_OTP_PARAMS.
When calling C_SignInit or C_VerifyInit with a mechanism that takes a CK_OTP_PARAMS structure as a parameter, the CK_OTP_PARAMS structure shall be populated in accordance with the CKA_OTP_X_REQUIREMENT key attributes for the identified key, where X is PIN, CHALLENGE, TIME, or COUNTER.
For example, if CKA_OTP_TIME_REQUIREMENT = CK_OTP_PARAM_MANDATORY, then the CK_OTP_TIME parameter shall be present. If CKA_OTP_TIME_REQUIREMENT = CK_OTP_PARAM_OPTIONAL, then a CK_OTP_TIME parameter may be present. If it is not present, then the library may collect it (during the C_Sign call). If CKA_OTP_TIME_REQUIREMENT = CK_OTP_PARAM_IGNORED, then a provided CK_OTP_TIME parameter will always be ignored. Additionally, a provided CK_OTP_TIME parameter will always be ignored if CKF_EXCLUDE_TIME is set in a CK_OTP_FLAGS parameter. Similarly, if this flag is set, a library will not attempt to collect the value itself, and it will also instruct the token not to make use of any internal value, subject to token policies. It is an error (CKR_MECHANISM_PARAM_INVALID) to set the CKF_EXCLUDE_TIME flag when the CKA_OTP_TIME_REQUIREMENT attribute is CK_OTP_PARAM_MANDATORY.
The above discussion holds for all CKA_OTP_X_REQUIREMENT
attributes (i.e., CKA_OTP_PIN_REQUIREMENT, CKA_OTP_CHALLENGE_REQURIEMENTREQUIREMENT,
CKA_OTP_COUNTER_REQUIREMENT, CKA_OTP_TIME_REQUIREMENT). A library may set a
particular CKA_OTP_X_REQUIREMENT attribute to CK_OTP_PARAM_OPTIONAL even
if it is required by the mechanism as long as the token (or the library itself)
has the capability of providing the value to the computation. One example of
this is a token with an on-board clock.
In addition, applications may use the CK_OTP_FLAGS, the CK_OTP_OUTPUT_FORMAT and the CKA_OTP_LENGTH parameters to set additional parameters.
CK_OTP_SIGNATURE_INFO, CK_OTP_SIGNATURE_INFO_PTR
CK_OTP_SIGNATURE_INFO is a structure that is returned by all OTP mechanisms in successful calls to C_Sign (C_SignFinal). The structure informs applications of actual parameter values used in particular OTP computations in addition to the OTP value itself. It is used by all mechanisms for which the key belongs to the class CKO_OTP_KEY and is defined as follows:
typedef struct CK_OTP_SIGNATURE_INFO {
CK_OTP_PARAM_PTR pParams;
CK_ULONG ulCount;
} CK_OTP_SIGNATURE_INFO;
The fields of the structure have the following meanings:
pParams pointer to an array of OTP parameter values
ulCount the number of parameters in the array
After successful calls to C_Sign or C_SignFinal with an OTP mechanism, the pSignature parameter will be set to point to a CK_OTP_SIGNATURE_INFO structure. One of the parameters in this structure will be the OTP value itself, identified with the CK_OTP_VALUE tag. Other parameters may be present for informational purposes, e.g. the actual time used in the OTP calculation. In order to simplify OTP validations, authentication protocols may permit authenticating parties to send some or all of these parameters in addition to OTP values themselves. Applications should therefore check for their presence in returned CK_OTP_SIGNATURE_INFO values whenever such circumstances apply.
Since C_Sign and C_SignFinal follows the convention described in Section 11.2 on producing output, a call to C_Sign (or C_SignFinal) with pSignature set to NULL_PTR will return (in the pulSignatureLen parameter) the required number of bytes to hold the CK_OTP_SIGNATURE_INFO structure as well as all the data in all its CK_OTP_PARAM components. If an application allocates a memory block based on this information, it shall therefore not subsequently de-allocate components of such a received value but rather de-allocate the complete CK_OTP_PARAMS structure itself. A Cryptoki library that is called with a non-NULL pSignature pointer will assume that it points to a contiguous memory block of the size indicated by the pulSignatureLen parameter.
When verifying an OTP value using an OTP mechanism, pSignature shall be set to the OTP value itself, e.g. the value of the CK_OTP_VALUE component of a CK_OTP_PARAMS structure returned by a call to C_Sign. The CK_OTP_PARAMS value supplied in the C_VerifyInit call sets the values to use in the verification operation.
CK_OTP_SIGNATURE_INFO_PTR points to a CK_OTP_SIGNATURE_INFO.
RSA SecurID secret key objects (object class CKO_OTP_KEY, key type CKK_SECURID) hold RSA SecurID secret keys. The following table defines the RSA SecurID secret key object attributes, in addition to the common attributes defined for this object class:
Table 136, RSA SecurID secret key object attributes
|
Attribute |
Data type |
Meaning |
|
CKA_OTP_TIME_INTERVAL1 |
CK_ULONG |
Interval between OTP values produced with this key, in seconds. Default is 60. |
Refer to [PKCS #11-Base] table 10 for footnotes..
The following is a sample template for creating an RSA SecurID secret key object:
CK_OBJECT_CLASS class = CKO_OTP_KEY;
CK_KEY_TYPE keyType = CKK_SECURID;
CK_DATE endDate = {...};
CK_UTF8CHAR label[] = “RSA SecurID secret key object”;
CK_BYTE keyId[]= {...};
CK_ULONG outputFormat = CK_OTP_FORMAT_DECIMAL;
CK_ULONG outputLength = 6;
CK_ULONG needPIN = CK_OTP_PARAM_MANDATORY;
CK_ULONG timeInterval = 60;
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_END_DATE, &endDate, sizeof(endDate)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_SIGN, &true, sizeof(true)},
{CKA_VERIFY, &true, sizeof(true)},
{CKA_ID, keyId, sizeof(keyId)},
{CKA_OTP_FORMAT, &outputFormat, sizeof(outputFormat)},
{CKA_OTP_LENGTH, &outputLength, sizeof(outputLength)},
{CKA_OTP_PIN_REQUIREMENT, &needPIN, sizeof(needPIN)},
{CKA_OTP_TIME_INTERVAL, &timeInterval, sizeof(timeInterval)},
{CKA_VALUE, value, sizeof(value)}
};
The RSA SecurID key generation mechanism, denoted CKM_SECURID_KEY_GEN, is a key generation mechanism for the RSA SecurID algorithm.
It does not have a parameter.
The mechanism generates RSA SecurID keys with a particular set of attributes as specified in the template for the key.
The mechanism contributes at least the CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE_LEN, and CKA_VALUE attributes to the new key. Other attributes supported by the RSA SecurID key type 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 SecurID key sizes, in bytes.
CKM_SECURID is the mechanism for the retrieval and verification of RSA SecurID OTP values.
The mechanism takes a pointer to a CK_OTP_PARAMS structure as a parameter.
When signing or verifying using the CKM_SECURID mechanism, pData shall be set to NULL_PTR and ulDataLen shall be set to 0.
Support for the CKM_SECURID mechanism extends the set of return values for C_Verify with the following values:
· CKR_NEW_PIN_MODE: The supplied OTP was not accepted and the library requests a new OTP computed using a new PIN. The new PIN is set through means out of scope for this document.
· CKR_NEXT_OTP: The supplied OTP was correct but indicated a larger than normal drift in the token's internal state (e.g. clock, counter). To ensure this was not due to a temporary problem, the application should provide the next one-time password to the library for verification.
HOTP secret key objects (object class CKO_OTP_KEY, key type CKK_HOTP) hold generic secret keys and associated counter values.
The CKA_OTP_COUNTER value may be set at key generation; however, some tokens may set it to a fixed initial value. Depending on the token’s security policy, this value may not be modified and/or may not be revealed if the object has its CKA_SENSITIVE attribute set to CK_TRUE or its CKA_EXTRACTABLE attribute set to CK_FALSE.
For HOTP keys, the CKA_OTP_COUNTER value shall be an 8 bytes unsigned integer in big endian (i.e. network byte order) form. The same holds true for a CK_OTP_COUNTER value in a CK_OTP_PARAM structure.
The following is a sample template for creating a HOTP secret key object:
CK_OBJECT_CLASS class = CKO_OTP_KEY;
CK_KEY_TYPE keyType = CKK_HOTP;
CK_UTF8CHAR label[] = “HOTP secret key object”;
CK_BYTE keyId[]= {...};
CK_ULONG outputFormat = CK_OTP_FORMAT_DECIMAL;
CK_ULONG outputLength = 6;
CK_DATE endDate = {...};
CK_BYTE counterValue[8] = {0};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_END_DATE, &endDate, sizeof(endDate)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_SIGN, &true, sizeof(true)},
{CKA_VERIFY, &true, sizeof(true)},
{CKA_ID, keyId, sizeof(keyId)},
{CKA_OTP_FORMAT, &outputFormat, sizeof(outputFormat)},
{CKA_OTP_LENGTH, &outputLength, sizeof(outputLength)},
{CKA_OTP_COUNTER, counterValue, sizeof(counterValue)},
{CKA_VALUE, value, sizeof(value)}
};
The HOTP key generation mechanism, denoted CKM_HOTP_KEY_GEN, is a key generation mechanism for the HOTP algorithm.
It does not have a parameter.
The mechanism generates HOTP keys with a particular set of attributes as specified in the template for the key.
The mechanism contributes at least the CKA_CLASS, CKA_KEY_TYPE, CKA_OTP_COUNTER, CKA_VALUE and CKA_VALUE_LEN attributes to the new key. Other attributes supported by the HOTP key type 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 HOTP key sizes, in bytes.
CKM_HOTP is the mechanism for the retrieval and verification of HOTP OTP values based on the current internal counter, or a provided counter.
The mechanism takes a pointer to a CK_OTP_PARAMS structure as a parameter.
As for the CKM_SECURID mechanism, when signing or verifying using the CKM_HOTP mechanism, pData shall be set to NULL_PTR and ulDataLen shall be set to 0.
For verify operations, the counter value CK_OTP_COUNTER must be provided as a CK_OTP_PARAM parameter to C_VerifyInit. When verifying an OTP value using the CKM_HOTP mechanism, pSignature shall be set to the OTP value itself, e.g. the value of the CK_OTP_VALUE component of a CK_OTP_PARAMS structure in the case of an earlier call to C_Sign.
ACTI secret key objects (object class CKO_OTP_KEY, key type CKK_ACTI) hold ActivIdentity ACTI secret keys.
For ACTI keys, the CKA_OTP_COUNTER value shall be an 8 bytes unsigned integer in big endian (i.e. network byte order) form. The same holds true for the CK_OTP_COUNTER value in the CK_OTP_PARAM structure.
The CKA_OTP_COUNTER value may be set at key generation; however, some tokens may set it to a fixed initial value. Depending on the token’s security policy, this value may not be modified and/or may not be revealed if the object has its CKA_SENSITIVE attribute set to CK_TRUE or its CKA_EXTRACTABLE attribute set to CK_FALSE.
The CKA_OTP_TIME value may be set at key generation; however, some tokens may set it to a fixed initial value. Depending on the token’s security policy, this value may not be modified and/or may not be revealed if the object has its CKA_SENSITIVE attribute set to CK_TRUE or its CKA_EXTRACTABLE attribute set to CK_FALSE.
The following is a sample template for creating an ACTI secret key object:
CK_OBJECT_CLASS class = CKO_OTP_KEY;
CK_KEY_TYPE keyType = CKK_ACTI;
CK_UTF8CHAR label[] = “ACTI secret key object”;
CK_BYTE keyId[]= {...};
CK_ULONG outputFormat = CK_OTP_FORMAT_DECIMAL;
CK_ULONG outputLength = 6;
CK_DATE endDate = {...};
CK_BYTE counterValue[8] = {0};
CK_BYTE value[] = {...};
CK_BBOOL true = CK_TRUE;
CK_ATTRIBUTE template[] = {
{CKA_CLASS, &class, sizeof(class)},
{CKA_KEY_TYPE, &keyType, sizeof(keyType)},
{CKA_END_DATE, &endDate, sizeof(endDate)},
{CKA_TOKEN, &true, sizeof(true)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_LABEL, label, sizeof(label)-1},
{CKA_SIGN, &true, sizeof(true)},
{CKA_VERIFY, &true, sizeof(true)},
{CKA_ID, keyId, sizeof(keyId)},
{CKA_OTP_FORMAT, &outputFormat,
sizeof(outputFormat)},
{CKA_OTP_LENGTH, &outputLength,
sizeof(outputLength)},
{CKA_OTP_COUNTER, counterValue,
sizeof(counterValue)},
{CKA_VALUE, value, sizeof(value)}
};
The ACTI key generation mechanism, denoted CKM_ACTI_KEY_GEN, is a key generation mechanism for the ACTI algorithm.
It does not have a parameter.
The mechanism generates ACTI keys with a particular set of attributes as specified in the template for the key.
The mechanism contributes at least the CKA_CLASS, CKA_KEY_TYPE, CKA_VALUE and CKA_VALUE_LEN attributes to the new key. Other attributes supported by the ACTI key type 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 ACTI key sizes, in bytes.
CKM_ACTI is the mechanism for the retrieval and verification of ACTI OTP values.
The mechanism takes a pointer to a CK_OTP_PARAMS structure as a parameter.
When signing or verifying using the CKM_ACTI mechanism, pData shall be set to NULL_PTR and ulDataLen shall be set to 0.
When verifying an OTP value using the CKM_ACTI mechanism, pSignature shall be set to the OTP value itself, e.g. the value of the CK_OTP_VALUE component of a CK_OTP_PARAMS structure in the case of an earlier call to C_Sign.
Figure 4: PKCS #11 and CT-KIP integration
Figure 3 shows an integration of PKCS #11 into an application that generates cryptographic keys through the use of CT-KIP. The application invokes C_DeriveKey to derive a key of a particular type on the token. The key may subsequently be used as a basis to e.g., generate one-time password values. The application communicates with a CT-KIP server that participates in the key derivation and stores a copy of the key in its database. The key is transferred to the server in wrapped form, after a call to C_WrapKey. The server authenticates itself to the client and the client verifies the authentication by calls to C_Verify.
The following table shows, for the mechanisms defined in this document, their support by different cryptographic operations. For any particular token, of course, a particular operation may well support only a subset of the mechanisms listed. There is also no guarantee that a token that supports one mechanism for some operation supports any other mechanism for any other operation (or even supports that same mechanism for any other operation).
Table 137: CT-KIP Mechanisms vs. applicable functions
|
|
Functions |
||||||
|
Mechanism |
Encrypt & Decrypt |
Sign & Verify |
SR & VR1 |
Digest |
Gen. Key/ Key Pair |
Wrap & Unwrap |
Derive |
|
CKM_KIP_DERIVE |
|
|
|
|
|
|
ü |
|
CKM_KIP_WRAP |
|
|
|
|
|
ü |
|
|
CKM_KIP_MAC |
|
ü |
|
|
|
|
|
The remainder of this section will present in detail the mechanisms and the parameters that are supplied to them.
Mechanisms:
CKM_KIP_DERIVE
CKM_KIP_WRAP
CKM_KIP_MAC
¨ CK_KIP_PARAMS; CK_KIP_PARAMS_PTR
CK_KIP_PARAMS is a structure that provides the parameters to all the CT-KIP related mechanisms: The CKM_KIP_DERIVE key derivation mechanism, the CKM_KIP_WRAP key wrap and key unwrap mechanism, and the CKM_KIP_MAC signature mechanism. The structure is defined as follows:
typedef struct CK_KIP_PARAMS {
CK_MECHANISM_PTR pMechanism;
CK_OBJECT_HANDLE hKey;
CK_BYTE_PTR pSeed;
CK_ULONG ulSeedLen;
} CK_KIP_PARAMS;
The fields of the structure have the following meanings:
pMechanism pointer to the underlying cryptographic mechanism (e.g. AES, SHA-256), see further 0, Appendix D
hKey handle to a key that will contribute to the entropy of the derived key (CKM_KIP_DERIVE) or will be used in the MAC operation (CKM_KIP_MAC)
pSeed pointer to an input seed
ulSeedLen length in bytes of the input seed
CK_KIP_PARAMS_PTR is a pointer to a CK_KIP_PARAMS structure.
The CT-KIP key derivation mechanism, denoted CKM_KIP_DERIVE, is a key derivation mechanism that is capable of generating secret keys of potentially any type, subject to token limitations.
It takes a parameter of type CK_KIP_PARAMS which allows for the passing of the desired underlying cryptographic mechanism as well as some other data. In particular, when the hKey parameter is a handle to an existing key, that key will be used in the key derivation in addition to the hBaseKey of C_DeriveKey. The pSeed parameter may be used to seed the key derivation operation.
The mechanism derives a secret key with a particular set of attributes as specified in the attributes of the template for the key.
The mechanism contributes the CKA_CLASS and CKA_VALUE attributes to the new key. Other attributes supported by the key type may be specified in the template for the key, or else will be assigned default initial values. Since the mechanism is generic, the CKA_KEY_TYPE attribute should be set in the template, if the key is to be used with a particular mechanism.
The CT-KIP key wrap and unwrap mechanism, denoted CKM_KIP_WRAP, is a key wrap mechanism that is capable of wrapping and unwrapping generic secret keys.
It takes a parameter of type CK_KIP_PARAMS, which allows for the passing of the desired underlying cryptographic mechanism as well as some other data. It does not make use of the hKey parameter of CK_KIP_PARAMS.
The CT-KIP signature (MAC) mechanism, denoted CKM_KIP_MAC, is a mechanism used to produce a message authentication code of arbitrary length. The keys it uses are secret keys.
It takes a parameter of type CK_KIP_PARAMS, which allows for the passing of the desired underlying cryptographic mechanism as well as some other data. The mechanism does not make use of the pSeed and the ulSeedLen parameters of CT_KIP_PARAMS.
This mechanism produces a MAC of the length specified by pulSignatureLen parameter in calls to C_Sign.
If a call to C_Sign with this mechanism fails, then no output will be generated.
The remainder of this section will present in detail the mechanisms and the parameters which are supplied to them.

This section defines the key type “CKK_GOST28147” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects and domain parameter objects.
Mechanisms:
CKM_GOST28147_KEY_GEN
CKM_GOST28147_ECB
CKM_GOST28147
CKM_GOST28147_MAC
CKM_GOST28147_KEY_WRAP
GOST 28147‑89 secret key objects (object class CKO_SECRET_KEY, key type CKK_GOST28147) hold GOST 28147‑89 keys. The following table defines the GOST 28147‑89 secret key object attributes, in addition to the common attributes defined for this object class:
Table 139, GOST 28147-89 Secret Key Object Attributes
|
Attribute |
Data type |
Meaning |
|
CKA_VALUE1,4,6,7 |
Byte array |
32 bytes in little endian order |
|
CKA_GOST28147_PARAMS1,3,5 |
Byte array |
DER-encoding of the object identifier indicating the data object type of GOST 28147‑89. When key is used the domain parameter object of key type CKK_GOST28147 must be specified with the same attribute CKA_OBJECT_ID |
Refer to [PKCS #11-Base] Table 10 for footnotes
The following is a sample template for creating a GOST 28147‑89 secret key object:
CK_OBJECT_CLASS class = CKO_SECRET_KEY;
CK_KEY_TYPE keyType = CKK_GOST28147;
CK_UTF8CHAR label[] = “A GOST 28147-89 secret key object”;
CK_BYTE value[32] = {...};
CK_BYTE params_oid[] = {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x00};
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_GOST28147_PARAMS, params_oid, sizeof(params_oid)},
{CKA_VALUE, value, sizeof(value)}
};
GOST 28147‑89 domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type CKK_GOST28147) hold GOST 28147‑89 domain parameters.
The following table defines the GOST 28147‑89 domain parameter object attributes, in addition to the common attributes defined for this object class:
Table 140, GOST 28147-89 Domain Parameter Object Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_VALUE1 |
Byte array |
DER-encoding of the domain parameters as it was introduced in [4] section 8.1 (type Gost28147-89-ParamSetParameters) |
|
CKA_OBJECT_ID1 |
Byte array |
DER-encoding of the object identifier indicating the domain parameters |
Refer to [PKCS #11-Base] Table 10 for footnotes
For any particular token, there is no guarantee that a token supports domain parameters loading up and/or fetching out. Furthermore, applications, that make direct use of domain parameters objects, should take in account that CKA_VALUE attribute may be inaccessible.
The following is a sample template for creating a GOST 28147‑89 domain parameter object:
CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS;
CK_KEY_TYPE keyType = CKK_GOST28147;
CK_UTF8CHAR label[] = “A GOST 28147-89 cryptographic parameters object”;
CK_BYTE oid[] = {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x00};
CK_BYTE value[] = {
0x30,0x62,0x04,0x40,0x4c,0xde,0x38,0x9c,0x29,0x89,0xef,0xb6,0xff,0xeb,0x56,
0xc5,0x5e,0xc2,0x9b,0x02,0x98,0x75,0x61,0x3b,0x11,0x3f,0x89,0x60,0x03,0x97,
0x0c,0x79,0x8a,0xa1,0xd5,0x5d,0xe2,0x10,0xad,0x43,0x37,0x5d,0xb3,0x8e,0xb4,
0x2c,0x77,0xe7,0xcd,0x46,0xca,0xfa,0xd6,0x6a,0x20,0x1f,0x70,0xf4,0x1e,0xa4,
0xab,0x03,0xf2,0x21,0x65,0xb8,0x44,0xd8,0x02,0x01,0x00,0x02,0x01,0x40,
0x30,0x0b,0x06,0x07,0x2a,0x85,0x03,0x02,0x02,0x0e,0x00,0x05,0x00
};
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_OBJECT_ID, oid, sizeof(oid)},
{CKA_VALUE, value, sizeof(value)}
};
The GOST 28147‑89 key generation mechanism, denoted CKM_GOST28147_KEY_GEN, is a key generation mechanism for GOST 28147‑89.
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 GOST 28147‑89 key type may be specified for objects of object class CKO_SECRET_KEY.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO are not used.
GOST 28147‑89-ECB, denoted CKM_GOST28147_ECB, is a mechanism for single and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on GOST 28147‑89 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 (C_WrapKey), 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 so that the resulting length is a multiple of the block size.
For unwrapping (C_UnwrapKey), 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.
Constraints on key types and the length of data are summarized in the following table:
Table 141, GOST 28147-89-ECB: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
|
C_Encrypt |
CKK_GOST28147 |
Multiple of block size |
Same as input length |
|
C_Decrypt |
CKK_GOST28147 |
Multiple of block size |
Same as input length |
|
C_WrapKey |
CKK_GOST28147 |
Any |
Input length rounded up to multiple of block size |
|
C_UnwrapKey |
CKK_GOST28147 |
Multiple of block size |
Determined by type of key being unwrapped |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure are not used.
GOST 28147‑89 encryption mode except ECB, denoted CKM_GOST28147, is a mechanism for single and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on [GOST 28147‑89] and CFB, counter mode, and additional CBC mode defined in [RFC 4357] section 2. Encryption’s parameters are specified in object identifier of attribute CKA_GOST28147_PARAMS.
It has a parameter, which is an 8-byte initialization vector. This parameter may be omitted then a zero initialization vector is used.
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 (C_WrapKey), the mechanism encrypts the value of the CKA_VALUE attribute of the key that is wrapped.
For unwrapping (C_UnwrapKey), the mechanism decrypts the wrapped key, and contributes the result as the CKA_VALUE attribute of the new key.
Constraints on key types and the length of data are summarized in the following table:
Table 142, GOST 28147-89 encryption modes except ECB: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
|
C_Encrypt |
CKK_GOST28147 |
Any |
For counter mode and CFB is the same as input length. For CBC is the same as input length padded on the trailing end with up to block size so that the resulting length is a multiple of the block size |
|
C_Decrypt |
CKK_GOST28147 |
Any |
|
|
C_WrapKey |
CKK_GOST28147 |
Any |
|
|
C_UnwrapKey |
CKK_GOST28147 |
Any |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure are not used.
GOST 28147-89-MAC, denoted CKM_GOST28147_MAC, is a mechanism for data integrity and authentication based on GOST 28147-89 and key meshing algorithms [RFC 4357] section 2.3.
MACing parameters are specified in object identifier of attribute CKA_GOST28147_PARAMS.
The output bytes from this mechanism are taken from the start of the final GOST 28147‑89 cipher block produced in the MACing process.
It has a parameter, which is an 8-byte MAC initialization vector. This parameter may be omitted then a zero initialization vector is used.
Constraints on key types and the length of data are summarized in the following table:
Table 143, GOST28147-89-MAC: Key and Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_GOST28147 |
Any |
4 bytes |
|
C_Verify |
CKK_GOST28147 |
Any |
4 bytes |
For this mechanism, the ulMinKeySize and ulMaxKeySize
fields of the CK_MECHANISM_INFO structure are not used.
GOST 28147-89 keys wrapping/unwrapping with GOST 28147-89
GOST 28147‑89 keys as a KEK (key encryption keys) for encryption GOST 28147‑89 keys, denoted by CKM_GOST28147_KEY_WRAP, is a mechanism for key wrapping; and key unwrapping, based on GOST 28147‑89. Its purpose is to encrypt and decrypt keys have been generated by key generation mechanism for GOST 28147‑89.
For wrapping (C_WrapKey), the mechanism first computes MAC from the value of the CKA_VALUE attribute of the key that is wrapped and then encrypts in ECB mode the value of the CKA_VALUE attribute of the key that is wrapped. The result is 32 bytes of the key that is wrapped and 4 bytes of MAC.
For unwrapping (C_UnwrapKey), the mechanism first decrypts in ECB mode the 32 bytes of the key that was wrapped and then computes MAC from the unwrapped key. Then compared together 4 bytes MAC has computed and 4 bytes MAC of the input. If these two MACs do not match the wrapped key is disallowed. The mechanism contributes the result as the CKA_VALUE attribute of the unwrapped key.
It has a parameter, which is an 8-byte MAC initialization vector. This parameter may be omitted then a zero initialization vector is used.
Constraints on key types and the length of data are summarized in the following table:
Table 144, GOST 28147-89 keys as KEK: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
|
C_WrapKey |
CKK_GOST28147 |
32 bytes |
36 bytes |
|
C_UnwrapKey |
CKK_GOST28147 |
32 bytes |
36 bytes |
For this mechanism, the ulMinKeySize and ulMaxKeySize
fields of the CK_MECHANISM_INFO structure are not used.
GOST R 34.11-94
GOST R 34.11-94 is a mechanism for message digesting, following the hash algorithm with 256-bit message digest defined in [GOST R 34.11-94].
This section defines the key type “CKK_GOSTR3411” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of domain parameter objects.
Mechanisms:
CKM_GOSTR3411
CKM_GOSTR3411_HMAC
GOST R 34.11-94 domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type CKK_GOSTR3411) hold GOST R 34.11-94 domain parameters.
The following table defines the GOST R 34.11-94 domain parameter object attributes, in addition to the common attributes defined for this object class:
Table 145, GOST R 34.11-94 Domain Parameter Object Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_VALUE1 |
Byte array |
DER-encoding of the domain parameters as it was introduced in [4] section 8.2 (type GostR3411-94-ParamSetParameters) |
|
CKA_OBJECT_ID1 |
Byte array |
DER-encoding of the object identifier indicating the domain parameters |
Refer to [PKCS #11-Base] Table 10 for footnotes
For any particular token, there is no guarantee that a token supports domain parameters loading up and/or fetching out. Furthermore, applications, that make direct use of domain parameters objects, should take in account that CKA_VALUE attribute may be inaccessible.
The following is a sample template for creating a GOST R 34.11-94 domain parameter object:
CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS;
CK_KEY_TYPE keyType = CKK_GOSTR3411;
CK_UTF8CHAR label[] = “A GOST R34.11-94 cryptographic parameters object”;
CK_BYTE oid[] = {0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1e, 0x00};
CK_BYTE value[] = {
0x30,0x64,0x04,0x40,0x4e,0x57,0x64,0xd1,0xab,0x8d,0xcb,0xbf,0x94,0x1a,0x7a,
0x4d,0x2c,0xd1,0x10,0x10,0xd6,0xa0,0x57,0x35,0x8d,0x38,0xf2,0xf7,0x0f,0x49,
0xd1,0x5a,0xea,0x2f,0x8d,0x94,0x62,0xee,0x43,0x09,0xb3,0xf4,0xa6,0xa2,0x18,
0xc6,0x98,0xe3,0xc1,0x7c,0xe5,0x7e,0x70,0x6b,0x09,0x66,0xf7,0x02,0x3c,0x8b,
0x55,0x95,0xbf,0x28,0x39,0xb3,0x2e,0xcc,0x04,0x20,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00
};
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_OBJECT_ID, oid, sizeof(oid)},
{CKA_VALUE, value, sizeof(value)}
};
GOST R 34.11-94 digest, denoted CKM_GOSTR3411, is a mechanism for message digesting based on GOST R 34.11-94 hash algorithm [GOST R 34.11-94].
As a parameter this mechanism utilizes a DER-encoding of the object identifier. A mechanism parameter may be missed then parameters of the object identifier id-GostR3411-94-CryptoProParamSet [RFC 4357] (section 11.2) must be used.
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 146, GOST R 34.11-94: Data Length
|
Function |
Input length |
Digest length |
|
C_Digest |
Any |
32 bytes |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure are not used.
GOST R 34.11-94 HMAC mechanism, denoted CKM_GOSTR3411_HMAC, is a mechanism for signatures and verification. It uses the HMAC construction, based on the GOST R 34.11-94 hash function [GOST R 34.11-94] and core HMAC algorithm [RFC 2104]. The keys it uses are of generic key type CKK_GENERIC_SECRET or CKK_GOST28147.
To be conformed to GOST R 34.11-94 hash algorithm [GOST R 34.11-94] the block length of core HMAC algorithm is 32 bytes long (see [RFC 2104] section 2, and [RFC 4357] section 3).
As a parameter this mechanism utilizes a DER-encoding of the object identifier. A mechanism parameter may be missed then parameters of the object identifier id-GostR3411-94-CryptoProParamSet [RFC 4357] (section 11.2) must be used.
Signatures (MACs) produced by this mechanism are of 32 bytes long.
Constraints on the length of input and output data are summarized in the following table:
Table 147, GOST R 34.11-94 HMAC: Key And Data Length
|
Function |
Key type |
Data length |
Signature length |
|
C_Sign |
CKK_GENERIC_SECRET or CKK_GOST28147 |
Any |
32 byte |
|
C_Verify |
CKK_GENERIC_SECRET or CKK_GOST28147 |
Any |
32 bytes |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure are not used.
GOST R 34.10-2001 is a mechanism for single- and multiple-part signatures and verification, following the digital signature algorithm defined in [GOST R 34.10-2001].
This section defines the key type “CKK_GOSTR3410” for type CK_KEY_TYPE as used in the CKA_KEY_TYPE attribute of key objects and domain parameter objects.
Mechanisms:
CKM_GOSTR3410_KEY_PAIR_GEN
CKM_GOSTR3410
CKM_GOSTR3410_WITH_GOSTR3411
CKM_GOSTR3410
CKM_GOSTR3410_KEY_WRAP
CKM_GOSTR3410_DERIVE
GOST R 34.10-2001 public key objects (object class CKO_PUBLIC_KEY, key type CKK_GOSTR3410) hold GOST R 34.10-2001 public keys.
The following table defines the GOST R 34.10-2001 public key object attributes, in addition to the common attributes defined for this object class:
Table 148, GOST R 34.10-2001 Public Key Object Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_VALUE1,4 |
Byte array |
64 bytes for public key; 32 bytes for each coordinates X and Y of elliptic curve point P(X, Y) in little endian order |
|
CKA_GOSTR3410_PARAMS1,3 |
Byte array |
DER-encoding of the object identifier indicating the data object type of GOST R 34.10-2001. When key is used the domain parameter object of key type CKK_GOSTR3410 must be specified with the same attribute CKA_OBJECT_ID |
|
CKA_GOSTR3411_PARAMS1,3,8 |
Byte array |
DER-encoding of the object identifier indicating the data object type of GOST R 34.11-94. When key is used the domain parameter object of key type CKK_GOSTR3411 must be specified with the same attribute CKA_OBJECT_ID |
|
CKA_GOST28147_PARAMS8 |
Byte array |
DER-encoding of the object identifier indicating the data object type of GOST 28147‑89. When key is used the domain parameter object of key type CKK_GOST28147 must be specified with the same attribute CKA_OBJECT_ID. The attribute value may be omitted |
Refer to [PKCS #11-Base] Table 10 for footnotes
The following is a sample template for creating an GOST R 34.10-2001 public key object:
CK_OBJECT_CLASS class = CKO_PUBLIC_KEY;
CK_KEY_TYPE keyType = CKK_GOSTR3410;
CK_UTF8CHAR label[] = “A GOST R34.10-2001 public key object”;
CK_BYTE gostR3410params_oid[] =
{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x00};
CK_BYTE gostR3411params_oid[] =
{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1e, 0x00};
CK_BYTE gost28147params_oid[] =
{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x00};
CK_BYTE value[64] = {...};
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_GOSTR3410_PARAMS, gostR3410params_oid, sizeof(gostR3410params_oid)},
{CKA_GOSTR3411_PARAMS, gostR3411params_oid, sizeof(gostR3411params_oid)},
{CKA_GOST28147_PARAMS, gost28147params_oid, sizeof(gost28147params_oid)},
{CKA_VALUE, value, sizeof(value)}
};
GOST R 34.10-2001 private key objects (object class CKO_PRIVATE_KEY, key type CKK_GOSTR3410) hold GOST R 34.10-2001 private keys.
The following table defines the GOST R 34.10-2001 private key object attributes, in addition to the common attributes defined for this object class:
Table 149, GOST R 34.10-2001 Private Key Object Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_VALUE1,4,6,7 |
Byte array |
32 bytes for private key in little endian order |
|
CKA_GOSTR3410_PARAMS1,4,6 |
Byte array |
DER-encoding of the object identifier indicating the data object type of GOST R 34.10-2001. When key is used the domain parameter object of key type CKK_GOSTR3410 must be specified with the same attribute CKA_OBJECT_ID |
|
CKA_GOSTR3411_PARAMS1,4,6,8 |
Byte array |
DER-encoding of the object identifier indicating the data object type of GOST R 34.11-94. When key is used the domain parameter object of key type CKK_GOSTR3411 must be specified with the same attribute CKA_OBJECT_ID |
|
CKA_GOST28147_PARAMS44,6,8 |
Byte array |
DER-encoding of the object identifier indicating the data object type of GOST 28147‑89. When key is used the domain parameter object of key type CKK_GOST28147 must be specified with the same attribute CKA_OBJECT_ID. The attribute value may be omitted |
Refer to [PKCS #11-Base] Table 10 for footnotes
Note that when generating an GOST R 34.10-2001 private key, the GOST R 34.10-2001 domain parameters are not specified in the key’s template. This is because GOST R 34.10-2001 private keys are only generated as part of an GOST R 34.10-2001 key pair, and the GOST R 34.10-2001 domain parameters for the pair are specified in the template for the GOST R 34.10-2001 public key.
The following is a sample template for creating an GOST R 34.10-2001 private key object:
CK_OBJECT_CLASS class = CKO_PRIVATE_KEY;
CK_KEY_TYPE keyType = CKK_GOSTR3410;
CK_UTF8CHAR label[] = “A GOST R34.10-2001 private key object”;
CK_BYTE subject[] = {...};
CK_BYTE id[] = {123};
CK_BYTE gostR3410params_oid[] =
{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x00};
CK_BYTE gostR3411params_oid[] =
{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1e, 0x00};
CK_BYTE gost28147params_oid[] =
{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x1f, 0x00};
CK_BYTE value[32] = {...};
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_SUBJECT, subject, sizeof(subject)},
{CKA_ID, id, sizeof(id)},
{CKA_SENSITIVE, &true, sizeof(true)},
{CKA_SIGN, &true, sizeof(true)},
{CKA_GOSTR3410_PARAMS, gostR3410params_oid, sizeof(gostR3410params_oid)},
{CKA_GOSTR3411_PARAMS, gostR3411params_oid, sizeof(gostR3411params_oid)},
{CKA_GOST28147_PARAMS, gost28147params_oid, sizeof(gost28147params_oid)},
{CKA_VALUE, value, sizeof(value)}
};
GOST R 34.10-2001 domain parameter objects (object class CKO_DOMAIN_PARAMETERS, key type CKK_GOSTR3410) hold GOST R 34.10‑2001 domain parameters.
The following table defines the GOST R 34.10-2001 domain parameter object attributes, in addition to the common attributes defined for this object class:
Table 150, GOST R 34.10-2001 Domain Parameter Object Attributes
|
Attribute |
Data Type |
Meaning |
|
CKA_VALUE1 |
Byte array |
DER-encoding of the domain parameters as it was introduced in [4] section 8.4 (type GostR3410-2001-ParamSetParameters) |
|
CKA_OBJECT_ID1 |
Byte array |
DER-encoding of the object identifier indicating the domain parameters |
Refer to [PKCS #11-Base] Table 10 for footnotes
For any particular token, there is no guarantee that a token supports domain parameters loading up and/or fetching out. Furthermore, applications, that make direct use of domain parameters objects, should take in account that CKA_VALUE attribute may be inaccessible.
The following is a sample template for creating a GOST R 34.10-2001 domain parameter object:
CK_OBJECT_CLASS class = CKO_DOMAIN_PARAMETERS;
CK_KEY_TYPE keyType = CKK_GOSTR3410;
CK_UTF8CHAR label[] = “A GOST R34.10-2001 cryptographic parameters object”;
CK_BYTE oid[] =
{0x06, 0x07, 0x2a, 0x85, 0x03, 0x02, 0x02, 0x23, 0x00};
CK_BYTE value[] = {
0x30,0x81,0x90,0x02,0x01,0x07,0x02,0x20,0x5f,0xbf,0xf4,0x98,
0xaa,0x93,0x8c,0xe7,0x39,0xb8,0xe0,0x22,0xfb,0xaf,0xef,0x40,
0x56,0x3f,0x6e,0x6a,0x34,0x72,0xfc,0x2a,0x51,0x4c,0x0c,0xe9,
0xda,0xe2,0x3b,0x7e,0x02,0x21,0x00,0x80,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x04,0x31,0x02,0x21,0x00,0x80,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01,0x50,0xfe,
0x8a,0x18,0x92,0x97,0x61,0x54,0xc5,0x9c,0xfc,0x19,0x3a,0xcc,
0xf5,0xb3,0x02,0x01,0x02,0x02,0x20,0x08,0xe2,0xa8,0xa0,0xe6,
0x51,0x47,0xd4,0xbd,0x63,0x16,0x03,0x0e,0x16,0xd1,0x9c,0x85,
0xc9,0x7f,0x0a,0x9c,0xa2,0x67,0x12,0x2b,0x96,0xab,0xbc,0xea,
0x7e,0x8f,0xc8
};
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_OBJECT_ID, oid, sizeof(oid)},
{CKA_VALUE, value, sizeof(value)}
};
♦ CK_GOSTR3410_KEY_WRAP_PARAMS
CK_GOSTR3410_KEY_WRAP_PARAMS is a structure that provides the parameters to the CKM_GOSTR3410_KEY_WRAP mechanism.
It is defined as follows:
typedef struct CK_GOSTR3410_KEY_WRAP_PARAMS {
CK_BYTE_PTR pWrapOID;
CK_ULONG ulWrapOIDLen;
CK_BYTE_PTR pUKM;
CK_ULONG ulUKMLen;
CK_OBJECT_HANDLE hKey;
} CK_GOSTR3410_KEY_WRAP_PARAMS;
The fields of the structure have the following meanings:
|
pWrapOID |
|
pointer to a data with DER-encoding of the object identifier indicating the data object type of GOST 28147‑89. If pointer takes NULL_PTR value in C_WrapKey operation then parameters are specified in object identifier of attribute CKA_GOSTR3411_PARAMS must be used. For C_UnwrapKey operation the pointer is not used and must take NULL_PTR value anytime |
|
ulWrapOIDLen |
|
length of data with DER-encoding of the object identifier indicating the data object type of GOST 28147‑89 |
|
pUKM |
|
pointer to a data with UKM. If pointer takes NULL_PTR value in C_WrapKey operation then random value of UKM will be used. If pointer takes non-NULL_PTR value in C_UnwrapKey operation then the pointer value will be compared with UKM value of wrapped key. If these two values do not match the wrapped key will be rejected |
|
ulUKMLen |
|
length of UKM data. If pUKM-pointer is different from NULL_PTR then equal to 8 |
|
hKey |
|
key handle. Key handle of a sender for C_WrapKey operation. Key handle of a receiver for C_UnwrapKey operation. When key handle takes CK_INVALID_HANDLE value then an ephemeral (one time) key pair of a sender will be used |
CK_GOSTR3410_KEY_WRAP_PARAMS_PTR is a pointer to a CK_GOSTR3410_KEY_WRAP_PARAMS.
♦ CK_GOSTR3410_DERIVE_PARAMS
CK_GOSTR3410_DERIVE_PARAMS is a structure that provides the parameters to the CKM_GOSTR3410_DERIVE mechanism.
It is defined as follows:
typedef struct CK_GOSTR3410_DERIVE_PARAMS {
CK_EC_KDF_TYPE kdf;
CK_BYTE_PTR pPublicData;
CK_ULONG ulPublicDataLen;
CK_BYTE_PTR pUKM;
CK_ULONG ulUKMLen;
} CK_GOSTR3410_DERIVE_PARAMS;
The fields of the structure have the following meanings:
|
kdf |
|
additional key diversification algorithm identifier. Possible values are CKD_NULL and CKD_CPDIVERSIFY_KDF. In case of CKD_NULL, result of the key derivation function described in [RFC 4357], section 5.2 is used directly; In case of CKD_CPDIVERSIFY_KDF, the resulting key value is additionally processed with algorithm from [RFC 4357], section 6.5.
|
|
pPublicData1 |
|
pointer to data with public key of a receiver |
|
ulPublicDataLen |
|
length of data with public key of a receiver (must be 64) |
|
pUKM |
|
pointer to a UKM data |
|
ulUKMLen |
|
length of UKM data in bytes (must be 8) |
1 Public key of a receiver is an octet string of 64 bytes long. The public key octets correspond to the concatenation of X and Y coordinates of a point. Any one of them is 32 bytes long and represented in little endian order.
CK_GOSTR3410_DERIVE_PARAMS_PTR is a pointer to a CK_GOSTR3410_DERIVE_PARAMS.
The GOST R 34.10‑2001 key pair generation mechanism, denoted CKM_GOSTR3410_KEY_PAIR_GEN, is a key pair generation mechanism for GOST R 34.10‑2001.
This mechanism does not have a parameter.
The mechanism generates GOST R 34.10‑2001 public/private key pairs with particular GOST R 34.10‑2001 domain parameters, as specified in the CKA_GOSTR3410_PARAMS, CKA_GOSTR3411_PARAMS, and CKA_GOST28147_PARAMS attributes of the template for the public key. Note that CKA_GOST28147_PARAMS attribute may not be present in the template.
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_VALUE, and CKA_GOSTR3410_PARAMS, CKA_GOSTR3411_PARAMS, CKA_GOST28147_PARAMS attributes to the new private key.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure are not used.
The GOST R 34.10‑2001 without hashing mechanism, denoted CKM_GOSTR3410, is a mechanism for single-part signatures and verification for GOST R 34.10‑2001. (This mechanism corresponds only to the part of GOST R 34.10‑2001 that processes the 32-bytes hash value; it does not compute the hash value.)
This mechanism does not have a parameter.
For the purposes of these mechanisms, a GOST R 34.10‑2001 signature is an octet string of 64 bytes long. The signature octets correspond to the concatenation of the GOST R 34.10‑2001 values s and r’, both represented as a 32 bytes octet string in big endian order with the most significant byte first [RFC 4490] section 3.2, and [RFC 4491] section 2.2.2.
The input for the mechanism is an octet string of 32 bytes long with digest has computed by means of GOST R 34.11‑94 hash algorithm in the context of signed or should be signed message.
Table 151, GOST R 34.10-2001 without hashing: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
|
C_Sign1 |
CKK_GOSTR3410 |
32 bytes |
64 bytes |
|
C_Verify1 |
CKK_GOSTR3410 |
32 bytes |
64 bytes |
1 Single-part operations only.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure are not used.
The GOST R 34.10‑2001 with GOST R 34.11‑94, denoted CKM_GOSTR3410_WITH_GOSTR3411, is a mechanism for signatures and verification for GOST R 34.10‑2001. This mechanism computes the entire GOST R 34.10‑2001 specification, including the hashing with GOST R 34.11‑94 hash algorithm.
As a parameter this mechanism utilizes a DER-encoding of the object identifier indicating GOST R 34.11‑94 data object type. A mechanism parameter may be missed then parameters are specified in object identifier of attribute CKA_GOSTR3411_PARAMS must be used.
For the purposes of these mechanisms, a GOST R 34.10‑2001 signature is an octet string of 64 bytes long. The signature octets correspond to the concatenation of the GOST R 34.10‑2001 values s and r’, both represented as a 32 bytes octet string in big endian order with the most significant byte first [RFC 4490] section 3.2, and [RFC 4491] section 2.2.2.
The input for the mechanism is signed or should be signed message of any length. Single- and multiple-part signature operations are available.
Table 152, GOST R 34.10-2001 with GOST R 34.11-94: Key and Data Length
|
Function |
Key type |
Input length |
Output length |
|
C_Sign |
CKK_GOSTR3410 |
Any |
64 bytes |
|
C_Verify |
CKK_GOSTR3410 |
Any |
64 bytes |
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure are not used.
GOST R 34.10-2001 keys as a KEK (key encryption keys) for encryption GOST 28147 keys, denoted by CKM_GOSTR3410_KEY_WRAP, is a mechanism for key wrapping; and key unwrapping, based on GOST R 34.10-2001. Its purpose is to encrypt and decrypt keys have been generated by key generation mechanism for GOST 28147‑89. An encryption algorithm from [RFC 4490] (section 5.2) must be used. Encrypted key is a DER-encoded structure of ASN.1 GostR3410-KeyTransport type [RFC 4490] section 4.2.
It has a parameter, a CK_GOSTR3410_KEY_WRAP_PARAMS structure defined in section 2.45.5.
For unwrapping (C_UnwrapKey), the mechanism decrypts the wrapped key, and contributes the result as the CKA_VALUE attribute of the new key.
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure are not used.
Common key derivation, denoted CKM_GOSTR3410_DERIVE, is a mechanism for key derivation with assistance of GOST R 34.10‑2001 private and public keys. The key of the mechanism must be of object class CKO_DOMAIN_PARAMETERS and key type CKK_GOSTR3410. An algorithm for key derivation from [RFC 4357] (section 5.2) must be used.
The mechanism contributes the result as the CKA_VALUE attribute of the new private key. All other attributes must be specified in a template for creating private key object.
An implementation is a conforming implementation if it meets the conditions specified in one or more server profiles specified in [PKCS #11-Prof].