PKCS #11 Doxygen (#2326)

* PKCS #11 Doxygen

Fix macros not being included in the doxygen. Add dependency graphs. Various formatting fixes

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

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.<br>
 
 @configpossible Any positive integer.<br>
 @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.<br>
 
 @configpossible Any positive integer.<br>
 @configdefault `6`
 
+
+@section pkcs11configMAX_SESSIONS                           
+@brief Maximum number of sessions that can be stored by the PKCS #11 module.<br>
+The more sessions created, the higher RAM used by the PKCS #11 module.<br>
+@configpossible Any positive integer.<br>
+@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.<br>
+
+@configpossible 0 or 1 <br>
+@configdefault `0`
+
+@section pkcs11testGENERATE_KEYPAIR_SUPPORT
+@brief Set to 1 if the PKCS #11 stack or device/hsm can generate a key pair.<br>
+@note The device should be able to store certificate onboard as well.<br>
+
+@configpossible 0 or 1 <br>
+@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.<br>
+@configpossible 0 or 1 <br>
+@configdefault `0`
+
 @section pkcs11configPAL_DESTROY_SUPPORTED
 @brief Set to 1 if a PAL destroy object is implemented.
 

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

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 = "<No-Low-Level-Code>";
 /**
  * @ingroup pkcs11_macros
  * @brief Macro for logging in PKCS #11.
- *
  */
 #define PKCS11_PRINT( X )            configPRINTF( X )
 

libraries/freertos_plus/standard/pkcs11/include/iot_pkcs11.h

@@ -37,80 +37,100 @@
  * @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.
  */
 #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,17 +139,20 @@
 #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 }
@@ -145,6 +168,7 @@
 #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 +199,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

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.