426 lines
16 KiB
Plaintext
426 lines
16 KiB
Plaintext
/**
|
|
@mainpage Overview
|
|
@anchor core_pkcs11
|
|
@brief PKCS #11 Crypto Abstraction Library.
|
|
|
|
> PKCS #11 is a standard maintained by OASIS for interacting with cryptographic hardware.
|
|
|
|
<span style="float:right;margin-right:4em"> — <i>Official documentation of PKCS #11 from [oasis](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html)</i></span><br>
|
|
|
|
This corePKCS11 library implements a subset of the PKCS #11 API required to establish a secure connection to AWS IoT:
|
|
- Verifying the signature of the contents of a message.
|
|
- Signing a message.
|
|
- Managing certificates and keys.
|
|
- Generating random numbers.
|
|
|
|
@section pkcs11_memory_requirements Memory Requirements
|
|
@brief Memory requirements of the PKCS #11 library.
|
|
|
|
@include{doc} size_table.md
|
|
*/
|
|
|
|
/**
|
|
@page pkcs11_design Design
|
|
@section PKCS11_Wrapper Dependencies of the corePKCS11 Wrapper for the PKCS #11 standard
|
|
Currently, the corePKCS11 library provides a wrapper header around the [PKCS #11 standard](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html). It has dependencies on:
|
|
- `stdint.h` from the C standard library
|
|
- PKCS #11 standard.
|
|
|
|
Note: "core_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"];
|
|
}
|
|
|
|
pkcs11_wrapper -> pkcs11;
|
|
}
|
|
@enddot
|
|
|
|
@section PKCS11_implementation corePKCS11 Software Implementation Dependencies
|
|
|
|
The corePKCS11 library provides one implementation of the PKCS #11 standard, and it can easily be swapped out for other implementations. The corePKCS11 library documented here
|
|
is a software based implementation of the PKCS #11 standard, to allow for writing libraries and code that can easily interface with Hardware Security Modules (HSM).
|
|
|
|
Currently, the software based corePKCS11 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.
|
|
- [Mbed TLS](https://github.com/ARMmbed/mbedtls/tree/v2.26.0). 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.h`, 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"];
|
|
mbedtls[label="Mbed TLS"];
|
|
pkcs11_pal[label="PKCS #11 PAL"];
|
|
}
|
|
|
|
pkcs11_software_implementation -> pkcs11_wrapper;
|
|
pkcs11_software_implementation -> mbedtls;
|
|
pkcs11_software_implementation -> pkcs11_pal;
|
|
}
|
|
@enddot
|
|
|
|
@section PKCS11_utilities corePKCS11 Utilities Dependencies
|
|
|
|
The PKI utils module is a forked version of the PKI utilities provided by Mbed TLS. They provide helper utilities to convert the format of ECDSA P-256 signatures.
|
|
The conversions provided are:
|
|
- DER format to PKCS #11 format.
|
|
- PKCS #11 format to ASN.1 format.
|
|
|
|
Currently, the module has a dependency only on the C standard library.
|
|
|
|
@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;
|
|
stdlib[label="string.h"];
|
|
}
|
|
|
|
pkcs11_utils -> stdlib;
|
|
}
|
|
@enddot
|
|
*/
|
|
|
|
/**
|
|
@page pkcs11_seq PKCS #11 Sequence Diagrams
|
|
@brief The following are sequence diagrams for common PKCS #11 operations.
|
|
|
|
@subpage pkcs11_rng_seq <br>
|
|
@subpage pkcs11_dig_seq <br>
|
|
@subpage pkcs11_obj_imp_seq <br>
|
|
@subpage pkcs11_obj_gen_seq <br>
|
|
@subpage pkcs11_sign_verify_seq <br>
|
|
|
|
@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=50%
|
|
|
|
@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=50%
|
|
|
|
@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=50%
|
|
|
|
@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=50%
|
|
|
|
@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=50%
|
|
*/
|
|
|
|
/**
|
|
@page pkcs11_config PKCS #11 Configuration Macros
|
|
@brief These are the configuration macros used by the corePKCS11 Library.
|
|
|
|
@section pkcs11configPKCS11_MALLOC
|
|
@copydoc pkcs11configPKCS11_MALLOC
|
|
|
|
@section pkcs11configPKCS11_FREE
|
|
@copydoc pkcs11configPKCS11_FREE
|
|
|
|
@section pkcs11configPKCS11_DEFAULT_USER_PIN
|
|
@copydoc pkcs11configPKCS11_DEFAULT_USER_PIN
|
|
|
|
@section pkcs11configMAX_LABEL_LENGTH
|
|
@copydoc pkcs11configMAX_LABEL_LENGTH
|
|
|
|
@section pkcs11configMAX_NUM_OBJECTS
|
|
@copydoc pkcs11configMAX_NUM_OBJECTS
|
|
|
|
@section pkcs11configMAX_SESSIONS
|
|
@copydoc pkcs11configMAX_SESSIONS
|
|
|
|
@section pkcs11configPAL_DESTROY_SUPPORTED
|
|
@copydoc pkcs11configPAL_DESTROY_SUPPORTED
|
|
|
|
@section pkcs11configOTA_SUPPORTED
|
|
@copydoc pkcs11configOTA_SUPPORTED
|
|
|
|
@section pkcs11configJITP_CODEVERIFY_ROOT_CERT_SUPPORTED
|
|
@copydoc pkcs11configJITP_CODEVERIFY_ROOT_CERT_SUPPORTED
|
|
|
|
@section pkcs11configLABEL_DEVICE_PRIVATE_KEY_FOR_TLS
|
|
@copydoc pkcs11configLABEL_DEVICE_PRIVATE_KEY_FOR_TLS
|
|
|
|
@section pkcs11configLABEL_DEVICE_PUBLIC_KEY_FOR_TLS
|
|
@copydoc pkcs11configLABEL_DEVICE_PUBLIC_KEY_FOR_TLS
|
|
|
|
@section pkcs11configLABEL_DEVICE_CERTIFICATE_FOR_TLS
|
|
@copydoc pkcs11configLABEL_DEVICE_CERTIFICATE_FOR_TLS
|
|
|
|
@section pkcs11configLABEL_ROOT_CERTIFICATE
|
|
@copydoc pkcs11configLABEL_ROOT_CERTIFICATE
|
|
|
|
@section pkcs11configLABEL_HMAC_KEY
|
|
@copydoc pkcs11configLABEL_HMAC_KEY
|
|
|
|
@section pkcs11configLABEL_CMAC_KEY
|
|
@copydoc pkcs11configLABEL_CMAC_KEY
|
|
|
|
@section pkcs11configLABEL_CODE_VERIFICATION_KEY
|
|
@copydoc pkcs11configLABEL_CODE_VERIFICATION_KEY
|
|
|
|
@section pkcs11configLABEL_JITP_CERTIFICATE
|
|
@copydoc pkcs11configLABEL_JITP_CERTIFICATE
|
|
|
|
@section LogError
|
|
@copydoc LogError
|
|
|
|
@section LogWarn
|
|
@copydoc LogWarn
|
|
|
|
@section LogInfo
|
|
@copydoc LogInfo
|
|
|
|
@section LogDebug
|
|
@copydoc LogDebug
|
|
|
|
*/
|
|
|
|
/**
|
|
@page pkcs11_core_mbedtls_function PKCS #11 Mbed TLS Implementation Functions
|
|
@brief Primary functions of the PKCS #11 Mbed TLS based Implementation Library:<br><br>
|
|
@subpage pkcs11_mbedtls_function_c_initialize <br>
|
|
@subpage pkcs11_mbedtls_function_c_finalize <br>
|
|
@subpage pkcs11_mbedtls_function_c_getfunctionlist <br>
|
|
@subpage pkcs11_mbedtls_function_c_getslotlist <br>
|
|
@subpage pkcs11_mbedtls_function_c_gettokeninfo <br>
|
|
@subpage pkcs11_mbedtls_function_c_getmechanisminfo <br>
|
|
@subpage pkcs11_mbedtls_function_c_inittoken <br>
|
|
@subpage pkcs11_mbedtls_function_c_opensession <br>
|
|
@subpage pkcs11_mbedtls_function_c_closesession <br>
|
|
@subpage pkcs11_mbedtls_function_c_login <br>
|
|
@subpage pkcs11_mbedtls_function_c_createobject <br>
|
|
@subpage pkcs11_mbedtls_function_c_destroyobject <br>
|
|
@subpage pkcs11_mbedtls_function_c_getattributevalue <br>
|
|
@subpage pkcs11_mbedtls_function_c_findobjectsinit <br>
|
|
@subpage pkcs11_mbedtls_function_c_findobjects <br>
|
|
@subpage pkcs11_mbedtls_function_c_findobjectsfinal <br>
|
|
@subpage pkcs11_mbedtls_function_c_digestinit <br>
|
|
@subpage pkcs11_mbedtls_function_c_digestupdate <br>
|
|
@subpage pkcs11_mbedtls_function_c_digestfinal <br>
|
|
@subpage pkcs11_mbedtls_function_c_signinit <br>
|
|
@subpage pkcs11_mbedtls_function_c_verifyinit <br>
|
|
@subpage pkcs11_mbedtls_function_c_verify <br>
|
|
@subpage pkcs11_mbedtls_function_c_generatekeypair <br>
|
|
@subpage pkcs11_mbedtls_function_c_generate_random <br>
|
|
|
|
@page pkcs11_mbedtls_function_c_initialize C_Initialize
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_initialize
|
|
@copydoc C_Initialize
|
|
|
|
@page pkcs11_mbedtls_function_c_finalize C_Finalize
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_finalize
|
|
@copydoc C_Finalize
|
|
|
|
@page pkcs11_mbedtls_function_c_getfunctionlist C_GetFunctionList
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_getfunctionlist
|
|
@copydoc C_GetFunctionList
|
|
|
|
@page pkcs11_mbedtls_function_c_getslotlist C_GetSlotList
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_getslotlist
|
|
@copydoc C_GetSlotList
|
|
|
|
@page pkcs11_mbedtls_function_c_gettokeninfo C_GetTokenInfo
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_gettokeninfo
|
|
@copydoc C_GetTokenInfo
|
|
|
|
@page pkcs11_mbedtls_function_c_getmechanisminfo C_GetMechanismInfo
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_getmechanisminfo
|
|
@copydoc C_GetMechanismInfo
|
|
|
|
@page pkcs11_mbedtls_function_c_inittoken C_InitToken
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_inittoken
|
|
@copydoc C_InitToken
|
|
|
|
@page pkcs11_mbedtls_function_c_opensession C_OpenSession
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_opensession
|
|
@copydoc C_OpenSession
|
|
|
|
@page pkcs11_mbedtls_function_c_closesession C_CloseSession
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_closesession
|
|
@copydoc C_CloseSession
|
|
|
|
@page pkcs11_mbedtls_function_c_login C_Login
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_login
|
|
@copydoc C_Login
|
|
|
|
@page pkcs11_mbedtls_function_c_createobject C_CreateObject
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_createobject
|
|
@copydoc C_CreateObject
|
|
|
|
@page pkcs11_mbedtls_function_c_destroyobject C_DestroyObject
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_destroyobject
|
|
@copydoc C_DestroyObject
|
|
|
|
@page pkcs11_mbedtls_function_c_getattributevalue C_GetAttributeValue
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_getattributevalue
|
|
@copydoc C_GetAttributeValue
|
|
|
|
@page pkcs11_mbedtls_function_c_findobjectsinit C_FindObjectsInit
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_findobjectsinit
|
|
@copydoc C_FindObjectsInit
|
|
|
|
@page pkcs11_mbedtls_function_c_findobjects C_FindObjects
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_findobjects
|
|
@copydoc C_FindObjects
|
|
|
|
@page pkcs11_mbedtls_function_c_findobjectsfinal C_FindObjectsFinal
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_findobjectsfinal
|
|
@copydoc C_FindObjectsFinal
|
|
|
|
@page pkcs11_mbedtls_function_c_digestinit C_DigestInit
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_digestinit
|
|
@copydoc C_DigestInit
|
|
|
|
@page pkcs11_mbedtls_function_c_digestupdate C_DigestUpdate
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_digestupdate
|
|
@copydoc C_DigestUpdate
|
|
|
|
@page pkcs11_mbedtls_function_c_digestfinal C_DigestFinal
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_digestfinal
|
|
@copydoc C_DigestFinal
|
|
|
|
@page pkcs11_mbedtls_function_c_signinit C_SignInit
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_signinit
|
|
@copydoc C_SignInit
|
|
|
|
@page pkcs11_mbedtls_function_c_verifyinit C_VerifyInit
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_verifyinit
|
|
@copydoc C_VerifyInit
|
|
|
|
@page pkcs11_mbedtls_function_c_verify C_Verify
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_verify
|
|
@copydoc C_Verify
|
|
|
|
@page pkcs11_mbedtls_function_c_generatekeypair C_GenerateKeyPair
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_generatekeypair
|
|
@copydoc C_GenerateKeyPair
|
|
|
|
@page pkcs11_mbedtls_function_c_generate_random C_GenerateRandom
|
|
@snippet core_pkcs11_mbedtls.c declare_pkcs11_mbedtls_c_generate_random
|
|
@copydoc C_GenerateRandom
|
|
|
|
*/
|
|
|
|
/**
|
|
@page pkcs11_core_wrapper_function PKCS #11 Wrapper Functions
|
|
@brief Primary functions of the PKCS #11 wrapper Library:<br><br>
|
|
@subpage pkcs11_core_xinitializepkcs11 <br>
|
|
@subpage pkcs11_core_xgetslotlist <br>
|
|
@subpage pkcs11_core_xinitializepkcs11token <br>
|
|
@subpage pkcs11_core_xinitializepkcs11session <br>
|
|
@subpage pkcs11_core_xfindobjectwithlabelandclass <br>
|
|
@subpage pkcs11_core_vappendsha256algorithmidentifiersequence <br>
|
|
|
|
@page pkcs11_core_xinitializepkcs11 xInitializePKCS11
|
|
@snippet core_pkcs11.h declare_pkcs11_core_xinitializepkcs11
|
|
@copydoc xInitializePKCS11
|
|
|
|
@page pkcs11_core_xgetslotlist xGetSlotList
|
|
@snippet core_pkcs11.h declare_pkcs11_core_xgetslotlist
|
|
@copydoc xGetSlotList
|
|
|
|
@page pkcs11_core_xinitializepkcs11token xInitializePkcs11Token
|
|
@snippet core_pkcs11.h declare_pkcs11_core_xinitializepkcs11token
|
|
@copydoc xInitializePkcs11Token
|
|
|
|
@page pkcs11_core_xinitializepkcs11session xInitializePkcs11Session
|
|
@snippet core_pkcs11.h declare_pkcs11_core_xinitializepkcs11session
|
|
@copydoc xInitializePkcs11Session
|
|
|
|
@page pkcs11_core_xfindobjectwithlabelandclass xFindObjectWithLabelAndClass
|
|
@snippet core_pkcs11.h declare_pkcs11_core_xfindobjectwithlabelandclass
|
|
@copydoc xFindObjectWithLabelAndClass
|
|
|
|
@page pkcs11_core_vappendsha256algorithmidentifiersequence vAppendSHA256AlgorithmIdentifierSequence
|
|
@snippet core_pkcs11.h declare_pkcs11_core_vappendsha256algorithmidentifiersequence
|
|
@copydoc vAppendSHA256AlgorithmIdentifierSequence
|
|
*/
|
|
|
|
/**
|
|
@page pkcs11_core_pal_function PKCS #11 PAL Functions
|
|
@brief Primary functions of the PKCS #11 Platform Abstraction Layer Library:<br><br>
|
|
@subpage pkcs11_pal_initialize <br>
|
|
@subpage pkcs11_pal_saveobject <br>
|
|
@subpage pkcs11_pal_destroyobject <br>
|
|
@subpage pkcs11_pal_findobject <br>
|
|
@subpage pkcs11_pal_getobjectvalue <br>
|
|
@subpage pkcs11_pal_getobjectvaluecleanup <br>
|
|
|
|
@page pkcs11_pal_initialize PKCS11_PAL_Initialize
|
|
@snippet core_pkcs11_pal.h declare_pkcs11_pal_initialize
|
|
@copydoc PKCS11_PAL_Initialize
|
|
|
|
@page pkcs11_pal_saveobject PKCS11_PAL_SaveObject
|
|
@snippet core_pkcs11_pal.h declare_pkcs11_pal_saveobject
|
|
@copydoc PKCS11_PAL_SaveObject
|
|
|
|
@page pkcs11_pal_destroyobject PKCS11_PAL_DestroyObject
|
|
@snippet core_pkcs11_pal.h declare_pkcs11_pal_destroyobject
|
|
@copydoc PKCS11_PAL_DestroyObject
|
|
|
|
@page pkcs11_pal_findobject PKCS11_PAL_FindObject
|
|
@snippet core_pkcs11_pal.h declare_pkcs11_pal_findobject
|
|
@copydoc PKCS11_PAL_FindObject
|
|
|
|
@page pkcs11_pal_getobjectvalue PKCS11_PAL_GetObjectValue
|
|
@snippet core_pkcs11_pal.h declare_pkcs11_pal_getobjectvalue
|
|
@copydoc PKCS11_PAL_GetObjectValue
|
|
|
|
@page pkcs11_pal_getobjectvaluecleanup PKCS11_PAL_GetObjectValueCleanup
|
|
@snippet core_pkcs11_pal.h declare_pkcs11_pal_getobjectvaluecleanup
|
|
@copydoc PKCS11_PAL_GetObjectValueCleanup
|
|
*/
|
|
|
|
/**
|
|
@page pkcs11_core_utils_function PKCS #11 Utils Functions
|
|
@brief Primary functions of the PKCS #11 Utils Library:<br><br>
|
|
@subpage pkcs11_utils_pkipkcs11signaturetombedtlssignature <br>
|
|
@subpage pkcs11_utils_pkimbedtlssignaturetopkcs11signature <br>
|
|
|
|
@page pkcs11_utils_pkipkcs11signaturetombedtlssignature PKI_mbedTLSSignatureToPkcs11Signature
|
|
@snippet core_pki_utils.h declare_pkcs11_utils_pkipkcs11signaturetombedtlssignature
|
|
@copydoc PKI_mbedTLSSignatureToPkcs11Signature
|
|
|
|
@page pkcs11_utils_pkimbedtlssignaturetopkcs11signature PKI_pkcs11SignatureTombedTLSSignature
|
|
@snippet core_pki_utils.h declare_pkcs11_utils_pkimbedtlssignaturetopkcs11signature
|
|
@copydoc PKI_pkcs11SignatureTombedTLSSignature
|
|
*/
|