c_sign.h File Reference

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

Functions
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.

Function Documentation

C_Sign()

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.

hSession is the session's handle; pData points to the data; ulDataLen is the length of the data; pSignature points to the location that receives the signature; pulSignatureLen points to the location that holds the length of the signature.

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

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 cannot be used to terminate a multi-part operation, and MUST be called after C_SignInit without intervening C_SignUpdate calls.

For most mechanisms, C_Sign is equivalent to a sequence of C_SignUpdate operations followed by C_SignFinal.

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, CKR_FUNCTION_REJECTED.

C_SignFinal()

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.

hSession is the session's handle; pSignature points to the location that receives the signature; pulSignatureLen points to the location that holds the length of the signature.

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

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.

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN, CKR_FUNCTION_REJECTED.

C_SignInit()

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.

hSession is the session's handle; pMechanism points to the signature mechanism; hKey is the handle of the signature key.

The CKA_SIGN attribute of the signature key, which indicates whether the key supports signatures with appendix, MUST be CK_TRUE.

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.

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

C_SignRecover()

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.

Warning

This function is not supported.

hSession is the session's handle; pData points to the data; uLDataLen is the length of the data; pSignature points to the location that receives the signature; pulSignatureLen points to the location that holds the length of the signature.

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

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.

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

C_SignRecoverInit()

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.

Warning

This function is not supported.

hSession is the session's handle; pMechanism points to the structure that specifies the signature mechanism; hKey is the handle of the signature key.

The CKA_SIGN_RECOVER attribute of the signature key, which indicates whether the key supports signatures where the data can be recovered from the signature, MUST be CK_TRUE.

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.

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

C_SignUpdate()

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.

hSession is the session's handle, pPart points to the data part; ulPartLen is the length of the data part.

The signature operation MUST have been initialized with C_SignInit. This function may be called any number of times in succession. A call to C_SignUpdate which results in an error terminates the current signature operation.

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

C_Verify()

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.

hSession is the session's handle; pData points to the data; ulDataLen is the length of the data; pSignature points to the signature; ulSignatureLen is the length of the signature.

The verification operation MUST have been initialized with C_VerifyInit. A call to C_Verify always terminates the active verification operation.

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 cannot be used to terminate a multi-part operation, and MUST be called after C_VerifyInit without intervening C_VerifyUpdate calls.

For most mechanisms, C_Verify is equivalent to a sequence of C_VerifyUpdate operations followed by C_VerifyFinal.

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SIGNATURE_INVALID, CKR_SIGNATURE_LEN_RANGE.

C_VerifyFinal()

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.

hSession is the session's handle; pSignature points to the signature; ulSignatureLen is the length of the signature.

The verification operation MUST have been initialized with C_VerifyInit. A call to C_VerifyFinal always terminates the active verification operation.

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.

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SIGNATURE_INVALID, CKR_SIGNATURE_LEN_RANGE.

C_VerifyInit()

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.

hSession is the session's handle; pMechanism points to the structure that specifies the verification mechanism; hKey is the handle of the verification key.

The CKA_VERIFY attribute of the verification key, which indicates whether the key supports verification where the signature is an appendix to the data, MUST be CK_TRUE.

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.

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

C_VerifyRecover()

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.

Warning

This function is not supported.

hSession is the session's handle; pSignature points to the signature; ulSignatureLen is the length of the signature; pData points to the location that receives the recovered data; and pulDataLen points to the location that holds the length of the recovered data.

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

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.

Return values: CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_INVALID, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SIGNATURE_LEN_RANGE, CKR_SIGNATURE_INVALID.

C_VerifyRecoverInit()

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.

Warning

This function is not supported.

hSession is the session's handle; pMechanism points to the structure that specifies the verification mechanism; hKey is the handle of the verification key.

The CKA_VERIFY_RECOVER attribute of the verification key, which indicates whether the key supports verification where the data is recovered from the signature, MUST be CK_TRUE.

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.

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_KEY_FUNCTION_NOT_PERMITTED, CKR_KEY_HANDLE_INVALID, CKR_KEY_SIZE_RANGE, CKR_KEY_TYPE_INCONSISTENT, CKR_MECHANISM_INVALID, CKR_MECHANISM_PARAM_INVALID, CKR_OK, CKR_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

C_VerifyUpdate()

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.

hSession is the session's handle, pPart points to the data part; ulPartLen is the length of the data part.

The verification operation MUST have been initialized with C_VerifyInit. This function may be called any number of times in succession. A call to C_VerifyUpdate which results in an error terminates the current verification operation.

Return values: CKR_ARGUMENTS_BAD, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DATA_LEN_RANGE, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID.