PKCS#11
|
| Cryptographic Token Interface Standard |
PKCS#11 |
Go to the source code of this file.
Data Structures | |
| CK_VERSION | |
CK_VERSIONCK_VERSION is a structure that describes the version of a Cryptoki interface, a Cryptoki library, an SSL implementation, or the hardware or firmware version of a slot or token. More... | |
| CK_INFO | |
CK_INFOCK_INFO provides general information about Cryptoki. More... | |
| CK_SLOT_INFO | |
CK_SLOT_INFOCK_SLOT_INFO provides information about a slot. More... | |
| CK_TOKEN_INFO | |
CK_TOKEN_INFOCK_TOKEN_INFO provides information about a token. More... | |
| CK_SESSION_INFO | |
CK_SESSION_INFOCK_SESSION_INFO provides information about a session. More... | |
| CK_ATTRIBUTE | |
CK_ATTRIBUTECK_ATTRIBUTE is a structure that includes the type, length and value of an attribute. More... | |
| CK_DATE | |
CK_DATECK_DATE is a structure that defines a date. More... | |
| CK_MECHANISM | |
CK_MECHANISMCK_MECHANISM is a structure that specifies a particular mechanism. More... | |
| CK_MECHANISM_INFO | |
CK_MECHANISM_INFOCK_MECHANISM_INFO is a structure that provides information about a particular mechanism. More... | |
| CK_FUNCTION_LIST | |
CK_FUNCTION_LISTCK_FUNCTION_LIST is a structure which contains a Cryptoki version and a function pointer to each function in the Cryptoki API. More... | |
| CK_KEA_DERIVE | |
CK_KEA_DERIVE_PARAMSCK_KEA_DERIVE_PARAMS is a structure that provides the parameters to the CKM_KEA_DERIVE mechanism. More... | |
| CK_MAYFLY_DERIVE | |
CK_MAYFLY_DERIVE_PARAMSCK_MAYFLY_DERIVE_PARAMS is a structure that provides the parameters to the CKM_MAYFLY_DERIVE mechanism. More... | |
| CK_RC2_CBC_PARAMS | |
CK_RC2_CBC_PARAMSCK_RC2_CBC_PARAMS is a structure that provides the parameters to the CKM_RC2_CBC and CKM_RC2_CBC_PAD mechanisms. More... | |
| CK_RC2_MAC_GENERAL_PARAMS | |
CK_RC2_MAC_GENERAL_PARAMSCK_RC2_MAC_GENERAL_PARAMS is a structure that provides the parameters to the CKM_RC2_MAC_GENERAL mechanism. More... | |
| CK_RC5_CBC_PARAMS | |
CK_RC5_CBC_PARAMSCK_RC5_CBC_PARAMS is a structure that provides the parameters to the CKM_RC5_CBC and CKM_RC5_CBC_PAD mechanisms. More... | |
| CK_RC5_MAC_GENERAL_PARAMS | |
CK_RC5_MAC_GENERAL_PARAMSCK_RC5_MAC_GENERAL_PARAMS is a structure that provides the parameters to the CKM_RC5_MAC_GENERAL mechanism. More... | |
| CK_SKIPJACK_PRIVATE_WRAP_PARAMS | |
CK_SKIPJACK_PRIVATE_WRAP_PARAMSCK_SKIPJACK_PRIVATE_WRAP_PARAMS is a structure that provides the parameters to the CKM_SKIPJACK_PRIVATE_WRAP mechanism. More... | |
| CK_SKIPJACK_RELAYX_PARAMS | |
CK_SKIPJACK_RELAYX_PARAMSCK_SKIPJACK_RELAYX_PARAMS is a structure that provides the parameters to the CKM_SKIPJACK_RELAYX mechanism. More... | |
| CK_PBE_PARAMS | |
CK_PBE_PARAMSCK_PBE_PARAMS is a structure which provides all of the necessary information required by the CKM_PBE mechanisms (see PKCS#5 for information on the PBE generation mechanisms). More... | |
| CK_KEY_WRAP_SET_OAEP_PARAMS | |
CK_KEY_WRAP_SET_OAEP_PARAMSCK_KEY_WRAP_SET_OAEP_PARAMS is a structure that provides the parameters to the CKM_KEY_WRAP_SET_OAEP mechanism. More... | |
| CK_SSL3_RANDOM_DATA | |
CK_SSL3_RANDOM_DATACK_SSL3_RANDOM_DATA is a structure which provides information about the random data of a client and a server in an SSL context. More... | |
| CK_SSL3_MASTER_KEY_DERIVE_PARAMS | |
| CK_SSL3_KEY_MAT_OUT | |
CK_SSL3_KEY_MAT_OUTCK_SSL3_KEY_MAT_OUT is a structure that contains the resulting key handles after performing a C_DeriveKey function with the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. More... | |
| CK_SSL3_KEY_MAT_PARAMS | |
CK_SSL3_KEY_MAT_PARAMSCK_SSL3_KEY_MAT_PARAMS is a structure that provides the parameters to the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. More... | |
| CK_KEY_DERIVATION_STRING_DATA | |
CK_KEY_DERIVATION_STRING_DATA. More... | |
Defines | |
| #define | CK_INVALID_HANDLE |
| An invalid handle. More... | |
| #define | CK_TRUE |
| CK_BBOOL true. More... | |
| #define | CK_FALSE |
| CK_BBOOL false. More... | |
| #define | CK_UNAVAILABLE_INFORMATION |
| Information unavailable. More... | |
| #define | CK_EFFECTIVELY_INFINITE |
| Effectively infinite. More... | |
| #define | CKU_SO |
| Security Officer. More... | |
| #define | CKU_USER |
| User. More... | |
| #define | CKU_CONTEXT_SPECIFIC |
| Context specific. More... | |
| #define | CKS_RO_PUBLIC_SESSION |
| Read only public session. More... | |
| #define | CKS_RO_USER_FUNCTIONS |
| Read only user functions. More... | |
| #define | CKS_RW_PUBLIC_SESSION |
| Read write public session. More... | |
| #define | CKS_RW_USER_FUNCTIONS |
| Read write user functions. More... | |
| #define | CKS_RW_SO_FUNCTIONS |
| Read write security officer functions. More... | |
| #define | TRUE |
| True. More... | |
| #define | FALSE |
| False. More... | |
| #define | CKF_TOKEN_PRESENT |
| TRUE if a token is present in the slot (''e.g.'', a device is in the reader). More... | |
| #define | CKF_REMOVABLE_DEVICE |
| TRUE if the reader supports removable devices. More... | |
| #define | CKF_HW_SLOT |
| TRUE if the slot is a hardware slot, as opposed to a software slot implementing a "soft token". More... | |
| #define | CKF_RNG |
| TRUE if the token has its own random number generator. More... | |
| #define | CKF_WRITE_PROTECTED |
| TRUE if the token is write-protected. More... | |
| #define | CKF_LOGIN_REQUIRED |
| TRUE if a user must be logged in to perform cryptographic functions. More... | |
| #define | CKF_USER_PIN_INITIALIZED |
| TRUE if the normal user's PIN has been initialized. More... | |
| #define | CKF_EXCLUSIVE_EXISTS |
| TRUE if an exclusive session exists. More... | |
| #define | CKF_RESTORE_KEY_NOT_NEEDED |
| TRUE if a successful save of a session's cryptographic operations state always contains all keys needed to restore the state of the session. More... | |
| #define | CKF_CLOCK_ON_TOKEN |
| TRUE if token has its own hardware clock. More... | |
| #define | CKF_SUPPORTS_PARALLEL |
| TRUE if token supports parallel sessions through this Cryptoki library. More... | |
| #define | CKF_PROTECTED_AUTHENTICATION_PATH |
| TRUE if token has a "protected authentication path", whereby a user can log in to the token without passing a PIN through the Cryptoki library. More... | |
| #define | CKF_DUAL_CRYPTO_OPERATIONS |
| TRUE if a single session with the token can perform dual cryptographic operations (see Section ). More... | |
| #define | CKF_EXCLUSIVE_SESSION |
| TRUE if the session is exclusive; FALSE if the session is shared. More... | |
| #define | CKF_RW_SESSION |
| TRUE if the session is read/write; FALSE if the session is read-only. More... | |
| #define | CKF_SERIAL_SESSION |
| TRUE if cryptographic functions are performed in serial with the application; FALSE if the functions may be performed in parallel with the application. More... | |
| #define | CKF_INSERTION_CALLBACK |
| this flag is write-only, ''i.e.'', is supplied as an argument to a '''C_OpenSession''' call, but is never set in a session's '''CK_SESSION_INFO''' structure. More... | |
| #define | CKF_HW |
| TRUE if the mechanism is performed by the device; FALSE if the mechanism is performed in software. More... | |
| #define | CKF_ENCRYPT |
| TRUE if the mechanism can be used with '''C_EncryptInit'''. More... | |
| #define | CKF_DECRYPT |
| TRUE if the mechanism can be used with '''C_DecryptInit'''. More... | |
| #define | CKF_DIGEST |
| TRUE if the mechanism can be used with '''C_DigestInit'''. More... | |
| #define | CKF_SIGN |
| TRUE if the mechanism can be used with '''C_SignInit'''. More... | |
| #define | CKF_SIGN_RECOVER |
| TRUE if the mechanism can be used with '''C_SignRecoverInit'''. More... | |
| #define | CKF_VERIFY |
| TRUE if the mechanism can be used with '''C_VerifyInit'''. More... | |
| #define | CKF_VERIFY_RECOVER |
| TRUE if the mechanism can be used with '''C_VerifyRecoverInit'''. More... | |
| #define | CKF_GENERATE |
| TRUE if the mechanism can be used with '''C_GenerateKey'''. More... | |
| #define | CKF_GENERATE_KEY_PAIR |
| TRUE if the mechanism can be used with '''C_GenerateKeyPair'''. More... | |
| #define | CKF_WRAP |
| TRUE if the mechanism can be used with '''C_WrapKey'''. More... | |
| #define | CKF_UNWRAP |
| TRUE if the mechanism can be used with '''C_UnwrapKey'''. More... | |
| #define | CKF_DERIVE |
| TRUE if the mechanism can be used with '''C_DeriveKey'''. More... | |
| #define | CKF_EXTENSION |
| TRUE if an extension to the flags; FALSE if no extensions. More... | |
| #define | CKA_CLASS |
| Object class (type). More... | |
| #define | CKA_TOKEN |
| TRUE if object is a token object; FALSE if object is a session object (default FALSE). More... | |
| #define | CKA_PRIVATE |
| TRUE if object is a private object; FALSE if object is a public object (default FALSE). More... | |
| #define | CKA_MODIFIABLE |
| TRUE if object can be modified (default TRUE). More... | |
| #define | CKA_LABEL |
| Description of the object (default empty). More... | |
| #define | CKA_APPLICATION |
| Description of the application that manages the object (default empty). More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_CERTIFICATE_TYPE |
| Type of certificate. More... | |
| #define | CKA_SUBJECT |
| DER encoding of the certificate subject name. More... | |
| #define | CKA_ID |
| Key identifier for public/private key pair (default empty). More... | |
| #define | CKA_ISSUER |
| DER encoding of the certificate issuer name (default empty). More... | |
| #define | CKA_SERIAL_NUMBER |
| DER encoding of the certificate serial number (default empty). More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_KEY_TYPE |
| Type of key. More... | |
| #define | CKA_ID |
| Key identifier for public/private key pair (default empty). More... | |
| #define | CKA_START_DATE |
| Start date for the key (default empty). More... | |
| #define | CKA_END_DATE |
| End date for the key (default empty). More... | |
| #define | CKA_DERIVE |
| TRUE if key supports key derivation (default FALSE). More... | |
| #define | CKA_LOCAL |
| TRUE if key was generated locally (''i.e.'', on token). More... | |
| #define | CKA_SUBJECT |
| DER encoding of the certificate subject name. More... | |
| #define | CKA_ENCRYPT |
| TRUE if key supports encryption9. More... | |
| #define | CKA_VERIFY |
| TRUE if key supports verification9. More... | |
| #define | CKA_VERIFY_RECOVER |
| TRUE if key supports verification where the data is recovered from the signature9. More... | |
| #define | CKA_WRAP |
| TRUE if key supports wrapping9. More... | |
| #define | CKA_MODULUS |
| Modulus ''n''. More... | |
| #define | CKA_MODULUS_BITS |
| Length in bits of modulus ''n''. More... | |
| #define | CKA_PUBLIC_EXPONENT |
| Public exponent ''e''. More... | |
| #define | CKA_PRIME |
| Prime ''p'' (512 to 1024 bits, in steps of 64 bits). More... | |
| #define | CKA_SUBPRIME |
| Subprime ''q'' (160 bits). More... | |
| #define | CKA_BASE |
| Base ''g''. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_PRIME |
| Prime ''p'' (512 to 1024 bits, in steps of 64 bits). More... | |
| #define | CKA_SUBPRIME |
| Subprime ''q'' (160 bits). More... | |
| #define | CKA_BASE |
| Base ''g''. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_PRIME |
| Prime ''p'' (512 to 1024 bits, in steps of 64 bits). More... | |
| #define | CKA_BASE |
| Base ''g''. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_PRIME |
| Prime ''p'' (512 to 1024 bits, in steps of 64 bits). More... | |
| #define | CKA_SUBPRIME |
| Subprime ''q'' (160 bits). More... | |
| #define | CKA_BASE |
| Base ''g''. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_PRIME |
| Prime ''p'' (512 to 1024 bits, in steps of 64 bits). More... | |
| #define | CKA_SUBPRIME |
| Subprime ''q'' (160 bits). More... | |
| #define | CKA_BASE |
| Base ''g''. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_SUBJECT |
| DER encoding of the certificate subject name. More... | |
| #define | CKA_SENSITIVE |
| TRUE if key is sensitive9. More... | |
| #define | CKA_DECRYPT |
| TRUE if key supports decryption9. More... | |
| #define | CKA_SIGN |
| TRUE if key supports signatures where the signature is an appendix to the data9. More... | |
| #define | CKA_SIGN_RECOVER |
| TRUE if key supports signatures where the data can be recovered from the signature9. More... | |
| #define | CKA_UNWRAP |
| TRUE if key supports unwrapping9. More... | |
| #define | CKA_EXTRACTABLE |
| TRUE if key is extractable9. More... | |
| #define | CKA_ALWAYS_SENSITIVE |
| TRUE if key has ''always'' had the CKA_SENSITIVE attribute set to TRUE. More... | |
| #define | CKA_NEVER_EXTRACTABLE |
| TRUE if key has ''never'' had the CKA_EXTRACTABLE attribute set to TRUE. More... | |
| #define | CKA_MODULUS |
| Modulus ''n''. More... | |
| #define | CKA_PUBLIC_EXPONENT |
| Public exponent ''e''. More... | |
| #define | CKA_PRIVATE_EXPONENT |
| Private exponent ''d''. More... | |
| #define | CKA_PRIME_1 |
| Prime ''p''. More... | |
| #define | CKA_PRIME_2 |
| Prime ''q''. More... | |
| #define | CKA_EXPONENT_1 |
| Private exponent ''d'' modulo ''p''-1. More... | |
| #define | CKA_EXPONENT_2 |
| Private exponent ''d'' modulo ''q''-1. More... | |
| #define | CKA_COEFFICIENT |
| CRT coefficient ''q''-1 mod ''p''. More... | |
| #define | CKA_PRIME |
| Prime ''p'' (512 to 1024 bits, in steps of 64 bits). More... | |
| #define | CKA_SUBPRIME |
| Subprime ''q'' (160 bits). More... | |
| #define | CKA_BASE |
| Base ''g''. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_PRIME |
| Prime ''p'' (512 to 1024 bits, in steps of 64 bits). More... | |
| #define | CKA_SUBPRIME |
| Subprime ''q'' (160 bits). More... | |
| #define | CKA_BASE |
| Base ''g''. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_PRIME |
| Prime ''p'' (512 to 1024 bits, in steps of 64 bits). More... | |
| #define | CKA_BASE |
| Base ''g''. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE_BITS |
| Length in bits of private value ''x''. More... | |
| #define | CKA_PRIME |
| Prime ''p'' (512 to 1024 bits, in steps of 64 bits). More... | |
| #define | CKA_SUBPRIME |
| Subprime ''q'' (160 bits). More... | |
| #define | CKA_BASE |
| Base ''g''. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_PRIME |
| Prime ''p'' (512 to 1024 bits, in steps of 64 bits). More... | |
| #define | CKA_SUBPRIME |
| Subprime ''q'' (160 bits). More... | |
| #define | CKA_BASE |
| Base ''g''. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_SENSITIVE |
| TRUE if key is sensitive9. More... | |
| #define | CKA_ENCRYPT |
| TRUE if key supports encryption9. More... | |
| #define | CKA_DECRYPT |
| TRUE if key supports decryption9. More... | |
| #define | CKA_SIGN |
| TRUE if key supports signatures where the signature is an appendix to the data9. More... | |
| #define | CKA_VERIFY |
| TRUE if key supports verification9. More... | |
| #define | CKA_WRAP |
| TRUE if key supports wrapping9. More... | |
| #define | CKA_UNWRAP |
| TRUE if key supports unwrapping9. More... | |
| #define | CKA_EXTRACTABLE |
| TRUE if key is extractable9. More... | |
| #define | CKA_ALWAYS_SENSITIVE |
| TRUE if key has ''always'' had the CKA_SENSITIVE attribute set to TRUE. More... | |
| #define | CKA_NEVER_EXTRACTABLE |
| TRUE if key has ''never'' had the CKA_EXTRACTABLE attribute set to TRUE. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE_LEN |
| Length in bytes of key value. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE_LEN |
| Length in bytes of key value. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE_LEN |
| Length in bytes of key value. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE_LEN |
| Length in bytes of key value. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE_LEN |
| Length in bytes of key value. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE_LEN |
| Length in bytes of key value. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE_LEN |
| Length in bytes of key value. More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKA_VALUE |
| Value of the object (default empty). More... | |
| #define | CKR_GENERAL_ERROR |
| Some horrible, unrecoverable error has occurred. More... | |
| #define | CKR_HOST_MEMORY |
| The computer that the Cryptoki library is running on has insufficient memory to perform the requested function. More... | |
| #define | CKR_FUNCTION_FAILED |
| The requested function could not be performed, but detailed information about why not is not available in this error return. More... | |
| #define | CKR_OK |
| The function executed successfully. More... | |
| #define | CKR_SESSION_HANDLE_INVALID |
| The specified session handle was invalid ''at the time that the function was invoked''. More... | |
| #define | CKR_DEVICE_REMOVED |
| The token was removed from its slot ''during the execution of the function''. More... | |
| #define | CKR_SESSION_CLOSED |
| The session was closed ''during the execution of the function''. More... | |
| #define | CKR_DEVICE_MEMORY |
| The token does not have sufficient memory to perform the requested function. More... | |
| #define | CKR_DEVICE_ERROR |
| Some problem has occurred with the token and/or slot. More... | |
| #define | CKR_TOKEN_NOT_PRESENT |
| The token was not present in its slot ''at the time that the function was invoked''. More... | |
| #define | CKR_DEVICE_REMOVED |
| The token was removed from its slot ''during the execution of the function''. More... | |
| #define | CKR_ATTRIBUTE_READ_ONLY |
| An attempt was made to set a value for an attribute which may not be set, or which may not be modified. More... | |
| #define | CKR_ATTRIBUTE_SENSITIVE |
| An attempt was made to obtain the value of an attribute of an object which cannot be satisfied because the object is either sensitive or unextractable. More... | |
| #define | CKR_ATTRIBUTE_TYPE_INVALID |
| An invalid attribute type was specified in a template. More... | |
| #define | CKR_ATTRIBUTE_VALUE_INVALID |
| An invalid value was specified for an attribute in a template. More... | |
| #define | CKR_BUFFER_TOO_SMALL |
| The output of the function does not fit in the supplied buffer. More... | |
| #define | CKR_CANCEL |
| This is a value for an application callback to return. More... | |
| #define | CKR_DATA_INVALID |
| The plaintext input data to a cryptographic operation is invalid. More... | |
| #define | CKR_DATA_LEN_RANGE |
| The plaintext input data to a cryptographic operation has a bad length. More... | |
| #define | CKR_ENCRYPTED_DATA_INVALID |
| The encrypted input to a decryption operation has been determined to be invalid ciphertext. More... | |
| #define | CKR_ENCRYPTED_DATA_LEN_RANGE |
| The ciphertext input to a decryption operation has been determined to be invalid ciphertext solely on the basis of its length. More... | |
| #define | CKR_FUNCTION_CANCELED |
| The function was canceled in mid-execution. More... | |
| #define | CKR_FUNCTION_NOT_PARALLEL |
| There is currently no function executing in parallel in the specified session. More... | |
| #define | CKR_FUNCTION_NOT_SUPPORTED |
| The requested function is not supported by this Cryptoki library. More... | |
| #define | CKR_FUNCTION_PARALLEL |
| There is currently a function executing in parallel in the specified session. More... | |
| #define | CKR_INFORMATION_SENSITIVE |
| The information requested could not be obtained because the token considers it sensitive, and is not able or willing to reveal it. More... | |
| #define | CKR_INSERTION_CALLBACK_NOT_SUPPORTED |
| The specified slot does not support setting an application callback for token insertion. More... | |
| #define | CKR_KEY_CHANGED |
| One of the keys specified in a '''C_SetOperationState''' operation is not the same key that was being used in the original saved session. More... | |
| #define | CKR_KEY_FUNCTION_NOT_PERMITTED |
| An attempt has been made to use a key for a cryptographic purpose that the key's attributes are not set to allow it to do. More... | |
| #define | CKR_KEY_HANDLE_INVALID |
| The specified key handle is not valid. More... | |
| #define | CKR_KEY_INDIGESTIBLE |
| The value of the specified key cannot be digested for some reason (perhaps the key isn't a secret key, or perhaps the token simply can't digest this kind of key). More... | |
| #define | CKR_KEY_NEEDED |
| The '''C_SetOperationState''' operation cannot be carried out because it needs to be supplied with a key that was being used in the original saved session. More... | |
| #define | CKR_KEY_NOT_NEEDED |
| An extraneous key was supplied to '''C_SetOperationState'''. More... | |
| #define | CKR_KEY_NOT_WRAPPABLE |
| Although the specified private or secret key does not have its CKA_UNEXTRACTABLE attribute set to TRUE, Cryptoki (or the token) is unable to wrap the key as requested (possibly the token simply won't support it). More... | |
| #define | CKR_KEY_SIZE_RANGE |
| Although the requested keyed cryptographic operation could in principal be carried out, this Cryptoki library (or the token) is unable to actually do it because the supplied key 's size is outside the range of key sizes that it can handle. More... | |
| #define | CKR_KEY_TYPE_INCONSISTENT |
| The specified key is not the correct type of key to use with the specified mechanism. More... | |
| #define | CKR_KEY_UNEXTRACTABLE |
| The specified private or secret key can't be wrapped because its CKA_UNEXTRACTABLE attribute is set to TRUE. More... | |
| #define | CKR_MECHANISM_INVALID |
| An invalid mechanism was specified to the cryptographic operation. More... | |
| #define | CKR_MECHANISM_PARAM_INVALID |
| Invalid parameters were supplied to the mechanism specified to the cryptographic operation. More... | |
| #define | CKR_OBJECT_HANDLE_INVALID |
| The specified object handle is not valid. More... | |
| #define | CKR_OPERATION_ACTIVE |
| There is already an active operation (or combination of active operations) which prevents Cryptoki from activating the specified operation. More... | |
| #define | CKR_OPERATION_NOT_INITIALIZED |
| There is no active operation of an appropriate type in the specified session. More... | |
| #define | CKR_PIN_INCORRECT |
| The specified PIN is wrong, and does not match the PIN stored on the token. More... | |
| #define | CKR_PIN_INVALID |
| The specified PIN has invalid characters in it. More... | |
| #define | CKR_PIN_LEN_RANGE |
| The specified PIN is too long or too short. More... | |
| #define | CKR_RANDOM_NO_RNG |
| The specified token doesn't have a random number generator. More... | |
| #define | CKR_RANDOM_SEED_NOT_SUPPORTED |
| The token's random number generator does not accept seeding from an application. More... | |
| #define | CKR_SAVED_STATE_INVALID |
| The supplied saved cryptographic operations state is invalid, and so it cannot be restored to the specified session. More... | |
| #define | CKR_SESSION_COUNT |
| The attempt to open a session failed, either because the token has too many sessions already open, or because the token has too many read/write sessions already open. More... | |
| #define | CKR_SESSION_EXCLUSIVE_EXISTS |
| The attempt to open a session failed because there already exists an exclusive session. More... | |
| #define | CKR_SESSION_EXISTS |
| A session with the token is already open. More... | |
| #define | CKR_SESSION_PARALLEL_NOT_SUPPORTED |
| The specified token does not support parallel sessions. More... | |
| #define | CKR_SESSION_READ_ONLY |
| The specified session was unable to accomplish the desired action because it is a read-only session. More... | |
| #define | CKR_SESSION_READ_ONLY_EXISTS |
| A read-only session already exists, and so the SO cannot be logged in. More... | |
| #define | CKR_SESSION_READ_WRITE_SO_EXISTS |
| A read/write SO session already exists, and so a read-only session cannot be opened. More... | |
| #define | CKR_SIGNATURE_LEN_RANGE |
| The provided signature/MAC can be seen to be invalid, solely on the basis of its length. More... | |
| #define | CKR_SIGNATURE_INVALID |
| The provided signature/MAC is invalid. More... | |
| #define | CKR_SLOT_ID_INVALID |
| The specified slot ID is not valid. More... | |
| #define | CKR_STATE_UNSAVEABLE |
| The cryptographic operations state of the specified session cannot be saved for some reason (possibly the token is simply unable to save the current state). More... | |
| #define | CKR_TEMPLATE_INCOMPLETE |
| The template specified for creating an object is incomplete, and lacks some necessary attributes. More... | |
| #define | CKR_TEMPLATE_INCONSISTENT |
| The template specified for creating an object has conflicting attributes. More... | |
| #define | CKR_TOKEN_NOT_RECOGNIZED |
| The Cryptoki library and/or slot does not recognize the token in the slot. More... | |
| #define | CKR_TOKEN_WRITE_PROTECTED |
| The requested action could not be performed because the token is write-protected. More... | |
| #define | CKR_UNWRAPPING_KEY_HANDLE_INVALID |
| The key handle specified to be used to unwrap another key is not valid. More... | |
| #define | CKR_UNWRAPPING_KEY_SIZE_RANGE |
| Although the requested unwrapping operation could in principal be carried out, this Cryptoki library (or the token) is unable to actually do it because the supplied key's size is outside the range of key sizes that it can handle. More... | |
| #define | CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT |
| The type of the key specified to unwrap another key is not consistent with the mechanism specified for unwrapping. More... | |
| #define | CKR_USER_ALREADY_LOGGED_IN |
| The session cannot be logged in, because it is already logged in. More... | |
| #define | CKR_USER_NOT_LOGGED_IN |
| The desired action cannot be performed because the appropriate user (or ''an'' appropriate user) is not logged in. More... | |
| #define | CKR_USER_PIN_NOT_INITIALIZED |
| The normal user's PIN has not been initialized with '''C_InitPIN'''. More... | |
| #define | CKR_USER_TYPE_INVALID |
| An invalid value was specified as a '''CK_USER_TYPE'''. More... | |
| #define | CKR_WRAPPED_KEY_INVALID |
| The wrapped key is not valid. More... | |
| #define | CKR_WRAPPED_KEY_LEN_RANGE |
| The provided wrapped key can be seen to be invalid, solely on the basis of its length. More... | |
| #define | CKR_WRAPPING_KEY_HANDLE_INVALID |
| The key handle specified to be used to wrap another key is not valid. More... | |
| #define | CKR_WRAPPING_KEY_SIZE_RANGE |
| Although the requested wrapping operation could in principal be carried out, this Cryptoki library (or the token) is unable to actually do it because the supplied wrapping key's size is outside the range of key sizes that it can handle. More... | |
| #define | CKR_WRAPPING_KEY_TYPE_INCONSISTENT |
| The type of the key specified to wrap another key is not consistent with the mechanism specified for wrapping. More... | |
Typedefs | |
| typedef unsigned char | CK_BYTE |
| an unsigned 8-bit value. More... | |
| typedef CK_BYTE | CK_CHAR |
| an unsigned 8-bit character. More... | |
| typedef CK_BYTE | CK_BBOOL |
| a BYTE-sized Boolean flag. More... | |
| typedef unsigned long int | CK_ULONG |
| an unsigned value, at least 32 bits long. More... | |
| typedef long int | CK_LONG |
| a signed value, the same size as a CK_ULONG. More... | |
| typedef CK_ULONG | CK_FLAGS |
| at least 32 bits; each bit is a Boolean flag. More... | |
| typedef CK_BYTE CK_PTR | CK_BYTE_PTR |
| Pointer to a CK_BYTE. More... | |
| typedef CK_CHAR CK_PTR | CK_CHAR_PTR |
| Pointer to a CK_CHAR. More... | |
| typedef CK_ULONG CK_PTR | CK_ULONG_PTR |
| Pointer to a CK_ULONG. More... | |
| typedef void CK_PTR | CK_VOID_PTR |
| Pointer to a void. More... | |
| typedef NULL CK_PTR | NULL_PTR |
| A NULL pointer. More... | |
| typedef struct | CK_VERSION |
CK_VERSIONCK_VERSION is a structure that describes the version of a Cryptoki interface, a Cryptoki library, an SSL implementation, or the hardware or firmware version of a slot or token. More... | |
| typedef struct | CK_INFO |
CK_INFOCK_INFO provides general information about Cryptoki. More... | |
| typedef CK_ULONG | CK_NOTIFICATION |
CK_NOTIFICATIONCK_NOTIFICATION holds the types of notifications that Cryptoki provides to an application. More... | |
| typedef CK_ULONG | CK_SLOT_ID |
CK_SLOT_IDCK_SLOT_ID is a Cryptoki-assigned value that identifies a slot. More... | |
| typedef struct | CK_SLOT_INFO |
CK_SLOT_INFOCK_SLOT_INFO provides information about a slot. More... | |
| typedef struct | CK_TOKEN_INFO |
CK_TOKEN_INFOCK_TOKEN_INFO provides information about a token. More... | |
| typedef CK_ULONG | CK_SESSION_HANDLE |
CK_SESSION_HANDLECK_SESSION_HANDLE is a Cryptoki-assigned value that identifies a session. More... | |
| typedef CK_ULONG | CK_USER_TYPE |
CK_USER_TYPECK_USER_TYPE holds the types of Cryptoki users described in Section .. More... | |
| typedef CK_ULONG | CK_STATE |
CK_STATECK_STATE holds the session state, as decribed in Sections and . More... | |
| typedef struct | CK_SESSION_INFO |
CK_SESSION_INFOCK_SESSION_INFO provides information about a session. More... | |
| typedef CK_ULONG | CK_OBJECT_HANDLE |
CK_OBJECT_HANDLECK_OBJECT_HANDLE is a token-specific identifier for an object. More... | |
| typedef CK_ULONG | CK_OBJECT_CLASS |
CK_OBJECT_CLASSCK_OBJECT_CLASS is a value that identifies the classes (or types) of objects that Cryptoki recognizes. More... | |
| typedef CK_ULONG | CK_KEY_TYPE |
CK_KEY_TYPECK_KEY_TYPE is a value that identifies a key type. More... | |
| typedef CK_ULONG | CK_CERTIFICATE_TYPE |
CK_CERTIFICATE_TYPECK_CERTIFICATE_TYPE is a value that identifies a certificate type. More... | |
| typedef CK_ULONG | CK_ATTRIBUTE_TYPE |
CK_ATTRIBUTE_TYPECK_ATTRIBUTE_TYPE is a value that identifies an attribute type. More... | |
| typedef struct | CK_ATTRIBUTE |
CK_ATTRIBUTECK_ATTRIBUTE is a structure that includes the type, length and value of an attribute. More... | |
| typedef struct | CK_DATE |
CK_DATECK_DATE is a structure that defines a date. More... | |
| typedef CK_ULONG | CK_MECHANISM_TYPE |
CK_MECHANISM_TYPECK_MECHANISM_TYPE is a value that identifies a mechanism type. More... | |
| typedef struct | CK_MECHANISM |
CK_MECHANISMCK_MECHANISM is a structure that specifies a particular mechanism. More... | |
| typedef struct | CK_MECHANISM_INFO |
CK_MECHANISM_INFOCK_MECHANISM_INFO is a structure that provides information about a particular mechanism. More... | |
| typedef CK_ULONG | CK_RV |
CK_RVCK_RV is a value that identifies the return value of a Cryptoki function. More... | |
| typedef CK_RV(CK_ENTRY * | CK_NOTIFY )(CK_SESSION_HANDLE hSession, CK_NOTIFICATION event, CK_VOID_PTR pApplication) |
CK_NOTIFYCK_NOTIFY is the type of a pointer to a function used by Cryptoki to perform notification callbacks. More... | |
| typedef struct | CK_FUNCTION_LIST |
CK_FUNCTION_LISTCK_FUNCTION_LIST is a structure which contains a Cryptoki version and a function pointer to each function in the Cryptoki API. More... | |
| typedef struct | CK_KEA_DERIVE |
CK_KEA_DERIVE_PARAMSCK_KEA_DERIVE_PARAMS is a structure that provides the parameters to the CKM_KEA_DERIVE mechanism. More... | |
| typedef struct | CK_MAYFLY_DERIVE |
CK_MAYFLY_DERIVE_PARAMSCK_MAYFLY_DERIVE_PARAMS is a structure that provides the parameters to the CKM_MAYFLY_DERIVE mechanism. More... | |
| typedef struct | CK_RC2_CBC_PARAMS |
CK_RC2_CBC_PARAMSCK_RC2_CBC_PARAMS is a structure that provides the parameters to the CKM_RC2_CBC and CKM_RC2_CBC_PAD mechanisms. More... | |
| typedef struct | CK_RC2_MAC_GENERAL_PARAMS |
CK_RC2_MAC_GENERAL_PARAMSCK_RC2_MAC_GENERAL_PARAMS is a structure that provides the parameters to the CKM_RC2_MAC_GENERAL mechanism. More... | |
| typedef struct | CK_RC5_CBC_PARAMS |
CK_RC5_CBC_PARAMSCK_RC5_CBC_PARAMS is a structure that provides the parameters to the CKM_RC5_CBC and CKM_RC5_CBC_PAD mechanisms. More... | |
| typedef struct | CK_RC5_MAC_GENERAL_PARAMS |
CK_RC5_MAC_GENERAL_PARAMSCK_RC5_MAC_GENERAL_PARAMS is a structure that provides the parameters to the CKM_RC5_MAC_GENERAL mechanism. More... | |
| typedef CK_ULONG | CK_MAC_GENERAL_PARAMS |
CK_MAC_GENERAL_PARAMSCK_MAC_GENERAL_PARAMS provides the parameters to the general-length MACing mechanisms of the DES, DES3 (triple-DES), CAST, CAST3, CAST5, IDEA, and CDMF ciphers. More... | |
| typedef struct | CK_SKIPJACK_PRIVATE_WRAP_PARAMS |
CK_SKIPJACK_PRIVATE_WRAP_PARAMSCK_SKIPJACK_PRIVATE_WRAP_PARAMS is a structure that provides the parameters to the CKM_SKIPJACK_PRIVATE_WRAP mechanism. More... | |
| typedef struct | CK_SKIPJACK_RELAYX_PARAMS |
CK_SKIPJACK_RELAYX_PARAMSCK_SKIPJACK_RELAYX_PARAMS is a structure that provides the parameters to the CKM_SKIPJACK_RELAYX mechanism. More... | |
| typedef struct | CK_PBE_PARAMS |
CK_PBE_PARAMSCK_PBE_PARAMS is a structure which provides all of the necessary information required by the CKM_PBE mechanisms (see PKCS#5 for information on the PBE generation mechanisms). More... | |
| typedef struct | CK_KEY_WRAP_SET_OAEP_PARAMS |
CK_KEY_WRAP_SET_OAEP_PARAMSCK_KEY_WRAP_SET_OAEP_PARAMS is a structure that provides the parameters to the CKM_KEY_WRAP_SET_OAEP mechanism. More... | |
| typedef struct | CK_SSL3_RANDOM_DATA |
CK_SSL3_RANDOM_DATACK_SSL3_RANDOM_DATA is a structure which provides information about the random data of a client and a server in an SSL context. More... | |
| typedef struct | CK_SSL3_MASTER_KEY_DERIVE_PARAMS |
| typedef struct | CK_SSL3_KEY_MAT_OUT |
CK_SSL3_KEY_MAT_OUTCK_SSL3_KEY_MAT_OUT is a structure that contains the resulting key handles after performing a C_DeriveKey function with the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. More... | |
| typedef struct | CK_SSL3_KEY_MAT_PARAMS |
CK_SSL3_KEY_MAT_PARAMSCK_SSL3_KEY_MAT_PARAMS is a structure that provides the parameters to the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. More... | |
| typedef struct | CK_KEY_DERIVATION_STRING_DATA |
CK_KEY_DERIVATION_STRING_DATA. More... | |
| typedef CK_ULONG | CK_EXTRACT_PARAMS |
CK_EXTRACT_PARAMSCK_KEY_EXTRACT_PARAMS provides the parameter to the CKM_EXTRACT_KEY_FROM_KEY mechanism. More... | |
Functions | |
| CK_RV | C_Initialize (CK_VOID_PTR pReserved) |
| C_Initialize initializes the Cryptoki library. More... | |
| CK_RV | C_Finalize (CK_VOID_PTR pReserved) |
| C_Finalize is called to indicate that an application is finished with the Cryptoki library. More... | |
| CK_RV | C_GetInfo (CK_INFO_PTR pInfo) |
| C_GetInfo returns general information about Cryptoki. More... | |
| CK_RV | C_GetFunctionList (CK_FUNCTION_LIST_PTR_PTR ppFunctionList) |
| C_GetFunctionList obtains a pointer to the Cryptoki library's list of function pointers. More... | |
| CK_RV | C_GetSlotList (CK_BBOOL tokenPresent, CK_SLOT_ID_PTR pSlotList, CK_ULONG_PTR pulCount) |
| C_GetSlotList is used to obtain a list of slots in the system. More... | |
| CK_RV | C_GetSlotInfo (CK_SLOT_ID slotID, CK_SLOT_INFO_PTR pInfo) |
| C_GetSlotInfo obtains information about a particular slot in the system. More... | |
| CK_RV | C_GetTokenInfo (CK_SLOT_ID slotID, CK_TOKEN_INFO_PTR pInfo) |
| C_GetTokenInfo obtains information about a particular token in the system. More... | |
| CK_RV | C_GetMechanismList (CK_SLOT_ID slotID, CK_MECHANISM_TYPE_PTR pMechanismList, CK_ULONG_PTR pulCount) |
| C_GetMechanismList is used to obtain a list of mechanism types supported by a token. More... | |
| CK_RV | C_GetMechanismInfo (CK_SLOT_ID slotID, CK_MECHANISM_TYPE type, CK_MECHANISM_INFO_PTR pInfo) |
| C_GetMechanismInfo obtains information about a particular mechanism possibly supported by a token. More... | |
| CK_RV | C_InitToken (CK_SLOT_ID slotID, CK_CHAR_PTR pPin, CK_ULONG ulPinLen, CK_CHAR_PTR pLabel) |
| C_InitToken initializes a token. More... | |
| CK_RV | C_InitPIN (CK_SESSION_HANDLE hSession, CK_CHAR_PTR pPin, CK_ULONG ulPinLen) |
| C_InitPIN initializes the normal user's PIN. More... | |
| CK_RV | C_SetPIN (CK_SESSION_HANDLE hSession, CK_CHAR_PTR pOldPin, CK_ULONG ulOldLen, CK_CHAR_PTR pNewPin, CK_ULONG ulNewLen) |
| C_SetPIN modifies the PIN of the user that is currently logged in. More... | |
| CK_RV | C_OpenSession (CK_SLOT_ID slotID, CK_FLAGS flags, CK_VOID_PTR pApplication, CK_NOTIFY Notify, CK_SESSION_HANDLE_PTR phSession) |
| C_OpenSession has two distinct functions: it can set up an application callback so that an application will be notified when a token is inserted into a particular slot, or it can open a session between an application and a token in a particular slot. More... | |
| CK_RV | C_CloseSession (CK_SESSION_HANDLE hSession) |
| C_CloseSession closes a session between an application and a token. More... | |
| CK_RV | C_CloseAllSessions (CK_SLOT_ID slotID) |
| C_CloseAllSessions closes all sessions an application has with a token. More... | |
| CK_RV | C_GetSessionInfo (CK_SESSION_HANDLE hSession, CK_SESSION_INFO_PTR pInfo) |
| C_GetSessionInfo obtains information about a session. More... | |
| CK_RV | C_GetOperationState (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pOperationState, CK_ULONG_PTR pulOperationStateLen) |
| C_GetOperationState obtains the cryptographic operations state of a session, encoded as a string of bytes. More... | |
| CK_RV | C_SetOperationState (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pOperationState, CK_ULONG ulOperationStateLen, CK_OBJECT_HANDLE hEncryptionKey, CK_OBJECT_HANDLE hAuthenticationKey) |
| C_SetOperationState restores the cryptographic operations state of a session from a string of bytes obtained with C_GetOperationState. More... | |
| CK_RV | C_Login (CK_SESSION_HANDLE hSession, CK_USER_TYPE userType, CK_CHAR_PTR pPin, CK_ULONG ulPinLen) |
| C_Login logs a user into a token. More... | |
| CK_RV | C_Logout (CK_SESSION_HANDLE hSession) |
| C_Logout logs a user out from a token. More... | |
| CK_RV | C_CreateObject (CK_SESSION_HANDLE hSession, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_OBJECT_HANDLE_PTR phObject) |
| C_CreateObject creates a new object. More... | |
| CK_RV | C_CopyObject (CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_OBJECT_HANDLE_PTR phNewObject) |
| C_CopyObject copies an object, creating a new object for the copy. More... | |
| CK_RV | C_DestroyObject (CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject) |
| C_DestroyObject destroys an object. More... | |
| CK_RV | C_GetObjectSize (CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ULONG_PTR pulSize) |
| C_GetObjectSize gets the size of an object in bytes. More... | |
| CK_RV | C_GetAttributeValue (CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount) |
| C_GetAttributeValue obtains the value of one or more attributes of an object. More... | |
| CK_RV | C_SetAttributeValue (CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount) |
| C_SetAttributeValue modifies the value of one or more attributes of an object. More... | |
| CK_RV | C_FindObjectsInit (CK_SESSION_HANDLE hSession, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount) |
| C_FindObjectsInit initializes a search for token and session objects that match a template. More... | |
| CK_RV | C_FindObjects (CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE_PTR phObject, CK_ULONG ulMaxObjectCount, CK_ULONG_PTR pulObjectCount) |
| C_FindObjects continues a search for token and session objects that match a template, obtaining additional object handles. More... | |
| CK_RV | C_FindObjectsFinal (CK_SESSION_HANDLE hSession) |
| C_FindObjectsFinal terminates a search for token and session objects. More... | |
| CK_RV | C_EncryptInit (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey) |
| C_EncryptInit initializes an encryption operation. More... | |
| CK_RV | C_Encrypt (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData, CK_ULONG ulDataLen, CK_BYTE_PTR pEncryptedData, CK_ULONG_PTR pulEncryptedDataLen) |
| C_Encrypt encrypts single-part data. More... | |
| CK_RV | C_EncryptUpdate (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen, CK_BYTE_PTR pEncryptedPart, CK_ULONG_PTR pulEncryptedPartLen) |
| C_EncryptUpdate continues a multiple-part encryption operation, processing another data part. More... | |
| CK_RV | C_EncryptFinal (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pLastEncryptedPart, CK_ULONG_PTR pulLastEncryptedPartLen) |
| C_EncryptFinal finishes a multiple-part encryption operation. More... | |
| CK_RV | C_DecryptInit (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey) |
| C_DecryptInit initializes a decryption operation. More... | |
| CK_RV | C_Decrypt (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pEncryptedData, CK_ULONG ulEncryptedDataLen, CK_BYTE_PTR pData, CK_ULONG_PTR pulDataLen) |
| C_Decrypt decrypts encrypted data in a single part. More... | |
| CK_RV | C_DecryptUpdate (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pEncryptedPart, CK_ULONG ulEncryptedPartLen, CK_BYTE_PTR pPart, CK_ULONG_PTR pulPartLen) |
| C_DecryptUpdate continues a multiple-part decryption operation, processing another encrypted data part. More... | |
| CK_RV | C_DecryptFinal (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pLastPart, CK_ULONG_PTR pulLastPartLen) |
| C_DecryptFinal finishes a multiple-part decryption operation. More... | |
| CK_RV | C_DigestInit (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism) |
| C_DigestInit initializes a message-digesting operation. More... | |
| CK_RV | C_Digest (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData, CK_ULONG ulDataLen, CK_BYTE_PTR pDigest, CK_ULONG_PTR pulDigestLen) |
| C_Digest digests data in a single part. More... | |
| CK_RV | C_DigestUpdate (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen) |
| C_DigestUpdate continues a multiple-part message-digesting operation, processing another data part. More... | |
| CK_RV | C_DigestKey (CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hKey) |
| C_DigestKey continues a multiple-part message-digesting operation by digesting the value of a secret key. More... | |
| CK_RV | C_DigestFinal (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pDigest, CK_ULONG_PTR pulDigestLen) |
| C_DigestFinal finishes a multiple-part message-digesting operation, returning the message digest. More... | |
| CK_RV | C_SignInit (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey) |
| C_SignInit initializes a signature operation, where the signature is an appendix to the data. More... | |
| CK_RV | C_Sign (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData, CK_ULONG ulDataLen, CK_BYTE_PTR pSignature, CK_ULONG_PTR pulSignatureLen) |
| C_Sign signs data in a single part, where the signature is an appendix to the data. More... | |
| CK_RV | C_SignUpdate (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen) |
| C_SignUpdate continues a multiple-part signature operation, processing another data part. More... | |
| CK_RV | C_SignFinal (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pSignature, CK_ULONG_PTR pulSignatureLen) |
| C_SignFinal finishes a multiple-part signature operation, returning the signature. More... | |
| CK_RV | C_SignRecoverInit (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey) |
| C_SignRecoverInit initializes a signature operation, where the data can be recovered from the signature. More... | |
| CK_RV | C_SignRecover (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData, CK_ULONG ulDataLen, CK_BYTE_PTR pSignature, CK_ULONG_PTR pulSignatureLen) |
| C_SignRecover signs data in a single operation, where the data can be recovered from the signature. More... | |
| CK_RV | C_VerifyInit (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey) |
| C_VerifyInit initializes a verification operation, where the signature is an appendix to the data. More... | |
| CK_RV | C_Verify (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData, CK_ULONG ulDataLen, CK_BYTE_PTR pSignature, CK_ULONG ulSignatureLen) |
| C_Verify verifies a signature in a single-part operation, where the signature is an appendix to the data. More... | |
| CK_RV | C_VerifyUpdate (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen) |
| C_VerifyUpdate continues a multiple-part verification operation, processing another data part. More... | |
| CK_RV | C_VerifyFinal (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pSignature, CK_ULONG ulSignatureLen) |
| C_VerifyFinal finishes a multiple-part verification operation, checking the signature. More... | |
| CK_RV | C_VerifyRecoverInit (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey) |
| C_VerifyRecoverInit initializes a signature verification operation, where the data is recovered from the signature. More... | |
| CK_RV | C_VerifyRecover (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pSignature, CK_ULONG ulSignatureLen, CK_BYTE_PTR pData, CK_ULONG_PTR pulDataLen) |
| C_VerifyRecover verifies a signature in a single-part operation, where the data is recovered from the signature. More... | |
| CK_RV | C_DigestEncryptUpdate (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen, CK_BYTE_PTR pEncryptedPart, CK_ULONG_PTR pulEncryptedPartLen) |
| C_DigestEncryptUpdate continues multiple-part digest and encryption operations, processing another data part. More... | |
| CK_RV | C_DecryptDigestUpdate (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pEncryptedPart, CK_ULONG ulEncryptedPartLen, CK_BYTE_PTR pPart, CK_ULONG_PTR pulPartLen) |
| C_DecryptDigestUpdate continues a multiple-part combined decryption and digest operation, processing another data part. More... | |
| CK_RV | C_SignEncryptUpdate (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pPart, CK_ULONG ulPartLen, CK_BYTE_PTR pEncryptedPart, CK_ULONG_PTR pulEncryptedPartLen) |
| C_SignEncryptUpdate continues a multiple-part combined signature and encryption operation, processing another data part. More... | |
| CK_RV | C_DecryptVerifyUpdate (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pEncryptedPart, CK_ULONG ulEncryptedPartLen, CK_BYTE_PTR pPart, CK_ULONG_PTR pulPartLen) |
| C_DecryptVerifyUpdate continues a multiple-part combined decryption and verification operation, processing another data part. More... | |
| 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, creating a new key object. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| CK_RV | C_SeedRandom (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pSeed, CK_ULONG ulSeedLen) |
| C_SeedRandom mixes additional seed material into the token's random number generator. More... | |
| CK_RV | C_GenerateRandom (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pRandomData, CK_ULONG ulRandomLen) |
| C_GenerateRandom generates random data. More... | |
| CK_RV | C_GetFunctionStatus (CK_SESSION_HANDLE hSession) |
| C_GetFunctionStatus obtains the status of a function running in parallel with an application. More... | |
| CK_RV | C_CancelFunction (CK_SESSION_HANDLE hSession) |
| C_CancelFunction cancels a function running in parallel with an application. More... | |
Definition in file pkcs11_all.h.
|
|
An invalid handle. |
|
|
CK_BBOOL true. |
|
|
CK_BBOOL false. |
|
|
Information unavailable. |
|
|
Effectively infinite. |
|
|
Security Officer. |
|
|
User. |
|
|
Context specific. |
|
|
Read only public session. |
|
|
Read only user functions. |
|
|
Read write public session. |
|
|
Read write user functions. |
|
|
Read write security officer functions. |
|
|
True. |
|
|
False. |
|
|
TRUE if a token is present in the slot (''e.g.'', a device is in the reader). |
|
|
TRUE if the reader supports removable devices. |
|
|
TRUE if the slot is a hardware slot, as opposed to a software slot implementing a "soft token". |
|
|
TRUE if the token has its own random number generator. |
|
|
TRUE if the token is write-protected. |
|
|
TRUE if a user must be logged in to perform cryptographic functions. |
|
|
TRUE if the normal user's PIN has been initialized. |
|
|
TRUE if an exclusive session exists. |
|
|
TRUE if a successful save of a session's cryptographic operations state always contains all keys needed to restore the state of the session. |
|
|
TRUE if token has its own hardware clock. |
|
|
TRUE if token supports parallel sessions through this Cryptoki library. |
|
|
TRUE if token has a "protected authentication path", whereby a user can log in to the token without passing a PIN through the Cryptoki library. |
|
|
TRUE if a single session with the token can perform dual cryptographic operations (see Section ). |
|
|
TRUE if the session is exclusive; FALSE if the session is shared. |
|
|
TRUE if the session is read/write; FALSE if the session is read-only. |
|
|
TRUE if cryptographic functions are performed in serial with the application; FALSE if the functions may be performed in parallel with the application. |
|
|
this flag is write-only, ''i.e.'', is supplied as an argument to a '''C_OpenSession''' call, but is never set in a session's '''CK_SESSION_INFO''' structure. It is TRUE if the call is a request for a token insertion callback, instead of being a request to open a session |
|
|
TRUE if the mechanism is performed by the device; FALSE if the mechanism is performed in software. |
|
|
TRUE if the mechanism can be used with '''C_EncryptInit'''. |
|
|
TRUE if the mechanism can be used with '''C_DecryptInit'''. |
|
|
TRUE if the mechanism can be used with '''C_DigestInit'''. |
|
|
TRUE if the mechanism can be used with '''C_SignInit'''. |
|
|
TRUE if the mechanism can be used with '''C_SignRecoverInit'''. |
|
|
TRUE if the mechanism can be used with '''C_VerifyInit'''. |
|
|
TRUE if the mechanism can be used with '''C_VerifyRecoverInit'''. |
|
|
TRUE if the mechanism can be used with '''C_GenerateKey'''. |
|
|
TRUE if the mechanism can be used with '''C_GenerateKeyPair'''. |
|
|
TRUE if the mechanism can be used with '''C_WrapKey'''. |
|
|
TRUE if the mechanism can be used with '''C_UnwrapKey'''. |
|
|
TRUE if the mechanism can be used with '''C_DeriveKey'''. |
|
|
TRUE if an extension to the flags; FALSE if no extensions. Must be FALSE for this version. |
|
|
Object class (type). |
|
|
TRUE if object is a token object; FALSE if object is a session object (default FALSE). |
|
|
TRUE if object is a private object; FALSE if object is a public object (default FALSE). |
|
|
TRUE if object can be modified (default TRUE). |
|
|
Description of the object (default empty). |
|
|
Description of the application that manages the object (default empty). |
|
|
Value of the object (default empty). |
|
|
Type of certificate. |
|
|
DER encoding of the certificate subject name. |
|
|
Key identifier for public/private key pair (default empty). |
|
|
DER encoding of the certificate issuer name (default empty). |
|
|
DER encoding of the certificate serial number (default empty). |
|
|
Value of the object (default empty). |
|
|
Type of key. |
|
|
Key identifier for public/private key pair (default empty). |
|
|
Start date for the key (default empty). |
|
|
End date for the key (default empty). |
|
|
TRUE if key supports key derivation (default FALSE). |
|
|
TRUE if key was generated locally (''i.e.'', on token). |
|
|
DER encoding of the certificate subject name. |
|
|
TRUE if key supports encryption9. |
|
|
TRUE if key supports verification9. |
|
|
TRUE if key supports verification where the data is recovered from the signature9. |
|
|
TRUE if key supports wrapping9. |
|
|
Modulus ''n''. |
|
|
Length in bits of modulus ''n''. |
|
|
Public exponent ''e''. |
|
|
Prime ''p'' (512 to 1024 bits, in steps of 64 bits). |
|
|
Subprime ''q'' (160 bits). |
|
|
Base ''g''. |
|
|
Value of the object (default empty). |
|
|
Prime ''p'' (512 to 1024 bits, in steps of 64 bits). |
|
|
Subprime ''q'' (160 bits). |
|
|
Base ''g''. |
|
|
Value of the object (default empty). |
|
|
Prime ''p'' (512 to 1024 bits, in steps of 64 bits). |
|
|
Base ''g''. |
|
|
Value of the object (default empty). |
|
|
Prime ''p'' (512 to 1024 bits, in steps of 64 bits). |
|
|
Subprime ''q'' (160 bits). |
|
|
Base ''g''. |
|
|
Value of the object (default empty). |
|
|
Prime ''p'' (512 to 1024 bits, in steps of 64 bits). |
|
|
Subprime ''q'' (160 bits). |
|
|
Base ''g''. |
|
|
Value of the object (default empty). |
|
|
DER encoding of the certificate subject name. |
|
|
TRUE if key is sensitive9. |
|
|
TRUE if key supports decryption9. |
|
|
TRUE if key supports signatures where the signature is an appendix to the data9. |
|
|
TRUE if key supports signatures where the data can be recovered from the signature9. |
|
|
TRUE if key supports unwrapping9. |
|
|
TRUE if key is extractable9. |
|
|
TRUE if key has ''always'' had the CKA_SENSITIVE attribute set to TRUE. |
|
|
TRUE if key has ''never'' had the CKA_EXTRACTABLE attribute set to TRUE. |
|
|
Modulus ''n''. |
|
|
Public exponent ''e''. |
|
|
Private exponent ''d''. |
|
|
Prime ''p''. |
|
|
Prime ''q''. |
|
|
Private exponent ''d'' modulo ''p''-1. |
|
|
Private exponent ''d'' modulo ''q''-1. |
|
|
CRT coefficient ''q''-1 mod ''p''. |
|
|
Prime ''p'' (512 to 1024 bits, in steps of 64 bits). |
|
|
Subprime ''q'' (160 bits). |
|
|
Base ''g''. |
|
|
Value of the object (default empty). |
|
|
Prime ''p'' (512 to 1024 bits, in steps of 64 bits). |
|
|
Subprime ''q'' (160 bits). |
|
|
Base ''g''. |
|
|
Value of the object (default empty). |
|
|
Prime ''p'' (512 to 1024 bits, in steps of 64 bits). |
|
|
Base ''g''. |
|
|
Value of the object (default empty). |
|
|
Length in bits of private value ''x''. |
|
|
Prime ''p'' (512 to 1024 bits, in steps of 64 bits). |
|
|
Subprime ''q'' (160 bits). |
|
|
Base ''g''. |
|
|
Value of the object (default empty). |
|
|
Prime ''p'' (512 to 1024 bits, in steps of 64 bits). |
|
|
Subprime ''q'' (160 bits). |
|
|
Base ''g''. |
|
|
Value of the object (default empty). |
|
|
TRUE if key is sensitive9. |
|
|
TRUE if key supports encryption9. |
|
|
TRUE if key supports decryption9. |
|
|
TRUE if key supports signatures where the signature is an appendix to the data9. |
|
|
TRUE if key supports verification9. |
|
|
TRUE if key supports wrapping9. |
|
|
TRUE if key supports unwrapping9. |
|
|
TRUE if key is extractable9. |
|
|
TRUE if key has ''always'' had the CKA_SENSITIVE attribute set to TRUE. |
|
|
TRUE if key has ''never'' had the CKA_EXTRACTABLE attribute set to TRUE. |
|
|
Value of the object (default empty). |
|
|
Length in bytes of key value. |
|
|
Value of the object (default empty). |
|
|
Length in bytes of key value. |
|
|
Value of the object (default empty). |
|
|
Length in bytes of key value. |
|
|
Value of the object (default empty). |
|
|
Length in bytes of key value. |
|
|
Value of the object (default empty). |
|
|
Value of the object (default empty). |
|
|
Value of the object (default empty). |
|
|
Value of the object (default empty). |
|
|
Length in bytes of key value. |
|
|
Value of the object (default empty). |
|
|
Length in bytes of key value. |
|
|
Value of the object (default empty). |
|
|
Length in bytes of key value. |
|
|
Value of the object (default empty). |
|
|
Value of the object (default empty). |
|
|
Value of the object (default empty). |
|
|
Value of the object (default empty). |
|
|
Value of the object (default empty). |
|
|
Some horrible, unrecoverable error has occurred. In the worst case, it is possible that the function only partially succeeded, and that the computer and/or token is in an inconsistent state. |
|
|
The computer that the Cryptoki library is running on has insufficient memory to perform the requested function. In the worst case, it is possible that the function only partially succeeded, and that the computer and/or token is in an inconsistent state. |
|
|
The requested function could not be performed, but detailed information about why not is not available in this error return. If the failed function uses a session, it is possible that the '''CK_SESSION_INFO''' that can be obtained by calling '''C_GetSessionInfo''' holds useful information about what happened in its ''ulDeviceError'' field. In any event, although the function call failed, the situation is not necessarily totally hopeless, as it is likely to be when CKR_GENERAL_ERROR is returned. |
|
|
The function executed successfully. |
|
|
The specified session handle was invalid ''at the time that the function was invoked''. Note that this can happen if the session's token is removed before the function invokation, since removing a token closes all sessions with it. |
|
|
The token was removed from its slot ''during the execution of the function''. |
|
|
The session was closed ''during the execution of the function''. |
|
|
The token does not have sufficient memory to perform the requested function. |
|
|
Some problem has occurred with the token and/or slot. |
|
|
The token was not present in its slot ''at the time that the function was invoked''. |
|
|
The token was removed from its slot ''during the execution of the function''. |
|
|
An attempt was made to set a value for an attribute which may not be set, or which may not be modified. |
|
|
An attempt was made to obtain the value of an attribute of an object which cannot be satisfied because the object is either sensitive or unextractable. |
|
|
An invalid attribute type was specified in a template. |
|
|
An invalid value was specified for an attribute in a template. |
|
|
The output of the function does not fit in the supplied buffer. |
|
|
This is a value for an application callback to return. When a function executing in serial with an application decides to give the application a chance to do some work, it calls an application-supplied function with a CKN_SURRENDER callback. If the callback returns the value CKR_CANCEL, then the function aborts (see CKR_FUNCTION_CANCELED). |
|
|
The plaintext input data to a cryptographic operation is invalid. This error only applies to the '''CKM_RSA_X_509''' mechanism, when plaintext is supplied that has the same number of bytes as the RSA modulus and is numerically at least as large as the modulus. This return value has lower priority than CKR_DATA_LEN_RANGE. |
|
|
The plaintext input data to a cryptographic operation has a bad length. Depending on the operation's mechanism, this could mean that the plaintext data is too short, too long, or is not a multiple of some particular blocksize. This return value has higher priority than CKR_DATA_INVALID. |
|
|
The encrypted input to a decryption operation has been determined to be invalid ciphertext. This return value has lower priority than CKR_ENCRYPTED_DATA_LEN_RANGE. |
|
|
The ciphertext input to a decryption operation has been determined to be invalid ciphertext solely on the basis of its length. Depending on the operation's mechanism, this could mean that the ciphertext is too short, too long, or is not a multiple of some particular blocksize. This return value has higher priority than CKR_ENCRYPTED_DATA_INVALID. |
|
|
The function was canceled in mid-execution. This can happen to a function executing in parallel with an application, if the application calls '''C_CancelFunction'''; it can also happen to a function executing in serial with an application, if the function makes a '''CKN_SURRENDER''' application callback, and the callback returns CKR_CANCEL (see CKR_CANCEL). |
|
|
There is currently no function executing in parallel in the specified session. |
|
|
The requested function is not supported by this Cryptoki library. Even unsupported functions in the Cryptoki API should have a "stub" in the library which simply returns the value CKR_FUNCTION_NOT_SUPPORTED. |
|
|
There is currently a function executing in parallel in the specified session. CKR_FUNCTION_PARALLEL is also returned whenever a Cryptoki function call is made that executes in parallel. |
|
|
The information requested could not be obtained because the token considers it sensitive, and is not able or willing to reveal it. |
|
|
The specified slot does not support setting an application callback for token insertion. |
|
|
One of the keys specified in a '''C_SetOperationState''' operation is not the same key that was being used in the original saved session. |
|
|
An attempt has been made to use a key for a cryptographic purpose that the key's attributes are not set to allow it to do. For example, to use a key for performing encryption, that key must have its '''CKA_ENCRYPT''' attribute set to TRUE (the fact that the key must have a '''CKA_ENCRYPT''' attribute implies that the key cannot be a private key). This return value has lower priority than CKR_KEY_TYPE_INCONSISTENT. |
|
|
The specified key handle is not valid. It may be the case that the specified handle is a valid handle for an object which is not a key. We reiterate here that 0 is never a valid key handle. |
|
|
The value of the specified key cannot be digested for some reason (perhaps the key isn't a secret key, or perhaps the token simply can't digest this kind of key). |
|
|
The '''C_SetOperationState''' operation cannot be carried out because it needs to be supplied with a key that was being used in the original saved session. |
|
|
An extraneous key was supplied to '''C_SetOperationState'''. For example, an attempt was made to restore a session that had been performing a message digesting operation, and an encryption key was supplied. |
|
|
Although the specified private or secret key does not have its CKA_UNEXTRACTABLE attribute set to TRUE, Cryptoki (or the token) is unable to wrap the key as requested (possibly the token simply won't support it). |
|
|
Although the requested keyed cryptographic operation could in principal be carried out, this Cryptoki library (or the token) is unable to actually do it because the supplied key 's size is outside the range of key sizes that it can handle. |
|
|
The specified key is not the correct type of key to use with the specified mechanism. This return value has a higher priority than CKR_KEY_FUNCTION_NOT_PERMITTED. |
|
|
The specified private or secret key can't be wrapped because its CKA_UNEXTRACTABLE attribute is set to TRUE. |
|
|
An invalid mechanism was specified to the cryptographic operation. |
|
|
Invalid parameters were supplied to the mechanism specified to the cryptographic operation. |
|
|
The specified object handle is not valid. We reiterate here that 0 is never a valid object handle. |
|
|
There is already an active operation (or combination of active operations) which prevents Cryptoki from activating the specified operation. For example, an active object-searching operation would prevent Cryptoki from activating an encryption operation with '''C_EncryptInit'''. Or, an active digesting operation and an active encryption operation would prevent Cryptoki from activating a signature operation. Or, on a token which doesn't support dual cryptographic operations (see the description of the CKF_DUAL_CRYPTO_OPERATIONS flag in the '''CK_TOKEN_INFO''' structure), an active signature operation would prevent Cryptoki from activating an encryption operation. |
|
|
There is no active operation of an appropriate type in the specified session. For example, an application cannot call '''C_Encrypt''' in a session without having called '''C_EncryptInit''' first to activate an encryption operation. |
|
|
The specified PIN is wrong, and does not match the PIN stored on the token. More generally, the attempt to authenticate the user has failed. |
|
|
The specified PIN has invalid characters in it. This return code only applies to functions which attempt to set a PIN. |
|
|
The specified PIN is too long or too short. This return code only applies to functions which attempt to set a PIN. |
|
|
The specified token doesn't have a random number generator. |
|
|
The token's random number generator does not accept seeding from an application. |
|
|
The supplied saved cryptographic operations state is invalid, and so it cannot be restored to the specified session. |
|
|
The attempt to open a session failed, either because the token has too many sessions already open, or because the token has too many read/write sessions already open. |
|
|
The attempt to open a session failed because there already exists an exclusive session. |
|
|
A session with the token is already open. |
|
|
The specified token does not support parallel sessions. |
|
|
The specified session was unable to accomplish the desired action because it is a read-only session. This return value has higher priority than CKR_TOKEN_WRITE_PROTECTED. |
|
|
A read-only session already exists, and so the SO cannot be logged in. |
|
|
A read/write SO session already exists, and so a read-only session cannot be opened. |
|
|
The provided signature/MAC can be seen to be invalid, solely on the basis of its length. This return value has higher priority than CKR_SIGNATURE_INVALID. |
|
|
The provided signature/MAC is invalid. This return value has lower priority than CKR_SIGNATURE_LEN_RANGE. |
|
|
The specified slot ID is not valid. |
|
|
The cryptographic operations state of the specified session cannot be saved for some reason (possibly the token is simply unable to save the current state). This return value has lower priority than CKR_FUNCTION_PARALLEL and CKR_OPERATION_NOT_INITIALIZED. |
|
|
The template specified for creating an object is incomplete, and lacks some necessary attributes. |
|
|
The template specified for creating an object has conflicting attributes. |
|
|
The Cryptoki library and/or slot does not recognize the token in the slot. |
|
|
The requested action could not be performed because the token is write-protected. This return value has higher priority than CKR_SESSION_READ_ONLY. |
|
|
The key handle specified to be used to unwrap another key is not valid. |
|
|
Although the requested unwrapping operation could in principal be carried out, this Cryptoki library (or the token) is unable to actually do it because the supplied key's size is outside the range of key sizes that it can handle. |
|
|
The type of the key specified to unwrap another key is not consistent with the mechanism specified for unwrapping. |
|
|
The session cannot be logged in, because it is already logged in. |
|
|
The desired action cannot be performed because the appropriate user (or ''an'' appropriate user) is not logged in. One example is that a session cannot be logged out unless it is logged in. Another example is that a private object cannot be created on a token unless the session attempting to create it is logged in as the normal user. A final example is that cryptographic operations on certain tokens cannot be performed unless the normal user is logged in. |
|
|
The normal user's PIN has not been initialized with '''C_InitPIN'''. |
|
|
An invalid value was specified as a '''CK_USER_TYPE'''. Valid types are '''CKU_SO''' and '''CKU_USER'''. |
|
|
The wrapped key is not valid. This return value has lower priority than CKR_WRAPPED_KEY_LEN_RANGE. |
|
|
The provided wrapped key can be seen to be invalid, solely on the basis of its length. This return value has higher priority than CKR_WRAPPED_KEY_INVALID. |
|
|
The key handle specified to be used to wrap another key is not valid. |
|
|
Although the requested wrapping operation could in principal be carried out, this Cryptoki library (or the token) is unable to actually do it because the supplied wrapping key's size is outside the range of key sizes that it can handle. |
|
|
The type of the key specified to wrap another key is not consistent with the mechanism specified for wrapping. |
|
|
an unsigned 8-bit value. |
|
|
an unsigned 8-bit character. |
|
|
a BYTE-sized Boolean flag. |
|
|
an unsigned value, at least 32 bits long. |
|
|
a signed value, the same size as a CK_ULONG. |
|
|
at least 32 bits; each bit is a Boolean flag. |
|
|
Pointer to a CK_BYTE. |
|
|
Pointer to a CK_CHAR. |
|
|
Pointer to a CK_ULONG. |
|
|
Pointer to a void. |
|
|
A NULL pointer. |
|
|
CK_VERSIONCK_VERSION is a structure that describes the version of a Cryptoki interface, a Cryptoki library, an SSL implementation, or the hardware or firmware version of a slot or token.
For version 1.0, major = 1 and minor = For version 2.1, major = 2 and minor = 10. Minor revisions of the Cryptoki standard are always upwardly compatible within the same major version number.
CK_VERSION_PTRCK_VERSION_PTR points to a CK_VERSION structure. It is implementation-dependent.
CK_INFOCK_INFO provides general information about Cryptoki. It is defined as follows:
|
|
|
CK_INFOCK_INFO provides general information about Cryptoki. It is defined as follows:
For libraries written to the Cryptoki v2.0 document, the value of cryptokiVersion should be 2.0; the value of libraryVersion is the version number of the library software itself.
CK_INFO_PTRCK_INFO_PTR points to a CK_INFO structure. It is implementation-dependent.
CK_NOTIFICATIONCK_NOTIFICATION holds the types of notifications that Cryptoki provides to an application. It is defined as follows:
typedef CK_ULONG CK_NOTIFICATION; For this version of Cryptoki, the following types of notifications are defined:
#define CKN_SURRENDER 0 #define CKN_COMPLETE 1 #define CKN_DEVICE_REMOVED 2 #define CKN_TOKEN_INSERTION 3 The notifications have the following meanings: CKN_SURRENDER Cryptoki is surrendering the execution of a function executing in serial so that the application may perform other operations. After performing any desired operations, the application should indicate to Cryptoki whether to continue or cancel the function. CKN_COMPLETE a function running in parallel has completed. CKN_DEVICE_REMOVED Cryptoki has detected that the device underlying the token has been removed from the reader. Not all slots/tokens support this notification. CKN_TOKEN_INSERTION Cryptoki has detected that the device underlying the token has been inserted into the reader. Not all slots/tokens support this notification. Slot and token types Cryptoki represents slot and token information with the following types:
CK_SLOT_IDCK_SLOT_ID is a Cryptoki-assigned value that identifies a slot. It is defined as follows:
typedef CK_ULONG CK_SLOT_ID; A CK_SLOT_ID is returned by C_GetSlotList.
CK_SLOT_ID_PTRCK_SLOT_ID_PTR points to a CK_SLOT_ID. It is implementation-dependent.
CK_SLOT_INFOCK_SLOT_INFO provides information about a slot. It is defined as follows:
|
|
|
CK_NOTIFICATIONCK_NOTIFICATION holds the types of notifications that Cryptoki provides to an application. |
|
|
CK_SLOT_IDCK_SLOT_ID is a Cryptoki-assigned value that identifies a slot. It is defined as follows: |
|
|
CK_SLOT_INFOCK_SLOT_INFO provides information about a slot. It is defined as follows:
The following table defines the flags parameter:
Table 7-1, Slot Information Flags
CK_SLOT_INFO_PTRCK_SLOT_INFO_PTR points to a CK_SLOT_INFO structure. It is implementation-dependent.
CK_TOKEN_INFOCK_TOKEN_INFO provides information about a token. It is defined as follows:
|
|
|
CK_TOKEN_INFOCK_TOKEN_INFO provides information about a token. It is defined as follows:
The following table defines the flags parameter:
Table 7-2, Token Information Flags
Exactly what the CKF_WRITE_PROTECTED flag means is not specified in Cryptoki. An application may be unable to perform certain actions on a write-protected token; these actions can include any of the following, among other actions:
CK_TOKEN_INFO info; . . . if ((CK_LONG) info.ulMaxSessionCount == -1) { /* Token refuses to give value of ulMaxSessionCount */ . . . } else { /* info.ulMaxSessionCount really does contain what it should */ . . . }
CK_TOKEN_INFO_PTRCK_TOKEN_INFO_PTR points to a CK_TOKEN_INFO structure. It is implementation-dependent.Session types Cryptoki represents session information with the following types:
CK_SESSION_HANDLECK_SESSION_HANDLE is a Cryptoki-assigned value that identifies a session. It is defined as follows:
typedef CK_ULONG CK_SESSION_HANDLE;
CK_SESSION_HANDLE_PTRCK_SESSION_HANDLE_PTR points to a CK_SESSION_HANDLE. It is implementation-dependent.
CK_USER_TYPECK_USER_TYPE holds the types of Cryptoki users described in Section . It is defined as follows:
typedef CK_ULONG CK_USER_TYPE; For this version of Cryptoki, the following types of users are defined:
#define CKU_SO 0 #define CKU_USER 1
CK_STATECK_STATE holds the session state, as decribed in Sections and . It is defined as follows:
For this version of Cryptoki, the following session states are defined:
#define CKS_RO_PUBLIC_SESSION 0 #define CKS_RO_USER_FUNCTIONS 1 #define CKS_RW_PUBLIC_SESSION 2 #define CKS_RW_USER_FUNCTIONS 3 #define CKS_RW_SO_FUNCTIONS 4
CK_SESSION_INFOCK_SESSION_INFO provides information about a session. It is defined as follows:
|
|
|
CK_SESSION_HANDLECK_SESSION_HANDLE is a Cryptoki-assigned value that identifies a session. |
|
|
CK_USER_TYPECK_USER_TYPE holds the types of Cryptoki users described in Section .. |
|
|
CK_STATECK_STATE holds the session state, as decribed in Sections and . It is defined as follows: |
|
|
CK_SESSION_INFOCK_SESSION_INFO provides information about a session. It is defined as follows:
The following table defines the flags parameter:
Table 7-3, Session Information Flags
CK_SESSION_INFO_PTRCK_SESSION_INFO_PTR points to a CK_SESSION_INFO structure. It is implementation-dependent.Object types Cryptoki represents object information with the following types:
CK_OBJECT_HANDLECK_OBJECT_HANDLE is a token-specific identifier for an object. It is defined as follows:
typedef CK_ULONG CK_OBJECT_HANDLE; When an object is created or found on a token, Cryptoki assigns it an object handle for sessions to use to access it. A particular object on a token does not necessarily have a handle which is fixed for the lifetime of the object; however, if a particular session can use a particular handle to access a particular object, then that session will continue to be able to use that handle to acces that object as long as the session continues to exist, the object continues to exist, and the object continues to be accessible to the session.
CK_OBJECT_HANDLE_PTRCK_OBJECT_HANDLE_PTR points to a CK_OBJECT_HANDLE. It is implementation-dependent.
CK_OBJECT_CLASSCK_OBJECT_CLASS is a value that identifies the classes (or types) of objects that Cryptoki recognizes. It is defined as follows:
typedef CK_ULONG CK_OBJECT_CLASS; For this version of Cryptoki, the following classes of objects are defined:
#define CKO_DATA 0x00000000 #define CKO_CERTIFICATE 0x00000001 #define CKO_PUBLIC_KEY 0x00000002 #define CKO_PRIVATE_KEY 0x00000003 #define CKO_SECRET_KEY 0x00000004 #define CKO_VENDOR_DEFINED 0x80000000 Object classes CKO_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their object classes through the PKCS process.
CK_OBJECT_CLASS_PTRCK_OBJECT_CLASS_PTR points to a CK_OBJECT_CLASS structure. It is implementation-dependent.
CK_KEY_TYPECK_KEY_TYPE is a value that identifies a key type. It is defined as follows:
typedef CK_ULONG CK_KEY_TYPE; For this version of Cryptoki, the following key types are defined:
#define CKK_RSA 0x00000000 #define CKK_DSA 0x00000001 #define CKK_DH 0x00000002 #define CKK_ECDSA 0x00000003 #define CKK_MAYFLY 0x00000004 #define CKK_KEA 0x00000005 #define CKK_GENERIC_SECRET 0x00000010 #define CKK_RC2 0x00000011 #define CKK_RC4 0x00000012 #define CKK_DES 0x00000013 #define CKK_DES2 0x00000014 #define CKK_DES3 0x00000015 #define CKK_CAST 0x00000016 #define CKK_CAST3 0x00000017 #define CKK_CAST5 0x00000018 #define CKK_RC5 0x00000019 #define CKK_IDEA 0x0000001A #define CKK_SKIPJACK 0x0000001B #define CKK_BATON 0x0000001C #define CKK_JUNIPER 0x0000001D #define CKK_CDMF 0x0000001E #define CKK_VENDOR_DEFINED 0x80000000 Key types CKK_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their key types through the PKCS process.
CK_CERTIFICATE_TYPECK_CERTIFICATE_TYPE is a value that identifies a certificate type. It is defined as follows:
typedef CK_ULONG CK_CERTIFICATE_TYPE; For this version of Cryptoki, the following certificate types are defined:
#define CKC_X_509 0x00000000 #define CKC_VENDOR_DEFINED 0x80000000 Certificate types CKC_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their certificate types through the PKCS process.
CK_ATTRIBUTE_TYPECK_ATTRIBUTE_TYPE is a value that identifies an attribute type. It is defined as follows:
typedef CK_ULONG CK_ATTRIBUTE_TYPE; For this version of Cryptoki, the following attribute types are defined:
#define CKA_CLASS 0x00000000 #define CKA_TOKEN 0x00000001 #define CKA_PRIVATE 0x00000002 #define CKA_LABEL 0x00000003 #define CKA_APPLICATION 0x00000010 #define CKA_VALUE 0x00000011 #define CKA_CERTIFICATE_TYPE 0x00000080 #define CKA_ISSUER 0x00000081 #define CKA_SERIAL_NUMBER 0x00000082 #define CKA_KEY_TYPE 0x00000100 #define CKA_SUBJECT 0x00000101 #define CKA_ID 0x00000102 #define CKA_SENSITIVE 0x00000103 #define CKA_ENCRYPT 0x00000104 #define CKA_DECRYPT 0x00000105 #define CKA_WRAP 0x00000106 #define CKA_UNWRAP 0x00000107 #define CKA_SIGN 0x00000108 #define CKA_SIGN_RECOVER 0x00000109 #define CKA_VERIFY 0x0000010A #define CKA_VERIFY_RECOVER 0x0000010B #define CKA_DERIVE 0x0000010C #define CKA_START_DATE 0x00000110 #define CKA_END_DATE 0x00000111 #define CKA_MODULUS 0x00000120 #define CKA_MODULUS_BITS 0x00000121 #define CKA_PUBLIC_EXPONENT 0x00000122 #define CKA_PRIVATE_EXPONENT 0x00000123 #define CKA_PRIME_1 0x00000124 #define CKA_PRIME_2 0x00000125 #define CKA_EXPONENT_1 0x00000126 #define CKA_EXPONENT_2 0x00000127 #define CKA_COEFFICIENT 0x00000128 #define CKA_PRIME 0x00000130 #define CKA_SUBPRIME 0x00000131 #define CKA_BASE 0x00000132 #define CKA_VALUE_BITS 0x00000160 #define CKA_VALUE_LEN 0x00000161 #define CKA_EXTRACTABLE 0x00000162 #define CKA_LOCAL 0x00000163 #define CKA_NEVER_EXTRACTABLE 0x00000164 #define CKA_ALWAYS_SENSITIVE 0x00000165 #define CKA_MODIFIABLE 0x00000170 #define CKA_VENDOR_DEFINED 0x80000000 Section defines the attributes for each object class. Attribute types CKA_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their attribute types through the PKCS process.
CK_ATTRIBUTECK_ATTRIBUTE is a structure that includes the type, length and value of an attribute. It is defined as follows:
|
|
|
CK_OBJECT_HANDLECK_OBJECT_HANDLE is a token-specific identifier for an object. It is defined as follows: |
|
|
CK_OBJECT_CLASSCK_OBJECT_CLASS is a value that identifies the classes (or types) of objects that Cryptoki recognizes. |
|
|
CK_KEY_TYPECK_KEY_TYPE is a value that identifies a key type. It is defined as follows: |
|
|
CK_CERTIFICATE_TYPECK_CERTIFICATE_TYPE is a value that identifies a certificate type. |
|
|
CK_ATTRIBUTE_TYPECK_ATTRIBUTE_TYPE is a value that identifies an attribute type. It is defined as follows: |
|
|
CK_ATTRIBUTECK_ATTRIBUTE is a structure that includes the type, length and value of an attribute.
If an attribute has no value, then pValue = NULL_PTR, and ulValueLen = 0. An array of CK_ATTRIBUTEs is called a "template" and is used for creating, manipulating and searching for objects. Note that pValue is an "void" pointer, facilitating the passing of arbitrary values. Both the application and Cryptoki library must ensure that the pointer can be safely cast to the expected type (e.g., without word-alignment errors).
CK_ATTRIBUTE_PTRCK_ATTRIBUTE_PTR points to a CK_ATTRIBUTE structure. It is implementation-dependent.
CK_DATECK_DATE is a structure that defines a date. It is defined as follows:
|
|
|
CK_DATECK_DATE is a structure that defines a date. It is defined as follows:
The fields hold numeric characters from the character set in Table 4 -3, not the literal byte values. Data types for mechanisms Cryptoki supports the following types for describing mechanisms and parameters to them:
CK_MECHANISM_TYPECK_MECHANISM_TYPE is a value that identifies a mechanism type. It is defined as follows:
typedef CK_ULONG CK_MECHANISM_TYPE; For Cryptoki v2.0, the following mechanism types are defined:
#define CKM_RSA_PKCS_KEY_PAIR_GEN 0x00000000 #define CKM_RSA_PKCS 0x00000001 #define CKM_RSA_9796 0x00000002 #define CKM_RSA_X_509 0x00000003 #define CKM_MD2_RSA_PKCS 0x00000004 #define CKM_MD5_RSA_PKCS 0x00000005 #define CKM_SHA1_RSA_PKCS 0x00000006 #define CKM_DSA_KEY_PAIR_GEN 0x00000010 #define CKM_DSA 0x00000011 #define CKM_DSA_SHA1 0x00000012 #define CKM_DH_PKCS_KEY_PAIR_GEN 0x00000020 #define CKM_DH_PKCS_DERIVE 0x00000021 #define CKM_RC2_KEY_GEN 0x00000100 #define CKM_RC2_ECB 0x00000101 #define CKM_RC2_CBC 0x00000102 #define CKM_RC2_MAC 0x00000103 #define CKM_RC2_MAC_GENERAL 0x00000104 #define CKM_RC2_CBC_PAD 0x00000105 #define CKM_RC4_KEY_GEN 0x00000110 #define CKM_RC4 0x00000111 #define CKM_DES_KEY_GEN 0x00000120 #define CKM_DES_ECB 0x00000121 #define CKM_DES_CBC 0x00000122 #define CKM_DES_MAC 0x00000123 #define CKM_DES_MAC_GENERAL 0x00000124 #define CKM_DES_CBC_PAD 0x00000125 #define CKM_DES2_KEY_GEN 0x00000130 #define CKM_DES3_KEY_GEN 0x00000131 #define CKM_DES3_ECB 0x00000132 #define CKM_DES3_CBC 0x00000133 #define CKM_DES3_MAC 0x00000134 #define CKM_DES3_MAC_GENERAL 0x00000135 #define CKM_DES3_CBC_PAD 0x00000136 #define CKM_CDMF_KEY_GEN 0x00000140 #define CKM_CDMF_ECB 0x00000141 #define CKM_CDMF_CBC 0x00000142 #define CKM_CDMF_MAC 0x00000143 #define CKM_CDMF_MAC_GENERAL 0x00000144 #define CKM_CDMF_CBC_PAD 0x00000145 #define CKM_MD2 0x00000200 #define CKM_MD2_HMAC 0x00000201 #define CKM_MD2_HMAC_GENERAL 0x00000202 #define CKM_MD5 0x00000210 #define CKM_MD5_HMAC 0x00000211 #define CKM_MD5_HMAC_GENERAL 0x00000212 #define CKM_SHA_1 0x00000220 #define CKM_SHA_1_HMAC 0x00000221 #define CKM_SHA_1_HMAC_GENERAL 0x00000222 #define CKM_CAST_KEY_GEN 0x00000300 #define CKM_CAST_ECB 0x00000301 #define CKM_CAST_CBC 0x00000302 #define CKM_CAST_MAC 0x00000303 #define CKM_CAST_MAC_GENERAL 0x00000304 #define CKM_CAST_CBC_PAD 0x00000305 #define CKM_CAST3_KEY_GEN 0x00000310 #define CKM_CAST3_ECB 0x00000311 #define CKM_CAST3_CBC 0x00000312 #define CKM_CAST3_MAC 0x00000313 #define CKM_CAST3_MAC_GENERAL 0x00000314 #define CKM_CAST3_CBC_PAD 0x00000315 #define CKM_CAST5_KEY_GEN 0x00000320 #define CKM_CAST5_ECB 0x00000321 #define CKM_CAST5_CBC 0x00000322 #define CKM_CAST5_MAC 0x00000323 #define CKM_CAST5_MAC_GENERAL 0x00000324 #define CKM_CAST5_CBC_PAD 0x00000325 #define CKM_RC5_KEY_GEN 0x00000330 #define CKM_RC5_ECB 0x00000331 #define CKM_RC5_CBC 0x00000332 #define CKM_RC5_MAC 0x00000333 #define CKM_RC5_MAC_GENERAL 0x00000334 #define CKM_RC5_CBC_PAD 0x00000335 #define CKM_IDEA_KEY_GEN 0x00000340 #define CKM_IDEA_ECB 0x00000341 #define CKM_IDEA_CBC 0x00000342 #define CKM_IDEA_MAC 0x00000343 #define CKM_IDEA_MAC_GENERAL 0x00000344 #define CKM_IDEA_CBC_PAD 0x00000345 #define CKM_GENERIC_SECRET_KEY_GEN 0x00000350 #define CKM_CONCATENATE_BASE_AND_KEY 0x00000360 #define CKM_CONCATENATE_BASE_AND_DATA 0x00000362 #define CKM_CONCATENATE_DATA_AND_BASE 0x00000363 #define CKM_XOR_BASE_AND_DATA 0x00000364 #define CKM_EXTRACT_KEY_FROM_KEY 0x00000365 #define CKM_SSL3_PRE_MASTER_KEY_GEN 0x00000370 #define CKM_SSL3_MASTER_KEY_DERIVE 0x00000371 #define CKM_SSL3_KEY_AND_MAC_DERIVE 0x00000372 #define CKM_SSL3_MD5_MAC 0x00000380 #define CKM_SSL3_SHA1_MAC 0x00000381 #define CKM_MD5_KEY_DERIVATION 0x00000390 #define CKM_MD2_KEY_DERIVATION 0x00000391 #define CKM_SHA1_KEY_DERIVATION 0x00000392 #define CKM_PBE_MD2_DES_CBC 0x000003A0 #define CKM_PBE_MD5_DES_CBC 0x000003A1 #define CKM_PBE_MD5_CAST_CBC 0x000003A2 #define CKM_PBE_MD5_CAST3_CBC 0x000003A3 #define CKM_PBE_MD5_CAST5_CBC 0x000003A4 #define CKM_KEY_WRAP_LYNKS 0x00000400 #define CKM_KEY_WRAP_SET_OAEP 0x00000401 #define CKM_SKIPJACK_KEY_GEN 0x00001000 #define CKM_SKIPJACK_ECB64 0x00001001 #define CKM_SKIPJACK_CBC64 0x00001002 #define CKM_SKIPJACK_OFB64 0x00001003 #define CKM_SKIPJACK_CFB64 0x00001004 #define CKM_SKIPJACK_CFB32 0x00001005 #define CKM_SKIPJACK_CFB16 0x00001006 #define CKM_SKIPJACK_CFB8 0x00001007 #define CKM_SKIPJACK_WRAP 0x00001008 #define CKM_SKIPJACK_PRIVATE_WRAP 0x00001009 #define CKM_SKIPJACK_RELAYX 0x0000100a #define CKM_KEA_KEY_PAIR_GEN 0x00001010 #define CKM_KEA_KEY_DERIVE 0x00001011 #define CKM_FORTEZZA_TIMESTAMP 0x00001020 #define CKM_BATON_KEY_GEN 0x00001030 #define CKM_BATON_ECB128 0x00001031 #define CKM_BATON_ECB96 0x00001032 #define CKM_BATON_CBC128 0x00001033 #define CKM_BATON_COUNTER 0x00001034 #define CKM_BATON_SHUFFLE 0x00001035 #define CKM_BATON_WRAP 0x00001036 #define CKM_ECDSA_KEY_PAIR_GEN 0x00001040 #define CKM_ECDSA 0x00001041 #define CKM_ECDSA_SHA1 0x00001042 #define CKM_MAYFLY_KEY_PAIR_GEN 0x00001050 #define CKM_MAYFLY_KEY_DERIVE 0x00001051 #define CKM_JUNIPER_KEY_GEN 0x00001060 #define CKM_JUNIPER_ECB128 0x00001061 #define CKM_JUNIPER_CBC128 0x00001062 #define CKM_JUNIPER_COUNTER 0x00001063 #define CKM_JUNIPER_SHUFFLE 0x00001064 #define CKM_JUNIPER_WRAP 0x00001065 #define CKM_FASTHASH 0x00001070 #define CKM_VENDOR_DEFINED 0x80000000 Mechanism types CKM_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their mechanism types through the PKCS process.
CK_MECHANISM_TYPE_PTRCK_MECHANISM_TYPE_PTR points to a CK_MECHANISM_TYPE structure. It is implementation-dependent.
CK_MECHANISMCK_MECHANISM is a structure that specifies a particular mechanism. It is defined as follows:
|
|
|
CK_MECHANISM_TYPECK_MECHANISM_TYPE is a value that identifies a mechanism type. It is defined as follows: |
|
|
CK_MECHANISMCK_MECHANISM is a structure that specifies a particular mechanism.
Note that pParameter is a "void" pointer, facilitating the passing of arbitrary values. Both the application and Cryptoki library must ensure that the pointer can be safely cast to the expected type (e.g., without word-alignment errors).
CK_MECHANISM_PTRCK_MECHANISM_PTR points to a CK_MECHANISM structure. It is implementation-dependent.
CK_MECHANISM_INFOCK_MECHANISM_INFO is a structure that provides information about a particular mechanism. It is defined as follows:
|
|
|
CK_MECHANISM_INFOCK_MECHANISM_INFO is a structure that provides information about a particular mechanism.
For some mechanisms, the ulMinKeySize and ulMaxKeySize fields have meaningless values. The following table defines the flags parameter:
Table 7-4, Mechanism Information Flags
CK_MECHANISM_INFO_PTRCK_MECHANISM_INFO_PTR points to a CK_MECHANISM_INFO structure. It is implementation-dependent.Function types Cryptoki represents information about functions with the following data types:
CK_ENTRYCK_ENTRY is not really a type. Rather, it is a string used provided to a C compiler in a given environment to produce an entry into Cryptoki (i.e., a Cryptoki function). It is implementation-dependent. For a Win32 Cryptoki .dll, it might be "__declspec( dllexport)". For a Win16 Cryptoki .dll, it might be "_export _far _pascal". For a Unix library, it might be "".
CK_RVCK_RV is a value that identifies the return value of a Cryptoki function. It is defined as follows:
For this version of Cryptoki, the following return values are defined:
#define CKR_OK 0x00000000 #define CKR_CANCEL 0x00000001 #define CKR_HOST_MEMORY 0x00000002 #define CKR_SLOT_ID_INVALID 0x00000003 #define CKR_GENERAL_ERROR 0x00000005 #define CKR_FUNCTION_FAILED 0x00000006 #define CKR_ATTRIBUTE_READ_ONLY 0x00000010 #define CKR_ATTRIBUTE_SENSITIVE 0x00000011 #define CKR_ATTRIBUTE_TYPE_INVALID 0x00000012 #define CKR_ATTRIBUTE_VALUE_INVALID 0x00000013 #define CKR_DATA_INVALID 0x00000020 #define CKR_DATA_LEN_RANGE 0x00000021 #define CKR_DEVICE_ERROR 0x00000030 #define CKR_DEVICE_MEMORY 0x00000031 #define CKR_DEVICE_REMOVED 0x00000032 #define CKR_ENCRYPTED_DATA_INVALID 0x00000040 #define CKR_ENCRYPTED_DATA_LEN_RANGE 0x00000041 #define CKR_FUNCTION_CANCELED 0x00000050 #define CKR_FUNCTION_NOT_PARALLEL 0x00000051 #define CKR_FUNCTION_PARALLEL 0x00000052 #define CKR_FUNCTION_NOT_SUPPORTED 0x00000054 #define CKR_KEY_HANDLE_INVALID 0x00000060 #define CKR_KEY_SIZE_RANGE 0x00000062 #define CKR_KEY_TYPE_INCONSISTENT 0x00000063 #define CKR_KEY_NOT_NEEDED 0x00000064 #define CKR_KEY_CHANGED 0x00000065 #define CKR_KEY_NEEDED 0x00000066 #define CKR_KEY_INDIGESTIBLE 0x00000067 #define CKR_KEY_FUNCTION_NOT_PERMITTED 0x00000068 #define CKR_KEY_NOT_WRAPPABLE 0x00000069 #define CKR_KEY_UNEXTRACTABLE 0x0000006A #define CKR_MECHANISM_INVALID 0x00000070 #define CKR_MECHANISM_PARAM_INVALID 0x00000071 #define CKR_OBJECT_HANDLE_INVALID 0x00000082 #define CKR_OPERATION_ACTIVE 0x00000090 #define CKR_OPERATION_NOT_INITIALIZED 0x00000091 #define CKR_PIN_INCORRECT 0x000000A0 #define CKR_PIN_INVALID 0x000000A1 #define CKR_PIN_LEN_RANGE 0x000000A2 #define CKR_SESSION_CLOSED 0x000000B0 #define CKR_SESSION_COUNT 0x000000B1 #define CKR_SESSION_EXCLUSIVE_EXISTS 0x000000B2 #define CKR_SESSION_HANDLE_INVALID 0x000000B3 #define CKR_SESSION_PARALLEL_NOT_SUPPORTED 0x000000B4 #define CKR_SESSION_READ_ONLY 0x000000B5 #define CKR_SESSION_EXISTS 0x000000B6 #define CKR_SESSION_READ_ONLY_EXISTS 0x000000B7 #define CKR_SESSION_READ_WRITE_SO_EXISTS 0x000000B8 #define CKR_SIGNATURE_INVALID 0x000000C0 #define CKR_SIGNATURE_LEN_RANGE 0x000000C1 #define CKR_TEMPLATE_INCOMPLETE 0x000000D0 #define CKR_TEMPLATE_INCONSISTENT 0x000000D1 #define CKR_TOKEN_NOT_PRESENT 0x000000E0 #define CKR_TOKEN_NOT_RECOGNIZED 0x000000E1 #define CKR_TOKEN_WRITE_PROTECTED 0x000000E2 #define CKR_UNWRAPPING_KEY_HANDLE_INVALID 0x000000F0 #define CKR_UNWRAPPING_KEY_SIZE_RANGE 0x000000F1 #define CKR_UNWRAPPING_KEY_TYPE_INCONSISTENT 0x000000F2 #define CKR_USER_ALREADY_LOGGED_IN 0x00000100 #define CKR_USER_NOT_LOGGED_IN 0x00000101 #define CKR_USER_PIN_NOT_INITIALIZED 0x00000102 #define CKR_USER_TYPE_INVALID 0x00000103 #define CKR_WRAPPED_KEY_INVALID 0x00000110 #define CKR_WRAPPED_KEY_LEN_RANGE 0x00000112 #define CKR_WRAPPING_KEY_HANDLE_INVALID 0x00000113 #define CKR_WRAPPING_KEY_SIZE_RANGE 0x00000114 #define CKR_WRAPPING_KEY_TYPE_INCONSISTENT 0x00000115 #define CKR_RANDOM_SEED_NOT_SUPPORTED 0x00000120 #define CKR_RANDOM_NO_RNG 0x00000121 #define CKR_INSERTION_CALLBACK_NOT_SUPPORTED 0x00000141 #define CKR_BUFFER_TOO_SMALL 0x00000150 #define CKR_SAVED_STATE_INVALID 0x00000160 #define CKR_INFORMATION_SENSITIVE 0x00000170 #define CKR_STATE_UNSAVEABLE 0x00000180 #define CKR_VENDOR_DEFINED 0x80000000 Section defines the meaning of each CK_RV value. Return values CKR_VENDOR_DEFINED and above are permanently reserved for token vendors. For interoperability, vendors should register their return values through the PKCS process.
CK_NOTIFYCK_NOTIFY is the type of a pointer to a function used by Cryptoki to perform notification callbacks. It is implementation-dependent, but it is typically defined as follows, where CK_PTR is the C string used to create function pointers (e.g., "*"):
typedef CK_RV (CK_ENTRY * CK_NOTIFY)( CK_SESSION_HANDLE hSession, CK_NOTIFICATION event, CK_VOID_PTR pApplication ); The arguments to a notification callback function have the following meanings: hSession The handle of the session performing the callback event The type of notification callback pApplication An application-defined value. This is the same value as was passed to C_OpenSession to open the session performing the callback Cryptoki also defines an entire family of other function pointer types. For each function C_XXX in the Cryptoki API (there are 67 such functions in Cryptoki v2.0; see Section for detailed information about each of them), Cryptoki defines a type CK_C_XXX, which is a pointer to a function of C_XXX 's type.
CK_FUNCTION_LISTCK_FUNCTION_LIST is a structure which contains a Cryptoki version and a function pointer to each function in the Cryptoki API. It is defined as follows:
|
|
|
CK_RVCK_RV is a value that identifies the return value of a Cryptoki function. |
|
|
CK_NOTIFYCK_NOTIFY is the type of a pointer to a function used by Cryptoki to perform notification callbacks. It is implementation-dependent, but it is typically defined as follows, where CK_PTR is the C string used to create function pointers (e.g., "*"): |
|
|
CK_FUNCTION_LISTCK_FUNCTION_LIST is a structure which contains a Cryptoki version and a function pointer to each function in the Cryptoki API. It is defined as follows:CK_FUNCTION_LIST_PTRCK_FUNCTION_LIST_PTR points to a CK_FUNCTION_LIST. It is implementation-dependent.
CK_FUNCTION_LIST_PTR_PTRCK_FUNCTION_LIST_PTR_PTR points to a CK_FUNCTION_LIST_PTR. It is implementation-dependent. |
|
|
CK_KEA_DERIVE_PARAMSCK_KEA_DERIVE_PARAMS is a structure that provides the parameters to the CKM_KEA_DERIVE mechanism.
CK_KEA_DERIVE_PARAMS_PTR points to a CK_KEA_DERIVE_PARAMS structure. It is implementation-dependent. KEA mechanisms KEA key pair generation The KEA key pair generation mechanism, denoted CKM_KEA_KEY_PAIR_GEN, is a key pair generation mechanism It does not have a parameter. The mechanism generates KEA public/private key pairs with a particular prime, subprime and base, as specified in the CKA_PRIME, CKA_SUBPRIME, and CKA_BASE attributes of the template for the public key. Note that this version of Cryptoki does not include a mechanism for generating these KEA parameters. The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_BASE, and CKA_VALUE attributes to the new private key. Other attributes supported by the KEA public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys, 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 KEA prime sizes, in bits. KEA key derivation The KEA key derivation mechanism, denoted CKM_KEA_DERIVE, is a mechanism for key derivation based on KEA, the Key Exchange Algorithm. It has a parameter, a CK_KEA_DERIVE_PARAMS structure. This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. The derived key inherits the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The values of the CKA_SENSITIVE and CKA_EXTRACTABLE attributes may be overridden in the template for the derived key, however. Of course, if the base key has the CKA_ALWAYS_SENSITIVE attribute set to TRUE, then the template may not specify that the derived key should have the CKA_SENSITIVE attribute set to FALSE; similarly, if the base key has the CKA_NEVER_EXTRACTABLE attribute set to TRUE, then the template may not specify that the derived key should have the CKA_EXTRACTABLE attribute set to TRUE. For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of KEA prime sizes, in bits. MAYFLY mechanism parameters
CK_MAYFLY_DERIVE_PARAMSCK_MAYFLY_DERIVE_PARAMS is a structure that provides the parameters to the CKM_MAYFLY_DERIVE mechanism. It is defined as follows:
|
|
|
CK_MAYFLY_DERIVE_PARAMSCK_MAYFLY_DERIVE_PARAMS is a structure that provides the parameters to the CKM_MAYFLY_DERIVE mechanism.
CK_MAYFLY_DERIVE_PARAMS_PTR points to a CK_MAYFLY_DERIVE_PARAMS structure. It is implementation-dependent. MAYFLY mechanisms MAYFLY key pair generation The MAYFLY key pair generation mechanism, called CKM_KEA_KEY_PAIR_GEN, is a key pair generation mechanism for the MAYFLY key exchange key pair. It does not have a parameter. The mechanism generates MAYFLY public/private key pairs with a particular prime, subprime and base, as specified in the CKA_PRIME, CKA_SUBPRIME, and CKA_BASE attributes of the template for the public key. Note that this version of Cryptoki does not include a mechanism for generating these MAYFLY parameters. The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new public key and the CKA_CLASS, CKA_KEY_TYPE, CKA_PRIME, CKA_SUBPRIME, CKA_BASE, and CKA_VALUE attributes to the new private key. Other attributes supported by the MAYFLY public and private key types (specifically, the flags indicating which functions the keys support) may also be specified in the templates for the keys 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 MAYFLY prime sizes, in bits. MAYFLY key derivation The MAYFLY key derivation mechanism, denoted CKM_MAYFLY_DERIVE, is a mechanism for key derivation based on MAYFLY. It has a parameter, a CK_MAYFLY_DERIVE_PARAMS structure. This mechanism derives a secret value, and truncates the result according to the CKA_KEY_TYPE attribute of the template and, if it has one and the key type supports it, the CKA_VALUE_LEN attribute of the template. (The truncation removes bytes from the leading end of the secret value.) The mechanism contributes the result as the CKA_VALUE attribute of the new key; other attributes required by the key type must be specified in the template. The derived key inherits the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The values of the CKA_SENSITIVE and CKA_EXTRACTABLE attributes may be overridden in the template for the derived key, however. Of course, if the base key has the CKA_ALWAYS_SENSITIVE attribute set to TRUE, then the template may not specify that the derived key should have the CKA_SENSITIVE attribute set to FALSE; similarly, if the base key has the CKA_NEVER_EXTRACTABLE attribute set to TRUE, then the template may not specify that the derived key should have the CKA_EXTRACTABLE attribute set to TRUE. For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of MAYFLY prime sizes, in bits. Generic secret key mechanisms Generic secret key generation The generic secret key generation mechanism, denoted CKM_GENERIC_SECRET_KEY_GEN, is used to generate generic secret keys. The generated keys take on any attributes provided in the template passed to the C_GenerateKey call, and the CKA_VALUE_LEN attribute specifies the length of the key to be generated. It does not have a parameter. The template supplied must specify a value for the CKA_VALUE_LEN attribute. If the template specifies an object type and a class, they must have the following values:
CK_OBJECT_CLASS = CKO_SECRET_KEY; CK_KEY_TYPE = CKK_GENERIC_SECRET; For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of key sizes, in bits. Wrapping/unwrapping private keys (RSA, Diffie-Hellman, and DSA) Cryptoki v2.0 allows the use of secret keys for wrapping and unwrapping RSA private keys, Diffie-Hellman private keys, and DSA private keys. For wrapping, a private key is BER-encoded according to PKCS #8's PrivateKeyInfo ASN.1 type. PKCS #8 requires an algorithm identifier for the type of the secret key. The object identifiers for the needed algorithm identifiers are as follows:
rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1 }
dhKeyAgreement OBJECT IDENTIFIER ::= { pkcs-3 1}
DSA OBJECT IDENTIFIER ::= { iso(1) identifier-organization(3) oiw(14) secsig(3) algorithm(2) 12 }
where
pkcs-1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 1 }
pkcs-3 OBJECT IDENTIFIER ::= { iso(1) member-body(2) US(840) rsadsi(113549) pkcs(1) 3 }
These object identifiers have the following parameters, respectively:
NULL
DHParameter ::= SEQUENCE {
prime INTEGER, -- p
base INTEGER, -- g
privateValueLength INTEGER OPTIONAL
}
DSAParameters ::= SEQUENCE {
modulusLength INTEGER, -- length of p in bits
prime1 INTEGER, -- modulus p
prime2 INTEGER, -- modulus q
base INTEGER -- base g
}
Within the PrivateKeyInfo type:
* Diffie-Hellman private keys are encoded by expressing the private value as a sequence of bytes, most-significant byte first, and then BER-encoding that sequence of bytes as an OCTET STRING. * DSA private keys are encoded by expressing the private value as a sequence of of bytes, most-significant byte first, and then BER-encoding that sequence of bytes as an OCTET STRING. Once a private key has been BER-encoded as a PrivateKeyInfo type, the resulting string of bytes can be encrypted with the secret key. This encryption must be done in CBC mode with PKCS padding. Unwrapping a wrapped private key undoes the above procedure. The CBC-encrypted ciphertext is decrypted, and the PKCS padding is removed. The data thereby obtained are parsed as a PrivateKeyInfo type, and the wrapped key is produced. An error will result if the original wrapped key does not decrypt properly, or if the decrypted unpadded data does not parse properly, or its type does not match the key type specified in the template for the new key. The unwrapping mechanism contributes only those attributes specified in the PrivateKeyInfo type to the newly-unwrapped key; other attributes must be specified in the template, or will take their default values. The RC2 cipher RC2 is a proprietary block cipher which is trademarked by RSA Data Security. It has a variable keysize and an additional parameter, the "effective number of bits in the RC2 search space", which can take on values in the range 1-1024, inclusive. RC2 mechanism parameters
CK_RC2_PARAMSCK_RC2_PARAMS provides the parameters to the CKM_RC2_ECB and CKM_RC2_MAC mechanisms. It holds the effective number of bits in the RC2 search space. It is defined as follows:
typdef CK_ULONG CK_RC2_PARAMS;
CK_RC2_PARAMS_PTRCK_RC2_PARAMS_PTR points to a CK_RC2_PARAMS structure. It is implementation-dependent.
CK_RC2_CBC_PARAMSCK_RC2_CBC_PARAMS is a structure that provides the parameters to the CKM_RC2_CBC and CKM_RC2_CBC_PAD mechanisms. It is defined as follows:
|
|
|
CK_RC2_CBC_PARAMSCK_RC2_CBC_PARAMS is a structure that provides the parameters to the CKM_RC2_CBC and CKM_RC2_CBC_PAD mechanisms. It is defined as follows:
CK_RC2_CBC_PARAMS_PTR points to a CK_RC2_CBC_PARAMS structure. It is implementation-dependent.
CK_RC2_MAC_GENERAL_PARAMSCK_RC2_MAC_GENERAL_PARAMS is a structure that provides the parameters to the CKM_RC2_MAC_GENERAL mechanism. It is defined as follows:
|
|
|
CK_RC2_MAC_GENERAL_PARAMSCK_RC2_MAC_GENERAL_PARAMS is a structure that provides the parameters to the CKM_RC2_MAC_GENERAL mechanism. It is defined as follows:
CK_RC2_MAC_GENERAL_PARAMS_PTR points to a CK_RC2_MAC_GENERAL_PARAMS structure. It is implementation-dependent. RC2 mechanisms RC2 key generation The RC2 key generation mechanism, denoted CKM_RC2_KEY_GEN, is a key generation mechanism for RSA Data Security's proprietary block cipher RC2. It does not have a parameter. The mechanism generates RC2 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 RC2 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 RC2 key sizes, in bits. RC2-ECB RC2-ECB, denoted CKM_RC2_ECB, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on RSA Data Security's proprietary block cipher RC2 and electronic codebook mode as defined in FIPS PUB 81. It has a parameter, a CK_RC2_PARAMS, which indicates the effective number of bits in the RC2 search space. 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 seven null bytes so that the resulting length is a multiple of eight. 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 10-11, RC2-ECB: Key And Data Length Constraints
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC2 effective number of bits. RC2-CBC RC2-CBC, denoted CKM_RC2_CBC, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on RSA Data Security's proprietary block cipher RC2 and cipher-block chaining mode as defined in FIPS PUB 81. It has a parameter, a CK_RC2_CBC_PARAMS structure, where the first field indicates the effective number of bits in the RC2 search space, and the next field is the initialization vector for cipher block chaining mode. 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 seven null bytes so that the resulting length is a multiple of eight. 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 10-12, RC2-CBC: Key And Data Length Constraints
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC2 effective number of bits. RC2-CBC with PKCS padding RC2-CBC with PKCS padding, denoted CKM_RC2_CBC_PAD, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on RSA Data Security's proprietary block cipher RC2; cipher-block chaining mode as defined in FIPS PUB 81; and the block cipher padding method detailed in PKCS #7. It has a parameter, a CK_RC2_CBC_PARAMS structure, where the first field indicates the effective number of bits in the RC2 search space, and the next field is the 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, and DSA private keys (see Section for details). The entries in Table 10 -13 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 10-13, RC2-CBC with PKCS padding: Key And Data Length Constraints
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC2 effective number of bits. General-length RC2-MAC General-length RC2-MAC, denoted CKM_RC2_MAC_GENERAL, is a mechanism for single- and multiple-part signatures and verification, based on RSA Data Security's proprietary block cipher RC2 and data authentication as defined in FIPS PUB 113. It has a parameter, a CK_RC2_MAC_GENERAL_PARAMS structure, which specifies the effective number of bits in the RC2 search space and the output length desired from the mechanism. The output bytes from this mechanism are taken from the start of the final RC2 cipher block produced in the MACing process. Constraints on key types and the length of data are summarized in the following table:
Table 10-14, General-length RC2-MAC: Key And Data Length Constraints
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC2 effective number of bits. RC2-MAC RC2-MAC, denoted by CKM_RC2_MAC, is a special case of the general-length RC2-MAC mechanism (see Section). Instead of taking a CK_RC2_MAC_GENERAL_PARAMS parameter, it takes a CK_RC2_PARAMS parameter, which only contains the effective number of bits in the RC2 search space. RC2-MAC always produces and verifies 4-byte MACs. Constraints on key types and the length of data are summarized in the following table:
Table 10-15, RC2-MAC: Key And Data Length Constraints
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC2 effective number of bits. RC4 mechanisms RC4 key generation The RC4 key generation mechanism, denoted CKM_RC4_KEY_GEN, is a key generation mechanism for RSA Data Security's proprietary stream cipher RC4. It does not have a parameter. The mechanism generates RC4 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 RC4 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 RC4 key sizes, in bits. RC4 RC4, denoted CKM_RC4, is a mechanism for single- and multiple-part encryption and decryption based on RSA Data Security's proprietary stream cipher RC4. It does not have a parameter. Constraints on key types and the length of input and output data are summarized in the following table:
Table 10-16, RC4 Key And Data Length Constraints
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of RC4 key sizes, in bits. The RC5 cipher RC5 is a parametrizable block cipher for which RSA Data Security has applied for a patent. It has a variable wordsize, a variable keysize, and a variable number of rounds. The blocksize of RC5 is always equal to twice its wordsize. RC5 mechanism parameters
CK_RC5_PARAMSCK_RC5_PARAMS provides the parameters to the CKM_RC5_ECB and CKM_RC5_MAC mechanisms. It is defined as follows:
|
|
|
CK_RC5_CBC_PARAMSCK_RC5_CBC_PARAMS is a structure that provides the parameters to the CKM_RC5_CBC and CKM_RC5_CBC_PAD mechanisms. It is defined as follows:
CK_RC5_CBC_PARAMS_PTR points to a CK_RC5_CBC_PARAMS structure. It is implementation-dependent.
CK_RC5_MAC_GENERAL_PARAMSCK_RC5_MAC_GENERAL_PARAMS is a structure that provides the parameters to the CKM_RC5_MAC_GENERAL mechanism. It is defined as follows:
|
|
|
CK_RC5_MAC_GENERAL_PARAMSCK_RC5_MAC_GENERAL_PARAMS is a structure that provides the parameters to the CKM_RC5_MAC_GENERAL mechanism. It is defined as follows:
CK_RC5_MAC_GENERAL_PARAMS_PTR points to a CK_RC5_MAC_GENERAL_PARAMS structure. It is implementation-dependent. RC5 mechanisms RC5 key generation The RC5 key generation mechanism, denoted CKM_RC5_KEY_GEN, is a key generation mechanism for RSA Data Security's block cipher RC5. It does not have a parameter. The mechanism generates RC5 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 RC5 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 RC5 key sizes, in bytes. RC5-ECB RC5-ECB, denoted CKM_RC5_ECB, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on RSA Data Security's block cipher RC5 and electronic codebook mode as defined in FIPS PUB 81. It has a parameter, a CK_RC5_PARAMS, which indicates the wordsize and number of rounds of encryption to use. 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 null bytes so that the resulting length is a multiple of the cipher blocksize (twice the wordsize). 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 attributes 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 10-17, RC5-ECB: Key And Data Length Constraints
RC5-CBC RC5-CBC, denoted CKM_RC5_CBC, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on RSA Data Security's block cipher RC5 and cipher-block chaining mode as defined in FIPS PUB 81. It has a parameter, a CK_RC5_CBC_PARAMS structure, which specifies the wordsize and number of rounds of encryption to use, as well as the initialization vector for cipher block chaining mode. 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 seven null bytes so that the resulting length is a multiple of eight. 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 10-18, RC5-CBC: Key And Data Length Constraints
RC5-CBC with PKCS padding RC5-CBC with PKCS padding, denoted CKM_RC5_CBC_PAD, is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping, based on RSA Data Security's block cipher RC5; cipher-block chaining mode as defined in FIPS PUB 81; and the block cipher padding method detailed in PKCS #7. It has a parameter, a CK_RC5_CBC_PARAMS structure, which specifies the wordsize and number of rounds of encryption to use, as well as the initialization vector for cipher block chaining mode. 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, and DSA private keys (see Section for details). The entries in Table 10 -19 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 10-19, RC5-CBC with PKCS padding: Key And Data Length Constraints
General-length RC5-MAC General-length RC5-MAC, denoted CKM_RC5_MAC_GENERAL, is a mechanism for single- and multiple-part signatures and verification, based on RSA Data Security's block cipher RC5 and data authentication as defined in FIPS PUB 113. It has a parameter, a CK_RC5_MAC_GENERAL_PARAMS structure, which specifies the wordsize and number of rounds of encryption to use and the output length desired from the mechanism. The output bytes from this mechanism are taken from the start of the final RC5 cipher block produced in the MACing process. Constraints on key types and the length of data are summarized in the following table:
Table 10-20, General-length RC2-MAC: Key And Data Length Constraints
RC5-MAC RC5-MAC, denoted by CKM_RC5_MAC, is a special case of the general-length RC5-MAC mechanism (see Section). Instead of taking a CK_RC5_MAC_GENERAL_PARAMS parameter, it takes a CK_RC5_PARAMS parameter. RC5-MAC always produces and verifies MACs half as large as the RC5 blocksize. Constraints on key types and the length of data are summarized in the following table:
Table 10-21, RC5-MAC: Key And Data Length Constraints
General block cipher mechanism parameters
CK_MAC_GENERAL_PARAMSCK_MAC_GENERAL_PARAMS provides the parameters to the general-length MACing mechanisms of the DES, DES3 (triple-DES), CAST, CAST3, CAST5, IDEA, and CDMF ciphers. It holds the length of the MAC that these mechanisms will produce. It is defined as follows:
typedef CK_ULONG CK_MAC_GENERAL_PARAMS;
CK_MAC_GENERAL_PARAMS_PTRCK_MAC_GENERAL_PARAMS_PTR points to a CK_MAC_GENERAL_PARAMS. It is implementation-dependent.General block cipher mechanisms For brevity's sake, the mechanisms for the DES, DES3 (triple-DES), CAST, CAST3, CAST5, IDEA, and CDMF block ciphers will be described together here. Each of these ciphers has the following mechanisms, which will be described in a templatized form: General block cipher key generation Cipher <NAME> has a key generation mechanism, "<NAME> key generation", denoted CKM_<NAME>_KEY_GEN. This mechanism 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 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. When DES keys or CDMF keys are generated, their parity bits are set properly, as specified in FIPS PUB 46-2. Similarly, when a triple-DES key is generated, each of the DES keys comprising it has its parity bits set properly. When DES or CDMF keys are generated, it is token-dependent whether or not it is possible for "weak" or "semi-weak" keys to be generated. Similarly, when triple-DES keys are generated, it is token dependent whether or not it is possible for any of the component DES keys to be "weak" or "semi-weak" keys. When CAST, CAST3, or CAST5 keys are generated, the template for the secret key must specify a CKA_VALUE_LEN attribute. For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure may or may not be used. The CAST, CAST3, and CAST5 ciphers have variable key sizes, and so for the the key generation mechanisms for these ciphers, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of key sizes, in bytes. For the DES, DES3 (triple-DES), IDEA, and CDMF ciphers, these fields are not used. General block cipher ECB Cipher <NAME> has an electronic codebook mechanism, "<NAME>-ECB", denoted CKM_<NAME>_ECB. It is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping with <NAME>. 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 null bytes so that the resulting length is a multiple of <NAME>'s blocksize. 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 10-22, General block cipher ECB: Key And Data Length Constraints
General block cipher CBC Cipher <NAME> has a cipher-block chaining mode, "<NAME>-CBC", denoted CKM_<NAME>_CBC. It is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping with <NAME>. It has a parameter, an initialization vector for cipher block chaining mode. The initialization vector has the same length as <NAME>'s blocksize. Constraints on key types and the length of data are summarized in the following table:
Table 10-23, General block cipher CBC: Key And Data Length Constraints
General block cipher CBC with PKCS padding Cipher <NAME> has a cipher-block chaining mode with PKCS padding, "<NAME>-CBC with PKCS padding", denoted CKM_<NAME>_CBC_PAD. It is a mechanism for single- and multiple-part encryption and decryption; key wrapping; and key unwrapping with <NAME>. All ciphertext is padded with PKCS padding. It has a parameter, an initialization vector for cipher block chaining mode. The initialization vector has the same length as <NAME>'s blocksize. 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, and DSA private keys (see Section for details). The entries in Table 10 -24 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 10-24, General block cipher CBC with PKCS padding: Key And Data Length Constraints
General-length general block cipher MAC Cipher <NAME> has a general-length MACing mode, "General-length <NAME>-MAC", denoted CKM_<NAME>_MAC_GENERAL. It is a mechanism for single- and multiple-part signatures and verification. It has a parameter, a CK_MAC_GENERAL_PARAMS, which specifies the size of the output. The output bytes from this mechanism are taken from the start of the final cipher block produced in the MACing process. Constraints on key types and the length of input and output data are summarized in the following table:
Table 10-25, General-length general block cipher MAC: Key And Data Length Constraints
General block cipher MAC Cipher <NAME> has a MACing mechanism, "<NAME>-MAC", denoted CKM_<NAME>_MAC. This mechanism is a special case of the CKM_<NAME>_MAC_GENERAL mechanism described in SECTION_ "Section ." It always produces an output of size half as large as <NAME>'s blocksize. This mechanism has no parameters. Constraints on key types and the length of data are summarized in the following table:
Table 10-26, General block cipher MAC: Key And Data Length Constraints
Double-length DES mechanisms Double-length DES key generation The double-length DES key generation mechanism, denoted CKM_DES2_KEY_GEN, is a key generation mechanism for double-length DES keys. The DES keys making up a double-length DES key both have their parity bits set properly, as specified in FIPS PUB 46-2. It does not have a parameter. The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key. Other attributes supported by the double-length DES key type (specifically, the flags indicating which functions the key supports) may be specified in the template for the key, or else are assigned default initial values. Double-length DES keys can be used with all the same mechanisms as triple-DES keys: CKM_DES_ECB, CKM_DES_CBC, CKM_DES_CBC_PAD, CKM_DES_MAC_GENERAL, and CKM_DES_MAC (these mechanisms are described in templatized form in Section). Triple-DES encryption with a double-length DES key consists of three steps: encryption with the first DES key; decryption with the second DES key; and encryption with the first DES key. When double-length DES keys are generated, it is token-dependent whether or not it is possible for either of the component DES keys to be "weak" or "semi-weak" keys. SKIPJACK mechanism parameters
CK_SKIPJACK_PRIVATE_WRAP_PARAMSCK_SKIPJACK_PRIVATE_WRAP_PARAMS is a structure that provides the parameters to the CKM_SKIPJACK_PRIVATE_WRAP mechanism. It is defined as follows:
|
|
|
CK_MAC_GENERAL_PARAMSCK_MAC_GENERAL_PARAMS provides the parameters to the general-length MACing mechanisms of the DES, DES3 (triple-DES), CAST, CAST3, CAST5, IDEA, and CDMF ciphers. It holds the length of the MAC that these mechanisms will produce. |
|
|
CK_SKIPJACK_PRIVATE_WRAP_PARAMSCK_SKIPJACK_PRIVATE_WRAP_PARAMS is a structure that provides the parameters to the CKM_SKIPJACK_PRIVATE_WRAP mechanism. It is defined as follows:
CK_SKIPJACK_PRIVATE_WRAP_PARAMS_PTR points to a CK_PRIVATE_WRAP_PARAMS structure. It is implementation-dependent.
CK_SKIPJACK_RELAYX_PARAMSCK_SKIPJACK_RELAYX_PARAMS is a structure that provides the parameters to the CKM_SKIPJACK_RELAYX mechanism. It is defined as follows:
|
|
|
CK_SKIPJACK_RELAYX_PARAMSCK_SKIPJACK_RELAYX_PARAMS is a structure that provides the parameters to the CKM_SKIPJACK_RELAYX mechanism. It is defined as follows:
CK_SKIPJACK_RELAYX_PARAMS_PTR points to a CK_SKIPJACK_RELAYX_PARAMS structure. It is implementation-dependent. SKIPJACK mechanisms SKIPJACK key generation The SKIPJACK key generation mechanism, denoted CKM_SKIPJACK_KEY_GEN, is a key generation mechanism for SKIPJACK. The output of this mechanism is called a Message Encryption Key (MEK). It does not have a parameter. The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key. SKIPJACK-ECB64 SKIPJACK-ECB64, denoted CKM_SKIPJACK_ECB64, is a mechanism for single- and multiple-part encryption and decryption with SKIPJACK in 64-bit electronic codebook mode as defined in FIPS PUB 185. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-27, SKIPJACK-ECB64: Data and Length Constraints
SKIPJACK-CBC64 SKIPJACK-CBC64, denoted CKM_SKIPJACK_CBC64, is a mechanism for single- and multiple-part encryption and decryption with SKIPJACK in 64-bit cipher-block chaining mode as defined in FIPS PUB 185. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-28, SKIPJACK-CBC64: Data and Length Constraints
SKIPJACK-OFB64 SKIPJACK-OFB64, denoted CKM_SKIPJACK_OFB64, is a mechanism for single- and multiple-part encryption and decryption with SKIPJACK in 64-bit output feedback mode as defined in FIPS PUB 185. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-29, SKIPJACK-OFB64: Data and Length Constraints
SKIPJACK-CFB64 SKIPJACK-CFB64, denoted CKM_SKIPJACK_CFB64, is a mechanism for single- and multiple-part encryption and decryption with SKIPJACK in 64-bit cipher feedback mode as defined in FIPS PUB 185. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-30, SKIPJACK-CFB64: Data and Length Constraints
SKIPJACK-CFB32 SKIPJACK-CFB32, denoted CKM_SKIPJACK_CFB32, is a mechanism for single- and multiple-part encryption and decryption with SKIPJACK in 32-bit cipher feedback mode as defined in FIPS PUB 185. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-31, SKIPJACK-CFB32: Data and Length Constraints
SKIPJACK-CFB16 SKIPJACK-CFB16, denoted CKM_SKIPJACK_CFB16, is a mechanism for single- and multiple-part encryption and decryption with SKIPJACK in 16-bit cipher feedback mode as defined in FIPS PUB 185. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-32, SKIPJACK-CFB16: Data and Length Constraints
SKIPJACK-CFB8 SKIPJACK-CFB8, denoted CKM_SKIPJACK_CFB8, is a mechanism for single- and multiple-part encryption and decryption with SKIPJACK in 8-bit cipher feedback mode as defined in FIPS PUB 185. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-33, SKIPJACK-CFB8: Data and Length Constraints
SKIPJACK-WRAP The SKIPJACK-WRAP mechanism, denoted CKM_SKIPJACK_WRAP, is used to wrap and unwrap a secret key (MEK). It can wrap or unwrap SKIPJACK, BATON, and JUNIPER keys. It does not have a parameter. SKIPJACK-PRIVATE-WRAP The SKIPJACK-PRIVATE-WRAP mechanism, denoted CKM_SKIPJACK_PRIVATE_WRAP, is used to wrap and unwrap a private key. It can wrap KEA and DSA private keys. It has a parameter, a CK_SKIPJACK_PRIVATE_WRAP_PARAMS structure SKIPJACK-RELAYX The SKIPJACK-RELAYX mechanism, denoted CKM_SKIPJACK_RELAYX, is used with the C_WrapKey function to "change the wrapping" on a private key which was wrapped with the SKIPJACK-PRIVATE-WRAP mechanism (see Section). It has a parameter, a CK_SKIPJACK_RELAYX_PARAMS structure. Although the SKIPJACK-RELAYX mechanism is used with C_WrapKey, it differs from other key-wrapping mechanisms. Other key-wrapping mechanisms take a key handle as one of the arguments to C_WrapKey ; however, for the SKIPJACK_RELAYX mechanism, the [always invalid] value 0 should be passed as the key handle for C_WrapKey, and the already-wrapped key is passed in as part of the CK_SKIPJACK_RELAYX_PARAMS structure. BATON mechanisms BATON key generation The BATON key generation mechanism, denoted CKM_BATON_KEY_GEN, is a key generation mechanism for BATON. The output of this mechanism is called a Message Encryption Key (MEK). It does not have a parameter. This mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key. BATON-ECB128 BATON-ECB128, denoted CKM_BATON_ECB128, is a mechanism for single- and multiple-part encryption and decryption with BATON in 128-bit electronic codebook mode. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-34, BATON-ECB128: Data and Length Constraints
BATON-ECB96 BATON-ECB96, denoted CKM_BATON_ECB96, is a mechanism for single- and multiple-part encryption and decryption with BATON in 96-bit electronic codebook mode. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-35, BATON-ECB96: Data and Length Constraints
BATON-CBC128 BATON-CBC128, denoted CKM_BATON_CBC128, is a mechanism for single- and multiple-part encryption and decryption with BATON in 128-bit cipher-block chaining mode. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-36, BATON-CBC128: Data and Length Constraints
BATON-COUNTER BATON-COUNTER, denoted CKM_BATON_COUNTER, is a mechanism for single- and multiple-part encryption and decryption with BATON in counter mode. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-37, BATON-COUNTER: Data and Length Constraints
BATON-SHUFFLE BATON-SHUFFLE, denoted CKM_BATON_SHUFFLE, is a mechanism for single- and multiple-part encryption and decryption with BATON in shuffle mode. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table:
Table 10-38, BATON-SHUFFLE: Data and Length Constraints
BATON WRAP The BATON wrap and unwrap mechanism, denoted CKM_BATON_WRAP, is a function used to wrap and unwrap a secret key (MEK). It can wrap and unwrap SKIPJACK, BATON, and JUNIPER keys. It has no parameters. When used to unwrap a key, this mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to it. JUNIPER mechanisms JUNIPER key generation The JUNIPER key generation mechanism, denoted CKM_JUNIPER_KEY_GEN, is a key generation mechanism for JUNIPER. The output of this mechanism is called a Message Encryption Key (MEK). It does not have a parameter. The mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key. JUNIPER-ECB128 JUNIPER-ECB128, denoted CKM_JUNIPER_ECB128, is a mechanism for single- and multiple-part encryption and decryption with JUNIPER in 128-bit electronic codebook mode. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table. For encryption and decryption, the input and output data (parts) may begin at the same location in memory.
Table 10-39, JUNIPER-ECB128: Data and Length Constraints
JUNIPER-CBC128 JUNIPER-CBC128, denoted CKM_JUNIPER_CBC128, is a mechanism for single- and multiple-part encryption and decryption with JUNIPER in 128-bit cipher-block chaining mode. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table. For encryption and decryption, the input and output data (parts) may begin at the same location in memory.
Table 10-40, JUNIPER-CBC128: Data and Length Constraints
JUNIPER-COUNTER JUNIPER COUNTER, denoted CKM_JUNIPER_COUNTER, is a mechanism for single- and multiple-part encryption and decryption with JUNIPER in counter mode. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table. For encryption and decryption, the input and output data (parts) may begin at the same location in memory.
Table 10-41, JUNIPER-COUNTER: Data and Length Constraints
JUNIPER-SHUFFLE JUNIPER-SHUFFLE, denoted CKM_JUNIPER_SHUFFLE, is a mechanism for single- and multiple-part encryption and decryption with JUNIPER in shuffle mode. It has a parameter, a 24-byte initialization vector. During an encryption operation, this IV is set to some value generated by the token"in other words, the application cannot specify a particular IV when encrypting. It can, of course, specify a particular IV when decrypting. Constraints on key types and the length of data are summarized in the following table. For encryption and decryption, the input and output data (parts) may begin at the same location in memory.
Table 10-42, JUNIPER-SHUFFLE: Data and Length Constraints
JUNIPER WRAP The JUNIPER wrap and unwrap mechanism, denoted CKM_JUNIPER_WRAP, is a function used to wrap and unwrap an MEK. It can wrap or unwrap SKIPJACK, BATON, and JUNIPER keys. It has no parameters. When used to unwrap a key, this mechanism contributes the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to it. MD2 mechanisms MD2 The MD2 mechanism, denoted CKM_MD2, is a mechanism for message digesting, following the MD2 message-digest algorithm defined in RFC 1319. It does not have a parameter. Constraints on the length of data are summarized in the following table:
Table 10-43, MD2: Data Length Constraints
General-length MD2-HMAC The general-length MD2-HMAC mechanism, denoted CKM_MD2_HMAC_GENERAL, is a mechanism for signatures and verification. It uses the HMAC construction, based on the MD2 hash function. The keys it uses are generic secret keys. It has a parameter, a CKA_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired output. This length should be in the range 0-16 (the output size of MD2 is 16 bytes). Signatures produced by this mechanism will be taken from the start of the full 16-byte HMAC output.
Table 10-44, General-length MD2-HMAC: Key And Data Length Constraints
MD2-HMAC The MD2-HMAC mechanism, denoted CKM_MD2_HMAC, is a special case of the general-length MD2-HMAC mechanism in Section . It has no parameter, and always produces an output of length 16. MD2 key derivation MD2 key derivation, denoted CKM_MD2_KEY_DERIVATION, is a mechanism which provides the capability of deriving a secret key by digesting the value of another secret key with MD2. The value of the base key is digested once, and the result is used to make the value of derived secret key.
This mechanism has the following rules about key sensitivity and extractability:
The MD5 mechanism, denoted CKM_MD5, is a mechanism for message digesting, following the MD5 message-digest algorithm defined in RFC 1321. It does not have a parameter. Constraints on the length of input and output data are summarized in the following table. For single-part digesting, the data and the digest may begin at the same location in memory.
Table 10-45, MD5: Data Length Constraints
General-length MD5-HMAC The general-length MD5-HMAC mechanism, denoted CKM_MD5_HMAC_GENERAL, is a mechanism for signatures and verification. It uses the HMAC construction, based on the MD5 hash function. The keys it uses are generic secret keys. It has a parameter, a CKA_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired output. This length should be in the range 0-16 (the output size of MD5 is 16 bytes). Signatures produced by this mechanism will be taken from the start of the full 16-byte HMAC output.
Table 10-46, General-length MD5-HMAC: Key And Data Length Constraints
MD5-HMAC The MD5-HMAC mechanism, denoted CKM_MD5_HMAC, is a special case of the general-length MD5-HMAC mechanism in Section . It has no parameter, and always produces an output of length 16. MD5 key derivation MD5 key derivation, denoted CKM_MD5_KEY_DERIVATION, is a mechanism which provides the capability of deriving a secret key by digesting the value of another secret key with MD5. The value of the base key is digested once, and the result is used to make the value of derived secret key.
This mechanism has the following rules about key sensitivity and extractability:
The SHA-1 mechanism, denoted CKM_SHA_1, is a mechanism for message digesting, following the Secure Hash Algorithm defined in FIPS PUB 180, as subsequently amended by NIST. It does not have a parameter. Constraints on the length of input and output data are summarized in the following table. For single-part digesting, the data and the digest may begin at the same location in memory.
Table 10-47, SHA-1: Data Length Constraints
General-length SHA-1-HMAC The general-length SHA-1-HMAC mechanism, denoted CKM_SHA_1_HMAC_GENERAL, is a mechanism for signatures and verification. It uses the HMAC construction, based on the SHA-1 hash function. The keys it uses are generic secret keys. It has a parameter, a CKA_MAC_GENERAL_PARAMS, which holds the length in bytes of the desired output. This length should be in the range 0-20 (the output size of SHA-1 is 20 bytes). Signatures produced by this mechanism will be taken from the start of the full 20-byte HMAC output.
Table 10-48, General-length SHA-1-HMAC: Key And Data Length Constraints
SHA-1-HMAC The SHA-1-HMAC mechanism, denoted CKM_SHA_1_HMAC, is a special case of the general-length SHA-1-HMAC mechanism in Section . It has no parameter, and always produces an output of length 20. SHA-1 key derivation SHA-1 key derivation, denoted CKM_SHA1_KEY_DERIVATION, is a mechanism which provides the capability of deriving a secret key by digesting the value of another secret key with SHA-1. The value of the base key is digested once, and the result is used to make the value of derived secret key.
This mechanism has the following rules about key sensitivity and extractability:
The FASTHASH mechanism, denoted CKM_FASTHASH, is a mechanism for message digesting, following the U. S. government's algorithm. It does not have a parameter. Constraints on the length of input and output data are summarized in the following table:
Table 10-49, FASTHASH: Data Length Constraints
Password-based encryption mechanism parameters
CK_PBE_PARAMSCK_PBE_PARAMS is a structure which provides all of the necessary information required by the CKM_PBE mechanisms (see PKCS#5 for information on the PBE generation mechanisms). It is defined as follows:
|
|
|
CK_PBE_PARAMSCK_PBE_PARAMS is a structure which provides all of the necessary information required by the CKM_PBE mechanisms (see PKCS#5 for information on the PBE generation mechanisms).
CK_PBE_PARAMS_PTR points to a CK_PBE_PARAMS structure. It is implementation-dependent. Password-based encryption mechanisms MD2-PBE for DES-CBC MD2-PBE for DES-CBC, denoted CKM_PBE_MD2_DES_CBC, is a mechanism used for generating a DES secret key and an initialization vector by using a password and a salt value and the MD2 digest algorithm. This functionality is defined in PKCS#5. It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the key generation process and the location of the application-supplied buffer which will receive the 8-byte IV generated by the mechanism. MD5-PBE for DES-CBC MD5-PBE for DES-CBC, denoted CKM_PBE_MD5_DES_CBC, is a mechanism used for generating a DES secret key and an initialization vector by using a password and a salt value and the MD5 digest algorithm. This functionality is defined in PKCS#5. It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the key generation process and the location of the application-supplied buffer which will receive the 8-byte IV generated by the mechanism. MD5-PBE for CAST-CBC MD5-PBE for CAST-CBC, denoted CKM_PBE_MD5_CAST_CBC, is a mechanism used for generating a CAST secret key and an initialization vector by using a password and a salt value and the MD5 digest algorithm. This functionality is essentially that defined in PKCS#5. It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the key generation process and the location of the application-supplied buffer which will receive the 8-byte IV generated by the mechanism. The CAST key generated by this mechanism is 8 bytes long. MD5-PBE for CAST3-CBC MD5-PBE for CAST3-CBC, denoted CKM_PBE_MD5_CAST3_CBC, is a mechanism used for generating a CAST3 secret key and an initialization vector by using a password and a salt value and the MD5 digest algorithm. This functionality is essentially that defined in PKCS#5. It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the key generation process and the location of the application-supplied buffer which will receive the 8-byte IV generated by the mechanism. The CAST3 key generated by this mechanism is 8 bytes long. MD5-PBE for CAST5-CBC MD5-PBE for CAST5-CBC, denoted CKM_PBE_MD5_CAST5_CBC, is a mechanism used for generating a CAST5 secret key and an initialization vector by using a password and a salt value and the MD5 digest algorithm. This functionality is essentially that defined in PKCS#5. It has a parameter, a CK_PBE_PARAMS structure. The parameter specifies the input information for the key generation process and the location of the application-supplied buffer which will receive the 8-byte IV generated by the mechanism. The CAST5 key generated by this mechanism is 8 bytes long. SET mechanism parameters
CK_KEY_WRAP_SET_OAEP_PARAMSCK_KEY_WRAP_SET_OAEP_PARAMS is a structure that provides the parameters to the CKM_KEY_WRAP_SET_OAEP mechanism. It is defined as follows:
|
|
|
CK_KEY_WRAP_SET_OAEP_PARAMSCK_KEY_WRAP_SET_OAEP_PARAMS is a structure that provides the parameters to the CKM_KEY_WRAP_SET_OAEP mechanism. It is defined as follows:
CK_KEY_WRAP_SET_OAEP_PARAMS_PTR points to a CK_KEY_WRAP_SET_OAEP_PARAMS structure. It is implementation-dependent. SET mechanisms OAEP key wrapping for SET The OAEP key wrapping for SET mechanism, denoted CKM_KEY_WRAP_SET_OAEP, is a mechanism for wrapping and unwrapping DES keys (and possibly some extra data) with RSA keys. This mechanism is defined in the SET protocol specifications. It takes a parameter, a CK_KEY_WRAP_SET_OAEP_PARAMS structure. This structure holds the "Block Contents" byte of the data, as well as any extra data. If no extra data is present, that is indicated by the ulXLen field having the value 0. When this mechanism is used to unwrap a key, the extra data is returned following the convention described in Section on producing output. If the inputs to C_UnwrapKey are such that the extra data is not returned (e.g., the buffer supplied in the CK_KEY_WRAP_SET_OAEP_PARAMS structure is NULL_PTR), then the unwrapped key object will not be created, either. Note that when this mechanism is used to unwrap a key, the bBC and pX fields of the parameter supplied to the mechanism may be modified. If an application uses C_UnwrapKey with CKM_KEY_WRAP_SET_OAEP, it is general preferable to simply allocate a 128-byte buffer for the extra data (the extra data is never larger than 128 bytes), rather than calling C_UnwrapKey twice. Each call of C_UnwrapKey with CKM_KEY_WRAP_SET_OAEP requires an RSA decryption operation to be performed, and this overhead can be avoided by this means. LYNKS mechanisms LYNKS key wrapping The LYNKS key wrapping mechanism, denoted CKM_WRAP_LYNKS, is a mechanism for wrapping and unwrapping secret keys with DES keys. It can wrap any 8-byte secret key, and it produces a 10-byte wrapped key, containing a cryptographic checksum. It does not have a parameter. When unwrapping a key with this mechanism, if the cryptographic checksum does not check out properly, an error is returned. In addition, if a DES key or CDMF key is unwrapped with this mechanism, the parity bits on the wrapped key must be set appropriately; if they are not set properly, an error is returned. SSL mechanism parameters
CK_SSL3_RANDOM_DATACK_SSL3_RANDOM_DATA is a structure which provides information about the random data of a client and a server in an SSL context. This structure is used by both the CKM_SSL3_MASTER_KEY_DERIVE and the CKM_SSL3_KEY_AND_MAC_DERIVE mechanisms. It is defined as follows:
|
|
|
CK_SSL3_RANDOM_DATACK_SSL3_RANDOM_DATA is a structure which provides information about the random data of a client and a server in an SSL context. This structure is used by both the CKM_SSL3_MASTER_KEY_DERIVE and the CKM_SSL3_KEY_AND_MAC_DERIVE mechanisms.
CK_SSL3_MASTER_KEY_DERIVE_PARAMS is a structure that provides the parameters to the CKM_SSL3_MASTER_KEY_DERIVE mechanism. It is defined as follows:
|
|
|
CK_SSL3_MASTER_KEY_DERIVE_PARAMS_PTR points to a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure. It is implementation-dependent.
CK_SSL3_KEY_MAT_OUTCK_SSL3_KEY_MAT_OUT is a structure that contains the resulting key handles after performing a C_DeriveKey function with the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. It is defined as follows:
|
|
|
CK_SSL3_KEY_MAT_OUTCK_SSL3_KEY_MAT_OUT is a structure that contains the resulting key handles after performing a C_DeriveKey function with the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism.
CK_SSL3_KEY_MAT_OUT_PTR points to a CK_SSL3_KEY_MAT_OUT structure. It is implementation-dependent.
CK_SSL3_KEY_MAT_PARAMSCK_SSL3_KEY_MAT_PARAMS is a structure that provides the parameters to the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. It is defined as follows:
|
|
|
CK_SSL3_KEY_MAT_PARAMSCK_SSL3_KEY_MAT_PARAMS is a structure that provides the parameters to the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism. It is defined as follows:
CK_SSL3_KEY_MAT_PARAMS_PTR points to a CK_SSL3_KEY_MAT_PARAMS structure. It is implementation-dependent. SSL mechanisms Pre_master key generation Pre_master key generation in SSL 3.0, denoted CKM_SSL3_PRE_MASTER_KEY_GEN, is a mechanism which generates a 48-byte generic secret key. It is used to produce the "pre_master" key used in SSL version 3.0. It has one parameter, a CK_VERSION structure, which provides the client's SSL version number. The mechanism contributes to the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may be specified in the template, or else are assigned default values. The template sent along with this mechanism during a C_GenerateKey call may indicate that the object class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to specify any of them. For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure both indicate 48 bytes. Master key derivation Master key derivation in SSL 3.0, denoted CKM_SSL3_MASTER_KEY_DERIVE, is a mechanism used to derive one 48-byte generic secret key from another 48-byte generic secret key. It is used to produce the "master_secret" key used in the SSL protocol from the "pre_master" key. This mechanism returns the value of the client version found in the "pre_master" key as well as a handle to the derived "master_secret" key. It has a parameter, a CK_SSL3_MASTER_KEY_DERIVE_PARAMS structure, which allows for the passing of random data to the token as well as the returning of the protocol version number which is part of the pre-master key. This structure is defined in Section . The mechanism contributes to the CKA_CLASS, CKA_KEY_TYPE, and CKA_VALUE attributes to the new key (as well as the CKA_VALUE_LEN attribute, if it is not supplied in the template). Other attributes may be specified in the template, or else are assigned default values. The template sent along with this mechanism during a C_GenerateKey call may indicate that the object class is CKO_SECRET_KEY, the key type is CKK_GENERIC_SECRET, and the CKA_VALUE_LEN attribute has value 48. However, since these facts are all implicit in the mechanism, there is no need to specify any of them. This mechanism has the following rules about key sensitivity and extractability:
Key, MAC and IV derivation in SSL 3.0, denoted CKM_SSL3_KEY_AND_MAC_DERIVE, is a mechanism is used to derive the appropriate cryptographic keying material used by a "CipherSuite" from the "master_secret" key and random data. This mechanism returns the key handles for the keys generated in the process, as well as the initialization vectors (IVs) created. It has a parameter, a CK_SSL3_KEY_MAT_PARAMS structure, which allows for the passing of random data as well as the characteristic of the cryptographic material for the given CipherSuite and a pointer to a structure which receives the handles and IVs which were generated. This structure is defined in Section . This mechanism contributes to the creation of four distinct keys on the token and returns two IVs (if IVs are requested by the caller) back to the caller. The keys are all given an object class of CKO_SECRET_KEY. The two MACing keys ("client_write_MAC_secret" and "server_write_MAC_secret") are always given a type of CKK_GENERIC_SECRET. They are flagged as valid for signing, verification (they are used for MACing), and derivation operations. The other two keys ("client_write_key" and "server_write_key") are typed according to information found in the template sent along with this mechanism during a C_DeriveKey function call. By default, they are flagged as valid for encryption, decryption, and derivation operations. All four keys inherit the values of the CKA_SENSITIVE, CKA_ALWAYS_SENSITIVE, CKA_EXTRACTABLE, and CKA_NEVER_EXTRACTABLE attributes from the base key. The template provided to C_DeriveKey may not specify values for any of these attributes which differ from those held by the base key. Note that the CK_SSL3_KEY_MAT_OUT structure pointed to by the CK_SSL3_KEY_MAT_PARAMS structure's pReturnedKeyMaterial field will by modified by the C_DeriveKey call; in particular, the four key handle fields in the CK_SSL3_KEY_MAT_OUT structure will be modified to hold handles to the newly-created keys. In addition, the buffers pointed to by the CK_SSL3_KEY_MAT_OUT structure's pIVClient and pIVServer fields will have IVs returned in them (if IVs are requested by the caller). Therefore, these two fields must point to buffers with sufficient space to hold any IVs that will be returned. This mechanism departs from the other key derivation mechanisms in Cryptoki in its returned information. For other mechanisms, the C_DeriveKey function returns a single key handle as a result of a successful completion. However, since the CKM_SSL3_KEY_AND_MAC_DERIVE mechanism returns all of its key handles in the CK_SSL3_KEY_MAT_OUT structure pointed to by the CK_SSL3_KEY_MAT_PARAMS structure specified as the mechanism parameter, the parameter phKey passed to C_DeriveKey is unnecessary, and should be a NULL_PTR. If a call to C_DeriveKey with this mechanism fails, then none of the four keys will be created on the token. MD5 MACing in SSL 3.0 MD5 MACing in SSL3.0, denoted CKM_SSL3_MD5_MAC, is a mechanism for single- and multiple-part signatures (data authentication) and verification using MD5, based on the SSL 3.0 protocol. This technique is very similar to the HMAC technique. It has a parameter, a CK_MAC_GENERAL_PARAMS, which specifies the length in bytes of the signatures produced by this mechanism. Constraints on key types and the length of input and output data are summarized in the following table:
Table 10-50, MD5 MACing in SSL 3.0: Key And Data Length Constraints
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of generic secret key sizes, in bits. SHA-1 MACing in SSL 3.0 SHA-1 MACing in SSL3.0, denoted CKM_SSL3_SHA1_MAC, is a mechanism for single- and multiple-part signatures (data authentication) and verification using SHA-1, based on the SSL 3.0 protocol. This technique is very similar to the HMAC technique. It has a parameter, a CK_MAC_GENERAL_PARAMS, which specifies the length in bytes of the signatures produced by this mechanism. Constraints on key types and the length of input and output data are summarized in the following table:
Table 10-51, SHA-1 MACing in SSL 3.0: Key And Data Length Constraints
For this mechanism, the ulMinKeySize and ulMaxKeySize fields of the CK_MECHANISM_INFO structure specify the supported range of generic secret key sizes, in bits. Parameters for miscellaneous simple key derivation mechanisms
CK_KEY_DERIVATION_STRING_DATA
CK_KEY_DERIVATION_STRING_DATA is a structure that holds a pointer to a byte string and the byte string's length. It provides the parameters for the CKM_CONCATENATE_BASE_AND_DATA, CKM_CONCATENATE_DATA_AND_BASE, and CKM_XOR_BASE_AND_DATA mechanisms. It is defined as follows: |
|
|
CK_KEY_DERIVATION_STRING_DATA.
CK_EXTRACT_PARAMSCK_KEY_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_PTRCK_EXTRACT_PARAMS_PTR points to a CK_EXTRACT_PARAMS. It is implemenation-dependent.Miscellaneous simple key derivation mechanisms Concatenation of a base key and another key 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.
This mechanism has the following rules about key sensitivity and extractability:
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.
This mechanism has the following rules about key sensitivity and extractability:
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.
This mechanism has the following rules about key sensitivity and extractability:
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.
This mechanism has the following rules about key sensitivity and extractability:
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).
If the original key used in this process is sensitive, then the derived key must also be sensitive for the derivation to succeed.
This mechanism has the following rules about key sensitivity and extractability:
|
|
|
CK_EXTRACT_PARAMSCK_KEY_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: |
|
|
C_Initialize initializes the Cryptoki library. C_Initialize should be the first Cryptoki call made by an application, except for calls to C_GetFunctionList. What this function actually does is implementation-dependent: for example, it may cause Cryptoki to initialize its internal memory buffers, or any other resources it requires; or it may perform no action.
|
|
|
C_Finalize is called to indicate that an application is finished with the Cryptoki library. It should be the last Cryptoki call made by an application.
|
|
|
C_GetInfo returns general information about Cryptoki.
CK_INFO info; CK_RV rv; rv = C_Initialize(NULL_PTR); assert(rv == CKR_OK); rv = C_GetInfo(&info); assert(rv == CKR_OK); if(info.version.major == 2) { /* Do lots of interesting cryptographic things with the token */ . . . } rv = C_Finalize(NULL_PTR); assert(rv == CKR_OK); |
|
|
C_GetFunctionList obtains a pointer to the Cryptoki library's list of function pointers.
CK_FUNCTION_LIST_PTR pFunctionList; CK_C_Initialize pC_Initialize; CK_RV rv; /* It's OK to call C_GetFunctionList before calling C_Initialize */ rv = C_GetFunctionList(&pFunctionList); assert(rv == CKR_OK); pC_Initialize = pFunctionList -> C_Initialize; /* Call the C_Initialize function in the library */ rv = (*pC_Initialize)(NULL_PTR); Slot and token management functions Cryptoki provides the following functions for slot and token management. These functions do not run in parallel with the application. |
|
||||||||||||||||
|
C_GetSlotList is used to obtain a list of slots in the system.
CK_ULONG ulSlotCount, ulSlotWithTokenCount; CK_SLOT_ID_PTR pSlotList, pSlotWithTokenList; CK_RV rv; /* Get list of all slots */ rv = C_GetSlotList(FALSE, NULL_PTR, &ulSlotCount); if (rv == CKR_OK) { pSlotList = (CK_SLOT_ID_PTR) malloc(ulSlotCount*sizeof(CK_SLOT_ID)); rv = C_GetSlotList(FALSE, pSlotList, &ulSlotCount); if (rv == CKR_OK) { /* Now use that list of all slots */ . . . } free(pSlotList); } /* Get list of all slots with a token present */ pSlotWithTokenList = (CK_SLOT_ID_PTR) malloc(0); ulSlotWithTokenCount = 0; while (1) { rv = C_GetSlotList( TRUE, pSlotWithTokenList, ulSlotWithTokenCount); if (rv != CKR_BUFFER_TOO_SMALL) break; pSlotWithTokenList = realloc( pSlotWithTokenList, ulSlotWithTokenList*sizeof(CK_SLOT_ID)); } if (rv == CKR_OK) { /* Now use that list of all slots with a token present */ . . . } free(pSlotWithTokenList); |
|
||||||||||||
|
C_GetSlotInfo obtains information about a particular slot in the system.
|
|
||||||||||||
|
C_GetTokenInfo obtains information about a particular token in the system.
CK_ULONG ulCount; CK_SLOT_ID_PTR pSlotList; CK_SLOT_INFO slotInfo; CK_TOKEN_INFO tokenInfo; CK_RV rv; rv = C_GetSlotList(FALSE, NULL_PTR, &ulCount); if ((rv == CKR_OK) && (ulCount > 0)) { pSlotList = (CK_SLOT_ID_PTR) malloc(ulCount*sizeof(CK_SLOT_ID)); rv = C_GetSlotList(FALSE, pSlotList, &ulCount); assert(rv == CKR_OK); /* Get slot information for first slot */ rv = C_GetSlotInfo(pSlotList[0], &slotInfo); assert(rv == CKR_OK); /* Get token information for first slot */ rv = C_GetTokenInfo(pSlotList[0], &tokenInfo); if (rv == CKR_TOKEN_NOT_PRESENT) { . . . } . . . free(pSlotList); } |
|
||||||||||||||||
|
C_GetMechanismList is used to obtain a list of mechanism types supported by a token.
CK_SLOT_ID slotID; CK_ULONG ulCount; CK_MECHANISM_TYPE_PTR pMechanismList; CK_RV rv; . . . rv = C_GetMechanismList(slotID, NULL_PTR, &ulCount); if ((rv == CKR_OK) && (ulCount > 0)) { pMechanismList = (CK_MECHANISM_TYPE_PTR) malloc(ulCount*sizeof(CK_MECHANISM_TYPE)); rv = C_GetMechanismList(slotID, pMechanismList, &ulCount); if (rv == CKR_OK) { . . . } free(pMechanismList); } |
|
||||||||||||||||
|
C_GetMechanismInfo obtains information about a particular mechanism possibly supported by a token.
CK_SLOT_ID slotID; CK_MECHANISM_INFO info; CK_RV rv; . . . /* Get information about the CKM_MD2 mechanism for this token */ rv = C_GetMechanismInfo(slotID, CKM_MD2, &info); if (rv == CKR_OK) { if (info.flags & CKF_DIGEST) { . . . } } |
|
||||||||||||||||||||
|
C_InitToken initializes a token.
If the token has a "protected authentication path", as indicated by the CKR_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means that there is some way for a user to be authenticated to the token without having the application send a PIN through the Cryptoki library. One such possibility is that the user enters a PIN on a PINpad on the token itself, or on the slot device. To initialize a token with such a protected authentication path, the pPin parameter to C_InitToken should be NULL_PTR. During the execution of C_InitToken, the SO's PIN will be entered through the protected authentication path. If the token has a protected authentication path other than a PINpad, then it is token-dependent whether or not C_InitToken can be used to initialize the token. A token cannot be initialized if Cryptoki detects that an application has an open session with it; when a call to C_InitToken is made under such circumstances, the call fails with error CKR_SESSION_EXISTS. It may happen that some other application does have an open session with the token, but Cryptoki cannot detect this, because it cannot detect anything about other applications using the token. If this is the case, then what happens as a result of the C_InitToken call is undefined.
CK_SLOT_ID slotID; CK_CHAR pin[] = {"MyPIN"}; CK_CHAR label[32]; CK_RV rv; . . . memset(label, ' ', sizeof(label)); memcpy(label, "My first token", sizeof("My first token")); rv = C_InitToken(slotID, pin, sizeof(pin), label); if (rv == CKR_OK) { . . . } |
|
||||||||||||||||
|
C_InitPIN initializes the normal user's PIN.
If the token has a "protected authentication path", as indicated by the CKR_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means that there is some way for a user to be authenticated to the token without having the application send a PIN through the Cryptoki library. One such possibility is that the user enters a PIN on a PINpad on the token itself, or on the slot device. To initialize the normal user's PIN on a token with such a protected authentication path, the pPin parameter to C_InitPIN should be NULL_PTR. During the execution of C_InitPIN, the SO will enter the new PIN through the protected authentication path. If the token has a protected authentication path other than a PINpad, then it is token-dependent whether or not C_InitPIN can be used to initialize the normal user's token access.
CK_SESSION_HANDLE hSession; CK_CHAR newPin[]= {"NewPIN"}; CK_RV rv; rv = C_InitPIN(hSession, newPin, sizeof(newPin)); if (rv == CKR_OK) { . . . } |
|
||||||||||||||||||||||||
|
C_SetPIN modifies the PIN of the user that is currently logged in.
If the token has a "protected authentication path", as indicated by the CKR_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means that there is some way for a user to be authenticated to the token without having the application send a PIN through the Cryptoki library. One such possibility is that the user enters a PIN on a PINpad on the token itself, or on the slot device. To modify the current user's PIN on a token with such a protected authentication path, the pOldPin and pNewPin parameters to C_SetPIN should be NULL_PTR. During the execution of C_SetPIN, the current user will enter the old PIN and the new PIN through the protected authentication path. It is not specified how the PINpad should be used to enter two PINs; this varies. If the token has a protected authentication path other than a PINpad, then it is token-dependent whether or not C_SetPIN can be used to modify the current user's PIN.
CK_SESSION_HANDLE hSession; CK_CHAR oldPin[] = {"OldPIN"}; CK_CHAR newPin[] = {"NewPIN"}; CK_RV rv; rv = C_SetPIN( hSession, oldPin, sizeof(oldPin), newPin, sizeof(newPin)); if (rv == CKR_OK) { . . . } Session management functions Cryptoki provides the following functions for session management. These functions do not run in parallel with the application. A typical application might perform the following series of steps to make use of a token:
An application may have concurrent sessions with more than one token. It is also possible for a token to have concurrent sessions with more than one application. |
|
||||||||||||||||||||||||
|
C_OpenSession has two distinct functions: it can set up an application callback so that an application will be notified when a token is inserted into a particular slot, or it can open a session between an application and a token in a particular slot.
When C_OpenSession is called to set up a token insertion callback, the return code is either CKR_INSERTION_CALLBACK_NOT_SUPPORTED (if the token doesn't support insertion callbacks) or CKR_OK (if the token does support insertion callbacks). When opening a session with C_OpenSession, the flags parameter consists of the logical OR of zero or more bit flags defined in the CK_SESSION_INFO data type. For example, if no bits are set in the flags parameter, then C_OpenSession attempts to open a shared, read-only session, with certain cryptographic functions being performed in parallel with the application. Any or all of the CKF_EXCLUSIVE_SESSION, CKF_RW_SESSION, and CKF_SERIAL_SESSION bits can be set in the flags parameter to modify the type of session requested. If an exclusive session is requested (by setting the CKF_EXCLUSIVE_SESSION bit), but is not available (because there is already a session open), C_OpenSession returns CKR_SESSION_EXISTS. If a parallel session is requested (by not setting the CKR_SERIAL_SESSION bit), but is not supported on this token, then C_OpenSession returns CKR_PARALLEL_NOT_SUPPORTED. These two error returns have equal priorities. In a parallel session, cryptographic functions may return control to the application before completing (the return value CKR_FUNCTION_PARALLEL indicates that this condition applies). The application may then call C_GetFunctionStatus to obtain an updated status of the function's execution, which will continue to be CKR_FUNCTION_PARALLEL until the function completes, and CKR_OK or some other return value when the function completes. Alternatively, the application can wait until Cryptoki sends notification that the function has completed through the Notify callback. The application may also call C_CancelFunction to cancel the function before it completes. Note that even in a parallel session, there is no guarantee that a particular function will execute in parallel. Therefore, an application should always check cryptographic functions' return codes to see whether the function is running in parallel, or whether it ran in serial [and is already finished]. If an application calls another function (cryptographic or otherwise) before one that is executing in parallel in the same session completes, Cryptoki will wait until the one that is executing completes. Thus, an application can run only one function at any given time in a given session. To achieve parallel execution of multiple functions, the application should open additional sessions. Cryptographic functions running in serial with the application may periodically surrender control to the application by calling Notify with a CKN_SURRENDER callback so that the application may perform other operations or cancel the function. Non-cryptographic functions always run in serial with the application, and do not surrender control. A function in a parallel session will never surrender control back to the application via a CKN_SURRENDER application callback, even if that particular function is actually executing in serial with the application. There may be a limit on the number of concurrent sessions with the token, which may depend on whether the session is "read-only" or "read/write". An attempt to open a session which does not succeed because there are too many existing sessions of some type should return CKR_SESSION_COUNT. If the token is write-protected (as indicated in the CK_TOKEN_INFO structure), then only read-only sessions may be opened with it. If the application calling C_OpenSession already has a R/W SO session open with the token, then any attempt to open a R/O session with the token fails with error code CKR_SESSION_READ_WRITE_SO_EXISTS (see Section). The Notify callback function is used by Cryptoki to notify the application of certain events. If the application does not wish to support callbacks, it should pass a value of NULL_PTR as the Notify parameter. See Section for more information about application callbacks.
|
|
|
C_CloseSession closes a session between an application and a token.
Depending on the token, when the last open session any application has with the token is closed, the token may be "ejected" from its reader (if this capability exists). Despite the fact this C_CloseSession is supposed to close a session, the return value CKR_SESSION_CLOSED is an error return. It indicates the (probably somewhat unlikely) event that while this function call was executing, another call was made to C_CloseSession to close this particular session, and that call finished executing first. Such uses of sessions are a bad idea, and Cryptoki makes little promise of what will occur in general if an application indulges in this sort of behavior.
CK_SLOT_ID slotID; CK_BYTE application; CK_NOTIFY MyNotify; CK_SESSION_HANDLE hSession; CK_RV rv; . . . application = 17; MyNotify = &EncryptionSessionCallback; rv = C_OpenSession( slotID, CKF_RW_SESSION,(CK_VOID_PTR) &application, MyNotify, &hSession); if (rv == CKR_OK) { . . . C_CloseSession(hSession); } |
|
|
C_CloseAllSessions closes all sessions an application has with a token.
Depending on the token, when the last open session any application has with the token is closed, the token may be "ejected" from its reader (if this capability exists).
CK_SLOT_ID slotID; CK_RV rv; . . . rv = C_CloseAllSessions(slotID); |
|
||||||||||||
|
C_GetSessionInfo obtains information about a session.
CK_SESSION_HANDLE hSession; CK_SESSION_INFO info; CK_RV rv; . . . rv = C_GetSessionInfo(hSession, &info); if (rv == CKR_OK) { if (info.state == CKS_RW_USER_FUNCTIONS) { . . . } . . . } |
|
||||||||||||||||
|
C_GetOperationState obtains the cryptographic operations state of a session, encoded as a string of bytes.
Precisely what the "cryptographic operations state" this function saves is varies from token to token; however, this state is what is provided as input to C_SetOperationState to restore the cryptographic activities of a session. Consider a session which is performing a message digest operation using SHA-1 (i.e., the session is using the CKM_SHA_1 mechanism). Suppose that the message digest operation was initialized properly, and that precisely 80 bytes of data have been supplied so far as input to SHA-1. The application now wants to "save the state" of this digest operation, so that it can continue it later. In this particular case, since SHA-1 processes 512 bits (64 bytes) of input at a time, the cryptographic operations state of the session most likely consists of three distinct parts: the state of SHA-1's 160-bit internal chaining variable; the 16 bytes of unprocessed input data; and some administrative data indicating that this saved state comes from a session which was performing SHA-1 hashing. Taken together, these three pieces of information suffice to continue the current hashing operation at a later time. Consider next a session which is performing an encryption operation with DES (a block cipher with a block size of 64 bits) in CBC (cipher-block chaining) mode (i.e., the session is using the CKM_RC2_CBC mechanism). Suppose that precisely 22 bytes of data (in addition to an IV for the CBC mode) have been supplied so far as input to DES, which means that the first two 8-byte blocks of ciphertext have already been produced and output. In this case, the cryptographic operations state of the session most likely consists of three or four distinct parts: the second 8-byte block of ciphertext (this will be used for cipher-block chaining to produce the next block of ciphertext); the 6 bytes of data still awaiting encryption; some administrative data indicating that this saved state comes from a session which was performing DES encryption in CBC mode; and possibly the DES key being used for encryption (see C_SetOperationState for more information on whether or not the key is present in the saved state). If a session is performing two cryptographic operations simultaneously (see Section), then the cryptographic operations state of the session will contain all the necessary information to restore both operations. A session which is in the middle of executing a Cryptoki function cannot have its cryptographic operations state saved. An attempt to do so returns the error CKR_FUNCTION_PARALLEL. An attempt to save the cryptographic operations state of a session which does not currently have some active saveable cryptographic operation(s) (encryption, decryption, digesting, signing without message recovery, verification without message recovery, or some legal combination of two of these) should fail with the error CKR_OPERATION_NOT_INITIALIZED. An attempt to save the cryptographic operations state of a session which is performing an appropriate cryptographic operation (or two), but which cannot be satisfied for any of various reasons (certain necessary state information and/or key information can't leave the token, for example) should fail with the error CKR_STATE_UNSAVEABLE.
|
|
||||||||||||||||||||||||
|
C_SetOperationState restores the cryptographic operations state of a session from a string of bytes obtained with C_GetOperationState.
If C_SetOperationState is supplied with alleged saved cryptographic operations state which it can determine is not valid saved state (or is cryptographic operations state from a session with a different session state, or is cryptographic operations state from a different token), it fails with the error CKR_SAVED_STATE_INVALID. Saved state obtained from calls to C_GetOperationState may or may not contain information about keys in use for ongoing cryptographic operations. If a saved cryptographic operations state has an ongoing encryption or decryption operation, and the key in use for the operation is not saved in the state, then it must be supplied to C_SetOperationState in the hEncryptionKey argument. If it is not, then C_SetOperationState will fail and return the error CKR_KEY_NEEDED. If the key in use for the operation is saved in the state, then it can be supplied in the hEncryptionKey argument, but this is not required. Similarly, if a saved cryptographic operations state has an ongoing signature, MACing, or verification operation, and the key in use for the operation is not saved in the state, then it must be supplied to C_SetOperationState in the hAuthenticationKey argument. If it is not, then C_SetOperationState will fail with the error CKR_KEY_NEEDED. If the key in use for the operation is saved in the state, then it can be supplied in the hAuthenticationKey argument, but this is not required. If an irrelevant key is supplied to C_SetOperationState call (e.g., a nonzero key handle is submitted in the hEncryptionKey argument, but the saved cryptographic operations state supplied does not have an ongoing encryption or decryption operation, then C_SetOperationState fails with the error CKR_KEY_NOT_NEEDED. If a key is supplied as an argument to C_SetOperationState, and C_SetOperationState can somehow detect that this key was not the key being used in the source session for the supplied cryptographic operations state (it may be able to detect this if the key or a hash of the key is present in the saved state, for example), then C_SetOperationState fails with the error CKR_KEY_CHANGED. An application can look at the CKF_RESTORE_KEY_NOT_NEEDED flag in the flags field of the CK_TOKEN_INFO field for a token to determine whether or not it needs to supply key handles to C_SetOperationState calls. If this flag is TRUE, then a call to C_SetOperationState never needs a key handle to be supplied to it. If this flag is FALSE, then at least some of the time, C_SetOperationState requires a key handle, and so the application should probably always pass in any relevant key handles when restoring cryptographic operations state to a session. C_SetOperationState can successfully restore cryptographic operations state to a session even if that session has active cryptographic or object search operations when C_SetOperationState is called (the ongoing operations are abruptly cancelled).
CK_SESSION_HANDLE hSession; CK_MECHANISM digestMechanism; CK_ULONG ulStateLen; CK_BYTE data1[] = {0x01, 0x03, 0x05, 0x07}; CK_BYTE data2[] = {0x02, 0x04, 0x08}; CK_BYTE data3[] = {0x10, 0x0F, 0x0E, 0x0D, 0x0C}; CK_BYTE pDigest[20]; CK_ULONG ulDigestLen; CK_RV rv; . . . /* Initialize hash operation */ rv = C_DigestInit(hSession, &digestMechanism); assert(rv == CKR_OK); /* Start hashing */ rv = C_DigestUpdate(hSession, data1, sizeof(data1)); assert(rv == CKR_OK); /* Find out how big the state might be */ rv = C_GetOperationState(hSession, NULL_PTR, &ulStateLen); assert(rv == CKR_OK); /* Allocate some memory and then get the state */ pState = (CK_BYTE_PTR) malloc(ulStateLen); rv = C_GetOperationState(hSession, pState, &ulStateLen); /* Continue hashing */ rv = C_DigestUpdate(hSession, data2, sizeof(data2)); assert(rv == CKR_OK); /* Restore state. No key handles needed */ rv = C_SetOperationState(hSession, pState, ulStateLen, 0, 0); assert(rv == CKR_OK); /* Continue hashing from where we saved state */ rv = C_DigestUpdate(hSession, data3, sizeof(data3)); assert(rv == CKR_OK); /* Conclude hashing operation */ ulDigestLen = sizeof(pDigest); rv = C_DigestFinal(hSession, pDigest, &ulDigestLen); if (rv == CKR_OK) { /* pDigest[] now contains the hash of 0x01030507100F0E0D0C */ . . . } |
|
||||||||||||||||||||
|
C_Login logs a user into a token.
If the token has a "protected authentication path", as indicated by the CKR_PROTECTED_AUTHENTICATION_PATH flag in its CK_TOKEN_INFO being set, then that means that there is some way for a user to be authenticated to the token without having the application send a PIN through the Cryptoki library. One such possibility is that the user enters a PIN on a PINpad on the token itself, or on the slot device. Or the user might not even use a PIN"authentication could be achieved by some fingerprint-reading device, for example. To log into a token with a protected authentication path, the pPin parameter to C_Login should be NULL_PTR. When C_Login returns, whatever authentication method supported by the token will have been performed; a return value of CKR_OK means that the user was successfully authenticated, and a return value of CKR_PIN_INCORRECT means that the user was denied access. If there are any active cryptographic or object finding operations in a session, and then C_Login is successfully executed, it may or may not be the case that those operations are still active. Therefore, before logging in, any active operations should be finished. If the application calling C_Login has a R/O session open with the token, then it will be unable to log the SO into a session (see Section). An attempt to do this will result in the error code CKR_SESSION_READ_ONLY_EXISTS.
|
|
|
C_Logout logs a user out from a token.
When C_Logout successfully executes, any of the application's handles to private objects become invalid (even if a user is later logged back into the token, those handles remain invalid). In addition, all private session objects are destroyed. If there are any active cryptographic or object finding operations in a session, and then C_Logout is successfully executed, it may or may not be the case that those operations are still active. Therefore, before logging out, any active operations should be finished.
CK_SESSION_HANDLE hSession; CK_CHAR userPIN[] = {"MyPIN"}; CK_RV rv; rv = C_Login(hSession, CKU_USER, userPIN, sizeof(userPIN)); if (rv == CKR_OK) { . . . rv == C_Logout(hSession); if (rv == CKR_OK) { . . . } } Object management functions Cryptoki provides the following functions for managing objects. These functions do not run in parallel with the application. Additional functions provided specifically for managing key objects are described in Section . |
|
||||||||||||||||||||
|
C_CreateObject creates a new object.
Only session object can be created during a read-only session. Only public objects can be created unless the normal user is logged in.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hData, hCertificate, hKey; CK_OBJECT_CLASS dataClass = CKO_DATA, certificateClass = CKO_CERTIFICATE, keyClass = CKO_PUBLIC_KEY; CK_KEY_TYPE keyType = CKK_RSA; CK_CHAR application[] = {"My Application"}; CK_BYTE dataValue[] = {...}; CK_BYTE subject[] = {...}; CK_BYTE id[] = {...}; CK_BYTE certificateValue[] = {...}; CK_BYTE modulus[] = {...}; CK_BYTE exponent[] = {...}; CK_BYTE true = TRUE; CK_ATTRIBUTE dataTemplate[] = { {CKA_CLASS, &dataClass, sizeof(dataClass)}, {CKA_TOKEN, &true, sizeof(true)}, {CKA_APPLICATION, application, sizeof(application)}, {CKA_VALUE, dataValue, sizeof(dataValue)} }; CK_ATTRIBUTE certificateTemplate[] = { {CKA_CLASS, &certificateClass, sizeof(certificateClass)}, {CKA_TOKEN, &true, sizeof(true)}, {CKA_SUBJECT, subject, sizeof(subject)}, {CKA_ID, id, sizeof(id)}, {CKA_VALUE, certificateValue, sizeof(certificateValue)} }; CK_ATTRIBUTE keyTemplate[] = { {CKA_CLASS, &keyClass, sizeof(keyClass)}, {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, {CKA_WRAP, &true, sizeof(true)}, {CKA_MODULUS, modulus, sizeof(modulus)}, {CKA_PUBLIC_EXPONENT, exponent, sizeof(exponent)} }; CK_RV rv; . . . /* Create a data object */ rv = C_CreateObject(hSession, &dataTemplate, 4, &hData); if (rv == CKR_OK) { . . . } /* Create a certificate object */ rv = C_CreateObject( hSession, &certificateTemplate, 5, &hCertificate); if (rv == CKR_OK) { . . . } /* Create an RSA private key object */ rv = C_CreateObject(hSession, &keyTemplate, 5, &hKey); if (rv == CKR_OK) { . . . } |
|
||||||||||||||||||||||||
|
C_CopyObject copies an object, creating a new object for the copy.
Only session objects can be created during a read-only session. Only public objects can be created unless the normal user is logged in.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey, hNewKey; CK_OBJECT_CLASS keyClass = CKO_SECRET_KEY; CK_KEY_TYPE keyType = CKK_DES; CK_BYTE id[] = {...}; CK_BYTE keyValue[] = {...}; CK_BYTE false = FALSE; CK_BYTE true = TRUE; CK_ATTRIBUTE keyTemplate[] = { {CKA_CLASS, &keyClass, sizeof(keyClass)}, {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, {CKA_TOKEN, &false, sizeof(false)}, {CKA_ID, id, sizeof(id)}, {CKA_VALUE, keyValue, sizeof(keyValue)} }; CK_ATTRIBUTE copyTemplate[] = { {CKA_TOKEN, &true, sizeof(true)} }; CK_RV rv; . . . /* Create a DES secret key session object */ rv = C_CreateObject(hSession, &keyTemplate, 5, &hKey); if (rv == CKR_OK) { /* Create a copy which is a token object */ rv = C_CopyObject(hSession, hKey, ©Template, 1, &hNewKey); . . . } |
|
||||||||||||
|
C_DestroyObject destroys an object.
|
|
||||||||||||||||
|
C_GetObjectSize gets the size of an object in bytes.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hObject; CK_OBJECT_CLASS dataClass = CKO_DATA; CK_CHAR application[] = {"My Application"}; CK_BYTE dataValue[] = {...}; CK_BYTE value[] = {...}; CK_BYTE true = TRUE; CK_ATTRIBUTE template[] = { {CKA_CLASS, &dataClass, sizeof(dataClass)}, {CKA_TOKEN, &true, sizeof(true)}, {CKA_APPLICATION, application, sizeof(application)}, {CKA_VALUE, value, sizeof(value)} }; CK_ULONG ulSize; CK_RV rv; . . . rv = C_CreateObject(hSession, &template, 4, &hObject); if (rv == CKR_OK) { rv = C_GetObjectSize(hSession, hObject, &ulSize); if (rv != CKR_INFORMATION_SENSITIVE) { . . . } rv = C_DestroyObject(hSession, hObject); . . . } |
|
||||||||||||||||||||
|
C_GetAttributeValue obtains the value of one or more attributes of an object.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hObject; CK_BYTE_PTR pModulus, pExponent; CK_ATTRIBUTE template[] = { {CKA_MODULUS, NULL_PTR, 0}, {CKA_PUBLIC_EXPONENT, NULL_PTR, 0} }; CK_RV rv; . . . rv = C_GetAttributeValue(hSession, hObject, &template, 2); if (rv == CKR_OK) { pModulus = (CK_BYTE_PTR) malloc(template[0].ulValueLen); template[0].pValue = pModulus; /* template[0].ulValueLen was set by C_GetAttributeValue */ pExponent = (CK_BYTE_PTR) malloc(template[1].ulValueLen); template[1].pValue = pExponent; /* template[1].ulValueLen was set by C_GetAttributeValue */ rv = C_GetAttributeValue(hSession, hObject, &template, 2); if (rv == CKR_OK) { . . . } free(pModulus); free(pExponent); } |
|
||||||||||||||||||||
|
C_SetAttributeValue modifies the value of one or more attributes of an object.
The template may specify new values for any attributes of the object that can be modified. If the template specifies a value of an attribute which is incompatible with other existing attributes of the object, the call fails with the return code CKR_TEMPLATE_INCONSISTENT. Not all attributes can be modified; see Section for more details.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hObject; CK_CHAR label[] = {"New label"}; CK_ATTRIBUTE template[] = { CKA_LABEL, label, sizeof(label) }; CK_RV rv; . . . rv = C_SetAttributeValue(hSession, hObject, &template, 1); if (rv == CKR_OK) { . . . } |
|
||||||||||||||||
|
C_FindObjectsInit initializes a search for token and session objects that match a template.
The object search operation will only find objects that the session can view. For example, an object search in an "R/W Public Session" will not find any private objects (even if one of the attributes in the search template specifies that the search is for private objects). If a search operation is active, and objects are created or destroyed which fit the search template for the active search operation, then those objects may or may not be found by the search operation. Note that this means that, under these circumstances, the search operation may return invalid object handles. Even though C_FindObjectsInit can return the values CKR_ATTRIBUTE_TYPE_INVALID and CKR_ATTRIBUTE_VALUE_INVALID, it is not required to. For example, if it is given a search template with nonexistent attributes in it, it can return CKR_ATTRIBUTE_TYPE_INVALID, or it can return CKR_OK and initialize a search operation which will match no objects.
|
|
||||||||||||||||||||
|
C_FindObjects continues a search for token and session objects that match a template, obtaining additional object handles.
The search must have been initialized with C_FindObjectsInit.
|
|
|
C_FindObjectsFinal terminates a search for token and session objects.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hObject; CK_ULONG ulObjectCount; CK_RV rv; . . . rv = C_FindObjectsInit(hSession, NULL_PTR, 0); assert(rv == CKR_OK); while (1) { rv = C_FindObjects(hSession, &hObject, 1, &ulObjectCount); if (rv != CKR_OK || ulObjectCount == 0) break; . . . } rv = C_FindObjectsFinal(hSession); assert(rv == CKR_OK); Encryption functions Cryptoki provides the following functions for encrypting data. All these functions may run in parallel with the application if the session was opened with the CKF_SERIAL_SESSION flag set to FALSE (check the return code of the function call to see if the function is running in parallel). |
|
||||||||||||||||
|
C_EncryptInit initializes an encryption operation.
After calling C_EncryptInit, the application can either call C_Encrypt to encrypt data in a single part; or call C_EncryptUpdate zero or more times, followed by C_EncryptFinal, to encrypt data in multiple parts. The encryption operation is active until the application uses a call to C_Encrypt or C_EncryptFinal to actually obtain the final piece of ciphertext. To process additional data (in single or multiple parts), the application must call C_EncryptInit again.
|
|
||||||||||||||||||||||||
|
C_Encrypt encrypts single-part data.
The encryption operation must have been initialized with C_EncryptInit. A call to C_Encrypt always terminates the active encryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the ciphertext. For some encryption mechanisms, the input plaintext data has certain length constraints (either because the mechanism can only encrypt relatively short pieces of plaintext, or because the mechanism's input data must consist of an integral number of blocks). If these constraints are not satisfied, then C_Encrypt will fail with return code CKR_DATA_LEN_RANGE. The plaintext and ciphertext can be in the same place, i.e., it is OK if pData and pEncryptedData point to the same location. C_Encrypt is equivalent to a sequence of C_EncryptUpdate and C_EncryptFinal.
|
|
||||||||||||||||||||||||
|
C_EncryptUpdate continues a multiple-part encryption operation, processing another data part.
The encryption operation must have been initialized with C_EncryptInit. This function may be called any number of times in succession. A call to C_EncryptUpdate which results in an error other than CKR_BUFFER_TOO_SMALL terminates the current encryption operation. The encryption operation must have been initialized with C_EncryptInit. A call to C_Encrypt always terminates the active encryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the ciphertext. The plaintext and ciphertext can be in the same place, i.e., it is OK if pPart and pEncryptedPart point to the same location.
|
|
||||||||||||||||
|
C_EncryptFinal finishes a multiple-part encryption operation.
The encryption operation must have been initialized with C_EncryptInit. A call to C_EncryptFinal always terminates the active encryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the ciphertext. For some multi-part encryption mechanisms, the input plaintext data has certain length constraints, because the mechanism's input data must consist of an integral number of blocks. If these constraints are not satisfied, then C_EncryptFinal will fail with return code CKR_DATA_LEN_RANGE.
#define PLAINTEXT_BUF_SZ 200 #define CIPHERTEXT_BUF_SZ 256 CK_ULONG firstPieceLen, secondPieceLen; CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey; CK_BYTE iv[8]; CK_MECHANISM mechanism = { CKM_DES_CBC_PAD, iv, sizeof(iv) }; CK_BYTE data[PLAINTEXT_BUF_SZ]; CK_BYTE encryptedData[CIPHERTEXT_BUF_SZ]; CK_ULONG ulEncryptedData1Len; CK_ULONG ulEncryptedData2Len; CK_ULONG ulEncryptedData3Len; CK_RV rv; . . . firstPieceLen = 90; secondPieceLen = PLAINTEXT_BUF_SZ-firstPieceLen; rv = C_EncryptInit(hSession, &mechanism, hKey); if (rv == CKR_OK) { /* Encrypt first piece */ ulEncryptedData1Len = sizeof(encryptedData); rv = C_EncryptUpdate( hSession, &data[0], firstPieceLen, &encryptedData[0], &ulEncryptedData1Len); if (rv != CKR_OK) { . . . } /* Encrypt second piece */ ulEncryptedData2Len = sizeof(encryptedData)-ulEncryptedData1Len; rv = C_EncryptUpdate( hSession, &data[firstPieceLen], secondPieceLen, &encryptedData[ulEncryptedData1Len], &ulEncryptedData2Len); if (rv != CKR_OK) { . . . } /* Get last little encrypted bit */ ulEncryptedData3Len = sizeof(encryptedData) -ulEncryptedData1Len-ulEncryptedData2Len; rv = C_EncryptFinal( hSession, &encryptedData[ulEncryptedData1Len+ulEncryptedData2Len], &ulEncryptedData3Len); if (rv != CKR_OK) { . . . } } Decryption functions Cryptoki provides the following functions for decrypting data. All these functions may run in parallel with the application if the session was opened with the CKF_SERIAL_SESSION flag set to FALSE (check the return code of the function call to see if the function is running in parallel). |
|
||||||||||||||||
|
C_DecryptInit initializes a decryption operation.
After calling C_DecryptInit, the application can either call C_Decrypt to decrypt data in a single part; or call C_DecryptUpdate zero or more times, followed by C_DecryptFinal, to decrypt data in multiple parts. The decryption operation is active until the application uses a call to C_Decrypt or C_DecryptFinal to actually obtain the final piece of plaintext. To process additional data (in single or multiple parts), the application must call C_DecryptInit again
|
|
||||||||||||||||||||||||
|
C_Decrypt decrypts encrypted data in a single part.
The decryption operation must have been initialized with C_DecryptInit. A call to C_Decrypt always terminates the active decryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the plaintext. The ciphertext and plaintext can be in the same place, i.e., it is OK if pEncryptedData and pData point to the same location. If the input ciphertext data cannot be decrypted because it has an inappropriate length, then either CKR_ENCRYPTED_DATA_INVALID or CKR_ENCRYPTED_DATA_LEN_RANGE may be returned. C_Decrypt is equivalent to a sequence of C_DecryptUpdate and C_DecryptFinal.
|
|
||||||||||||||||||||||||
|
C_DecryptUpdate continues a multiple-part decryption operation, processing another encrypted data part.
The decryption operation must have been initialized with C_DecryptInit. This function may be called any number of times in succession. A call to C_DecryptUpdate which results in an error other than CKR_BUFFER_TOO_SMALL terminates the current decryption operation. The ciphertext and plaintext can be in the same place, i.e., it is OK if pEncryptedPart and pPart point to the same location.
|
|
||||||||||||||||
|
C_DecryptFinal finishes a multiple-part decryption operation.
The decryption operation must have been initialized with C_DecryptInit. A call to C_DecryptFinal always terminates the active decryption operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the plaintext. If the input ciphertext data cannot be decrypted because it has an inappropriate length, then either CKR_ENCRYPTED_DATA_INVALID or CKR_ENCRYPTED_DATA_LEN_RANGE may be returned.
#define CIPHERTEXT_BUF_SZ 256 #define PLAINTEXT_BUF_SZ 256 CK_ULONG firstEncryptedPieceLen, secondEncryptedPieceLen; CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey; CK_BYTE iv[8]; CK_MECHANISM mechanism = { CKM_DES_CBC_PAD, iv, sizeof(iv) }; CK_BYTE data[PLAINTEXT_BUF_SZ]; CK_BYTE encryptedData[CIPHERTEXT_BUF_SZ]; CK_ULONG ulData1Len, ulData2Len, ulData3Len; CK_RV rv; . . . firstEncryptedPieceLen = 90; secondEncryptedPieceLen = CIPHERTEXT_BUF_SZ-firstEncryptedPieceLen; rv = C_DecryptInit(hSession, &mechanism, hKey); if (rv == CKR_OK) { /* Decrypt first piece */ ulData1Len = sizeof(data); rv = C_DecryptUpdate( hSession, &encryptedData[0], firstEncryptedPieceLen, &data[0], &ulData1Len); if (rv != CKR_OK) { . . . } /* Decrypt second piece */ ulData2Len = sizeof(data)-ulData1Len; rv = C_DecryptUpdate( hSession, &encryptedData[firstEncryptedPieceLen], secondEncryptedPieceLen, &data[ulData1Len], &ulData2Len); if (rv != CKR_OK) { . . . } /* Get last little decrypted bit */ ulData3Len = sizeof(data)-ulData1Len-ulData2Len; rv = C_DecryptFinal( hSession, &data[ulData1Len+ulData2Len], &ulData3Len); if (rv != CKR_OK) { . . . } } Message digesting functions Cryptoki provides the following functions for digesting data. All these functions may run in parallel with the application if the session was opened with the CKF_SERIAL_SESSION flag set to FALSE (check the return code of the function call to see if the function is running in parallel). |
|
||||||||||||
|
C_DigestInit initializes a message-digesting operation.
|
|
||||||||||||||||||||||||
|
C_Digest digests data in a single part.
The digest operation must have been initialized with C_DigestInit. A call to C_Digest always terminates the active digest operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the message digest. The input data and digest output can be in the same place, i.e., it is OK if pData and pDigest point to the same location. C_Digest is equivalent to a sequence of C_DigestUpdate and C_DigestFinal.
|
|
||||||||||||||||
|
C_DigestUpdate continues a multiple-part message-digesting operation, processing another data part.
|
|
||||||||||||
|
C_DigestKey continues a multiple-part message-digesting operation by digesting the value of a secret key.
If the value of the supplied key cannot be digested purely for some reason related to its length, C_DigestKey should return the error code CKR_KEY_SIZE_RANGE.
|
|
||||||||||||||||
|
C_DigestFinal finishes a multiple-part message-digesting operation, returning the message digest.
The digest operation must have been initialized with C_DigestInit. A call to C_DigestFinal always terminates the active digest operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the message digest.
CK_SESSION_HANDLE hSession; CK_MECHANISM mechanism = { CKM_MD5, NULL_PTR, 0 }; CK_BYTE data[] = {...}; CK_BYTE digest[16]; CK_ULONG ulDigestLen; CK_RV rv; . . . rv = C_DigestInit(hSession, &mechanism); if (rv != CKR_OK) { . . . } rv = C_DigestUpdate(hSession, data, sizeof(data)); if (rv != CKR_OK) { . . . } rv = C_DigestKey(hSession, hKey); if (rv != CKR_OK) { . . . } ulDigestLen = sizeof(digest); rv = C_DigestFinal(hSession, digest, &ulDigestLen); . . . Signing and MACing functions Cryptoki provides the following functions for signing data (for the purposes of Cryptoki, these operations also encompass message authentication codes). All these functions may run in parallel with the application if the session was opened with the CKF_SERIAL_SESSION flag set to FALSE (check the return code of the function call to see if the function is running in parallel). |
|
||||||||||||||||
|
C_SignInit initializes a signature operation, where the signature is an appendix to the data.
After calling C_SignInit, the application can either call C_Sign to sign in a single part; or call C_SignUpdate one or more times, followed by C_SignFinal, to sign data in multiple parts. The signature operation is active until the application uses a call to C_Sign or C_SignFinal to actually obtain the signature. To process additional data (in single or multiple parts), the application must call C_SignInit again.
|
|
||||||||||||||||||||||||
|
C_Sign signs data in a single part, where the signature is an appendix to the data.
The signing operation must have been initialized with C_SignInit. A call to C_Sign always terminates the active signing operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the signature. C_Sign is equivalent to a sequence of C_SignUpdate and C_SignFinal.
|
|
||||||||||||||||
|
C_SignUpdate continues a multiple-part signature operation, processing another data part.
|
|
||||||||||||||||
|
C_SignFinal finishes a multiple-part signature operation, returning the signature.
The signing operation must have been initialized with C_SignInit. A call to C_SignFinal always terminates the active signing operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the signature.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey; CK_MECHANISM mechanism = { CKM_DES_MAC, NULL_PTR, 0 }; CK_BYTE data[] = {...}; CK_BYTE mac[4]; CK_ULONG ulMacLen; CK_RV rv; . . . rv = C_SignInit(hSession, &mechanism, hKey); if (rv == CKR_OK) { rv = C_SignUpdate(hSession, data, sizeof(data)); . . . ulMacLen = sizeof(mac); rv = C_SignFinal(hSession, mac, &ulMacLen); . . . } |
|
||||||||||||||||
|
C_SignRecoverInit initializes a signature operation, where the data can be recovered from the signature.
After calling C_SignRecoverInit, the application may call C_SignRecover to sign in a single part. The signature operation is active until the application uses a call to C_SignRecover to actually obtain the signature. To process additional data in a single part, the application must call C_SignRecoverInit again.
|
|
||||||||||||||||||||||||
|
C_SignRecover signs data in a single operation, where the data can be recovered from the signature.
The signing operation must have been initialized with C_SignRecoverInit. A call to C_SignRecover always terminates the active signing operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the signature.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey; CK_MECHANISM mechanism = { CKM_RSA_9796, NULL_PTR, 0 }; CK_BYTE data[] = {...}; CK_BYTE signature[128]; CK_ULONG ulSignatureLen; CK_RV rv; . . . rv = C_SignRecoverInit(hSession, &mechanism, hKey); if (rv == CKR_OK) { usSignatureLen = sizeof(signature); rv = C_SignRecover( hSession, data, sizeof(data), signature, &usSignatureLen); if (rv == CKR_OK) { . . . } } Functions for verifying signatures and MACs Cryptoki provides the following functions for verifying signatures on data (for the purposes of Cryptoki, these operations also encompass message authentication codes). All these functions may run in parallel with the application if the session was opened with the CKF_SERIAL_SESSION flag set to FALSE (check the return code of the function call to see if the function is running in parallel). |
|
||||||||||||||||
|
C_VerifyInit initializes a verification operation, where the signature is an appendix to the data.
After calling C_VerifyInit, the application can either call C_Verify to verify a signature on data in a single part; or call C_VerifyUpdate one or more times, followed by C_VerifyFinal, to verify a signature on data in multiple parts. The verification operation is active until the application calls C_Verify or C_VerifyFinal. To process additional data (in single or multiple parts), the application must call C_VerifyInit again.
|
|
||||||||||||||||||||||||
|
C_Verify verifies a signature in a single-part operation, where the signature is an appendix to the data.
A successful call to C_Verify should return either the value CKR_OK (indicating that the supplied signature is valid) or CKR_SIGNATURE_INVALID (indicating that the supplied signature is invalid). If the signature can be seen to be invalid purely on the basis of its length, then CKR_SIGNATURE_LEN_RANGE should be returned. In any of these cases, the active signing operation is terminated. C_Verify is equivalent to a sequence of C_VerifyUpdate and C_VerifyFinal.
|
|
||||||||||||||||
|
C_VerifyUpdate continues a multiple-part verification operation, processing another data part.
|
|
||||||||||||||||
|
C_VerifyFinal finishes a multiple-part verification operation, checking the signature.
A successful call to C_VerifyFinal should return either the value CKR_OK (indicating that the supplied signature is valid) or CKR_SIGNATURE_INVALID (indicating that the supplied signature is invalid). If the signature can be seen to be invalid purely on the basis of its length, then CKR_SIGNATURE_LEN_RANGE should be returned. In any of these cases, the active verifying operation is terminated.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey; CK_MECHANISM mechanism = { CKM_DES_MAC, NULL_PTR, 0 }; CK_BYTE data[] = {...}; CK_BYTE mac[4]; CK_RV rv; . . . rv = C_VerifyInit(hSession, &mechanism, hKey); if (rv == CKR_OK) { rv = C_VerifyUpdate(hSession, data, sizeof(data)); . . . rv = C_VerifyFinal(hSession, mac, sizeof(mac)); . . . } |
|
||||||||||||||||
|
C_VerifyRecoverInit initializes a signature verification operation, where the data is recovered from the signature.
After calling C_VerifyRecoverInit, the application may call C_VerifyRecover to verify a signature on data in a single part. The verification operation is active until the application uses a call to C_VerifyRecover to actually obtain the recovered message.
|
|
||||||||||||||||||||||||
|
C_VerifyRecover verifies a signature in a single-part operation, where the data is recovered from the signature.
The verification operation must have been initialized with C_VerifyRecoverInit. A call to C_VerifyRecover always terminates the active verification operation unless it returns CKR_BUFFER_TOO_SMALL or is a successful call (i.e., one which returns CKR_OK) to determine the length of the buffer needed to hold the recovered data. A successful call to C_VerifyRecover should return either the value CKR_OK (indicating that the supplied signature is valid) or CKR_SIGNATURE_INVALID (indicating that the supplied signature is invalid). If the signature can be seen to be invalid purely on the basis of its length, then CKR_SIGNATURE_LEN_RANGE should be returned. The return codes CKR_SIGNATURE_INVALID and CKR_SIGNATURE_LEN_RANGE have a higher priority than the return code CKR_BUFFER_TOO_SMALL, i.e., if C_VerifyRecover is supplied with an invalid signature, it will never return CKR_BUFFER_TOO_SMALL.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey; CK_MECHANISM mechanism = { CKM_RSA_9796, NULL_PTR, 0 }; CK_BYTE data[] = {...}; CK_ULONG ulDataLen; CK_BYTE signature[128]; CK_RV rv; . . . rv = C_VerifyRecoverInit(hSession, &mechanism, hKey); if (rv == CKR_OK) { ulDataLen = sizeof(data); rv = C_VerifyRecover( hSession, signature, sizeof(signature), data, &ulDataLen); . . . } Dual-function cryptographic functions Cryptoki provides the following functions to perform two cryptographic operations "simultaneously" within a session. These functions are provided so as to avoid unnecessarily passing data back and forth to and from a token. All these functions may run in parallel with the application if the session was opened with the CKF_SERIAL_SESSION flag set to FALSE (check the return code of the function call to see if the function is running in parallel). |
|
||||||||||||||||||||||||
|
C_DigestEncryptUpdate continues multiple-part digest and encryption operations, processing another data part.
Digest and encryption operations must both be active (they must have been initialized with C_DigestInit and C_EncryptInit, respectively). This function may be called any number of times in succession, and may be interspersed with C_DigestUpdate, C_DigestKey, and C_EncryptUpdate calls (it would be somewhat unusual to intersperse calls to C_DigestEncryptUpdate with calls to C_DigestKey, however).
#define BUF_SZ 512 CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey; CK_BYTE iv[8]; CK_MECHANISM digestMechanism = { CKM_MD5, NULL_PTR, 0 }; CK_MECHANISM encryptionMechanism = { CKM_DES_ECB, iv, sizeof(iv) }; CK_BYTE encryptedData[BUF_SZ]; CK_ULONG ulEncryptedDataLen; CK_BYTE digest[16]; CK_ULONG ulDigestLen; CK_BYTE data[(2*BUF_SZ)+8]; CK_RV rv; int i; . . . memset(iv, 0, sizeof(iv)); memset(data, 'A', ((2*BUF_SZ)+5)); rv = C_EncryptInit(hSession, &encryptionMechanism, hKey); if (rv != CKR_OK) { . . . } rv = C_DigestInit(hSession, &digestMechanism); if (rv != CKR_OK) { . . . } ulEncryptedDataLen = sizeof(encryptedData); rv = C_DigestEncryptUpdate( hSession, &data[0], BUF_SZ, encryptedData, &ulEncryptedDataLen); . . . ulEncryptedDataLen = sizeof(encryptedData); rv = C_DigestEncryptUpdate( hSession, &data[BUF_SZ], BUF_SZ, encryptedData, &ulEncryptedDataLen); . . . /* * The last portion of the buffer needs to be handled with * separate calls to deal with padding issues in ECB mode */ /* First, complete the digest on the buffer */ rv = C_DigestUpdate(hSession, &data[BUF_SZ*2], 5); . . . ulDigestLen = sizeof(digest); rv = C_DigestFinal(hSession, digest, &ulDigestLen); . . . /* Then, pad last part with 3 0x00 bytes, and complete encryption */ for(i=0;i<3;i++) data[((BUF_SZ*2)+5)+i] = 0x00; /* Now, get second-to-last piece of ciphertext */ ulEncryptedDataLen = sizeof(encryptedData); rv = C_EncryptUpdate( hSession, &data[BUF_SZ*2], 8, encryptedData, &ulEncryptedDataLen); . . . /* Get last piece of ciphertext (should have length 0, here) */ ulEncryptedDataLen = sizeof(encryptedData); rv = C_EncryptFinal(hSession, encryptedData, &ulEncryptedDataLen); . . . |
|
||||||||||||||||||||||||
|
C_DecryptDigestUpdate continues a multiple-part combined decryption and digest operation, processing another data part.
Decryption and digesting operations must both be active (they must have been initialized with C_DecryptInit and C_DigestInit, respectively). This function may be called any number of times in succession, and may be interspersed with C_DecryptUpdate, C_DigestUpdate, and C_DigestKey calls (it would be somewhat unusual to intersperse calls to C_DigestEncryptUpdate with calls to C_DigestKey, however). Use of C_DecryptDigestUpdate involves a pipelining issue that does not arise when using C_DigestEncryptUpdate, the "inverse function" of C_DecryptDigestUpdate. This is because when C_DigestEncryptUpdate is called, precisely the same input is passed to both the active digesting operation and the active encryption operation; however, when C_DecryptDigestUpdate is called, the input passed to the active digesting operation is the output of the active decryption operation. This issue comes up only when the mechanism used for decryption performs padding. In particular, envision a 24-byte ciphertext which was obtained by encrypting an 18-byte plaintext with DES in CBC mode with PKCS padding. Consider an application which will simultaneously decrypt this ciphertext and digest the original plaintext thereby obtained. After initializing decryption and digesting operations, the application passes the 24-byte ciphertext (3 DES blocks) into C_DecryptDigestUpdate. C_DecryptDigestUpdate returns exactly 16 bytes of plaintext, since at this point, Cryptoki doesn't know if there's more ciphertext coming, or if the last block of ciphertext held any padding. These 16 bytes of plaintext are passed into the active digesting operation. Since there is no more ciphertext, the application calls C_DecryptFinal. This tells Cryptoki that there's no more ciphertext coming, and the call returns the last 2 bytes of plaintext. However, since the active decryption and digesting operations are linked only through the C_DecryptDigestUpdate call, these 2 bytes of plaintext are not passed on to be digested. A call to C_DigestFinal, therefore, would compute the message digest of the first 16 bytes of the plaintext, not the message digest of the entire plaintext. It is crucial that, before C_DigestFinal is called, the last 2 bytes of plaintext get passed into the active digesting operation. Because of this, it is critical that when an application uses a padded decryption mechanism with C_DecryptDigestUpdate, it knows exactly how much plaintext has been passed into the active digesting operation. Extreme caution is warranted when using a padded decryption mechanism with C_DecryptDigestUpdate.
#define BUF_SZ 512 CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey; CK_BYTE iv[8]; CK_MECHANISM decryptionMechanism = { CKM_DES_ECB, iv, sizeof(iv) }; CK_MECHANISM digestMechanism = { CKM_MD5, NULL_PTR, 0 }; CK_BYTE encryptedData[(2*BUF_SZ)+8]; CK_BYTE digest[16]; CK_ULONG ulDigestLen; CK_BYTE data[BUF_SZ]; CK_ULONG ulDataLen, ulLastUpdateSize; CK_RV rv; . . . memset(iv, 0, sizeof(iv)); memset(encryptedData, 'A', ((2*BUF_SZ)+8)); rv = C_DecryptInit(hSession, &decryptionMechanism, hKey); if (rv != CKR_OK) { . . . } rv = C_DigestInit(hSession, &digestMechanism); if (rv != CKR_OK){ . . . } ulDataLen = sizeof(data); rv = C_DecryptDigestUpdate( hSession, &encryptedData[0], BUF_SZ, data, &ulDataLen); . . . ulDataLen = sizeof(data); rv = C_DecryptDigestUpdate( hSession, &encryptedData[BUF_SZ], BUF_SZ, data, &uldataLen); . . . /* * The last portion of the buffer needs to be handled with * separate calls to deal with padding issues in ECB mode */ /* First, complete the decryption of the buffer */ ulLastUpdateSize = sizeof(data); rv = C_DecryptUpdate( hSession, &encryptedData[BUF_SZ*2], 8, data, &ulLastUpdateSize); . . . /* Get last piece of plaintext (should have length 0, here) */ ulDataLen = sizeof(data)-ulLastUpdateSize; rv = C_DecryptFinal(hSession, &data[ulLastUpdateSize], &ulDataLen); if (rv != CKR_OK) { . . . } /* Digest last bit of plaintext */ rv = C_DigestUpdate(hSession, &data[BUF_SZ*2], 5); if (rv != CKR_OK) { . . . } ulDigestLen = sizeof(digest); rv = C_DigestFinal(hSession, digest, &ulDigestLen); if (rv != CKR_OK) { . . . } |
|
||||||||||||||||||||||||
|
C_SignEncryptUpdate continues a multiple-part combined signature and encryption operation, processing another data part.
Signature and encryption operations must both be active (they must have been initialized with C_SigntInit and C_EncryptInit, respectively). This function may be called any number of times in succession, and may be interspersed with C_SignUpdate and C_EncryptUpdate calls.
#define BUF_SZ 512 CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hEncryptionKey, hMacKey; CK_BYTE iv[8]; CK_MECHANISM signMechanism = { CKM_DES_MAC, NULL_PTR, 0 }; CK_MECHANISM encryptionMechanism = { CKM_DES_ECB, iv, sizeof(iv) }; CK_BYTE encryptedData[BUF_SZ]; CK_ULONG ulEncryptedDataLen; CK_BYTE MAC[4]; CK_ULONG ulMacLen; CK_BYTE data[(2*BUF_SZ)+8]; CK_RV rv; int i; . . . memset(iv, 0, sizeof(iv)); memset(data, 'A', ((2*BUF_SZ)+5)); rv = C_EncryptInit(hSession, &encryptionMechanism, hEncryptionKey); if (rv != CKR_OK) { . . . } rv = C_SignInit(hSession, &signMechanism, hMacKey); if (rv != CKR_OK) { . . . } ulEncryptedDataLen = sizeof(encryptedData); rv = C_SignEncryptUpdate( hSession, &data[0], BUF_SZ, encryptedData, &ulEncryptedDataLen); . . . ulEncryptedDataLen = sizeof(encryptedData); rv = C_SignEncryptUpdate( hSession, &data[BUF_SZ], BUF_SZ, encryptedData, &ulEncryptedDataLen); . . . /* * The last portion of the buffer needs to be handled with * separate calls to deal with padding issues in ECB mode */ /* First, complete the signature on the buffer */ rv = C_SignUpdate(hSession, &data[BUF_SZ*2], 5); . . . ulMacLen = sizeof(MAC); rv = C_DigestFinal(hSession, MAC, &ulMacLen); . . . /* Then pad last part with 3 0x00 bytes, and complete encryption */ for(i=0;i<3;i++) data[((BUF_SZ*2)+5)+i] = 0x00; /* Now, get second-to-last piece of ciphertext */ ulEncryptedDataLen = sizeof(encryptedData); rv = C_EncryptUpdate( hSession, &data[BUF_SZ*2], 8, encryptedData, &ulEncryptedDataLen); . . . /* Get last piece of ciphertext (should have length 0, here) */ ulEncryptedDataLen = sizeof(encryptedData); rv = C_EncryptFinal(hSession, encryptedData, &ulEncryptedDataLen); . . . |
|
||||||||||||||||||||||||
|
C_DecryptVerifyUpdate continues a multiple-part combined decryption and verification operation, processing another data part.
Decryption and signature operations must both be active (they must have been initialized with C_DecryptInit and C_VerifyInit, respectively). This function may be called any number of times in succession, and may be interspersed with C_DecryptUpdate and C_VerifyUpdate calls. Use of C_DecryptVerifyUpdate involves a pipelining issue that does not arise when using C_SignEncryptUpdate, the "inverse function" of C_DecryptVerifyUpdate. This is because when C_SignEncryptUpdate is called, precisely the same input is passed to both the active signing operation and the active encryption operation; however, when C_DecryptVerifyUpdate is called, the input passed to the active verifying operation is the output of the active decryption operation. This issue comes up only when the mechanism used for decryption performs padding. In particular, envision a 24-byte ciphertext which was obtained by encrypting an 18-byte plaintext with DES in CBC mode with PKCS padding. Consider an application which will simultaneously decrypt this ciphertext and verify a signature on the original plaintext thereby obtained. After initializing decryption and verification operations, the application passes the 24-byte ciphertext (3 DES blocks) into C_DecryptVerifyUpdate. C_DecryptVerifyUpdate returns exactly 16 bytes of plaintext, since at this point, Cryptoki doesn't know if there's more ciphertext coming, or if the last block of ciphertext held any padding. These 16 bytes of plaintext are passed into the active verification operation. Since there is no more ciphertext, the application calls C_DecryptFinal. This tells Cryptoki that there's no more ciphertext coming, and the call returns the last 2 bytes of plaintext. However, since the active decryption and verification operations are linked only through the C_DecryptVerifyUpdate call, these 2 bytes of plaintext are not passed on to the verification mechanism. A call to C_VerifyFinal, therefore, would verify whether or not the signature supplied is a valid signature on the first 16 bytes of the plaintext, not on the entire plaintext. It is crucial that, before C_VerifyFinal is called, the last 2 bytes of plaintext get passed into the active verification operation. Because of this, it is critical that when an application uses a padded decryption mechanism with C_DecryptVerifyUpdate, it knows exactly how much plaintext has been passed into the active verification operation. Extreme caution is warranted when using a padded decryption mechanism with C_DecryptVerifyUpdate.
#define BUF_SZ 512 CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hDecryptionKey, hMacKey; CK_BYTE iv[8]; CK_MECHANISM decryptionMechanism = { CKM_DES_ECB, iv, sizeof(iv) }; CK_MECHANISM verifyMechanism = { CKM_DES_MAC, NULL_PTR, 0 }; CK_BYTE encryptedData[(2*BUF_SZ)+8]; CK_BYTE MAC[4]; CK_ULONG ulMacLen; CK_BYTE data[BUF_SZ]; CK_ULONG ulDataLen, ulLastUpdateSize; CK_RV rv; . . . memset(iv, 0, sizeof(iv)); memset(encryptedData, 'A', ((2*BUF_SZ)+8)); rv = C_DecryptInit(hSession, &decryptionMechanism, hDecryptionKey); if (rv != CKR_OK) { . . . } rv = C_VerifyInit(hSession, &verifyMechanism, hMacKey); if (rv != CKR_OK){ . . . } ulDataLen = sizeof(data); rv = C_DecryptVerifyUpdate( hSession, &encryptedData[0], BUF_SZ, data, &ulDataLen); . . . ulDataLen = sizeof(data); rv = C_DecryptVerifyUpdate( hSession, &encryptedData[BUF_SZ], BUF_SZ, data, &uldataLen); . . . /* * The last portion of the buffer needs to be handled with * separate calls to deal with padding issues in ECB mode */ /* First, complete the decryption of the buffer */ ulLastUpdateSize = sizeof(data); rv = C_DecryptUpdate( hSession, &encryptedData[BUF_SZ*2], 8, data, &ulLastUpdateSize); . . . /* Get last little piece of plaintext. Should have length 0 */ ulDataLen = sizeof(data)-ulLastUpdateSize; rv = C_DecryptFinal(hSession, &data[ulLastUpdateSize], &ulDataLen); if (rv != CKR_OK) { . . . } /* Send last bit of plaintext to verification operation */ rv = C_VerifyUpdate(hSession, &data[BUF_SZ*2], 5); if (rv != CKR_OK) { . . . } rv = C_VerifyFinal(hSession, MAC, ulMacLen); if (rv == CKR_SIGNATURE_INVALID) { . . . } Key management functions Cryptoki provides the following functions for key management. All these functions may run in parallel with the application if the session was opened with the CKF_SERIAL_SESSION flag set to FALSE (check the return code of the function call to see if the function is running in parallel). |
|
||||||||||||||||||||||||
|
C_GenerateKey generates a secret key, creating a new key object.
The key object created by a successful call to C_GenerateKey will have its CKA_LOCAL attribute set to TRUE.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hKey; CK_MECHANISM mechanism = { CKM_DES_KEY_GEN, NULL_PTR, 0 }; CK_RV rv; . . . rv = C_GenerateKey(hSession, &mechanism, NULL_PTR, 0, &hKey); if (rv == CKR_OK) { . . . } |
|
||||||||||||||||||||||||||||||||||||
|
C_GenerateKeyPair generates a public/private key pair, creating new key objects.
The key objects created by a successful call to C_GenerateKeyPair will have their CKA_LOCAL attributes set to TRUE.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hPublicKey, hPrivateKey; CK_MECHANISM mechanism = { CKM_RSA_PKCS_KEY_PAIR_GEN, NULL_PTR, 0 }; CK_ULONG modulusBits = 768; CK_BYTE publicExponent[] = { 3 }; CK_BYTE subject[] = {...}; CK_BYTE id[] = {123}; CK_BBOOL true = TRUE; CK_ATTRIBUTE publicKeyTemplate[] = { {CKA_ENCRYPT, &true, sizeof(true)}, {CKA_VERIFY, &true, sizeof(true)}, {CKA_WRAP, &true, sizeof(true)}, {CKA_MODULUS_BITS, &modulusBits, sizeof(modulusBits)}, {CKA_PUBLIC_EXPONENT, publicExponent, sizeof (publicExponent)} }; CK_ATTRIBUTE privateKeyTemplate[] = { {CKA_TOKEN, &true, sizeof(true)}, {CKA_PRIVATE, &true, sizeof(true)}, {CKA_SUBJECT, subject, sizeof(subject)}, {CKA_ID, id, sizeof(id)}, {CKA_SENSITIVE, &true, sizeof(true)}, {CKA_DECRYPT, &true, sizeof(true)}, {CKA_SIGN, &true, sizeof(true)}, {CKA_UNWRAP, &true, sizeof(true)} }; CK_RV rv; rv = C_GenerateKeyPair( hSession, &mechanism, publicKeyTemplate, 5, privateKeyTemplate, 8, &hPublicKey, &hPrivateKey); if (rv == CKR_OK) { . . . } |
|
||||||||||||||||||||||||||||
|
C_WrapKey wraps (i.e., encrypts) a private or secret key.
The CKA_WRAP attribute of the wrapping key, which indicates whether the key supports wrapping, must be TRUE. The CKA_EXTRACTABLE attribute of the key to be wrapped must also be TRUE. If the key to be wrapped cannot be wrapped for some token-specific reason, despite its having its CKA_EXTRACTABLE attribute set to 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 a priori be used in the following situations:
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hWrappingKey, hKey; CK_MECHANISM mechanism = { CKM_DES3_ECB, NULL_PTR, 0 }; CK_BYTE wrappedKey[8]; CK_ULONG ulWrappedKeyLen; CK_RV rv; . . . ulWrappedKeyLen = sizeof(wrappedKey); rv = C_WrapKey( hSession, &mechanism, hWrappingKey, hKey, wrappedKey, &ulWrappedKeyLen); if (rv == CKR_OK) { . . . } |
|
||||||||||||||||||||||||||||||||||||
|
C_UnwrapKey unwraps (i.e. decrypts) a wrapped key, creating a new private key or secret key object.
The new key will have the CKA_ALWAYS_SENSITIVE attribute set to FALSE, and the CKA_EXTRACTABLE attribute set to TRUE. If the template for the new key has the CKA_EXTRACTABLE attribute set to FALSE, C_UnwrapKey fails with the error CKR_TEMPLATE_INCONSISTENT. When C_UnwrapKey is used to unwrap a key with the CKM_KEY_WRAP_SET_OAEP mechanism (see Section), additional "extra data" is decrypted at the same time that the key is unwrapped. The return of this data follows the convention in Section on producing output. If the extra data is not returned from a call to C_UnwrapKey (either because the call was only to find out how large the extra data is, or because the buffer provided for the extra data was too small), then C_UnwrapKey will not create a new key, either. The key object created by a successful call to C_UnwrapKey will have its CKA_LOCAL attribute set to FALSE.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hUnwrappingKey, hKey; CK_MECHANISM mechanism = { CKM_DES3_ECB, NULL_PTR, 0 }; CK_BYTE wrappedKey[8] = {...}; CK_OBJECT_CLASS keyClass = CKO_SECRET_KEY; CK_KEY_TYPE keyType = CKK_DES; CK_BBOOL true = TRUE; CK_ATTRIBUTE template[] = { {CKA_CLASS, &keyClass, sizeof(keyClass)}, {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, {CKA_ENCRYPT, &true, sizeof(true)}, {CKA_DECRYPT, &true, sizeof(true)} }; CK_RV rv; . . . rv = C_UnwrapKey( hSession, &mechanism, hUnwrappingKey, wrappedKey, sizeof(wrappedKey), template, 4, &hKey); if (rv == CKR_OK) { . . . } |
|
||||||||||||||||||||||||||||
|
C_DeriveKey derives a key from a base key, creating a new key object.
The key object created by a successful call to C_DeriveKey will have its CKA_LOCAL attribute set to FALSE.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hPublicKey, hPrivateKey, hKey; CK_MECHANISM keyPairMechanism = { CKM_DH_PKCS_KEY_PAIR_GEN, NULL_PTR, 0 }; CK_BYTE prime[] = {...}; CK_BYTE base[] = {...}; CK_BYTE publicValue[128]; CK_BYTE otherPublicValue[128]; CK_MECHANISM mechanism = { CKM_DH_PKCS_DERIVE, otherPublicValue, sizeof(otherPublicValue) }; CK_ATTRIBUTE pTemplate[] = { CKA_VALUE, &publicValue, sizeof(publicValue)} }; CK_OBJECT_CLASS keyClass = CKO_SECRET_KEY; CK_KEY_TYPE keyType = CKK_DES; CK_BBOOL true = TRUE; CK_ATTRIBUTE publicKeyTemplate[] = { {CKA_PRIME, prime, sizeof(prime)}, {CKA_BASE, base, sizeof(base)} }; CK_ATTRIBUTE privateKeyTemplate[] = { {CKA_DERIVE, &true, sizeof(true)} }; CK_ATTRIBUTE template[] = { {CKA_CLASS, &keyClass, sizeof(keyClass)}, {CKA_KEY_TYPE, &keyType, sizeof(keyType)}, {CKA_ENCRYPT, &true, sizeof(true)}, {CKA_DECRYPT, &true, sizeof(true)} }; CK_RV rv; . . . rv = C_GenerateKeyPair( hSession, &keyPairMechanism, publicKeyTemplate, 2, privateKeyTemplate, 1, &hPublicKey, &hPrivateKey); if (rv == CKR_OK) { rv = C_GetAttributeValue(hSession, hPublicKey, &pTemplate, 1); if (rv == CKR_OK) { /* Put other guy's public value in otherPublicValue */ . . . rv = C_DeriveKey( hSession, &mechanism, hPrivateKey, template, 4, &hKey); if (rv == CKR_OK) { . . . } } } Random number generation functions Cryptoki provides the following functions for generating random numbers. All these functions may run in parallel with the application if the session was opened with the CKF_SERIAL_SESSION flag set to FALSE (check the return code of the function call to see if the function is running in parallel). |
|
||||||||||||||||
|
C_SeedRandom mixes additional seed material into the token's random number generator.
|
|
||||||||||||||||
|
C_GenerateRandom generates random data.
CK_SESSION_HANDLE hSession; CK_BYTE seed[] = {...}; CK_BYTE randomData[] = {...}; CK_RV rv; . . . rv = C_SeedRandom(hSession, seed, sizeof(seed)); if (rv != CKR_OK) { . . . } rv = C_GenerateRandom(hSession, randomData, sizeof(randomData)); if (rv == CKR_OK) { . . . } Parallel function management functions Cryptoki provides the following functions for managing parallel execution of cryptographic functions: |
|
|
C_GetFunctionStatus obtains the status of a function running in parallel with an application.
Typically, an application might call this function repeatedly when a function is executing in parallel. Eventually, once the function has finished its execution, the return value of C_GetFunctionStatus will no longer be CKR_FUNCTION_PARALLEL; instead, it will be the return code of the function. Because of the way C_GetFunctionState 's behavior is defined above, repeated calls to C_GetFunctionStatus will all yield the same return code of the function (until some other Cryptoki function is called in the specified session). Note that the application will also receive a CKN_COMPLETE notification callback when the function completes its parallel execution, assuming that the session the function is running in was opened with callbacks.
|
|
|
C_CancelFunction cancels a function running in parallel with an application.
CK_SESSION_HANDLE hSession; CK_OBJECT_HANDLE hPublicKey, hPrivateKey; CK_MECHANISM mechanism = { CKM_RSA_PKCS_KEY_PAIR_GEN, NULL_PTR, 0 }; CK_ULONG modulusBits = 768; CK_BYTE publicExponent[] = {...}; CK_BYTE subject[] = {...}; CK_BYTE id[] = {123}; CK_BBOOL true = TRUE; CK_ATTRIBUTE publicKeyTemplate[] = { {CKA_ENCRYPT, &true, sizeof(true)}, {CKA_VERIFY, &true, sizeof(true)}, {CKA_WRAP, &true, sizeof(true)}, {CKA_MODULUS_BITS, &modulusBits, sizeof(modulusBits)}, {CKA_PUBLIC_EXPONENT, publicExponent, sizeof(publicExponent)} }; CK_ATTRIBUTE privateKeyTemplate[] = { {CKA_TOKEN, &true, sizeof(true)}, {CKA_PRIVATE, &true, sizeof(true)}, {CKA_SUBJECT, subject, sizeof(subject)}, {CKA_ID, id, sizeof(id)}, {CKA_SENSITIVE, &true, sizeof(true)}, {CKA_DECRYPT, &true, sizeof(true)}, {CKA_SIGN, &true, sizeof(true)}, {CKA_UNWRAP, &true, sizeof(true)} }; CK_RV rv; . . . rv = C_GenerateKeyPair( hSession, &mechanism, publicKeyTemplate, 5, privateKeyTemplate, 8, &hPublicKey, &hPrivateKey); while (rv == CKR_FUNCTION_PARALLEL) { /* Check if user wants to cancel function */ if (kbhit()) { if (getch() == 27) { /* If user hit ESCape key */ rv = C_CancelFunction(hSession); . . . } } /* Perform other tasks or delay */ . . . rv = C_GetFunctionStatus(hSession); } Callback functions Cryptoki uses function pointers of type CK_NOTIFY to notify the application of certain events. There are four different types of application callbacks. Token insertion callbacks An application can use C_OpenSession to set up a token insertion callback function (assuming insertion callbacks are supported for that slot). When a token is inserted into the specified slot, the application callback function that was supplied to C_OpenSession is called with the arguments (0, CKN_TOKEN_INSERTION, pApplication), where pApplication was supplied to C_OpenSession. Token insertion callbacks should return the value CKR_OK. Token removal callbacks When a token is removed from its slot, each open session which had a callback function specified when it was opened receives a callback. Each session's callback is called with the arguments (hSession, CKN_DEVICE_REMOVED, pApplication), where hSession is the session's handle (although when the callback occurs, the session has just been closed because of the token removal) and pApplication was supplied to C_OpenSession. It is not necessarily the case that all slots/tokens will support token removal callbacks. Token removal callbacks should return the value CKR_OK. Parallel function completion callbacks When a function executing in parallel finishes execution, the callback for the session that function was running in (if there is such a callback) is executed with arguments (hSession, CKN_COMPLETE, pApplication), where hSession is the session's handle and pApplication was supplied to C_OpenSession. Parallel function completion callbacks should return the value CKR_OK. Serial function surrender callbacks Functions executing in serial sessions can periodically surrender control to the application who called them, if the session they are executing in has a callback function. They do this by calling their session's callback with arguments (hSession, CKN_SURRENDER, pApplication), where hSession is the session's handle and pApplication was supplied to C_OpenSession. Serial function surrender callbacks should return either the value CKR_OK (to indicate that Cryptoki should continue executing the function) or the value CKR_CANCEL (to indicate that Cryptoki should abort execution of the function). Of course, before returning one of these values, the callback function can perform some computation. Note that this type of callback is somewhat different from the other three types of callbacks, because it doesn't require a spontaneous generation of a thread or process to execute the callback. |