c_key_mgmt.h File Reference

#include <pkcs11/v2.40/cryptoki.h>

Include dependency graph for c_key_mgmt.h:

Functions
CK_RV	C_DeriveKey (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hBaseKey, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulAttributeCount, CK_OBJECT_HANDLE_PTR phKey)
	Derives a key from a base key, creating a new key object.
CK_RV	C_GenerateKey (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_OBJECT_HANDLE_PTR phKey)
	Generates a secret key or set of domain parameters, creating a new object.
CK_RV	C_GenerateKeyPair (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_ATTRIBUTE_PTR pPublicKeyTemplate, CK_ULONG ulPublicKeyAttributeCount, CK_ATTRIBUTE_PTR pPrivateKeyTemplate, CK_ULONG ulPrivateKeyAttributeCount, CK_OBJECT_HANDLE_PTR phPublicKey, CK_OBJECT_HANDLE_PTR phPrivateKey)
	Generates a public/private key pair, creating new key objects.
CK_RV	C_UnwrapKey (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hUnwrappingKey, CK_BYTE_PTR pWrappedKey, CK_ULONG ulWrappedKeyLen, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulAttributeCount, CK_OBJECT_HANDLE_PTR phKey)
	Unwraps (i.e., decrypts) a wrapped key, creating a new private key or secret key object.
CK_RV	C_WrapKey (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hWrappingKey, CK_OBJECT_HANDLE hKey, CK_BYTE_PTR pWrappedKey, CK_ULONG_PTR pulWrappedKeyLen)
	Wraps (i.e., encrypts) a private or secret key.

Function Documentation

C_DeriveKey()

CK_RV C_DeriveKey	(	CK_SESSION_HANDLE	hSession,
		CK_MECHANISM_PTR	pMechanism,
		CK_OBJECT_HANDLE	hBaseKey,
		CK_ATTRIBUTE_PTR	pTemplate,
		CK_ULONG	ulAttributeCount,
		CK_OBJECT_HANDLE_PTR	phKey )

Derives a key from a base key, creating a new key object.

Warning

This function is not supported.

Parameters

[in]	hSession	is the session's handle.
[in]	pMechanism	points to a structure that specifies the key derivation mechanism.
[in]	hBaseKey	is the handle of the base key.
[in]	pTemplate	points to the template for the new key.
[in]	ulAttributeCount	is the number of attributes in the template.
[out]	phKey	points to the location that receives the handle of the derived key.

The values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes for the base key affect the values that these attributes can hold for the newly-derived key. See the description of each particular key-derivation mechanism in Current Mechanisms Specification for any constraints of this type.

If a call to C_DeriveKey cannot support the precise template supplied to it, it will fail and return without creating any key object.

The key object created by a successful call to C_DeriveKey will have its CKA_LOCAL attribute set to CK_FALSE.

Returns

• CKR_OK on success.
• One of the following error codes on failure:
  CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN.

C_GenerateKey()

CK_RV C_GenerateKey	(	CK_SESSION_HANDLE	hSession,
		CK_MECHANISM_PTR	pMechanism,
		CK_ATTRIBUTE_PTR	pTemplate,
		CK_ULONG	ulCount,
		CK_OBJECT_HANDLE_PTR	phKey )

Generates a secret key or set of domain parameters, creating a new object.

Warning

This function is not supported.

Parameters

[in]	hSession	is the session's handle.
[in]	pMechanism	points to the generation mechanism.
[in]	pTemplate	points to the template for the new key or set of domain parameters.
[in]	ulCount	is the number of attributes in the template.
[out]	phKey	points to the location that receives the handle of the new key or set of domain parameters.

If the generation mechanism is for domain parameter generation, the CKA_CLASS attribute will have the value CKO_DOMAIN_PARAMETERS; otherwise, it will have the value CKO_SECRET_KEY.

Since the type of key or domain parameters to be generated is implicit in the generation mechanism, the template does not need to supply a key type. If it does supply a key type which is inconsistent with the generation mechanism, C_GenerateKey fails and returns the error code CKR_TEMPLATE_INCONSISTENT. The CKA_CLASS attribute is treated similarly.

If a call to C_GenerateKey cannot support the precise template supplied to it, it will fail and return without creating an object.

The object created by a successful call to C_GenerateKey will have its CKA_LOCAL attribute set to CK_TRUE.

Returns

• CKR_OK on success.
• One of the following error codes on failure:
  CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN.

C_GenerateKeyPair()

