HID® Crescendo® PKCS11
|
#include <pkcs11/v2.40/cryptoki.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) |
C_DeriveKey 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) |
C_GenerateKey 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) |
C_GenerateKeyPair 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) |
C_UnwrapKey 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) |
C_WrapKey wraps (i.e., encrypts) a private or secret key. | |
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 ) |
C_DeriveKey derives a key from a base key, creating a new key object.
hSession
is the session's handle; pMechanism
points to a structure that specifies the key derivation mechanism; hBaseKey
is the handle of the base key; pTemplate
points to the template for the new key; ulAttributeCount
is the number of attributes in the template; and 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 Section 5.16.2 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.
Return values: 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_OK, 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.
CK_RV C_GenerateKey | ( | CK_SESSION_HANDLE | hSession, |
CK_MECHANISM_PTR | pMechanism, | ||
CK_ATTRIBUTE_PTR | pTemplate, | ||
CK_ULONG | ulCount, | ||
CK_OBJECT_HANDLE_PTR | phKey ) |
C_GenerateKey generates a secret key or set of domain parameters, creating a new object.
hSession
is the session's handle; pMechanism
points to the generation mechanism; pTemplate
points to the template for the new key or set of domain parameters; ulCount
is the number of attributes in the template; 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.
Return values: 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_OK, 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.
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 ) |
C_GenerateKeyPair generates a public/private key pair, creating new key objects.
hSession
is the session's handle; pMechanism
points to the key generation mechanism; pPublicKeyTemplate
points to the template for the public key; ulPublicKeyAttributeCount
is the number of attributes in the public-key template; pPrivateKeyTemplate
points to the template for the private key; ulPrivateKeyAttributeCount
is the number of attributes in the private-key template; phPublicKey
points to the location that receives the handle of the new public key; phPrivateKey
points to the location that receives the handle of the new private key.
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.
Return values: 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_OK, 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.
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 ) |
C_UnwrapKey unwraps (i.e., decrypts) a wrapped key, creating a new private key or secret key object.
hSession
is the session's handle; pMechanism
points to the unwrapping mechanism; hUnwrappingKey
is the handle of the unwrapping key; pWrappedKey
points to the wrapped key; ulWrappedKeyLen
is the length of the wrapped key; pTemplate
points to the template for the new key; ulAttributeCount
is the number of attributes in the template; 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.
Return values: 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_OK, 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.
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 ) |
C_WrapKey wraps (i.e., encrypts) a private or secret key.
hSession
is the session's handle; pMechanism
points to the wrapping mechanism; hWrappingKey
is the handle of the wrapping key; hKey
is the handle of the key to be wrapped; pWrappedKey
points to the location that receives the wrapped key; and 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:
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.
Return Values: 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_OK, 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.