From 8b001785676e54852efb59c81b65adc52eb93057 Mon Sep 17 00:00:00 2001 From: Brett Nicholas <7547222+bigbrett@users.noreply.github.com> Date: Thu, 6 Jun 2024 15:49:30 -0600 Subject: [PATCH] renamed struct and whitespace cleanup --- wolfHSM/src/chapter02.md | 2 +- wolfHSM/src/chapter03.md | 14 +++++++------- wolfHSM/src/chapter04.md | 14 +++++++------- wolfHSM/src/chapter05.md | 10 +++++----- wolfHSM/src/chapter07.md | 30 +++++++++++++++--------------- wolfHSM/src/chapter08.md | 10 +++++----- 6 files changed, 40 insertions(+), 40 deletions(-) diff --git a/wolfHSM/src/chapter02.md b/wolfHSM/src/chapter02.md index 4b48b28b..a6810c02 100644 --- a/wolfHSM/src/chapter02.md +++ b/wolfHSM/src/chapter02.md @@ -1,4 +1,4 @@ -# Overview +# Overview wolfHSM is a software framework that provides a unified API for HSM operations such as cryptographic operations, key management, and non-volatile storage. diff --git a/wolfHSM/src/chapter03.md b/wolfHSM/src/chapter03.md index 1a1aaaf5..0d2fb58c 100644 --- a/wolfHSM/src/chapter03.md +++ b/wolfHSM/src/chapter03.md @@ -90,13 +90,13 @@ Configuring a wolfHSM server involves allocating a server context structure and The steps required to configure a server that supports client communication, NVM object storage using the NVM flash configuration, and local crypto (software only) are: -1. Initialize the server comms configuration - 1\. Allocate and initialize a transport configuration structure, context, and callback implementation for the desired transport +1. Initialize the server comms configuration + 1\. Allocate and initialize a transport configuration structure, context, and callback implementation for the desired transport 2\. Allocate and initialize a comm server configuration structure using the transport configuration from step 1.1 -2. Initialize the server NVM context - 1\. Allocate and initialize a config, context, and callback structure for the low-level flash storage drivers (the implementation of these structures is provided by the port) - 2\. Allocate and initialize an NVM flash config, context, and callback strucure and bind the port flash configuration from step 2.1 to them - 3\. Allocate an NVM context structure and initialize it with the configuration from step 2.2 using `wh_Nvm_Init()` +2. Initialize the server NVM context + 1\. Allocate and initialize a config, context, and callback structure for the low-level flash storage drivers (the implementation of these structures is provided by the port) + 2\. Allocate and initialize an NVM flash config, context, and callback strucure and bind the port flash configuration from step 2.1 to them + 3\. Allocate an NVM context structure and initialize it with the configuration from step 2.2 using `wh_Nvm_Init()` 3. Allocate and initialize a crypto context structure for the server 4. Initialize wolfCrypt (before initializing the server) 5. Allocate and initialize a server config structure and bind the comm server configuration, NVM context, and crypto context to it @@ -169,7 +169,7 @@ whNvmContext nvmCtx = {0}; wh_Nvm_Init(&nvmCtx, &whNvmConfig); /* Step 3: Allocate and initialize a crypto context structure */ -crypto_context cryptoCtx { +whServerCryptoContext cryptoCtx { .devID = INVALID_DEVID; /* or set to custom crypto callback devID */ }; diff --git a/wolfHSM/src/chapter04.md b/wolfHSM/src/chapter04.md index 0352ad20..3792aca8 100644 --- a/wolfHSM/src/chapter04.md +++ b/wolfHSM/src/chapter04.md @@ -36,13 +36,13 @@ sequence of a wolfHSM component is: #include "wolfhsm/component.h" /* wolfHSM abstract API reference for a component */ #include "port/vendor/mycomponent.h" /* Platform specific definitions of configuration * and context structures, as well as declarations of - * callback functions */ + * callback functions */ /* Provide the lookup table for function callbacks for mycomponent. Note the type is the abstract type provided in wolfhsm/component.h */ whComponentCb my_cb[1] = {MY_COMPONENT_CB}; -/* Fixed configuration data. Note that pertinent data is copied out of the structure +/* Fixed configuration data. Note that pertinent data is copied out of the structure * during init() */ const myComponentConfig my_config = { .my_number = 3, @@ -149,7 +149,7 @@ uint16_t req_magic = wh_COMM_MAGIC_NATIVE; uint16_t req_type = 123; uint16_t request_id; char* req_data = "RequestData"; -rc = wh_CommClient_SendRequest(context, req_magic, req_type, &request_id, +rc = wh_CommClient_SendRequest(context, req_magic, req_type, &request_id, sizeof(req_data), req_data); /* Do other work */ @@ -167,7 +167,7 @@ client/server should Cleanup any context as a result. ### Transports Transports provide intact packets (byte sequences) of variable size (up to a -maximum MTU), to the messaging layer for the library to process as a request or +maximum MTU), to the messaging layer for the library to process as a request or response. Transports implement the abstract interface defined by `whTransportClientCb` and are invoked directly by the commClient/commServer when needing to send and receive data. @@ -176,7 +176,7 @@ Custom transport modules that implement the `whTransportClientCb` interface can be registered with the server and client and then are automatically used via the standard server and client request/response functions. -Examples of a memory buffer transport module and a POSIX TCP socket transport can be found in wolfHSM's supported transports. +Examples of a memory buffer transport module and a POSIX TCP socket transport can be found in wolfHSM's supported transports. #### Supported Transports @@ -257,7 +257,7 @@ One of the defining features of wolfHSM is that it enables the client applicatio - local and remote HSM implementations can be easily switched between by changing a single parameter to the wolfCrypt call, enabling maximum flexibility of implementation and ease of development. Client application development can be prototyped with local instances of wolfCrypt before the HSM core is even brought on-line - the wolfHSM API is simple, stable, well documented, and battle tested -The ability to easily redirect wolfCrypt API calls to the wolfHSM server is based on the "crypto callback" (a.k.a cryptocb) of wolfCrypt. +The ability to easily redirect wolfCrypt API calls to the wolfHSM server is based on the "crypto callback" (a.k.a cryptocb) of wolfCrypt. The wolfHSM client is able to redirect wolfCrypt API calls to the wolfHSM server by implementing the remote procedure call logic as a [crypto callback](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter06.html#crypto-callbacks-cryptocb). The Crypto callback framework in wolfCrypt enables users to override the default implementation of select cryptographic algorithms and provide their own custom implementations at runtime. The wolfHSM client library registers a crypto callback with wolfCrypt that transforms each wolfCrypt crypto API function into a remote procedure call to the HSM server to be executed in a secure environment. Crypto callbacks are selected for use based on the device ID (`devId`) parameter accepted by most wolfCrypt API calls. @@ -269,6 +269,6 @@ wolfHSM defines the `WOLFHSM_DEV_ID` value to represent the wolfHSM server crypt Many HSM devices also have hardware acceleration capabilities for select algorithms available. In these cases, the wolfHSM server may also support offloading the HSM server-side cryptography to device hardware. If supported, the wolfHSM server can be configured to do this automatically with no input required from the user. Any port-specific hardware acceleration capabilities will be documented in the wolfHSM port for that device. -## AUTOSAR SHE +## AUTOSAR SHE TODO diff --git a/wolfHSM/src/chapter05.md b/wolfHSM/src/chapter05.md index c859fa80..100c4b31 100644 --- a/wolfHSM/src/chapter05.md +++ b/wolfHSM/src/chapter05.md @@ -51,7 +51,7 @@ if (rc != WH_ERROR_OK) { The client context structure (`whClientContext`) holds the runtime state of the client and represents the endpoint of the connection with the server. There is a one-to-one relationship between client and server contexts, meaning an application that interacts with multiple servers will need multiple client contexts - one for each server. Each client API function takes a client context as an argument, indicating which server connection the operations will correspond to. If familiar with wolfSSL, the client context structure is analogous to the `WOLFSSL` connection context structure. -### Initializing the client context +### Initializing the client context Before using any client APIs on a client context, the structure must be configured and initialized using the `whClientConfig` configuration structure and the `wh_Client_Init()` function. @@ -157,15 +157,15 @@ Note that the echo request in step 6 is just a simple usage example. Once the co ## NVM Operations -This section provides examples of how to use the client NVM API. Blocking APIs are used for simplicity, though the split transaction APIs can be used in a similar manner. +This section provides examples of how to use the client NVM API. Blocking APIs are used for simplicity, though the split transaction APIs can be used in a similar manner. Client usage of the server NVM storage first requires sending an initialization request to the server. This currently does not trigger any action on the server side but it may in the future and so it is recommended to include in client applications. ```c int rc; -int serverRc; +int serverRc; uint32_t clientId; /* unused for now */ -uint32_t serverId; +uint32_t serverId; rc = wh_Client_NvmInit(&clientCtx, &serverRc, &clientId, &serverId); @@ -202,7 +202,7 @@ For objects that should not be copied and sent over the transport, there exist D whNvmMetadata myMeta = { .id = 123, .access = WOLFHSM_NVM_ACCESS_ANY, - .flags = WOLFHSM_NVM_FLAGS_ANY, + .flags = WOLFHSM_NVM_FLAGS_ANY, .label = “My Label” }; diff --git a/wolfHSM/src/chapter07.md b/wolfHSM/src/chapter07.md index fab99a36..5d05afaf 100644 --- a/wolfHSM/src/chapter07.md +++ b/wolfHSM/src/chapter07.md @@ -72,8 +72,8 @@ This enables the callback to `switch` on the `oper` value and perform custom log #include "wolfhsm/wh_error.h" /* Example DMA callback for 32-bit client addresses */ -int myDmaCallback32(whServerContext* server, uint32_t clientAddr, - void** xformedCliAddr, uint32_t len, +int myDmaCallback32(whServerContext* server, uint32_t clientAddr, + void** xformedCliAddr, uint32_t len, whServerDmaOper oper, whServerDmaFlags flags) { /* Optionally transform client address to server address space, e.g. memmap() */ @@ -110,7 +110,7 @@ To register the callback at initialization, the callback function should be incl #include "wolfhsm/wh_server.h" /* Example of initializing a server config structr with a DMA32 callback then initializing the server */ -int main(void) +int main(void) { whServerDmaConfig dmaCfg = {0}; dmaCfg.dma32Cb = myDmaCallback32; @@ -125,7 +125,7 @@ int main(void) whServerContext serverCtx; wh_Server_Init(&serverCtx, &serverCfg); - + /* server app logic */ } ``` @@ -135,7 +135,7 @@ To register the callback after initialization, first initialize the server conte ```c #include "wolfhsm/wh_server.h" -int main(void) +int main(void) { whServerConfig serverCfg = { /* server config */ }; @@ -153,7 +153,7 @@ int main(void) ## DMA Address Allow List -wolfHSM also exposes an "allow list" for client DMA addresses, providing a mechanism for the server to restrict the client's access to a pre-configured list of specific memory regions. This feature is particularly useful in scenarios where the server needs to limit the client's access to certain memory regions to prevent unauthorized access or to ensure that the client only accesses memory that is safe to access. For example, in a multicore system with one client running per-core, it is most likely that clients should not be able to access each others memory regions, nor read out server memory which could contain sensitive information like cryptographic keys. +wolfHSM also exposes an "allow list" for client DMA addresses, providing a mechanism for the server to restrict the client's access to a pre-configured list of specific memory regions. This feature is particularly useful in scenarios where the server needs to limit the client's access to certain memory regions to prevent unauthorized access or to ensure that the client only accesses memory that is safe to access. For example, in a multicore system with one client running per-core, it is most likely that clients should not be able to access each others memory regions, nor read out server memory which could contain sensitive information like cryptographic keys. It is important to note that the software allow list feature is meant to work as a second layer of protection on top of device-specific memory protection mechanisms, and should not be considered a first line of defense in preventing unauthorized memory accesses. It is imperative that the user configure the device-specific memory protection mechanisms required to enforce the isolation of their applications and segment the HSM core and associated memory from the rest of the system. @@ -179,7 +179,7 @@ const whServerDmaAddrAllowList allowList = { }, }; -int main() +int main() { whServerConfig config; @@ -199,9 +199,9 @@ int main() /* Server is now configured with the allowlist */ /* Perform other server operations */ - /* Allow list can also be registered after initialization if the + /* Allow list can also be registered after initialization if the * list is not present in the server configuration struct using: - * + * * wh_Server_DmaRegisterAllowList(&server, &allowList); */ } @@ -283,7 +283,7 @@ First, common messages shared between the client and server should be defined: enum { MY_TYPE_A = WH_MESSAGE_CUSTOM_CB_TYPE_USER_DEFINED_START, - MY_TYPE_B, + MY_TYPE_B, } myUserDefinedTypes; typedef struct { @@ -327,13 +327,13 @@ static int customServerCb(whServerContext* server, if (req->type == WH_MESSAGE_CUSTOM_CB_TYPE_DMA32) { uint8_t* clientPtr = (uint8_t*)((uintptr_t)req->data.dma32.client_addr); size_t clientSz = req->data.dma32.client_sz; - + if (clientPtr == NULL) { resp->err = WH_ERROR_BADARGS; } else { rc = doWorkOnClientAddr(clientPtr, clientSz); - } + } } else if (req->type == MY_TYPE_A) { myCustomCbDataA *data = (myCustomCbDataA*)((uintptr_t)req->data.data); @@ -357,7 +357,7 @@ static int customServerCb(whServerContext* server, int main(void) { - + whServerContext serverCtx; whServerConfig serverCfg = { @@ -368,7 +368,7 @@ int main(void) { wh_Server_RegisterCustomCb(&serverCtx, MY_CUSTOM_CB_ID, customServerCb)); - /* process server requests (simplified) */ + /* process server requests (simplified) */ while (1) { wh_Server_HandleRequestMessage(&serverCtx); } @@ -399,7 +399,7 @@ if (isRegistered) { whMessageCustomCb_Request req = {0}; whMessageCustomCb_Request resp = {0}; - /* send custom request with built-in DMA type */ + /* send custom request with built-in DMA type */ req.id = MY_CUSTOM_CB_ID; req.type = WH_MESSAGE_CUSTOM_CB_TYPE_DMA32; req.data.dma32.client_addr = (uint32_t)((uintptr_t)&data); diff --git a/wolfHSM/src/chapter08.md b/wolfHSM/src/chapter08.md index 9105a24e..978ae12c 100644 --- a/wolfHSM/src/chapter08.md +++ b/wolfHSM/src/chapter08.md @@ -1,7 +1,7 @@ # WolfHSM Porting -This porting section aims to provide you with wolfHSM porting-related material and information. -We will cover the following: +This porting section aims to provide you with wolfHSM porting-related material and information. +We will cover the following: - WolfHSM Porting Overview - WolfHSM Ports @@ -29,7 +29,7 @@ Official ports of wolfHSM are provided for various supported architectures, with ### Infineon Aurix TC3XX (Port in progress) -The distribution of this port is restricted by the vendor. Please contact support@wolfssl.com for access. +The distribution of this port is restricted by the vendor. Please contact support@wolfssl.com for access. Infineon Aurix TC3xx - Up to 6x 300MHz TriCore application cores @@ -39,7 +39,7 @@ Infineon Aurix TC3xx ### ST SPC58NN (Port in progress) -The distribution of this port is restricted by the vendor. Please contact support@wolfssl.com for access. +The distribution of this port is restricted by the vendor. Please contact support@wolfssl.com for access. ST SPC58NN - 3x 200MHz e200z4256 PowerPC application cores @@ -56,7 +56,7 @@ The POSIX port provides: - Unix domain transport - RAM-based and file-based NVM flash simulators -### Skeleton +### Skeleton The Skeleton port source code provides a non-functioning layout to be used as a starting point for future hardware/platform ports. Each function provides the basic description and expected flow with error cases explained so that ports can be used interchangeably with consistent results.