[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]