From 09993fd74331eae9c2e494a34976134536f72c0e Mon Sep 17 00:00:00 2001 From: Carl Lundin Date: Fri, 31 Jul 2020 14:31:00 -0700 Subject: [PATCH 1/4] PKCS #11 Doxygen Fix macros not being included in the doxygen. Add dependency graphs. Various formatting fixes --- doc/config/pkcs11 | 4 +- doc/lib/pkcs11.txt | 131 +++++++++++++++++- .../pkcs11/include/iot_pkcs11_pal.h | 3 + .../pkcs11/mbedtls/iot_pkcs11_mbedtls.c | 13 +- .../standard/pkcs11/include/iot_pkcs11.h | 46 ++++-- .../config_files/iot_pkcs11_config.h | 6 +- 6 files changed, 176 insertions(+), 27 deletions(-) diff --git a/doc/config/pkcs11 b/doc/config/pkcs11 index b1eb83648d0..4821e763940 100644 --- a/doc/config/pkcs11 +++ b/doc/config/pkcs11 @@ -3,8 +3,8 @@ @INCLUDE = common # Basic project information. -PROJECT_NAME = "PKCS11" -PROJECT_BRIEF = "PKCS11 Cryptoki Library" +PROJECT_NAME = "PKCS #11" +PROJECT_BRIEF = "PKCS #11 Cryptoki Library" # Library documentation output directory. HTML_OUTPUT = pkcs11 diff --git a/doc/lib/pkcs11.txt b/doc/lib/pkcs11.txt index 2770d91a68f..222f593256f 100644 --- a/doc/lib/pkcs11.txt +++ b/doc/lib/pkcs11.txt @@ -1,7 +1,7 @@ /** @mainpage @anchor pkcs11 -@brief PKCS #11 Crytpo Abstraction Library. +@brief PKCS #11 Crypto Abstraction Library. > PKCS #11 is a standard maintained by OASIS for interacting with cryptographic hardware. @@ -13,10 +13,108 @@ This PKCS #11 library implements a subset of the PKCS #11 API required to establ - Managing certificates and keys. - Generating random numbers. +@section PKCS11_Wrapper PKCS #11 Wrapper Dependencies + +Currently, the PKCS #11 wrapper library has a dependency on FreeRTOS, the C standard library stdint and PKCS #11. This file, "iot_pkcs11.h" should always be included first as it +defines the macros that are needed by the standard PKCS #11 header files. + +@dot "PKCS #11 wrapper direct dependencies" +digraph pkcs11_wrapper_dependencies +{ + node[shape=box, fontname=Helvetica, fontsize=10, style=filled]; + edge[fontname=Helvetica, fontsize=10]; + subgraph + { + pkcs11_wrapper[label="PKCS #11 Wrapper", fillcolor="#cc00ccff"]; + } + subgraph + { + node[fillcolor="#aed8a9ff"]; + rank = same; + pkcs11[label="PKCS #11"]; + freertos[label="FreeRTOS"]; + } + + pkcs11_wrapper -> pkcs11; + pkcs11_wrapper -> freertos; +} +@enddot + +@section PKCS11_implementation PKCS #11 Software Implementation Dependencies + +PKCS #11 is a flexible library, and can easily be swapped out for other implementations. The PKCS #11 library documented here +is a software based implementation, to allow for writing libraries and code that can easily interface with Hardware Security Modules (HSM). + +Currently, the software based PKCS #11 library has the following dependencies: +- The API defined by the PKCS #11 specification. The headers used can be found [here](https://github.com/amazon-freertos/pkcs11/tree/v2.40_errata01). +- The PKCS #11 PAL layer. This is used for writing PKCS #11 objects to flash. +- FreeRTOS. This library uses FreeRTOS primitives, like semaphores. +- mbed TLS. This library uses mbed TLS for the cryptographic logic. Some examples include parsing key and certificate objects, signing operations, and creating digests. +- The standard C library string, for memory manipulation. + +@dot "PKCS #11 implementation direct dependencies" +digraph pkcs11_software_implementation_dependencies +{ + node[shape=box, fontname=Helvetica, fontsize=10, style=filled]; + edge[fontname=Helvetica, fontsize=10]; + subgraph + { + pkcs11_software_implementation[label="PKCS #11 Software Implementation", fillcolor="#cc00ccff"]; + } + subgraph + { + node[fillcolor="#aed8a9ff"]; + rank = same; + pkcs11_wrapper[label="PKCS #11"]; + freertos[label="FreeRTOS"]; + mbedtls[label="mbed TLS"]; + pkcs11_pal[label="PKCS #11 PAL"]; + } + + pkcs11_software_implementation -> pkcs11_wrapper; + pkcs11_software_implementation -> freertos; + pkcs11_software_implementation -> mbedtls; + pkcs11_software_implementation -> pkcs11_pal; +} +@enddot + +@section PKCS11_utilities PKCS #11 Utilities + +The PKI utils module is a forked version of the PKI utilities provided by mbed TLS. They are used to convert from +Currently, the module has the following dependencies: +The standard C library +FreeRTOS + +@dot "PKCS #11 Utilities Dependencies" +digraph pkcs11_utils_dependencies +{ + node[shape=box, fontname=Helvetica, fontsize=10, style=filled]; + edge[fontname=Helvetica, fontsize=10]; + subgraph + { + pkcs11_utils[label="PKCS #11 Utilities", fillcolor="#cc00ccff"]; + } + subgraph + { + node[fillcolor="#aed8a9ff"]; + rank = same; + freertos[label="FreeRTOS"]; + stdlib[label="string.h"]; + } + + pkcs11_utils -> stdlib; + pkcs11_utils -> freertos; +} +@enddot + @constants_page{pkcs11} @constants_brief{PKCS #11 library} @section pkcs11_pal_constants PKCS #11 PAL File Names +@constants_page{pkcs11} +@constants_brief{PKCS #11 library constants} +@section pkcs11_pal_constants PKCS #11 PAL File Names + @brief Provide file name mappings for the TLS client certificate, and keys. This value can be modified to create custom .dat file names. @@ -44,19 +142,42 @@ as the solution, the application will fail to use them for it's TLS needs. @section pkcs11configMAX_LABEL_LENGTH @brief Max length of a PKCS #11 Label attribute -PKCS #11 uses labels to map human readable strings to a PKCS #11 object. This defines the maximum allowable length for such a string. +PKCS #11 uses labels to map human readable strings to a PKCS #11 object. This defines the maximum allowable length for such a string.
@configpossible Any positive integer.
@configdefault `32` @section pkcs11configMAX_NUM_OBJECTS -@brief Maximum number of token objects that can be stored by the PKCS #11 module. - -The maximum number of token objects that can be stored by the PKCS #11 module. +@brief Maximum number of token objects that can be stored by the PKCS #11 module.
@configpossible Any positive integer.
@configdefault `6` + +@section pkcs11configMAX_SESSIONS +@brief Maximum number of sessions that can be stored by the PKCS #11 module.
+The more sessions created, the higher RAM used by the PKCS #11 module.
+@configpossible Any positive integer.
+@configdefault 10 + +@section pkcs11testIMPORT_PRIVATE_KEY_SUPPORT +@brief Set to 1 if the PKCS #11 stack or device/hsm can load objects from an external source.
+ +@configpossible 0 or 1
+@configdefault `0` + +@section pkcs11testGENERATE_KEYPAIR_SUPPORT +@brief Set to 1 if the PKCS #11 stack or device/hsm can generate a key pair.
+@note The device should be able to store certificate onboard as well.
+ +@configpossible 0 or 1
+@configdefault `0` + +@section pkcs11testPREPROVISIONED_SUPPORT +@brief Set to 1 if the PKCS #11 stack or device/hsm is pre-provisioned with all objects necessary to connect to AWS IoT Core.
+@configpossible 0 or 1
+@configdefault `0` + @section pkcs11configPAL_DESTROY_SUPPORTED @brief Set to 1 if a PAL destroy object is implemented. diff --git a/libraries/abstractions/pkcs11/include/iot_pkcs11_pal.h b/libraries/abstractions/pkcs11/include/iot_pkcs11_pal.h index 2d6c489651c..871ca2897e6 100644 --- a/libraries/abstractions/pkcs11/include/iot_pkcs11_pal.h +++ b/libraries/abstractions/pkcs11/include/iot_pkcs11_pal.h @@ -56,6 +56,9 @@ */ /** + * @function_page{PKCS11_PAL_Initialize,pkcs11_pal,initialize} + * @function_snippet{pkcs11_pal,initialize,this} + * @copydoc PKCS11_PAL_Initialize * @function_page{PKCS11_PAL_SaveObject,pkcs11_pal,saveobject} * @function_snippet{pkcs11_pal,saveobject,this} * @copydoc PKCS11_PAL_SaveObject diff --git a/libraries/abstractions/pkcs11/mbedtls/iot_pkcs11_mbedtls.c b/libraries/abstractions/pkcs11/mbedtls/iot_pkcs11_mbedtls.c index 7eacd23db82..d5f44fc23dc 100644 --- a/libraries/abstractions/pkcs11/mbedtls/iot_pkcs11_mbedtls.c +++ b/libraries/abstractions/pkcs11/mbedtls/iot_pkcs11_mbedtls.c @@ -60,7 +60,17 @@ /*-----------------------------------------------------------*/ /** - * @brief Default EC operations to ON. + * @defgroup pkcs11_macros PKCS #11 Implementation Macros + * @brief Macros for PKCS #11 software implementation. + */ + +/** + * @defgroup pkcs11_datatypes PKCS #11 Datatypes + * @brief Internal datatypes for PKCS #11 software implementation. + */ + +/* @ingroup pkcs11_macros + * @brief Suppress EC operations. */ #ifndef pkcs11configSUPPRESS_ECDSA_MECHANISM #define pkcs11configSUPPRESS_ECDSA_MECHANISM 0 @@ -97,7 +107,6 @@ static const char * pNoLowLevelMbedTlsCodeStr = ""; /** * @ingroup pkcs11_macros * @brief Macro for logging in PKCS #11. - * */ #define PKCS11_PRINT( X ) configPRINTF( X ) diff --git a/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h b/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h index 5308e1f68ea..2a6cedde0b0 100644 --- a/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h +++ b/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h @@ -37,52 +37,67 @@ * @brief Wrapper functions for PKCS #11 */ +/** + * @defgroup pkcs11_wrapper_macros PKCS #11 Wrapper Macros + * @brief Macros defined by the PKCS #11 wrapper code. + */ + /** * @brief FreeRTOS PKCS#11 Interface. * The following definitions are required by the PKCS#11 standard public * headers. */ +/** + * @ingroup pkcs11_wrapper_macros + * @brief PKCS #11 pointer data type + */ #define CK_PTR * -#ifndef NULL_PTR - /** - * @brief Null in case null is not already defined. + * @ingroup pkcs11_wrapper_macros + * @brief PKCS #11 NULL pointer value */ +#ifndef NULL_PTR #define NULL_PTR 0 #endif /** + * @ingroup pkcs11_wrapper_macros * @brief CK_DEFINE_FUNCTION is deprecated. Implementations should use CK_DECLARE_FUNCTION * instead when possible. */ #define CK_DEFINE_FUNCTION( returnType, name ) returnType name /** + * @ingroup pkcs11_wrapper_macros * @brief Macro for defining a PKCS #11 functions. * */ #define CK_DECLARE_FUNCTION( returnType, name ) returnType name /** + * @ingroup pkcs11_wrapper_macros * @brief Macro for defining a PKCS #11 function pointers. * */ #define CK_DECLARE_FUNCTION_POINTER( returnType, name ) returnType( CK_PTR name ) /** + * @ingroup pkcs11_wrapper_macros * @brief Macro for defining a PKCS #11 callback functions. * */ #define CK_CALLBACK_FUNCTION( returnType, name ) returnType( CK_PTR name ) /** - * @brief Length of a SHA256 digest, in bytes. + * @ingroup pkcs11_wrapper_macros + * @brief Length of a SHA256 digest, in bytes. */ #define pkcs11SHA256_DIGEST_LENGTH 32UL /** + * @ingroup pkcs11_wrapper_macros * @brief 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. @@ -90,27 +105,32 @@ #define pkcs11ECDSA_P256_SIGNATURE_LENGTH 64UL /** + * @ingroup pkcs11_wrapper_macros * @brief Key strength for elliptic-curve P-256. */ #define pkcs11ECDSA_P256_KEY_BITS 256UL /** + * @ingroup pkcs11_wrapper_macros * @brief Public exponent for RSA. */ #define pkcs11RSA_PUBLIC_EXPONENT { 0x01, 0x00, 0x01 } /** + * @ingroup pkcs11_wrapper_macros * @brief The number of bits in the RSA-2048 modulus. * */ #define pkcs11RSA_2048_MODULUS_BITS 2048UL /** + * @ingroup pkcs11_wrapper_macros * @brief Length of PKCS #11 signature for RSA 2048 key, in bytes. */ #define pkcs11RSA_2048_SIGNATURE_LENGTH ( pkcs11RSA_2048_MODULUS_BITS / 8UL ) /** + * @ingroup pkcs11_wrapper_macros * @brief Length of RSA signature data before padding. * * This is calculated by adding the SHA-256 hash len (32) to the 19 bytes in @@ -119,32 +139,26 @@ #define pkcs11RSA_SIGNATURE_INPUT_LENGTH 51UL /** + * @ingroup pkcs11_wrapper_macros * @brief Elliptic-curve object identifiers. * From https://tools.ietf.org/html/rfc6637#section-11. */ #define pkcs11ELLIPTIC_CURVE_NISTP256 "1.2.840.10045.3.1.7" /** + * @ingroup pkcs11_wrapper_macros * @brief Maximum length of storage for PKCS #11 label, in bytes. */ #define pkcs11MAX_LABEL_LENGTH 32UL /* 31 characters + 1 null terminator. */ /** + * @ingroup pkcs11_wrapper_macros * @brief OID for curve P-256. */ #define pkcs11DER_ENCODED_OID_P256 { 0x06, 0x08, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x03, 0x01, 0x07 } - -/** - * @brief 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 - */ -#ifndef pkcs11configIMPORT_PRIVATE_KEYS_SUPPORTED - #define pkcs11configIMPORT_PRIVATE_KEYS_SUPPORTED 1 -#endif - /** + * @ingroup pkcs11_wrapper_macros * @brief RSA signature padding for interoperability between providing hashed messages * and providing hashed messages encoded with the digest information. * @@ -175,7 +189,9 @@ #include "pkcs11.h" -/** @brief Certificate Template +/** + * @ingroup pkcs11_datatypes + * @brief Certificate Template * The object class must be the first attribute in the array. */ typedef struct PKCS11_CertificateTemplate diff --git a/vendors/pc/boards/windows/aws_demos/config_files/iot_pkcs11_config.h b/vendors/pc/boards/windows/aws_demos/config_files/iot_pkcs11_config.h index 97337d7ea5b..3699a2648ae 100644 --- a/vendors/pc/boards/windows/aws_demos/config_files/iot_pkcs11_config.h +++ b/vendors/pc/boards/windows/aws_demos/config_files/iot_pkcs11_config.h @@ -24,13 +24,13 @@ */ /** - * @file aws_pkcs11_config.h + * @file iot_pkcs11_config.h * @brief PCKS#11 config options. */ -#ifndef _AWS_PKCS11_CONFIG_H_ -#define _AWS_PKCS11_CONFIG_H_ +#ifndef _IOT_PKCS11_CONFIG_H_ +#define _IOT_PKCS11_CONFIG_H_ /** * @brief PKCS #11 default user PIN. From 1c41e939e760345f5d73b071ec47621d96c2c811 Mon Sep 17 00:00:00 2001 From: Carl Lundin Date: Mon, 3 Aug 2020 10:19:37 -0700 Subject: [PATCH 2/4] Uncrustify. --- libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h b/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h index 2a6cedde0b0..8848eaa1131 100644 --- a/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h +++ b/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h @@ -177,7 +177,7 @@ * This is the DigestInfo sequence, digest algorithm, and the octet string/length * for the digest, without the actual digest itself. */ -#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 } +#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 } /* Bring in the public header. */ From db6a2117841b5f9b66273250de52a6c31629cca7 Mon Sep 17 00:00:00 2001 From: Carl Lundin Date: Mon, 3 Aug 2020 12:39:43 -0700 Subject: [PATCH 3/4] Rvert removing default provisioning scheme. --- .../freertos_plus/standard/pkcs11/include/iot_pkcs11.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h b/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h index 8848eaa1131..e11f50f47bd 100644 --- a/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h +++ b/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h @@ -157,6 +157,16 @@ */ #define pkcs11DER_ENCODED_OID_P256 { 0x06, 0x08, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x03, 0x01, 0x07 } + +/** + * @brief 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 + */ +#ifndef pkcs11configIMPORT_PRIVATE_KEYS_SUPPORTED + #define pkcs11configIMPORT_PRIVATE_KEYS_SUPPORTED 1 +#endif + /** * @ingroup pkcs11_wrapper_macros * @brief RSA signature padding for interoperability between providing hashed messages From 0ffcd627a2a05e1380fc919185aa7bf8d8d0c2f1 Mon Sep 17 00:00:00 2001 From: Carl Lundin Date: Mon, 3 Aug 2020 14:02:25 -0700 Subject: [PATCH 4/4] Uncrustify. --- libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h b/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h index e11f50f47bd..ea77e8de72f 100644 --- a/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h +++ b/libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h @@ -187,7 +187,7 @@ * This is the DigestInfo sequence, digest algorithm, and the octet string/length * for the digest, without the actual digest itself. */ -#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 } +#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 } /* Bring in the public header. */