pkcs11 — archive

[Wan-Teh Chang]

Hi everyone, I attached the slides (PKCS11AEAD20140122.pdf) for my talk on PKCS #11 AEAD functions in the conference call today. I will refer to the slides during the talk. I also attached the preliminary proposal (pkcs11-aead-api.txt) that I sent to the mailing list on December 19, 2013. I read Mike's thoughtful comments yesterday. I didn't have time to make the changes he suggested, so the slides still describe the preliminary draft in pkcs11-aead-api.txt. 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 Attachment: PKCS11AEAD20140122.pdf Description: Adobe PDF document