PKCS#11
|
| Cryptographic Token Interface Standard |
PKCS#11 |
Cryptoki provides the following functions for encrypting data:
CK_RV C_EncryptInit( CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey);
C_EncryptInit initializes an encryption operation.
| hSession | is the session's handle; |
| pMechanism | points to the encryption mechanism; |
| hKey | is the handle of the encryption key. |
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.
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.
| hSession | is the session's handle; |
| pData | points to the data; |
| ulDataLen | is the length in bytes of the data; |
| pEncryptedData | points to the location that receives the encrypted data; |
| pulEncryptedDataLen | points to the location that holds the length in bytes of the encrypted 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.
C_Encrypt can not be used to terminate a multi-part operation, and must be called after C_EncryptInit without intervening C_EncryptUpdate calls.
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.
For most mechanisms, C_Encrypt is equivalent to a sequence of C_EncryptUpdate operations followed by C_EncryptFinal.
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.
| hSession | is the session's handle; |
| pPart | points to the data part; |
| ulPartLen | is the length of the data part; |
| pEncryptedPart | points to the location that receives the encrypted data part; |
| pulEncryptedPartLen | points to the location that holds the length in bytes of the encrypted 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.
CK_RV C_EncryptFinal( CK_SESSION_HANDLE hSession, CK_BYTE_PTR pLastEncryptedPart, CK_ULONG_PTR pulLastEncryptedPartLen);
C_EncryptFinal finishes a multiple-part encryption operation.
| hSession | is the session's handle; |
| pLastEncryptedPart | points to the location that receives the last encrypted data part, if any; |
| pulLastEncryptedPartLen | points to the location that holds the length of the last encrypted data part. |
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) { . . . } }