CK_RV C_GenerateKeyPair	(	CK_SESSION_HANDLE	hSession,
		CK_MECHANISM_PTR	pMechanism,
		CK_ATTRIBUTE_PTR	pPublicKeyTemplate,
		CK_ULONG	ulPublicKeyAttributeCount,
		CK_ATTRIBUTE_PTR	pPrivateKeyTemplate,
		CK_ULONG	ulPrivateKeyAttributeCount,
		CK_OBJECT_HANDLE_PTR	phPublicKey,
		CK_OBJECT_HANDLE_PTR	phPrivateKey )

Generates a public/private key pair, creating new key objects.

Parameters

[in]	hSession	is the session's handle.
[in]	pMechanism	points to the key generation mechanism.
[in]	pPublicKeyTemplate	points to the template for the public key.
[in]	ulPublicKeyAttributeCount	is the number of attributes in the public-key template.
[in]	pPrivateKeyTemplate	points to the template for the private key.
[in]	ulPrivateKeyAttributeCount	is the number of attributes in the private-key template.
[out]	phPublicKey	points to the location that receives the handle of the new public key.
[out]	phPrivateKey	points to the location that receives the handle of the new private key.

Note

The function currently supports only CKM_RSA_PKCS_KEY_PAIR_GEN and CKM_ECDSA_KEY_PAIR_GEN mechanisms. For CKM_RSA_PKCS_KEY_PAIR_GEN, the public key should include either the CKA_MODULUS_BITS or CKA_MODULUS attribute. If neither is found, 2048 is assumed. For CKM_ECDSA_KEY_PAIR_GEN, the public key template should include the CKA_EC_PARAMS attribute, which should be a DER-encoding of the curve OID. If it is not found, the NIST P-256 curve is assumed.

Note

A CKA_ID can be specified to generate a key pair with the specified ID or to overwrite an existing object with the same ID.
The PKCS#11 Specification v2.40 states that the CKA_ID should be equal to SKI (Subject Key Identifier) extension of the associated certificate. So if a certificate for this key-pair is requested, it's SKI extension should match the CKA_ID.
Additional methods for computing the SKI can be found in RFC7093.

If no CKA_ID is specified or found, the system will attempt to match the objects based on the public key value. If no match is found, the first available slot permitted for the current role will be used. Note that this logic may be subject to change in future versions.

Since the types of keys to be generated are implicit in the key pair generation mechanism, the templates do not need to supply key types. If one of the templates does supply a key type which is inconsistent with the key generation mechanism, C_GenerateKeyPair fails and returns the error code CKR_TEMPLATE_INCONSISTENT. The CKA_CLASS attribute is treated similarly.

If a call to C_GenerateKeyPair cannot support the precise templates supplied to it, it will fail and return without creating any key objects.

A call to C_GenerateKeyPair will never create just one key and return. A call can fail, and create no keys; or it can succeed, and create a matching public/private key pair.

The key objects created by a successful call to C_GenerateKeyPair will have their CKA_LOCAL attributes set to CK_TRUE.

Note carefully the order of the arguments to C_GenerateKeyPair. The last two arguments do not have the same order as they did in the original Cryptoki Version 1.0 document. The order of these two arguments has caused some unfortunate confusion.

Returns

• CKR_OK on success.
• One of the following error codes on failure:
  CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN.

C_UnwrapKey()

CK_RV C_UnwrapKey	(	CK_SESSION_HANDLE	hSession,
		CK_MECHANISM_PTR	pMechanism,
		CK_OBJECT_HANDLE	hUnwrappingKey,
		CK_BYTE_PTR	pWrappedKey,
		CK_ULONG	ulWrappedKeyLen,
		CK_ATTRIBUTE_PTR	pTemplate,
		CK_ULONG	ulAttributeCount,
		CK_OBJECT_HANDLE_PTR	phKey )

Unwraps (i.e., decrypts) a wrapped key, creating a new private key or secret key object.

Warning

This function is not supported.

Parameters

[in]	hSession	is the session's handle.
[in]	pMechanism	points to the unwrapping mechanism.
[in]	hUnwrappingKey	is the handle of the unwrapping key.
[in]	pWrappedKey	points to the wrapped key.
[in]	ulWrappedKeyLen	is the length of the wrapped key.
[in]	pTemplate	points to the template for the new key.
[in]	ulAttributeCount	is the number of attributes in the template.
[out]	phKey	points to the location that receives the handle of the recovered key.

The CKA_UNWRAP attribute of the unwrapping key, which indicates whether the key supports unwrapping, MUST be CK_TRUE.

