PKCS#11
|
| Cryptographic Token Interface Standard |
PKCS#11 |
Cryptoki provides the following functions for decrypting data:
CK_RV C_DecryptInit( CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey);
C_DecryptInit initializes a decryption operation.
| hSession | is the session's handle; |
| pMechanism | points to the decryption mechanism; |
| hKey | is the handle of the decryption key. |
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
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.
| hSession | is the session's handle; |
| pEncryptedData | points to the encrypted data; |
| ulEncryptedDataLen | is the length of the encrypted data; |
| pData | points to the location that receives the recovered data; |
| pulDataLen | points to the location that holds the length of the recovered data. |
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.
C_Decrypt can not be used to terminate a multi-part operation, and must be called after C_DecryptInit without intervening C_DecryptUpdate calls.
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.
For most mechanisms, C_Decrypt is equivalent to a sequence of C_DecryptUpdate operations followed by C_DecryptFinal.
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.
| hSession | is the session's handle; |
| pEncryptedPart | points to the encrypted data part; |
| ulEncryptedPartLen | is the length of the encrypted data part; |
| pPart | points to the location that receives the recovered data part; |
| pulPartLen | points to the location that holds the length of the recovered 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.
CK_RV C_DecryptFinal( CK_SESSION_HANDLE hSession, CK_BYTE_PTR pLastPart, CK_ULONG_PTR pulLastPartLen);
C_DecryptFinal finishes a multiple-part decryption operation.
| hSession | is the session's handle; |
| pLastPart | points to the location that receives the last recovered data part, if any; |
| pulLastPartLen | points to the location that holds the length of the last recovered data part. |
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) { . . . } }