Wrapper functions for PKCS #11. More...

#include <stdint.h>
#include "pkcs11.h"

Include dependency graph for core_pkcs11.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	PKCS11_CertificateTemplate_t
	Certificate Template The object class must be the first attribute in the array. More...

Macros
#define	CK_PTR *
	corePKCS11 Interface. The following definitions are required by the PKCS#11 standard public headers. More...

#define	NULL_PTR 0
	PKCS #11 NULL pointer value.

#define	CK_DEFINE_FUNCTION(returnType, name) returnType name
	CK_DEFINE_FUNCTION is deprecated. Implementations should use CK_DECLARE_FUNCTION instead when possible.

#define	CK_DECLARE_FUNCTION(returnType, name) returnType name
	Macro for defining a PKCS #11 functions.

#define	CK_DECLARE_FUNCTION_POINTER(returnType, name) returnType( CK_PTR name )
	Macro for defining a PKCS #11 function pointers.

#define	CK_CALLBACK_FUNCTION(returnType, name) returnType( CK_PTR name )
	Macro for defining a PKCS #11 callback functions.

#define	pkcs11SHA256_DIGEST_LENGTH 32UL
	Length of a SHA256 digest, in bytes.

#define	pkcs11AES_CMAC_SIGNATURE_LENGTH 16UL
	Length of a CMAC signature, in bytes.

#define	pkcs11ECDSA_P256_SIGNATURE_LENGTH 64UL
	Length of a curve P-256 ECDSA signature, in bytes. PKCS #11 EC signatures are represented as a 32-bit R followed by a 32-bit S value, and not ASN.1 encoded.

#define	pkcs11ECDSA_P256_KEY_BITS 256UL
	Key strength for elliptic-curve P-256.

#define	pkcs11RSA_PUBLIC_EXPONENT { 0x01, 0x00, 0x01 }
	Public exponent for RSA.

#define	pkcs11RSA_2048_MODULUS_BITS 2048UL
	The number of bits in the RSA-2048 modulus.

#define	pkcs11RSA_2048_SIGNATURE_LENGTH ( pkcs11RSA_2048_MODULUS_BITS / 8UL )
	Length of PKCS #11 signature for RSA 2048 key, in bytes.

#define	pkcs11RSA_SIGNATURE_INPUT_LENGTH 51UL
	Length of RSA signature data before padding. More...

#define	pkcs11ELLIPTIC_CURVE_NISTP256 "1.2.840.10045.3.1.7"
	Elliptic-curve object identifiers. From https://tools.ietf.org/html/rfc6637#section-11.

#define	pkcs11MAX_LABEL_LENGTH 32UL /* 31 characters + 1 null terminator. */
	Maximum length of storage for PKCS #11 label, in bytes.

#define	pkcs11DER_ENCODED_OID_P256 { 0x06, 0x08, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x03, 0x01, 0x07 }
	OID for curve P-256.

#define	pkcs11configIMPORT_PRIVATE_KEYS_SUPPORTED 1
	Set to 1 if importing private keys is supported. More...

#define	pkcs11STUFF_APPENDED_TO_RSA_SIG { 0x30, 0x31, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x05, 0x00, 0x04, 0x20 }
	RSA signature padding for interoperability between providing hashed messages and providing hashed messages encoded with the digest information. More...

Functions
CK_RV	xInitializePKCS11 (void)
	Initializes a PKCS #11 session. More...

CK_RV	xGetSlotList (CK_SLOT_ID *ppxSlotId, CK_ULONG pxSlotCount)
	Get a list of available PKCS #11 slots. More...

CK_RV	xInitializePkcs11Session (CK_SESSION_HANDLE *pxSession)
	Initializes the PKCS #11 module and opens a session. More...

CK_RV	xInitializePkcs11Token (void)
	Initializes a PKCS #11 module and token. More...

CK_RV	xFindObjectWithLabelAndClass (CK_SESSION_HANDLE xSession, char *pcLabelName, CK_ULONG ulLabelNameLen, CK_OBJECT_CLASS xClass, CK_OBJECT_HANDLE_PTR pxHandle)
	Searches for an object with a matching label and class provided. More...

CK_RV	vAppendSHA256AlgorithmIdentifierSequence (const uint8_t puc32ByteHashedMessage, uint8_t puc51ByteHashOidBuffer)
	Appends digest algorithm sequence to SHA-256 hash for RSA signatures. More...

Detailed Description

Wrapper functions for PKCS #11.

Macro Definition Documentation

◆ CK_PTR

#define CK_PTR *

corePKCS11 Interface. The following definitions are required by the PKCS#11 standard public headers.

PKCS #11 pointer data type

◆ pkcs11RSA_SIGNATURE_INPUT_LENGTH

#define pkcs11RSA_SIGNATURE_INPUT_LENGTH 51UL

Length of RSA signature data before padding.

This is calculated by adding the SHA-256 hash len (32) to the 19 bytes in pkcs11STUFF_APPENDED_TO_RSA_SIG = 51 bytes total.

