[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Preliminary draft proposal of PKCS #11 AEAD API
Hi, The attached file is a preliminary draft of proposed PKCS #11 AEAD functions, based on my meeting with Bob Relyea this Monday. It adds six new functions for performing authenticated encryption and decryption. * C_AEADEncryptInit * C_AEADEncrypt * C_AEADEncryptFinal * C_AEADDecryptInit * C_AEADDecrypt * C_AEADDecryptFinal Between the Init and Final calls, C_AEADEncrypt or C_AEADDecrypt can be called repeatedly to encrypt or decrypt multiple messages using the same key. Only single-part operations are supported. Bob Relyea and I are opposed to authenticated decryption functions that output unauthenticated plaintext. Multi-part authenticated decryption functions need to output unauthenticated plaintext unless the crypto module buffers it internally. I specified the CKM_AEAD_AES_GCM mechanism and its parameters as an example. I also specified two mechanisms for a crypto module to generate the GCM nonces during authenticated encryption, a la NIST SP-800-38D Sec. 8.2. Wan-Teh Chang
/* AES-GCM AEAD mechanism */
#define CKM_AEAD_AES_GCM 0x00000700
/* This mechanism parameters structure is not AES-specific. It can also be
* used by Camellia-GCM. */
typedef struct CK_AEAD_GCM_PARAMS {
CK_ULONG ulNonceLen;
CK_ULONG ulTagLen;
} CK_AEAD_GCM_PARAMS;
typedef CK_AEAD_GCM_PARAMS CK_PTR CK_AEAD_GCM_PARAMS_PTR;
/* Mechanisms for generating nonces during authenticated encryption */
/* For authenticated encryption, the nonce may be partially or fully generated
* by the crypto module. Therefore the source of the nonce needs to be
* specified.
*
* For authenticated 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;
/* AEAD Encryption and decryption */
/* C_AEADEncryptInit initializes an AEAD encryption operation. */
CK_PKCS11_FUNCTION_INFO(C_AEADEncryptInit)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* the session's handle */
CK_MECHANISM_PTR pMechanism, /* the AEAD encryption mechanism */
CK_OBJECT_HANDLE hKey, /* handle of AEAD encryption key */
CK_MECHANISM_PTR pNonceMech, /* 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. */
);
#endif
/* Multiple-part AEAD encryption operations are not supported. */
/* C_AEADEncrypt encrypts single-part data. Note that it does not finish
* the AEAD encryption operation. Additonal C_AEADEncrypt calls may be made
* on the session. */
CK_PKCS11_FUNCTION_INFO(C_AEADEncrypt)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* session's handle */
CK_BYTE_PTR pNonce, /* may be input or output, depending
* on the pNonceMech argument passed
* to C_AEADEncryptInit */
CK_ULONG ulNonceLen,
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
/* C_AEADEncryptFinal finishes an AEAD encryption operation. */
CK_PKCS11_FUNCTION_INFO(C_AEADEncryptFinal)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession /* the session's handle */
);
#endif
/* C_AEADDecryptInit initializes an AEAD decryption operation. */
CK_PKCS11_FUNCTION_INFO(C_AEADDecryptInit)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* the session's handle */
CK_MECHANISM_PTR pMechanism, /* the AEAD decryption mechanism */
CK_OBJECT_HANDLE hKey /* handle of AEAD decryption key */
);
#endif
/* Multiple-part AEAD encryption operations are not supported. */
/* 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_AEADDecrypt decrypts encrypted data in a single part. Note that it
* does not finish the AEAD decryption operation. Additonal C_AEADDecrypt
* calls may be made on the session. */
CK_PKCS11_FUNCTION_INFO(C_AEADDecrypt)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* session's handle */
CK_BYTE_PTR pNonce, /* input only */
CK_ULONG ulNonceLen,
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 p-text size */
);
#endif
/* C_AEADDecryptFinal finishes an AEAD decryption operation. */
CK_PKCS11_FUNCTION_INFO(C_AEADDecryptFinal)
#ifdef CK_NEED_ARG_LIST
(
CK_SESSION_HANDLE hSession, /* the session's handle */
);
#endif
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]