Slides for my talk on PKCS #11 AEAD functions today

[Wan-Teh Chang <wtc@google.com>]

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