Created sequence diagrams for the PKCS #11 demos. (aws#2362)

They cover the following workflows:
* RNG
* Message Digest Creation
* Importing an object
* Generating a key pair

doc/lib/pkcs11.txt

@@ -15,8 +15,12 @@ This PKCS #11 library implements a subset of the PKCS #11 API required to establ
 
 @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.
+Currently, the PKCS #11 wrapper library has a dependency on:
+- FreeRTOS 
+- The C standard library stdint
+- PKCS #11. 
+
+Note: "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
@@ -78,12 +82,12 @@ digraph pkcs11_software_implementation_dependencies
 }
 @enddot
 
-@section PKCS11_utilities PKCS #11 Utilities
+@section PKCS11_utilities PKCS #11 Utilities Dependencies
 
 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
+- The standard C library
+- FreeRTOS
 
 @dot "PKCS #11 Utilities Dependencies"
 digraph pkcs11_utils_dependencies
@@ -107,9 +111,26 @@ digraph pkcs11_utils_dependencies
 }
 @enddot
 
-@constants_page{pkcs11}
-@constants_brief{PKCS #11 library}
-@section pkcs11_pal_constants PKCS #11 PAL File Names
+
+@page pkcs11_rng_seq PKCS #11 RNG Sequence Diagram
+@brief Sequence diagram illustrating how to generate random bytes from PKCS #11.
+@image html pkcs11_rng.png "PKCS #11 RNG Sequence" width=80%
+
+@page pkcs11_dig_seq PKCS #11 Digest Sequence Diagram
+@brief Sequence diagram illustrating how to create a message digest with PKCS #11.
+@image html pkcs11_digest.png "PKCS #11 Digest Sequence" width=80%
+
+@page pkcs11_obj_imp_seq PKCS #11 Object Import Sequence Diagram
+@brief Sequence diagram illustrating how to import an object with PKCS #11.
+@image html pkcs11_object_import.png "PKCS #11 Object Import Sequence" width=80%
+
+@page pkcs11_obj_gen_seq PKCS #11 Generate Key Pair Sequence Diagram
+@brief Sequence diagram illustrating how to generate a key pair with PKCS #11.
+@image html pkcs11_object_generate.png "PKCS #11 Generate Key Pair Sequence" width=80%
+
+@page pkcs11_sign_verify_seq PKCS #11 Sign and Verify Sequence Diagram
+@brief Sequence diagram illustrating how to sign a hash and verify a signature with PKCS #11.
+@image html pkcs11_sign_verify.png "PKCS #11 Sign and Verify Sequence" width=80%
 
 @constants_page{pkcs11}
 @constants_brief{PKCS #11 library constants}

doc/plantuml/pkcs11_digest.pu

@@ -0,0 +1,38 @@
+@startuml
+skinparam classFontSize 8
+skinparam classFontName Helvetica
+autonumber
+
+participant "Application" as app
+participant "PKCS #11" as pkcs
+
+box "PKCS #11 - Creating A Message Digest" #LightBlue
+    participant app
+    participant pkcs
+end box
+
+app -> pkcs: Acquire function list with C_GetFunctionList
+pkcs -> app: Return CK_FUNCTION_LIST_PTR with supported functions
+
+app -> pkcs: Initialize with C_Initialize
+
+app -> pkcs: Query for a slot with C_GetSlotList
+pkcs -> app: Return an array of CK_SLOT_IDs
+
+app -> pkcs: Open a new session with a slot using C_OpenSession
+pkcs -> app: Return a CK_SESSION_HANDLE
+
+app -> pkcs: Log in to current session with C_Login
+
+app -> pkcs: Query for supported mechanisms with C_GetMechanismInfo
+pkcs -> app: Return CK_MECHANISM_INFO
+
+app -> pkcs: Start a digest operation using SHA-256 by passing CKM_SHA256 to C_DigestInit 
+app -> pkcs: Pass bytes buffer of message to C_DigestUpdate
+app -> pkcs: Pass bytes buffer for storing the digest to C_DigestFinal
+pkcs -> app: Fill buffer with digest bytes
+
+app -> pkcs: Close session with C_CloseSession
+app -> pkcs: Uninitialize with C_Finalize
+
+@enduml

doc/plantuml/pkcs11_object_generate.pu

@@ -0,0 +1,33 @@
+@startuml
+skinparam classFontSize 8
+skinparam classFontName Helvetica
+autonumber
+
+participant "Application" as app
+participant "PKCS #11" as pkcs
+
+box "PKCS #11 - Generating A Key Pair" #LightBlue
+    participant app
+    participant pkcs
+end box
+
+app -> pkcs: Acquire function list with C_GetFunctionList
+pkcs -> app: Return CK_FUNCTION_LIST_PTR with supported functions
+
+app -> pkcs: Initialize with C_Initialize
+
+app -> pkcs: Query for a slot with C_GetSlotList
+pkcs -> app: Return an array of CK_SLOT_IDs
+
+app -> pkcs: Open a new session with a slot using C_OpenSession
+pkcs -> app: Return a CK_SESSION_HANDLE
+
+app -> pkcs: Log in to current session with C_Login
+
+app -> pkcs: Pass CK_ATTRIBUTEs template to C_CreateKeyPair
+pkcs -> app: Return CK_OBJECT_HANDLE for public key and for private key 
+
+app -> pkcs: Close session with C_CloseSession
+app -> pkcs: Uninitialize with C_Finalize
+
+@endumlf

doc/plantuml/pkcs11_object_import.pu

@@ -0,0 +1,33 @@
+@startuml
+skinparam classFontSize 8
+skinparam classFontName Helvetica
+autonumber
+
+participant "Application" as app
+participant "PKCS #11" as pkcs
+
+box "PKCS #11 - Importing A Crypto Object" #LightBlue
+    participant app
+    participant pkcs
+end box
+
+app -> pkcs: Acquire function list with C_GetFunctionList
+pkcs -> app: Return CK_FUNCTION_LIST_PTR with supported functions
+
+app -> pkcs: Initialize with C_Initialize
+
+app -> pkcs: Query for a slot with C_GetSlotList
+pkcs -> app: Return an array of CK_SLOT_IDs
+
+app -> pkcs: Open a new session with a slot using C_OpenSession
+pkcs -> app: Return a CK_SESSION_HANDLE
+
+app -> pkcs: Log in to current session with C_Login
+
+app -> pkcs: Pass Attribute template to C_CreateObject
+pkcs -> app: Return CK_OBJECT_HANDLE associated with the new object
+
+app -> pkcs: Close session with C_CloseSession
+app -> pkcs: Uninitialize with C_Finalize
+
+@enduml

doc/plantuml/pkcs11_rng.pu

@@ -0,0 +1,33 @@
+@startuml
+skinparam classFontSize 8
+skinparam classFontName Helvetica
+autonumber
+
+participant "Application" as app
+participant "PKCS #11" as pkcs
+
+box "PKCS #11 - Generating A Random Number" #LightBlue
+    participant app
+    participant pkcs
+end box
+
+app -> pkcs: Acquire function list with C_GetFunctionList
+pkcs -> app: Return CK_FUNCTION_LIST_PTR with supported functions
+
+app -> pkcs: Initialize with C_Initialize
+
+app -> pkcs: Query for a slot with C_GetSlotList
+pkcs -> app: Return an array of CK_SLOT_IDs
+
+app -> pkcs: Open a new session with a slot using C_OpenSession
+pkcs -> app: Return a CK_SESSION_HANDLE
+
+app -> pkcs: Log in to current session with C_Login
+
+app -> pkcs: Request an array of random bytes with C_GenerateRandom
+pkcs -> app: Return an array of random bytes
+
+app -> pkcs: Close session with C_CloseSession
+app -> pkcs: Uninitialize with C_Finalize
+
+@enduml

doc/plantuml/pkcs11_sign_verify.pu

@@ -0,0 +1,49 @@
+@startuml
+skinparam classFontSize 8
+skinparam classFontName Helvetica
+autonumber
+
+participant "Application" as app
+participant "PKCS #11" as pkcs
+
+box "PKCS #11 - Signing And Verifying A Signature" #LightBlue
+    participant app
+    participant pkcs
+end box
+
+app -> pkcs: Acquire function list with C_GetFunctionList
+pkcs -> app: Return CK_FUNCTION_LIST_PTR with supported functions
+
+app -> pkcs: Initialize with C_Initialize
+
+app -> pkcs: Query for a slot with C_GetSlotList
+pkcs -> app: Return an array of CK_SLOT_IDs
+
+app -> pkcs: Open a new session with a slot using C_OpenSession
+pkcs -> app: Return a CK_SESSION_HANDLE
+
+app -> pkcs: Log in to current session with C_Login
+
+app -> pkcs: Initiate a find operation by passing a CK_ATTRIBUTEs template to C_FindObjectsInit
+app -> pkcs: Request a CK_OBJECT_HANDLE
+pkcs -> app: Return CK_OBJECT_HANDLE for the appropriate object
+app -> pkcs: Clean up find operation with C_FindObjectsFinal
+
+app -> pkcs: Start a digest operation using SHA-256 by passing CKM_SHA256 C_DigestInit 
+app -> pkcs: Provide bytes buffer of message to hash with C_DigestUpdate
+app -> pkcs: Provide bytes buffer to store digest in with C_DigestFinal
+pkcs -> app: Fill buffer with digest bytes
+
+app -> pkcs: Start a sign operation by passing the signature mechanism and private key handle to C_SignInit 
+app -> pkcs: Provide bytes buffer of message hash and bytes buffer to store the signature to C_Sign
+pkcs -> app: Fill signature buffer with signature bytes of hash buffer
+
+app -> pkcs: Start a verify operation by passing the verify mechanism and public key handle to C_VerifyInit 
+app -> pkcs: Provide bytes buffer of message hash and bytes buffer of the signature to C_Verify
+pkcs -> app: Return OK if public key could verify signature
+
+app -> pkcs: Close session with C_CloseSession
+app -> pkcs: Uninitialize with C_Finalize
+
+@endumla
+