pkcs11 — archive

[Wan-Teh Chang]

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