docs: updates documentation with nvm enforcing and key revocation

rizlik · rizlik · commit edb28d0ea305 · 2025-12-19T15:18:44.000+01:00
diff --git a/docs/src/appendix01.md b/docs/src/appendix01.md
@@ -1 +1,178 @@
 # wolfHSM API reference
+
+## Key Revocation
+
+### wh_Client_KeyRevokeRequest
+
+Send a key revocation request to the server (non-blocking).
+
+This function prepares and sends a revoke request for the specified key ID. It
+returns after the request is sent; use `wh_Client_KeyRevokeResponse()` to
+retrieve the result.
+
+Parameters:
+
+- `c`: Client context.
+- `keyId`: Key ID to revoke.
+
+Return values:
+
+- `WH_ERROR_OK` on successful request send.
+- A negative error code on failure.
+
+Error codes:
+
+- `WH_ERROR_BADARGS` if `c` is NULL or `keyId` is invalid.
+- Propagates comm layer errors on send failure.
+
+### wh_Client_KeyRevokeResponse
+
+Receive a key revocation response.
+
+This function polls for the revoke response and returns `WH_ERROR_NOTREADY`
+until the server reply is available.
+
+Parameters:
+
+- `c`: Client context.
+
+Return values:
+
+- `WH_ERROR_OK` on success.
+- `WH_ERROR_NOTREADY` if the response has not arrived.
+- A negative error code on failure.
+
+Error codes:
+
+- `WH_ERROR_BADARGS` if `c` is NULL.
+- Server error codes such as `WH_ERROR_NOTFOUND`.
+
+### wh_Client_KeyRevoke
+
+Revoke a key using a blocking request/response.
+
+This helper sends a revoke request and waits for the response.
+
+Parameters:
+
+- `c`: Client context.
+- `keyId`: Key ID to revoke.
+
+Return values:
+
+- `WH_ERROR_OK` on success.
+- A negative error code on failure.
+
+Error codes:
+
+- Any error code returned by `wh_Client_KeyRevokeRequest()` or
+  `wh_Client_KeyRevokeResponse()`.
+
+### wh_Server_KeystoreRevokeKey
+
+Revoke a key by updating its metadata.
+
+This server-side function marks a key as non-modifiable and clears all usage
+flags. If the key exists in NVM, the metadata update is committed so the revoke
+state persists.
+
+Parameters:
+
+- `server`: Server context.
+- `keyId`: Key ID to revoke.
+
+Return values:
+
+- `WH_ERROR_OK` on success.
+- A negative error code on failure.
+
+Error codes:
+
+- `WH_ERROR_BADARGS` if parameters are invalid.
+- `WH_ERROR_NOTFOUND` if the key is missing.
+- Propagates NVM/storage errors (for example `WH_ERROR_NOSPACE`).
+
+## NVM Access and Flag Controls
+
+### whNvmFlags
+
+Policy flags for NVM objects and keys.
+
+Flags include `WH_NVM_FLAGS_NONMODIFIABLE`, `WH_NVM_FLAGS_NONDESTROYABLE`,
+`WH_NVM_FLAGS_NONEXPORTABLE`, and the usage policy flags `WH_NVM_FLAGS_USAGE_*`.
+If no usage flags are set, the key is not permitted for cryptographic use.
+
+### wh_Nvm_AddObjectChecked
+
+Add an NVM object with policy enforcement.
+
+This function applies NVM policy checks (for example non-modifiable objects)
+before writing the object.
+
+Parameters:
+
+- `context`: NVM context.
+- `meta`: Metadata describing the object.
+- `data_len`: Length of object data.
+- `data`: Object data buffer.
+
+Return values:
+
+- `WH_ERROR_OK` on success.
+- A negative error code on failure.
+
+Error codes:
+
+- `WH_ERROR_BADARGS` if parameters are invalid.
+- `WH_ERROR_ACCESS` if the object is non-modifiable.
+- Propagates backend errors (for example `WH_ERROR_NOSPACE`).
+
+### wh_Nvm_ReadChecked
+
+Read an NVM object with policy enforcement.
+
+This function applies NVM policy checks (for example non-exportable objects)
+before reading the object data.
+
+Parameters:
+
+- `context`: NVM context.
+- `id`: Object ID to read.
+- `offset`: Byte offset into the object.
+- `data_len`: Length of data to read.
+- `data`: Output buffer.
+
+Return values:
+
+- `WH_ERROR_OK` on success.
+- A negative error code on failure.
+
+Error codes:
+
+- `WH_ERROR_BADARGS` if parameters are invalid.
+- `WH_ERROR_ACCESS` if the object is non-exportable.
+- `WH_ERROR_NOTFOUND` if the object does not exist.
+
+### wh_Nvm_DestroyObjectsChecked
+
+Destroy NVM objects with policy enforcement.
+
+This function applies NVM policy checks (for example non-destroyable objects)
+before erasing the objects.
+
+Parameters:
+
+- `context`: NVM context.
+- `list_count`: Number of IDs in the list.
+- `id_list`: Array of object IDs to destroy.
+
+Return values:
+
+- `WH_ERROR_OK` on success.
+- A negative error code on failure.
+
+Error codes:
+
+- `WH_ERROR_BADARGS` if parameters are invalid.
+- `WH_ERROR_ACCESS` if any object is non-destroyable or non-modifiable.
+- `WH_ERROR_NOTFOUND` if a listed object is missing.
diff --git a/docs/src/chapter04.md b/docs/src/chapter04.md
@@ -11,9 +11,11 @@ wolfHSM is a modular and extensible library designed to provide a secure and eff
     - [Comms Layer](#comms-layer)
 - [Non Volatile Memory](#non-volatile-memory)
   - [NVM Metadata](#nvm-metadata)
+  - [NVM Access and Flags](#nvm-access-and-flags)
   - [NVM Architecture](#nvm-architecture)
   - [NVM Back-Ends](#nvm-back-ends)
 - [Key Management](#key-management)
+  - [Key Revocation](#key-revocation)
 - [Cryptographic Operations](#cryptographic-operations)
   - [Hardware Cryptography Support](#hardware-cryptography-support)
 
@@ -222,6 +224,18 @@ typedef struct {
 Length (whNvmSize len): The length of the data associated with the object, in bytes.
 - Label (`uint8_t label[]`): A human-readable label or name for the object.
 
+### NVM Access and Flags
+
+NVM access controls are stored in the metadata for all objects and are returned by `wh_Nvm_GetMetadata()` and related client APIs. 
+
+NVM flags provide object and key policy hints that are enforced by the NVM library and keystore. Relevant flags include:
+
+- `WH_NVM_FLAGS_NONMODIFIABLE`: Object cannot be modified and/or destroyed.
+- `WH_NVM_FLAGS_NONDESTROYABLE`: Object cannot be destroyed.
+- `WH_NVM_FLAGS_NONEXPORTABLE`: Object data cannot be read/exported.
+- `WH_NVM_FLAGS_USAGE_*`: Key usage policy flags for encrypt/decrypt/sign/verify/wrap/derive.
+- `WH_NVM_FLAGS_USAGE_ANY`: Allow all usage flags.
+
 ### NVM Architecture
 
 The wolfHSM server follows the generic component architecture approach to handle Non-Volatile Memory (NVM) operations. The configuration is divided into generic and specific parts, allowing for flexibility and customization.
@@ -249,6 +263,21 @@ Currently, wolfHSM only supports one NVM back-end provider: the NVM flash module
 
 The wolfHSM library provides comprehensive key management capabilities, including storing, loading, and exporting keys from non-volatile memory, caching of frequently used keys in RAM for fast access, and interacting with hardware-exclusive device keys. Keys are stored in non-volatile memory along side other NVM objects with corresponding access protections. wolfHSM will automatically load keys into the necessary cryptographic hardware when the key is selected for use with a specific consumer. More information on the key management API can be found in the [client library](./chapter05.md) and [API documentation](./appendix01.md) sections.
 
+### Key Revocation
+
+Key revocation provides a lightweight mechanism to invalidate a key without destroying its storage. When a key is revoked on the server, its metadata is updated by setting `WH_NVM_FLAGS_NONMODIFIABLE` and clearing all `WH_NVM_FLAGS_USAGE_*` bits. The key remains present in cache/NVM, but is no longer eligible for cryptographic operations that enforce usage flags.
+
+Runtime behavior for revoked keys:
+
+- Cryptographic operations that enforce usage flags return `WH_ERROR_USAGE` when the required usage bit is no longer set.
+- The `WH_NVM_FLAGS_NONMODIFIABLE` setting prevents further key metadata changes and blocks NVM modification or destruction checks.
+- Revocation does not automatically set `WH_NVM_FLAGS_NONEXPORTABLE`; export behavior remains controlled by those flags.
+
+Persistence behavior:
+
+- Revocation is committed to NVM for keys that already exist in NVM, so the revoked state persists across resets or power cycles.
+- If a key exists only in cache and has not been committed, the revoked state is limited to the cache lifetime.
+
 ## Cryptographic Operations
 
 One of the defining features of wolfHSM is that it enables the client application to use the wolfCrypt API directly, but with the underlying cryptographic operations actually being executed on the HSM core. This is an incredibly powerful feature for a number of reasons:
diff --git a/docs/src/chapter05.md b/docs/src/chapter05.md
@@ -9,7 +9,9 @@ The client library API is the primary mechanism through which users will interac
 - [The Client Context](#the-client-context)
   - [Initializing the client context](#initializing-the-client-context)
 - [NVM Operations](#nvm-operations)
+- [NVM Access and Flags](#nvm-access-and-flags)
 - [Key Management](#key-management)
+- [Key Revocation](#key-revocation)
 - [Cryptography](#cryptography)
 - [AUTOSAR SHE API](#autosar-she-api)
 
@@ -250,6 +252,10 @@ int wh_Client_NvmList(whClientContext* c,
 
 For a full description of all the NVM API functions, please refer to the [API documentation](./appendix01.md).
 
+## NVM Flags
+
+NVM objects include flags in their metadata. Flags (such as `WH_NVM_FLAGS_NONMODIFIABLE`, `WH_NVM_FLAGS_NONDESTROYABLE`, and `WH_NVM_FLAGS_NONEXPORTABLE`) are enforced by the server NVM policy checks. Key usage flags (`WH_NVM_FLAGS_USAGE_*`) are enforced by the keystore during cryptographic operations.
+
 ## Key Management
 
 Keys meant for use with wolfCrypt can be loaded into the HSM's keystore and optionally saved to NVM with the following APIs:
@@ -281,6 +287,70 @@ wh_Client_KeyErase(clientCtx, keyId);
 `wh_Client_KeyExport` will read the key contents out of the HSM back to the client.
 `wh_Client_KeyErase` will remove the indicated key from cache and erase it from NVM.
 
+## Key Revocation
+
+Key revocation updates key metadata to prevent further cryptographic use without destroying storage. Revocation clears all `WH_NVM_FLAGS_USAGE_*` bits and sets `WH_NVM_FLAGS_NONMODIFIABLE`. The revoked state is persisted when the key is already committed to NVM.
+
+Creating a key with NVM usage flags:
+
+```c
+int rc;
+uint16_t keyId = WH_KEYID_ERASED;
+byte label[WH_NVM_LABEL_LEN] = "app-signing";
+byte key[AES_128_KEY_SIZE] = { /* key bytes */ };
+whNvmFlags flags = WH_NVM_FLAGS_USAGE_SIGN | WH_NVM_FLAGS_NONEXPORTABLE;
+
+rc = wh_Client_KeyCache(&clientCtx, flags, label, sizeof(label),
+                        key, sizeof(key), &keyId);
+if (rc == WH_ERROR_OK) {
+    rc = wh_Client_KeyCommit(&clientCtx, keyId);
+}
+```
+
+Revoking a key:
+
+```c
+int rc;
+
+rc = wh_Client_KeyRevoke(&clientCtx, keyId);
+if (rc != WH_ERROR_OK) {
+    /* handle error */
+}
+```
+
+Attempting to use a revoked key and handling failure:
+
+```c
+int rc;
+Aes aes;
+byte iv[AES_BLOCK_SIZE] = {0};
+byte plain[AES_BLOCK_SIZE] = {0};
+byte cipher[AES_BLOCK_SIZE] = {0};
+
+wc_AesInit(&aes, NULL, WOLFHSM_DEV_ID);
+wh_Client_AesSetKeyId(&aes, keyId);
+wc_AesSetIV(&aes, iv);
+
+rc = wh_Client_AesCbc(&clientCtx, &aes, AES_ENCRYPTION,
+                      plain, sizeof(plain), cipher);
+if (rc == WH_ERROR_USAGE) {
+    /* key revoked or usage not permitted */
+}
+wc_AesFree(&aes);
+```
+
+Security notes:
+
+- Set explicit usage flags for each key; avoid `WH_NVM_FLAGS_USAGE_ANY` unless required.
+- Use `WH_NVM_FLAGS_NONEXPORTABLE` for private keys and long-lived secrets.
+- Revoke keys on compromise and rotate to new key IDs rather than reusing revoked IDs.
+
+Compatibility notes:
+
+- Keys stored with `WH_NVM_FLAGS_NONE` (no usage flags) are treated as not permitted for cryptographic use and will return `WH_ERROR_USAGE`.
+- Keys committed to NVM retain revocation state across resets; cached-only keys do not persist after reset or eviction.
+- Keys cached via `wh_Client_KeyCache` are stored with `WH_NVM_ACCESS_ANY` on the server side.
+
 ## Cryptography
 
 When using wolfCrypt in the client application, compatible crypto operations can be executed on the wolfHSM server by passing `WOLFHSM_DEV_ID` as the `devId` argument. The wolfHSM client must be initialized before using any wolfHSM remote crypto.
@@ -367,4 +437,3 @@ For CMAC operations that need to use cached keys, seperate wolfHSM specific func
 
 ## AUTOSAR SHE API
 
-
