PKCS#11
|
| Cryptographic Token Interface Standard |
PKCS#11 |
Cryptoki provides the following functions for verifying signatures on data (for the purposes of Cryptoki, these operations also encompass message authentication codes):
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. |
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.
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. |
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 can not 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.
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. |
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. |
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)); . . . }
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.
| hSession | is the session's handle; |
| pMechanism | points to the structure that specifies the verification mechanism; |
| hKey | is the handle of the verification key. |
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.
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.
| 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; |
| pulDataLen | points to the location that holds the length of the recovered data. |
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); . . . }