The new key will have the CKA_ALWAYS_SENSITIVE attribute set to CK_FALSE, and the CKA_NEVER_EXTRACTABLE attribute set to CK_FALSE. The CKA_EXTRACTABLE attribute is by default set to CK_TRUE.

Some mechanisms may modify, or attempt to modify. the contents of the pMechanism structure at the same time that the key is unwrapped.

If a call to C_UnwrapKey cannot support the precise template supplied to it, it will fail and return without creating any key object.

The key object created by a successful call to C_UnwrapKey will have its CKA_LOCAL attribute set to CK_FALSE.

To partition the unwrapping keys so they can only unwrap a subset of keys the attribute CKA_UNWRAP_TEMPLATE can be used on the unwrapping key to specify an attribute set that will be added to attributes of the key to be unwrapped. If the attributes do not conflict with the user supplied attribute template, in pTemplate, then the unwrap will proceed. The value of this attribute is an attribute template and the size is the number of items in the template times the size of CK_ATTRIBUTE. If this attribute is not present on the unwrapping key then no additional attributes will be added. If any attribute conflict occurs on an attempt to unwrap a key then the function SHALL return CKR_TEMPLATE_INCONSISTENT.

Returns

• CKR_OK on success.
• One of the following error codes on failure:
  CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY, CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_CURVE_NOT_SUPPORTED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY, CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT, CKR_TOKEN_WRITE_PROTECTED, CKR_UNWRAPPING_KEY_HANDLE_INVALID, CKR_UNWRAPPING_KEY_SIZE_RANGE, CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT, CKR_USER_NOT_LOGGED_IN, CKR_WRAPPED_KEY_INVALID, CKR_WRAPPED_KEY_LEN_RANGE.

C_WrapKey()

CK_RV C_WrapKey	(	CK_SESSION_HANDLE	hSession,
		CK_MECHANISM_PTR	pMechanism,
		CK_OBJECT_HANDLE	hWrappingKey,
		CK_OBJECT_HANDLE	hKey,
		CK_BYTE_PTR	pWrappedKey,
		CK_ULONG_PTR	pulWrappedKeyLen )

Wraps (i.e., encrypts) a private or secret key.

Warning

This function is not supported.

Parameters

[in]	hSession	is the session's handle.
[in]	pMechanism	points to the wrapping mechanism.
[in]	hWrappingKey	is the handle of the wrapping key.
[in]	hKey	is the handle of the key to be wrapped.
[out]	pWrappedKey	points to the location that receives the wrapped key.
[in,out]	pulWrappedKeyLen	points to the location that receives the length of the wrapped key.

C_WrapKey uses the convention described in Section 5.2 on producing output.

The CKA_WRAP attribute of the wrapping key, which indicates whether the key supports wrapping, MUST be CK_TRUE. The CKA_EXTRACTABLE attribute of the key to be wrapped MUST also be CK_TRUE.

If the key to be wrapped cannot be wrapped for some token-specific reason, despite its having its CKA_EXTRACTABLE attribute set to CK_TRUE, then C_WrapKey fails with error code CKR_KEY_NOT_WRAPPABLE. If it cannot be wrapped with the specified wrapping key and mechanism solely because of its length, then C_WrapKey fails with error code CKR_KEY_SIZE_RANGE.

C_WrapKey can be used in the following situations:

• To wrap any secret key with a public key that supports encryption and decryption.
• To wrap any secret key with any other secret key. Consideration MUST be given to key size and mechanism strength or the token may not allow the operation.
• To wrap a private key with any secret key.

Of course, tokens vary in which types of keys can actually be wrapped with which mechanisms.

To partition the wrapping keys so they can only wrap a subset of extractable keys the attribute CKA_WRAP_TEMPLATE can be used on the wrapping key to specify an attribute set that will be compared against the attributes of the key to be wrapped. If all attributes match according to the C_FindObjects rules of attribute matching then the wrap will proceed. The value of this attribute is an attribute template and the size is the number of items in the template times the size of CK_ATTRIBUTE. If this attribute is not supplied then any template is acceptable. If an attribute is not present, it will not be checked. If any attribute mismatch occurs on an attempt to wrap a key then the function SHALL return CKR_KEY_HANDLE_INVALID.

Returns

• CKR_OK on success.
• One of the following error codes on failure:
  CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_HANDLE_INVALID, CKR_KEY_NOT_WRAPPABLE, CKR_KEY_SIZE_RANGE, CKR_KEY_UNEXTRACTABLE, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, CKR_WRAPPING_KEY_HANDLE_INVALID, CKR_WRAPPING_KEY_SIZE_RANGE, CKR_WRAPPING_KEY_TYPE_INCONSISTENT.