c_decrypt.h File Reference

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

Include dependency graph for c_decrypt.h:

Functions
CK_RV	C_Decrypt (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pEncryptedData, CK_ULONG ulEncryptedDataLen, CK_BYTE_PTR pData, CK_ULONG_PTR pulDataLen)
	Decrypts encrypted data in a single part.
CK_RV	C_DecryptFinal (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pLastPart, CK_ULONG_PTR pulLastPartLen)
	Finishes a multiple-part decryption operation.
CK_RV	C_DecryptInit (CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey)
	Initializes a decryption operation.
CK_RV	C_DecryptUpdate (CK_SESSION_HANDLE hSession, CK_BYTE_PTR pEncryptedPart, CK_ULONG ulEncryptedPartLen, CK_BYTE_PTR pPart, CK_ULONG_PTR pulPartLen)
	Continues a multiple-part decryption operation, processing another encrypted data part.

Function Documentation

C_Decrypt()

CK_RV C_Decrypt	(	CK_SESSION_HANDLE	hSession,
		CK_BYTE_PTR	pEncryptedData,
		CK_ULONG	ulEncryptedDataLen,
		CK_BYTE_PTR	pData,
		CK_ULONG_PTR	pulDataLen )

Decrypts encrypted data in a single part.

Parameters

[in]	hSession	is the session's handle.
[in]	pEncryptedData	points to the encrypted data.
[in]	ulEncryptedDataLen	is the length of the encrypted data.
[in,out]	pData	points to the location that receives the recovered data.
[in,out]	pulDataLen	points to the location that holds the length of the recovered data.

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

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

Returns

• CKR_OK on success.
• One of the following error codes on failure:
  CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_ENCRYPTED_DATA_INVALID, CKR_ENCRYPTED_DATA_LEN_RANGE, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

C_DecryptFinal()

CK_RV C_DecryptFinal	(	CK_SESSION_HANDLE	hSession,
		CK_BYTE_PTR	pLastPart,
		CK_ULONG_PTR	pulLastPartLen )

Finishes a multiple-part decryption operation.

Parameters

[in]	hSession	is the session's handle.
[out]	pLastPart	points to the location that receives the last recovered data part, if any.
[in,out]	pulLastPartLen	points to the location that holds the length of the last recovered data part.

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

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.

Returns

• CKR_OK on success.
• One of the following error codes on failure:
  CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_ENCRYPTED_DATA_INVALID, CKR_ENCRYPTED_DATA_LEN_RANGE, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

C_DecryptInit()

CK_RV C_DecryptInit	(	CK_SESSION_HANDLE	hSession,
		CK_MECHANISM_PTR	pMechanism,
		CK_OBJECT_HANDLE	hKey )

Initializes a decryption operation.

Parameters

[in]	hSession	is the session's handle.
[in]	pMechanism	points to the decryption mechanism.
[in]	hKey	is the handle of the decryption key.

The CKA_DECRYPT attribute of the decryption key, which indicates whether the key supports decryption, MUST be CK_TRUE.

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

Returns

• CKR_OK on success.
• One of the following error codes on failure:
  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_OPERATION_ACTIVE, CKR_PIN_EXPIRED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.

C_DecryptUpdate()

CK_RV C_DecryptUpdate	(	CK_SESSION_HANDLE	hSession,
		CK_BYTE_PTR	pEncryptedPart,
		CK_ULONG	ulEncryptedPartLen,
		CK_BYTE_PTR	pPart,
		CK_ULONG_PTR	pulPartLen )

Continues a multiple-part decryption operation, processing another encrypted data part.

Parameters

[in]	hSession	is the session's handle.
[in]	pEncryptedPart	points to the encrypted data part.
[in]	ulEncryptedPartLen	is the length of the encrypted data part.
[out]	pPart	points to the location that receives the recovered data part.
[in,out]	pulPartLen	points to the location that holds the length of the recovered data part.

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

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.

Returns

• CKR_OK on success.
• One of the following error codes on failure:
  CKR_ARGUMENTS_BAD, CKR_BUFFER_TOO_SMALL, CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY, CKR_DEVICE_REMOVED, CKR_ENCRYPTED_DATA_INVALID, CKR_ENCRYPTED_DATA_LEN_RANGE, CKR_FUNCTION_CANCELED, CKR_FUNCTION_FAILED, CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OPERATION_NOT_INITIALIZED, CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_USER_NOT_LOGGED_IN.