[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: PKCS #11 encryption v2 API (formerly called AEAD API)
Hi, In the last conference call, I presented a preliminary proposal of PKCS #11 AEAD API. I met with Bob Relyea last week to go over the feedback from Michael (by email) and from others. Here is a second attempt at the API. We removed "AEAD" from the function names because they also apply to non-AEAD algorithms such as CTR mode. For lack of a better term, I refer to the new functions "encryption v2". Attached are a presentation (the PDF file) and the C types and functions (the .txt file) of the proposed PKCS #11 encryption v2 API. In short, we still kick off an encryption or decryption process using the existing C_EncryptInit or C_DecryptInit function. But each mechanism specifies whether it is old style or new style (v2). For a new-style (v2) mechanism, new V2 functions must be used to perform the encryption or decryption, and to finish (finalize) the encryption or decryption process. Wan-Teh Chang
#define CKM_AES_GCM_V2 0x00000700 /* AES-GCM mechanism for v2 encryption and
* decryption. Must not be used with
* multi-part v2 functions. */
/* This mechanism parameters structure is not AES-specific. It can also be
* used by Camellia-GCM. */
typedef struct CK_GCM_PARAMS_V2 {
CK_ULONG ulNonceLen;
CK_ULONG ulTagLen;
CK_MECHANISM_PTR pNonceMech; /* For encryption:
* - If NULL, the entire nonce is provided by
* the caller.
* - If not NULL, specifies how the nonce is
* generated partially or fully by the crypto
* module.
*
* For decryption: must be NULL and the entire
* nonce is provided by the caller. */
} CK_GCM_PARAMS_V2;
typedef CK_GCM_PARAMS_V2 CK_PTR CK_GCM_PARAMS_V2_PTR;
/* Mechanisms for generating nonces during encryption */
/* For encryption, the nonce may be partially or fully generated by the
* crypto module. Therefore the source of the nonce needs to be specified.
*
* For decryption, the caller always provides the entire nonce.
*/
#define CKM_GCM_NONCE_DETERMINISTIC 0x00000750
#define CKM_GCM_NONCE_RBG_BASED 0x00000751
/* CKM_GCM_NONCE_DETERMINISTIC */
/* NIST SP 800-38D, Sec. 8.2.1 Deterministic Construction.
* The fixed field is on the left, the invocation field is on the right.
* The caller provides the fixed field. The crypto module generates and
* outputs the invocation field.
*/
typedef struct CK_GCM_NONCE_DETERMINISTIC_PARAMS {
CK_BYTE_PTR pFixed; /* the fixed field */
CK_ULONG ulFixedLen;
} CK_GCM_NONCE_DETERMINISTIC_PARAMS;
/* CKM_GCM_NONCE_RBG_BASED */
/* NIST SP 800-38D, Sec. 8.2.2 RBG-based Construction.
* The random field is on the left, the free field is on the right.
* The caller provides the free field. The crypto module generates and
* outputs the random field. The free field is recommended to be empty
*/
typedef struct CK_GCM_NONCE_RBG_BASED_PARAMS {
CK_BYTE_PTR pFree; /* the free field */
CK_ULONG ulFreeLen;
} CK_GCM_NONCE_RBG_BASED_PARAMS;
/* Encryption and decryption v2 */
/* The existing C_EncryptInit function is used to initialize a v2 encryption
* operation. */
CK_PKCS11_FUNCTION_INFO(C_EncryptInit)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* the session's handle */
CK_MECHANISM_PTR pMechanism, /* the encryption mechanism */
CK_OBJECT_HANDLE hKey, /* handle of encryption key */
);
#endif
/* Single-part v2 encryption. */
/* C_EncryptV2 encrypts single-part data. Note that it does not finish
* the v2 encryption operation. Additonal C_EncryptV2* calls may be made
* on the session. */
CK_PKCS11_FUNCTION_INFO(C_EncryptV2)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* session's handle */
CK_VOID_PTR pPerMessageParam, /* may be input or output, depending
* on the pMechanism argument passed
* to C_EncryptInit */
CK_ULONG ulPerMessageParamLen,
CK_BYTE_PTR pAssociatedData, /* the associated data */
CK_ULONG ulAssociatedDataLen, /* bytes of associated data */
CK_BYTE_PTR pData, /* the plaintext data */
CK_ULONG ulDataLen, /* bytes of plaintext */
CK_BYTE_PTR pEncryptedData, /* gets ciphertext */
CK_ULONG_PTR pulEncryptedDataLen /* gets c-text size */
);
#endif
/* Multiple-part v2 encryption functions. */
/* C_EncryptV2Begin begins a multi-part v2 encryption. */
CK_PKCS11_FUNCTION_INFO(C_EncryptV2Begin)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* the session's handle */
CK_VOID_PTR pPerMessageParam, /* may be input or output, depending
* on the pMechanism argument passed
* to C_EncryptInit */
CK_ULONG ulPerMessageParamLen,
CK_BYTE_PTR pAssociatedData, /* the associated data */
CK_ULONG ulAssociatedDataLen, /* bytes of associated data */
);
#endif
/* C_EncryptV2Update continues a multiple-part v2 encryption. */
CK_PKCS11_FUNCTION_INFO(C_EncryptV2Update)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* session's handle */
CK_BYTE_PTR pPart, /* the plaintext data */
CK_ULONG ulPartLen, /* plaintext data len */
CK_BYTE_PTR pEncryptedPart, /* gets ciphertext */
CK_ULONG_PTR pulEncryptedPartLen /* gets c-text size */
);
#endif
/* C_EncryptV2End ends a v2 multiple-part encryption. */
CK_PKCS11_FUNCTION_INFO(C_EncryptV2End)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* session handle */
CK_BYTE_PTR pLastEncryptedPart, /* last c-text */
CK_ULONG_PTR pulLastEncryptedPartLen /* gets last size */
);
#endif
/* C_EncryptV2Final finishes a v2 encryption operation. */
CK_PKCS11_FUNCTION_INFO(C_EncryptV2Final)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession /* the session's handle */
);
#endif
/* The existing C_DecryptInit function is used to initialize a v2 decryption
* operation. */
CK_PKCS11_FUNCTION_INFO(C_DecryptInit)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* the session's handle */
CK_MECHANISM_PTR pMechanism, /* the decryption mechanism */
CK_OBJECT_HANDLE hKey /* handle of decryption key */
);
#endif
/* Error code for AEAD decryption failure, which means the inputs are
* not authentic.
*
* Alternatively, we can just use the existing error code
* CKR_ENCRYPTED_DATA_INVALID (0x00000040) for this purpose. */
#define CKR_AEAD_DECRYPT_FAILED 0x00000042
/* C_DecryptV2 decrypts encrypted data in a single part. Note that it
* does not finish the v2 decryption operation. Additonal C_DecryptV2*
* calls may be made on the session. */
CK_PKCS11_FUNCTION_INFO(C_DecryptV2)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* session's handle */
CK_VOID_PTR pPerMessageParam, /* input only */
CK_ULONG ulPerMessageParamLen,
CK_BYTE_PTR pAssociatedData, /* the associated data */
CK_ULONG ulAssociatedDataLen, /* bytes of associated data */
CK_BYTE_PTR pEncryptedData, /* ciphertext */
CK_ULONG ulEncryptedDataLen, /* ciphertext length */
CK_BYTE_PTR pData, /* gets plaintext */
CK_ULONG_PTR pulDataLen /* gets plaintext size */
);
#endif
/* Multiple-part v2 decryption functions. */
/* C_DecryptV2Begin begins a multi-part v2 decryption. */
CK_PKCS11_FUNCTION_INFO(C_DecryptV2Begin)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* the session's handle */
CK_VOID_PTR pPerMessageParam, /* input only */
CK_ULONG ulPerMessageParamLen,
CK_BYTE_PTR pAssociatedData, /* the associated data */
CK_ULONG ulAssociatedDataLen, /* bytes of associated data */
);
#endif
/* C_DecryptV2Update continues a multiple-part v2 decryption. */
CK_PKCS11_FUNCTION_INFO(C_DecryptV2Update)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* session's handle */
CK_BYTE_PTR pEncryptedPart, /* encrypted data */
CK_ULONG ulEncryptedPartLen, /* input length */
CK_BYTE_PTR pPart, /* gets plaintext */
CK_ULONG_PTR pulPartLen /* plaintext size */
);
#endif
/* C_DecryptV2End ends a multiple-part v2 decryption. */
CK_PKCS11_FUNCTION_INFO(C_DecryptV2End)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* the session's handle */
CK_BYTE_PTR pLastPart, /* gets plaintext */
CK_ULONG_PTR pulLastPartLen /* plaintext size */
);
#endif
/* C_DecryptV2Final finishes a v2 decryption operation. */
CK_PKCS11_FUNCTION_INFO(C_DecryptV2Final)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* the session's handle */
);
#endif
Attachment:
PKCS11EncryptionV2-20140205.pdf
Description: Adobe PDF document
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]