◆ pkcs11configIMPORT_PRIVATE_KEYS_SUPPORTED

#define pkcs11configIMPORT_PRIVATE_KEYS_SUPPORTED 1

Set to 1 if importing private keys is supported.

If private key import is not supported, this value should be defined 0 in aws_pkcs11_config.h

◆ pkcs11STUFF_APPENDED_TO_RSA_SIG

#define pkcs11STUFF_APPENDED_TO_RSA_SIG { 0x30, 0x31, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x05, 0x00, 0x04, 0x20 }

RSA signature padding for interoperability between providing hashed messages and providing hashed messages encoded with the digest information.

The TLS connection for mbedTLS expects a hashed, but unpadded input, and it appended message digest algorithm encoding. However, the PKCS #11 sign function either wants unhashed data which it will both hash and pad OR as done in this workaround, we provide hashed data with padding appended.

DigestInfo :: = SEQUENCE{ digestAlgorithm DigestAlgorithmIdentifier, digest Digest }

DigestAlgorithmIdentifier :: = AlgorithmIdentifier Digest :: = OCTET STRING

This is the DigestInfo sequence, digest algorithm, and the octet string/length for the digest, without the actual digest itself.

Function Documentation

◆ xInitializePKCS11()

CK_RV xInitializePKCS11 ( void )

Initializes a PKCS #11 session.

Returns: CKR_OK if successful.

◆ xGetSlotList()

CK_RV xGetSlotList	(	CK_SLOT_ID **	ppxSlotId,
		CK_ULONG *	pxSlotCount
	)

Get a list of available PKCS #11 slots.

Note: This function allocates memory for slots. Freeing this memory is the responsibility of the caller.

Parameters

[out]	ppxSlotId	Pointer to slot list. This slot list is malloc'ed by the function and must be freed by the caller.
[out]	pxSlotCount	Pointer to the number of slots found.

Returns: CKR_OK or PKCS #11 error code. (PKCS #11 error codes are positive).

◆ xInitializePkcs11Session()

CK_RV xInitializePkcs11Session ( CK_SESSION_HANDLE * pxSession )

Initializes the PKCS #11 module and opens a session.

Parameters

[out] pxSession Pointer to the PKCS #11 session handle that is created by this function.

Returns: CKR_OK upon success. PKCS #11 error code on failure. Note that PKCS #11 error codes are positive.

◆ xInitializePkcs11Token()

CK_RV xInitializePkcs11Token ( void )

Initializes a PKCS #11 module and token.

Returns: CKR_OK upon success. PKCS #11 error code on failure. Note that PKCS #11 error codes are positive.

◆ xFindObjectWithLabelAndClass()

CK_RV xFindObjectWithLabelAndClass	(	CK_SESSION_HANDLE	xSession,
		char *	pcLabelName,
		CK_ULONG	ulLabelNameLen,
		CK_OBJECT_CLASS	xClass,
		CK_OBJECT_HANDLE_PTR	pxHandle
	)

Searches for an object with a matching label and class provided.

Parameters

[in]	xSession	An open PKCS #11 session.
[in]	pcLabelName	A pointer to the object's label (CKA_LABEL).
[in]	ulLabelNameLen	The size (in bytes) of pcLabelName.
[in]	xClass	The class (CKA_CLASS) of the object. ex: CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, CKO_CERTIFICATE
[out]	pxHandle	Pointer to the location where the handle of the found object should be placed.

Note: If no matching object is found, pxHandle will point to an object with handle 0 (Invalid Object Handle).; This function assumes that there is only one object that meets the CLASS/LABEL criteria.

◆ vAppendSHA256AlgorithmIdentifierSequence()

CK_RV vAppendSHA256AlgorithmIdentifierSequence	(	const uint8_t *	puc32ByteHashedMessage,
		uint8_t *	puc51ByteHashOidBuffer
	)

Appends digest algorithm sequence to SHA-256 hash for RSA signatures.

This function pre-appends the digest algorithm identifier to the SHA-256 hash of a message.

DigestInfo :: = SEQUENCE{ digestAlgorithm DigestAlgorithmIdentifier, digest Digest }

Parameters

[in]	puc32ByteHashedMessage	A 32-byte buffer containing the SHA-256 hash of the data to be signed.
[out]	puc51ByteHashOidBuffer	A 51-byte output buffer containing the DigestInfo structure. This memory must be allocated by the caller.

Returns: CKR_OK if successful, CKR_ARGUMENTS_BAD if NULL pointer passed in.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ CK_PTR

◆ pkcs11RSA_SIGNATURE_INPUT_LENGTH

◆ pkcs11configIMPORT_PRIVATE_KEYS_SUPPORTED

◆ pkcs11STUFF_APPENDED_TO_RSA_SIG

Function Documentation

◆ xInitializePKCS11()

◆ xGetSlotList()

◆ xInitializePkcs11Session()

◆ xInitializePkcs11Token()

◆ xFindObjectWithLabelAndClass()

◆ vAppendSHA256AlgorithmIdentifierSequence()