Skip to content

Keep keys in a CryptoCb backend: key ids, TLS client auth, TPM example - #64

Open
Frauschi wants to merge 17 commits into
wolfSSL:mainfrom
Frauschi:key-id-offload
Open

Frauschi wants to merge 17 commits into
wolfSSL:mainfrom
Frauschi:key-id-offload

Conversation

@Frauschi

@Frauschi Frauschi commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Keys in a CryptoCb backend (TPM, HSM, secure element) can now be generated, used for CSRs and TLS client auth, and renewed over EST without leaving the backend, named by a wolfCrypt key id that replaces key_label. This PR now stacks on #65; its first two commits are #65's.

Changes

  • wolfcert_key_generate creates a key under key_id on dev_id, following the id the device assigns; wolfcert_key_from_id rebuilds it from the stored certificate.
  • dev_id is used as given (INVALID_DEVID = software); an unregistered device is refused.
  • WolfCertServerCfg.client_key_obj (appended) takes the TLS client key as a key handle; EST /simplereenroll signs with the renewed key in its backend.
  • SCEP refuses key-id keys, since wolfSSL's PKCS#7 takes the private key as DER.
  • WOLFCERT_DEFAULT_DEVID / wolfcert_set_default_dev_id() put the TLS context and PKCS#7 on a default device, WC_USE_DEVID when defined.
  • Enroll/reenroll hand a key-id key back on failure and refuse non-EST protocols before keygen.
  • WOLF_CRYPTO_CB is optional; without it every key runs in software.
  • wolfcert-server: --tls-trust-issued, and --ca-dir keeps the CA across restarts to renew what it issued.
  • examples/enroll_tpm.c: ECC, RSA and ML-DSA keys in a TPM via wolfTPM.
  • Shared library version 1 (key_label removed, fields appended).

Testing

  • test_est_devid_roundtrip (mock CryptoCb key store), new keygen and mTLS cases.
  • tests/interop/tpm_wolftpm.sh runs the TPM example against wolfTPM's fwTPM, per PR and nightly.
  • New no-cryptocb CI job; the -Werror job builds the examples.

Follow-ups

  • PKCS#11 and wolfHSM as key-id backends, with examples.

Copilot AI balanced review requested due to automatic review settings November 12, 2026 12:52
@Frauschi Frauschi self-assigned this Nov 12, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The CLI integration test fails on supported builds with POSIX storage disabled because cases requiring CA storage are not gated on backend availability.

1 open issue
What changed in this PR

This PR extends wolfCert’s certificate lifecycle support to backend-resident keys, enabling EST enrollment, TLS client authentication, and renewal without exporting private keys.

Changes:

  • Replaces key labels with opaque key IDs and adds configurable default crypto devices.
  • Adds persistent test-server CA storage and trust for renewing issued certificates.
  • Expands TPM interoperability coverage, optional-CryptoCb builds, documentation, and shared-library versioning.
File Description
zephyr/​samples/​wolfcert_est_client/​src/​main.c Uses the default-device selector.
wolfcert/​types.h Defines key IDs, TLS key sources, and default-device APIs.
wolfcert/​server.h Adds trust for issued client certificates.
wolfcert/​keygen.h Exposes backend-key reconstruction and ID access.
wolfcert/​http.h Adds TLS client key-source fields.
wolfcert/​client.h Documents backend-key ownership on failure.
wolfcert/​check_config.h Makes CryptoCb optional.
tests/​unit/​test_store.c Updates key-device selection.
tests/​unit/​test_server_ca_store.c Tests issued certificate key identifiers.
tests/​unit/​test_scep_msg.c Supplies explicit crypto-device arguments.
tests/​unit/​test_parse_negative.c Updates SCEP helper arguments.
tests/​unit/​test_http.c Tests TLS key-source validation.
tests/​unit/​test_est.c Updates key-device selection.
tests/​unit/​test_csr.c Updates key-device selection.
tests/​interop/​tpm_wolftpm.sh Exercises TPM enrollment, renewal, rotation, and cleanup.
tests/​integration/​test_scep_roundtrip.c Tests default-device crypto routing.
tests/​integration/​test_scep_poll_roundtrip.c Updates device arguments for polling tests.
tests/​integration/​test_scep_get_cert.c Updates key-device selection.
tests/​integration/​test_scep_async_roundtrip.c Updates asynchronous test key configurations.
tests/​integration/​test_est_tls_roundtrip.c Updates TLS test key configurations.
tests/​integration/​test_est_roundtrip.c Updates enrollment key configurations.
tests/​integration/​test_est_pha_roundtrip.c Updates post-handshake authentication key configurations.
tests/​integration/​test_est_pending_roundtrip.c Updates pending-enrollment key configurations.
tests/​integration/​test_est_mldsa_roundtrip.c Updates ML-DSA device selection.
tests/​integration/​test_est_csr_attrs_enforce.c Updates CSR-policy test key configurations.
tests/​integration/​test_est_csr_attrs_apply_roundtrip.c Updates automatic CSR-attribute key configurations.
tests/​integration/​test_est_chunked_robustness.c Updates robustness-test device selection.
tests/​integration/​test_est_async_roundtrip.c Updates asynchronous EST device selection.
tests/​integration/​est_client_cases.h Updates shared enrollment test configurations.
tests/​integration/​cli_proto_scoping.sh Tests CA persistence and renewal options; uses dynamic ports.
tests/​CMakeLists.txt Registers device-backed EST tests and keygen includes.
src/​wolfcert.c Resets the default device during cleanup.
src/​server.c Configures issued-certificate trust and renewal-only operation.
src/​scep/​scep_server.c Keeps server crypto on explicit software devices.
src/​scep/​scep_msg.c Passes device IDs through PKCS#7 operations.
src/​scep/​scep_client.c Routes crypto to devices and rejects backend-resident signing keys.
src/​pkcs7_util.c Uses explicit software-device selection.
src/​keygen.c Generates, reconstructs, and tracks backend-resident keys.
src/​key_algs.h Adds backend-key algorithm hooks.
src/​key_algs.c Implements key-ID initialization and public-key decoding.
src/​internal.h Declares device helpers and backend-key state.
src/​internal.c Implements default-device management and key-ID validation.
src/​http.c Loads backend key IDs for TLS authentication.
src/​est/​est_server.c Restricts issued-certificate authentication to permitted enrollment flows.
src/​est/​est_client.c Authenticates renewals using the current key’s device.
src/​client.c Preserves backend keys on failure and rejects unsupported protocols early.
src/​ca_issue.c Adds CA subject and issued authority key identifiers.
scripts/​ci/​check-buildsystem-parity.sh Checks shared-library version parity.
scripts/​ci/​build-wolftpm.sh Builds wolfTPM and its firmware TPM.
scripts/​ci/​build-wolfssl.sh Adds TPM and no-CryptoCb configurations.
README.md Documents persistent CA renewal and default-device selection.
Makefile.am Bumps library version and registers device-backed tests.
examples/​enroll_scep.c Uses the default-device selector.
examples/​enroll_est.c Uses the default-device selector.
examples/​enroll_cryptocb.c Clarifies computation offload versus resident keys.
examples/​CMakeLists.txt Conditionally builds CryptoCb and TPM examples.
docs/​MIGRATING-FROM-WOLFSCEP.md Explains key IDs and SCEP restrictions.
docs/​INTEROP.md Documents TPM interoperability coverage.
docs/​EMBEDDED.md Documents optional CryptoCb support.
docs/​CI.md Describes new build and interoperability coverage.
docs/​ARCHITECTURE.md Explains backend-key lifecycle and device routing.
CONTRIBUTING.md Documents key-ID and non-export requirements.
configure.ac Removes the mandatory CryptoCb dependency.
CMakeLists.txt Probes optional CryptoCb and bumps shared-library version.
cli/​wolfcert_server.c Adds CA storage, issued-certificate trust, and dynamic ports.
cli/​wolfcert_client.c Uses the default-device selector.
AGENTS.md Updates hardware-key integration guidance.
.github/​workflows/​pr.yml Adds no-CryptoCb and pinned TPM checks.
.github/​workflows/​nightly.yml Adds no-CryptoCb coverage.
.github/​workflows/​interop.yml Adds interoperability against wolfTPM master.
.github/​actions/​tpm-interop/​action.yml Builds dependencies and runs TPM interoperability checks.

Review effort: Balanced

Comment thread tests/integration/cli_proto_scoping.sh Resolved
@Frauschi

Copy link
Copy Markdown
Member Author

@claude review

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reviewed this PR and found no bugs. It's a large change (75 files, about 4.7k lines added) to how private keys are generated, named and used for CSRs and TLS client auth, and it breaks the ABI, so a human should still review it.

What was reviewed:

  • Key-id keygen in src/keygen.c: id validation, the check that rejects a software fallback when the device declines to generate the key, and adoption of an id the device assigns.
  • Rebuilding a key from the stored certificate's SubjectPublicKeyInfo, the default dev_id wiring, and the new server client_key_src/client_key_dev_id path for EST reenroll.
  • SCEP rejecting key-id keys, and enroll/reenroll returning the key on failure.
Extended reasoning...

This change replaces key_label with wolfCrypt key ids and routes keygen, CSR signing, TLS client auth and EST renewal through CryptoCb backends such as a TPM. It also adds a TPM example, CI jobs and a shared-library version bump. The changes are in crypto and key-handling code, including private-key custody, device fallbacks and mTLS client keys, which are security-sensitive. The size of the change, the crypto surface and the public API/ABI break are why I deferred instead of approving. The one third-party review comment (from Copilot) was resolved by the PR author, and later commits followed it.

@wolfSSL-Fenrir-bot wolfSSL-Fenrir-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fenrir Automated Review — PR #64

Scan targets checked: wolfcert-src, wolfcert-bugs
Not reviewed (no scan target covers them): .github/actions/tpm-interop/action.yml, .github/workflows/interop.yml, .github/workflows/nightly.yml, .github/workflows/pr.yml, AGENTS.md, CMakeLists.txt, CONTRIBUTING.md, Makefile.am, README.md, configure.ac, docs/ARCHITECTURE.md, docs/CI.md, docs/EMBEDDED.md, docs/INTEROP.md, docs/MIGRATING-FROM-WOLFSCEP.md, examples/CMakeLists.txt, examples/enroll_cryptocb.c, examples/enroll_est.c, examples/enroll_scep.c, examples/enroll_tpm.c and 19 more
Coverage: 18 of 36 in-scope changed file(s) opened by the reviewer; not opened: tests/integration/test_est_async_roundtrip.c, tests/integration/test_est_chunked_robustness.c, tests/integration/test_est_csr_attrs_apply_roundtrip.c, tests/integration/test_est_csr_attrs_enforce.c, tests/integration/test_est_mldsa_roundtrip.c, tests/integration/test_est_pending_roundtrip.c, tests/integration/test_est_pha_roundtrip.c, tests/integration/test_est_roundtrip.c, tests/integration/test_est_tls_roundtrip.c, tests/integration/test_scep_async_roundtrip.c and 8 more

Findings: 1
1 finding(s) posted as inline comments (see file-level comments below)

This review was generated automatically by Fenrir. Reported findings require changes before merge.

Review tier: Max

Comment thread tests/unit/test_keygen.c Resolved

@wolfSSL-Fenrir-bot wolfSSL-Fenrir-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fenrir Automated Review — PR #64

Scan targets checked: wolfcert-src, wolfcert-bugs
Not reviewed (no scan target covers them): .github/actions/tpm-interop/action.yml, .github/workflows/interop.yml, .github/workflows/nightly.yml, .github/workflows/pr.yml, AGENTS.md, CMakeLists.txt, CONTRIBUTING.md, Makefile.am, README.md, configure.ac, docs/ARCHITECTURE.md, docs/CI.md, docs/EMBEDDED.md, docs/INTEROP.md, docs/MIGRATING-FROM-WOLFSCEP.md, examples/CMakeLists.txt, examples/enroll_cryptocb.c, examples/enroll_est.c, examples/enroll_scep.c, examples/enroll_tpm.c and 19 more
Coverage: 0 of 1 in-scope changed file(s) opened by the reviewer; not opened: tests/unit/test_keygen.c

Fenrir result: Approved ✅

No new issues found in the changed files.

Advisory only — this automated result does not count as a GitHub approval.

Review tier: Lite

@wolfSSL-Fenrir-bot
wolfSSL-Fenrir-bot dismissed their stale review November 12, 2026 15:39

Fenrir's latest completed scan found no issues; clearing the prior automated change request.

@Frauschi Frauschi assigned wolfSSL-Bot and unassigned Frauschi Nov 12, 2026

@yosuke-wolfssl yosuke-wolfssl left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is a big step for keys in TPMs and secure elements. Most of my comments are about how the devId is chosen. Right now it's decided in several places with different rules, so it's hard to tell which device runs what. Below is a simpler model; the inline comments point at where each part applies.

How it works today

  • INVALID_DEVID in WolfCertKeyCfg.dev_id and client_key_dev_id means "the default". wolfCrypt reads it as software, and so did the software sentinel this PR replaces.
  • A key copies the default when it's made (keygen, from_id, from_pem). Connections and PKCS#7 read the current default on every call. A PEM key loaded before wolfcert_set_default_dev_id() keeps "none".
  • EST reenroll with a software key runs the whole TLS context on key->dev_id (tls_dev_id), and SCEP signs on in_signer_dev_id. If such a key carries a TPM's devId, all the TLS crypto goes through the TPM, which is what a24097e avoids by not using wc_CryptoCb_DefaultDevID().
  • client_key_src and client_key_dev_id exist because client_key holds bytes. Reenroll takes a WolfCertKey apart into those fields, and http.c puts it back together.

Proposal

  1. One default devId, used only for wolfCert's own crypto. Its starting value is WOLFCERT_DEFAULT_DEVID, which falls back to WC_USE_DEVID and can be overridden in user_settings.h. wolfcert_set_default_dev_id() stays for devIds registered at run time. It applies to the TLS context, PKCS#7 objects and RNGs, which have no caller field.

  2. Caller devIds are used as given. WolfCertKeyCfg.dev_id = INVALID_DEVID means software, as in wolfCrypt. A caller who wants the default device writes kcfg.dev_id = wolfcert_default_dev_id(). A key_id without a devId fails at once with BAD_ARG in wolfcert_key_id_check, instead of landing on an accelerator and failing in keygen.

  3. A key handle for the TLS client key, e.g. const WolfCertKey* client_key_obj, set instead of client_key. It's borrowed only while the session opens:

    • a key with an id → wolfSSL_CTX_use_PrivateKey_Id(ctx, id, len, key->dev_id);
    • a software key → exported to DER.

    client_key bytes stay as they are for PEM/DER keys.

wolfSSL already separates the two devIds: the context's devId covers the connection and any key loaded from a buffer, and privateKeyDevId covers only a key given by id. So "TPM holds the key, ELS speeds up the connection" needs nothing more. A software key's private half is in host RAM anyway, so its devId only decides which device accelerates its signature, not where the key lives.

What this removes

client_key_src, client_key_dev_id (in WolfCertServerCfg and both HTTP structs), tls_dev_id, est_session_open_dev, wolfcert_http_session_open_dev, in_signer_dev_id, wolfcert_devid_or_default and wolfcert_key_generate_on. All of them are new in this PR, so nothing that has shipped changes.

Trade-off to confirm

A key handle has to come from wolfcert_key_from_id, which only accepts curves and RSA sizes wolfCert generates. Raw id bytes let wolfSSL take the type from the certificate, so, for example, a factory mTLS key on P-224 in a TPM works today and wouldn't with a handle. Is that a case you want to keep? If so, the bytes-plus-src form could stay just for that, with the handle added for keys wolfCert made.

What this costs the RW612 build: one line per key config (dev_id = WC_USE_DEVID). TLS and PKCS#7 still use ELS with no change.

Comment thread wolfcert/types.h Resolved
Comment thread wolfcert/types.h Resolved
Comment thread src/internal.c Resolved
Comment thread src/est/est_client.c Resolved
Comment thread src/http.c Resolved
Comment thread src/keygen.c Resolved
Comment thread wolfcert/client.h Resolved
Comment thread wolfcert/keygen.h Resolved
Comment thread wolfcert/server.h Resolved
Comment thread src/key_algs.c Resolved
@Frauschi

Copy link
Copy Markdown
Member Author

I adopted the proposed model in 66de97f, with the handle-only client key. This PR now stacks on #65, so its first two commits are #65's until that merges, and --ca-dir now keeps the CA as ca_cert/ca_key files in the CLI.

@yosuke-wolfssl yosuke-wolfssl left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working through the last round. Using devIds as given and taking the TLS client key as a handle make the model much easier to follow. The remaining comments are about docs and two helpers that 66de97f left with a single caller; none change behavior.

  • ARCHITECTURE.md 4.2: one table of where each operation runs, and a shorter body that leaves the return codes to the headers (inline).
  • Two internal helpers each have one caller now (inline).
  • examples/enroll_tpm.c is not listed in README, and nothing says how to build it (below).

README.md:185 (not in the diff)

examples/enroll_tpm.c is missing from this list, and nothing outside .github/actions/tpm-interop/action.yml says how to build it or which TPM it talks to:

  • CMake builds it as example_enroll_tpm only when find_package(wolftpm) finds a wolfTPM with its CryptoCb, which usually needs -Dwolftpm_DIR=<prefix>/lib/cmake/wolftpm. Otherwise it is skipped with only a STATUS message.
  • The TPM it talks to is chosen when wolfTPM is built.

Maybe:

To call the library directly, see `examples/enroll_est.c`,
`examples/enroll_scep.c`, `examples/enroll_cryptocb.c` and
`examples/enroll_tpm.c`. CMake builds the TPM example as
`example_enroll_tpm` when it finds a wolfTPM with its CryptoCb (pass
`-Dwolftpm_DIR=<prefix>/lib/cmake/wolftpm`). See [wolfTPM](https://github.com/wolfSSL/wolfTPM).

Comment thread docs/ARCHITECTURE.md
};
WolfCertKey* key;
wolfcert_key_generate(&cfg, &key);
```

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The split between the key's devId and the default devId is the hardest part of this section to keep in our head. A table right after the example could cover it:

`dev_id` and `key_id` answer different questions. `dev_id` picks the
registered CryptoCb device that runs an operation; `key_id` names one key
inside that device. Together they decide where each operation runs:

| | `INVALID_DEVID` | `dev_id` only | `dev_id` + `key_id` |
|---|---|---|---|
| Key generation | software | device | device; the key stays there |
| CSR signature | software | key's device | key's device |
| TLS client-auth signature (`client_key_obj`) | default devId | default devId (loaded as DER) | key's device |
| Export, SCEP signing | yes | only if the private half is in host memory | `WOLFCERT_ERR_UNSUPPORTED` |
| Reload in a later run | from PEM or DER | from PEM or DER | `wolfcert_key_from_id` |
| TLS connection, SCEP PKCS#7 and RNGs | default devId | default devId | default devId |

The last row is work wolfCert sets up itself, with no caller field to pick
a device, so it runs on `wolfcert_default_dev_id()` whatever key is used.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added the table after the example as suggested.

Comment thread docs/ARCHITECTURE.md Outdated
Comment on lines +345 to +416
The `key_id` bytes are opaque to wolfCert. They reach the backend in the
wolfCrypt key's `id` field, the same way wolfPKCS11, wolfHSM and the hardware
ports name their keys, and the backend decides what they mean (a PKCS#11
`CKA_ID`, a TPM handle, a key-store slot). The backend generates the key there
and returns only its public half. It may also rename the key, as a TPM does
when it picks a transient handle, and `wolfcert_key_id` returns the new id.

From there, every private-key operation on the key routes through
`my_callback`: CSR signing, and TLS client authentication by id or for EST
`/simplereenroll`. wolfSSL also hands the backend public-key operations on
that id, such as the check of its own RSA signature in TLS, so the backend
must serve those too.

A `dev_id` without a `key_id` only offloads the computation. The key itself
is an ordinary wolfCrypt key in host memory, and `wolfcert_key_to_pem` exports
it. Only a `key_id` keeps the key in the backend.

A crypto accelerator gets the work of the objects wolfCert creates itself, the
TLS connection and SCEP's PKCS#7 objects and RNGs, through the default devId.
It starts as `WOLFCERT_DEFAULT_DEVID`, which is `WC_USE_DEVID` when wolfSSL
defines it, as the NXP EdgeLock port does, else `INVALID_DEVID`, and a build
may define it in `user_settings.h`. `wolfcert_set_default_dev_id` changes it
at run time, before other threads use wolfCert, and returns
`WOLFCERT_ERR_BAD_ARG` for a devId with no registered device, unless wolfSSL
has `WOLF_CRYPTO_CB_FIND`; `wolfcert_cleanup` restores the start value. With
`INVALID_DEVID` all of this runs in software, except that TLS keeps a devId
wolfSSL picks itself (CAAM, ARIA, MAXQ10xx). The built-in test server always
runs in software.

Keys use the `dev_id` they are given. `INVALID_DEVID` is software, as in
wolfCrypt, and `dev_id = wolfcert_default_dev_id()` puts a key on the default
device. A `dev_id` with no registered device, or a `key_id` without a
`dev_id`, returns `WOLFCERT_ERR_BAD_ARG`. A key held in one device can
therefore sign while another accelerates the connection.

For TLS client authentication, `client_key` takes the key as PEM or DER, and
the handshake signs with it on the connection's device, the default devId.
`client_key_obj` takes a key handle instead, borrowed while the connection
opens: a key with a `key_id` signs in its own device, and any other key is
loaded as DER. Setting both returns `WOLFCERT_ERR_BAD_ARG`. EST
`/simplereenroll` passes the key being renewed as the handle.

A key with a `key_id` never leaves the backend: `wolfcert_key_to_pem` and
`wolfcert_key_to_der` fail with `WOLFCERT_ERR_UNSUPPORTED`. Persist the id and
the issued certificate instead. `wolfcert_key_from_id(&cfg, cert, cert_len,
&key)` rebuilds the handle from those two, taking the public half from the
certificate, since a backend need not be able to return it. The handle serves
as `client_key_obj`, with the certificate in `client_cert`, and for
re-enrollment, whose CSR carries the public key.

`wolfcert_client_enroll` and `wolfcert_client_reenroll` hand back a key they
generated under a `key_id` even when they fail, so the caller can delete it
in the backend.

RSA, ECC and ML-DSA keys take a `key_id`. Ed25519 and Ed448 keys take one
with a wolfSSL newer than 5.9.4, which has `wc_ed25519_init_id` and
`wc_ed448_init_id`. SCEP does not support a `key_id` key: its PKCS#7
signing and decryption take the private key as DER, so the SCEP calls return
`WOLFCERT_ERR_UNSUPPORTED`. A `key_id` needs wolfSSL built with
`WOLF_CRYPTO_CB` and `WOLF_PRIVATE_KEY_ID`. See `examples/enroll_cryptocb.c`
for the registration pattern.

`examples/enroll_tpm.c` enrolls and re-enrolls over EST with an ECC, RSA or
ML-DSA key in a TPM. It needs a wolfTPM whose CryptoCb reads a 4-byte
`key_id` as a persistent or transient handle. A key generated under a
persistent handle is stored there. Under `0x80000000`
(`WOLFTPM2_KEYID_TRANSIENT`) the TPM loads it at a transient handle it picks;
a TPM reset drops that key, and so does `/dev/tpmrm0` when the process exits.
An older wolfTPM generates the key in software, which `wolfcert_key_generate`
refuses. ML-DSA needs a TPM with the v1.85 commands, such as wolfTPM's fwTPM.
For a test CA that renews the certificates it issued, start the EST server
from README.md with `--ca-dir DIR --tls-trust-issued` added.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the table above, most of this can shrink:

  • The table covers 352-356, 358-360 and 374-378.
  • 366-369, 374-377, 387-388 and 395-397 repeat return codes that types.h, keygen.h and client.h already state.

Two sentences are also not quite right:

  • 358-360: a dev_id-only key is not always in host memory. wolfcert_key_export_der() refuses one whose device kept the private half.
  • 378: "therefore sign while another accelerates the connection" holds only for a key with a key_id. A dev_id-only key signs its handshake on the default devId (http.c:971).

Suggested replacement:

The `key_id` bytes are opaque to wolfCert. They reach the backend in the
wolfCrypt key's `id` field, as with wolfPKCS11, wolfHSM and the hardware
ports, and the backend decides what they mean (a PKCS#11 `CKA_ID`, a TPM
handle, a key-store slot). The backend may rename the key, as a TPM does
when it picks a transient handle; `wolfcert_key_id` returns the id in use.
wolfSSL also hands the backend public-key operations on that id, such as
the check of its own RSA signature in TLS, so the backend must serve those
too.

The default devId starts as `WOLFCERT_DEFAULT_DEVID`: `WC_USE_DEVID` when
wolfSSL defines it, as the NXP EdgeLock port does, else `INVALID_DEVID`. A
build may define it in `user_settings.h`, and `wolfcert_set_default_dev_id`
changes it at run time. With `INVALID_DEVID`, TLS still keeps a devId
wolfSSL picks itself (CAAM, ARIA, MAXQ10xx). The built-in test server always
runs in software.

For TLS client authentication, give the key as PEM or DER in `client_key`,
or as a handle in `client_key_obj`; only a handle can carry a `key_id`. EST
`/simplereenroll` passes the key being renewed as the handle.

A key with a `key_id` is never exported, so persist its id and the issued
certificate. `wolfcert_key_from_id` rebuilds the handle from those two,
taking the public half from the certificate, and the handle then serves for
TLS client authentication and re-enrollment.

RSA, ECC and ML-DSA keys take a `key_id`; Ed25519 and Ed448 need a wolfSSL
newer than 5.9.4 (`wc_ed25519_init_id`, `wc_ed448_init_id`). SCEP does not
take one, because its PKCS#7 code needs the private key as DER. A `key_id`
needs wolfSSL built with `WOLF_CRYPTO_CB` and `WOLF_PRIVATE_KEY_ID`;
`examples/enroll_cryptocb.c` shows the registration.

`examples/enroll_tpm.c` enrolls and re-enrolls over EST with an ECC, RSA or
ML-DSA key in a TPM. It needs a wolfTPM whose CryptoCb reads a 4-byte
`key_id` as a persistent or transient handle. A key generated under a
persistent handle is stored there. Under `0x80000000`
(`WOLFTPM2_KEYID_TRANSIENT`) the TPM picks a transient handle, and a TPM
reset drops the key, as does `/dev/tpmrm0` when the process exits. An older
wolfTPM generates the key in software, which `wolfcert_key_generate`
refuses. ML-DSA needs a TPM with the v1.85 commands, such as wolfTPM's
fwTPM. For a test CA that renews the certificates it issued, start the EST
server from README.md with `--ca-dir DIR --tls-trust-issued` added.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Replaced the body with your text, keeping one clause: wolfcert_cleanup restores the default devId, which no header says.

Comment thread src/internal.c Outdated
}
#endif /* WOLFCERT_HAVE_ECC */

int wolfcert_key_id_check(const uint8_t* id, size_t id_len, int dev_id,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since 66de97f removed the http.c caller, check_key_id() in keygen.c is the only caller left, and it always passes "keygen". The key_id checks are also split between the two functions: check_key_id() handles key_id_len == 0, and this function handles NULL, the length cap and the devId. Could this move into check_key_id() and come out of internal.h?

static int check_key_id(const WolfCertKeyCfg* cfg, int dev_id)
{
    int rc = wolfcert_dev_id_check(dev_id, "keygen");

    if (rc != WOLFCERT_OK)
        return rc;
    if (cfg->key_id_len == 0)
        return cfg->key_id == NULL ? WOLFCERT_OK
               : WOLFCERT_ERR(WOLFCERT_ERR_BAD_ARG, "keygen",
                              "key_id is set but key_id_len is 0");
    if (cfg->key_id == NULL || cfg->key_id_len > WOLFCERT_KEY_ID_MAX_LEN)
        return WOLFCERT_ERR(WOLFCERT_ERR_BAD_ARG, "keygen",
                            "key id must be 1..%d bytes",
                            WOLFCERT_KEY_ID_MAX_LEN);
    if (dev_id == INVALID_DEVID)
        return WOLFCERT_ERR(WOLFCERT_ERR_BAD_ARG, "keygen",
                            "key id needs a CryptoCb device id");
#ifndef WOLFCERT_USE_KEY_ID
    return WOLFCERT_ERR(WOLFCERT_ERR_UNSUPPORTED, "keygen",
                        "wolfSSL lacks WOLF_CRYPTO_CB or WOLF_PRIVATE_KEY_ID");
#else
    return WOLFCERT_OK;
#endif
}

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved into check_key_id() as suggested; wolfcert_key_id_check() is gone from internal.c and internal.h.

Comment thread src/internal.h Outdated
#define WOLFCERT_USE_KEY_ID
#endif

static inline int wolfcert_devid_is_cb(int dev_id)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its only caller is wolfcert_key_id_check(), and the body is dev_id != INVALID_DEVID. The name made sense when INVALID_DEVID meant "the default"; now the plain comparison reads better. With the check_key_id() change above it has no callers left and can go.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed; the check is a plain dev_id == INVALID_DEVID now.

The test server is about to hand out its CA private key in a
WolfCertBuffer, and freeing that with wolfcert_buffer_free() leaves the
key bytes in freed heap. Export the wiping variant the library already
uses internally. wolfcert_buffer_free() stays a plain free, so
certificate and response buffers pay no wiping cost.
Drop WolfCertStoreOps, wolfcert/store.h, src/store.c with its POSIX and
in-memory backends, the WOLFCERT_ENABLE_POSIX_STORE / --enable-posix-store
option and the WOLFCERT_HAVE_POSIX_STORE / WOLFCERT_NO_POSIX_STORE check
in check_config.h.

Nothing on the client side used the store: enroll, the CLI client, the
examples and the Zephyr sample all handle their own files. The key and
cert helpers were wolfcert_key_to_pem / wolfcert_key_from_pem plus one
vtable call, which applications can already make. The vtable could not
help where persistence is hard on a device either: a renewal has to
replace the certificate and key together, which per-object writes cannot
guarantee across a power cut, and a key held in a CryptoCb backend cannot
be exported into it. Once in 1.0 it would have been frozen ABI; a store
can still be added later without breaking anyone.

The test server was the only user, for CA persistence. Its config loses
ca_store and gains ca_cert / ca_key (PEM or DER, copied at start; both
NULL generates a CA, one without the other is WOLFCERT_ERR_BAD_ARG), and
wolfcert_server_get_ca() copies out the CA a server issues from, so a
caller can keep a generated one for the next start. wolfcert_ca_load()
now takes the two buffers and wolfcert_ca_save() is gone. The key is
decoded and re-encoded, so a PKCS#8 RSA or ECC key comes back out under
the PEM label that matches its body; a DER certificate or key with
trailing bytes is refused rather than half-read.

Removing ca_store from the middle of WolfCertServerCfgSrv breaks the ABI;
the SOVERSION bump planned for 1.0 covers it.

test_server_ca_store becomes test_server_ca and covers the DER and PEM
round trip, a half or empty pair, the get_ca arguments, every algorithm
reloading from both encodings, a PKCS#8 key, an ECC key without its
public point, a padded certificate or key, mixed encodings, get_ca on a
split-RA SCEP server, and the OOM sweep on the load path. The
integration tests share one CA per process, minted with mint_self_id()
and set through TEST_CA_CFG in tls_test_util.h, instead of a memory
store. test_store and the Zephyr wolfcert.unit.store suite are removed.
The script started its test servers on fixed ports (18086 to 18099)
and moved 100 up when one was busy. Its readiness probe could reach
another run's server on that port before its own server had failed to
bind, so two build directories testing at once enrolled against each
other's CAs and failed a dozen cases.

wolfcert-server now accepts --listen ADDR:0 and prints the port the
kernel picked, which the library already reports through
wolfcert_server_port(). The script binds port 0 everywhere and reads
the port from that line, so the retry loops go away. parse_listen also
stops taking a port with trailing characters, such as 80x, as 80.

Eight copies running concurrently pass all 86 cases, three rounds in a
row; four copies of the old script fail 8 to 16 cases each.
wolfCert never registers a CryptoCb or calls one directly; it only passes
the application's devId to wolfCrypt, which ignores it when wolfSSL lacks
WOLF_CRYPTO_CB. Requiring the callback layer made every user pay for it,
including software-only builds on small targets.

Drop WOLF_CRYPTO_CB from check_config.h and from the CMake and autoconf
feature probes. Without it wolfCert builds and every key runs in
software. CMake probes the symbol separately to skip the CryptoCb
example, which now fails with a clear #error if built anyway.

CI gains a no-cryptocb wolfSSL profile and a -Werror job that builds
against it with the examples on, in the PR matrix and in the nightly
one that seeds the PR cache and tracks wolfSSL master. The canonical
full -Werror job turns the examples on as well, so enroll_cryptocb.c
compiles in CI.
WolfCertKeyCfg.key_label was copied into the key handle and never read,
so a key generated with a dev_id had no way to name its storage in the
backend. Every backend wolfSSL ships (wolfPKCS11, wolfHSM and the
hardware ports) identifies a key by the byte id that the wc_*_init_id
functions carry, not by a label.

key_label is removed and key_id plus key_id_len are appended to
WolfCertKeyCfg. This changes the struct layout, which is accepted since
the field never worked. A key_id needs a CryptoCb dev_id and is at most
WOLFCERT_KEY_ID_MAX_LEN (32) bytes, matching wolfSSL's ECC_MAX_ID_LEN.
Key generation passes it to wc_ecc_init_id, wc_InitRsaKey_Id or
wc_MlDsaKey_InitId, so the backend generates the key under that id.
Ed25519 and Ed448 return WOLFCERT_ERR_UNSUPPORTED for now.

Key ids need wolfSSL's WOLF_CRYPTO_CB and WOLF_PRIVATE_KEY_ID, which
wolfSSL defines with the former unless NO_WOLF_PRIVATE_KEY_ID is set.
Neither is required: without them a key_id returns
WOLFCERT_ERR_UNSUPPORTED and the id-based init calls are compiled out,
so builds that do not use the feature do not pay for it.

When a device declines key generation, wolfCrypt generates the key in
software instead and the call still succeeds. A new host_priv entry in
the key algorithm table reports whether the private half sits in host
memory, and key generation with a key_id fails with
WOLFCERT_ERR_UNSUPPORTED in that case rather than return a handle that
names a key the backend does not hold. The ELS port, for example,
declines every curve but P-256.

A key with an id is never exported: wolfcert_key_to_pem and
wolfcert_key_to_der fail with WOLFCERT_ERR_UNSUPPORTED instead of
serializing a key struct that holds no private scalar.

wolfcert_key_from_id rebuilds a handle for a key that already lives in
the backend, which re-enrollment after a reboot needs: the CSR carries
the public key and is signed by the backend. A backend such as NXP
EdgeLock cannot return the public key after generation, so it comes from
the issued certificate, PEM or DER, read the same way as the certificate
being renewed: the first certificate of a PEM chain, and DER may be
followed by padding. The key must have a curve or RSA size key
generation makes (P-256, P-384 or P-521; 2048, 3072 or 4096), or the
call returns WOLFCERT_ERR_UNSUPPORTED as key generation does, and a
non-zero param that names another one is WOLFCERT_ERR_BAD_ARG. A
certificate whose key is not of cfg->type is WOLFCERT_ERR_PARSE.
wolfcert_key_id returns the id of a key.

The key algorithm table gains a pub_decode entry for from_id.
test_keygen covers a declined key generation for ECC, RSA and each
ML-DSA level, an empty key_id_len, the
from_id argument and input checks, an RSA-1024 and a P-224 certificate,
and the UNSUPPORTED results in a build without key ids.
The HTTP layer only accepted the TLS client key as PEM or DER bytes, so
a key held behind a CryptoCb could not authenticate a connection. EST
/simplereenroll exported the current key with wolfcert_key_to_pem to
use it as the mTLS identity, which fails for any key that cannot leave
its backend, so renewing such a key was broken before any network
traffic.

WolfCertServerCfg, WolfCertHttpRequest and WolfCertHttpSessionCfg gain
an appended client_key_src and client_key_dev_id, mirroring wolfSSL's
split between a context's devId and its private key's devId:
- WOLFCERT_CLIENT_KEY_BUFFER (0, the default for a zeroed struct):
  client_key is PEM or DER and used in software, as before.
- WOLFCERT_CLIENT_KEY_BUFFER_DEV: client_key is PEM or DER, and
  wolfSSL_CTX_SetDevId puts the connection's crypto, the client key's
  included, on client_key_dev_id. This is the acceleration case.
  Without WOLF_CRYPTO_CB it returns WOLFCERT_ERR_UNSUPPORTED.
- WOLFCERT_CLIENT_KEY_ID: client_key holds a key id, loaded with
  wolfSSL_CTX_use_PrivateKey_Id on client_key_dev_id, so the handshake
  signature runs in the backend. Without WOLF_CRYPTO_CB and
  WOLF_PRIVATE_KEY_ID it returns WOLFCERT_ERR_UNSUPPORTED.
An explicit source rather than a non-zero dev_id selects the device, so
a zeroed struct keeps today's behaviour and device id 0 stays usable.

wolfcert_http_request and wolfcert_http_session_open check the source
before connecting. A source other than _BUFFER needs client_cert,
client_key, a CryptoCb client_key_dev_id and an https:// URL, and _ID an
id of 1 to WOLFCERT_KEY_ID_MAX_LEN bytes; anything else, or an unknown
source, is WOLFCERT_ERR_BAD_ARG, so a request cannot silently go out
without the client authentication the caller asked for. The id rules are the ones
key generation applies, from one helper. test_http covers each case.

wolfcert_est_simple_reenroll passes a key with a key_id by id instead
of exporting it. Any other key is exported as DER rather than PEM, since
wolfSSL turns a PEM key back into DER anyway, with the _DEV source when
it has a dev_id and wolfSSL has WOLF_CRYPTO_CB, so the handshake runs on
the device its CSR was signed with. test_est_mtls_roundtrip re-enrolls a
software key of every compiled-in type to cover the untyped DER.

SCEP still takes the signer and recipient key as DER for PKCS#7, and
wolfSSL's PKCS#7 code carries a devId but no key id, so a backend could
not tell which key to use. Every SCEP entry point now refuses a key
with a key_id with WOLFCERT_ERR_UNSUPPORTED next to its RSA check,
before the self-signed signer certificate is signed in the backend.
SCEP now exports its signer key with wolfcert_key_export_der, which
refuses such a key as well, instead of keeping its own copy of the
export.

With a key_id, a failed wolfcert_client_enroll, or a
wolfcert_client_reenroll that generated a new key, frees the handle but
leaves the key in the backend. client.h now says so.
test_est_devid_roundtrip registers a mock CryptoCb key store that keeps
ECC, RSA and ML-DSA keys by id and never hands them out. For each key
type, and each ML-DSA level wolfSSL has, it generates a key in the
store, checks that export is refused, builds a CSR, enrolls over a
bootstrap mTLS identity, rebuilds the handle by id from the issued
certificate as PEM, as PEM ahead of another certificate and as DER
padded like a fixed-size flash slot, re-enrolls with that key as the
mTLS identity, and enrolls again with its id as the client key, both
one-shot and over a keep-alive EST session. A param or ML-DSA level
that does not match the certificate is refused.
The store counts the private-key operations it performs, and the test
checks that the CSR and TLS signatures went through it. It also checks
the key_id argument errors and that the four one-shot SCEP calls and the
three SCEP session calls refuse a key with a key_id without asking the
store for a signature first. The session calls run over a loopback
listener that never answers, since the refusal comes before any I/O.

For the client key sources, the bootstrap PEM key enrolls once in
software, without the store seeing a signature request, and once with
WOLFCERT_CLIENT_KEY_BUFFER_DEV, where the store is asked first and
declines. The store counts only signature requests, since wolfSSL sends
one-shot hashes to the first registered device on its own. An unknown
source is refused with WOLFCERT_ERR_BAD_ARG. A key with the store's
dev_id but no key_id then re-enrolls, and the store is asked for both
the CSR signature and the handshake's, which shows the _DEV source.

The mock answers public RSA operations on a stored key as well, because
wolfSSL checks its own RSA signature in the handshake with the id-only
key, which carries no modulus. Its key generation declines a key with
no id, such as a TLS ephemeral key under the _DEV source.

The test skips, with exit code 77, when wolfSSL lacks WOLF_CRYPTO_CB or
WOLF_PRIVATE_KEY_ID.
ARCHITECTURE section 4.2 showed a key_label and said every operation on
a dev_id key, including TLS client auth and SCEP signing, ran in the
backend, and told integrators to persist the label. It now shows
key_id, says which operations reach the backend, that the backend must
also serve public operations on the id, and that a dev_id without a
key_id only offloads the computation while the key stays in host
memory and can be exported. A table lists the three client_key_src
values for TLS client authentication. It says the key cannot be
exported, that TLS client auth needs only the id and the certificate
while re-enrollment rebuilds a handle with wolfcert_key_from_id, that
Ed25519, Ed448 and
SCEP do not support a key_id yet, and that a key_id needs
WOLF_CRYPTO_CB and WOLF_PRIVATE_KEY_ID. Section 4.7, CONTRIBUTING.md,
the AGENTS.md porting hooks and the wolfSCEP migration guide follow.
wolfSSL now has wc_ed25519_init_id and wc_ed448_init_id, and its TLS
layer builds Ed25519 and Ed448 device keys for
wolfSSL_CTX_use_PrivateKey_Id. wolfCert refused a key_id for both
because neither existed.

When wolfSSL defines ED25519_MAX_ID_LEN or ED448_MAX_ID_LEN, which come
with those functions, key generation and wolfcert_key_from_id pass the
id to them, and the key algorithm table gains the pub_decode and
host_priv entries for both. A version check would not do: wolfSSL
master still reports 5.9.4. Older wolfSSL keeps returning
WOLFCERT_ERR_UNSUPPORTED.

wolfSSL does not hand Ed448 key generation to a CryptoCb yet, so it runs
in software and the host_priv check refuses the key. An Ed448 key that
already exists in the backend works through wolfcert_key_from_id, and
generation needs no change here once wolfSSL dispatches it.

The mock key store in test_est_devid_roundtrip generates and signs
Ed25519 keys and signs Ed448 ones. Ed25519 runs the same flow as the
other types; Ed448 checks that generation is refused, provisions a key
in the store with a self-signed certificate, and continues from
wolfcert_key_from_id. Both skip on a wolfSSL without the id init.
test_keygen also checks that a declined Ed25519 generation is refused.
Removing WolfCertKeyCfg.key_label, and appending fields to
WolfCertKeyCfg, WolfCertServerCfg, WolfCertHttpRequest and
WolfCertHttpSessionCfg, changes struct layouts that the library and its
callers share. A binary built against the v0.1.0 libwolfcert.so.0 must
not load this one.

Autoconf moves to -version-info 1:0:0, since an interface was removed.
CMake now sets VERSION and SOVERSION itself rather than deriving them
from the project version, so both build systems install
libwolfcert.so.1.0.0 with soname libwolfcert.so.1. Before, CMake named
the file after the project version (0.1.0) and autoconf after libtool's
(0.0.0). The release version stays 0.1.0.

The two are set by hand in two files, so the build-system parity check
now fails when CMake's VERSION or SOVERSION differs from what libtool
derives from -version-info.

CONTRIBUTING.md's append-only rule for public structs now holds within
one shared library version, and removing or moving a field takes a
version bump.
A CryptoCb device can give a key it generates another id than the one it
was asked for. A TPM does so for a transient key, whose handle it picks
itself. wolfcert_key_generate now copies the id the device left in the
wolfCrypt key back into the WolfCertKey, so wolfcert_key_id, TLS client
authentication by id and a later wolfcert_key_from_id reach the key the
device made. An id the device left empty or longer than
WOLFCERT_KEY_ID_MAX_LEN fails with WOLFCERT_ERR_CRYPTO. The device holds
the key by then, so *out_key still gets the handle, under the requested
id, for the caller to delete it there; every other failure leaves
*out_key NULL.

wolfcert_client_enroll and wolfcert_client_reenroll freed a key they had
generated under a key_id when the request failed, and told the caller to
delete it in the backend. With an id the device picked, the caller cannot
name that key, and a retry loop fills the TPM with transient keys. Both
now hand such a key back in out_key on failure too; keys without a key_id
are still freed. Both set *out_key to NULL before anything can fail, so
the caller always finds a defined value there, and refuse a protocol
other than EST with WOLFCERT_ERR_UNSUPPORTED before generating a key, so
a SCEP config does not leave one in the backend.

test_keygen covers a device that renames the key and one that leaves no
id, and est_devid_roundtrip a failed enroll and rekey that hand back a
key_id key but not a software one, early failures that leave out_key
NULL, and a SCEP config that generates no key.
The test server generated a new CA on every start, and it checked client
certificates only against tls_client_ca_pem, which also demands one on
every handshake. A client could therefore neither renew a certificate
this server issued once it restarted, nor enroll anonymously and renew
over mTLS from the same server.

WolfCertServerCfgSrv gains tls_client_trust_issued, appended to keep the
layout: the server asks EST clients for a certificate and accepts one
its own CA issued, without demanding one, so /simplereenroll can renew
it. Such a certificate does not authenticate /simpleenroll, so next to
tls_client_ca_pem alone it cannot enroll a new identity, and a
connection whose certificate cannot be checked, such as a resumed
session, cannot enroll either. Basic or anonymous enrollment still admit
such a client, since they authenticate the request on their own. A
self-signed client certificate pinned through tls_client_ca_pem, which
wolfSSL with OPENSSL_ALL reports as ASN_SELF_SIGNED_E, and one whose key
algorithm differs from that of the CA (ASN_SIG_OID_E) count as not
issued here. With no Basic user, client CA or anonymous enrollment the
server only renews, so it needs ca_cert and ca_key, since a new CA has
issued nothing. wolfcert_server_start() refuses the option for SCEP,
without KEEP_PEER_CERT, and alone without ca_cert, all before it loads
or creates a CA. wolfcert-server gets --tls-trust-issued, which sets the
new field, and --ca-dir DIR, which must name an existing directory owned
by the user and not writable by others. It loads ca.cert.der and
ca.key.der from DIR into ca_cert and ca_key or, when DIR holds neither,
saves the CA the server generated there through
wolfcert_server_get_ca(), the key first and with mode 0600, each through
a temporary file and a rename. Both files must be regular files of that
user that others cannot write, the key one that others cannot read
either, and a DIR holding one file without the other is refused. The CLI
leaves the option's checks to wolfcert_server_start() and prints its
message.

Every CA wolfCert generates has the same subject, and neither the CA nor
the certificates it issued carried key identifiers, so wolfSSL found an
issuer by name only and took the first match. With tls_client_ca_pem
naming another wolfCert CA, certificates from one of the two then failed
TLS verification. Generated CAs now carry a subject key identifier and
issued certificates the matching authority key identifier. A loaded CA
without one, or with one that is not KEYID_SIZE bytes, which wolfSSL
would hash so that it no longer matches, issues without an authority key
identifier. That is decided once, when the CA is generated or loaded.

test_est_mtls_roundtrip covers an anonymous enroll followed by an mTLS
reenroll, a foreign certificate refused in the handshake, an anonymous
reenroll refused with 403, a renewal-only server, and a server whose
client CA is a second wolfCert CA: the certificate from that CA enrolls,
one the server issued renews but cannot enroll, also not over a resumed
TLS session (403 when SESSION_CERTS keeps its certificate, 500 when
there is none), and enrolls once Basic is configured, and a client
without a certificate is refused. A pinned self-signed client
certificate enrolls next to tls_client_trust_issued, and a renewal-only
server without ca_cert is refused. A foreign certificate is checked to
fail without an HTTP answer, since TLS 1.3 reports the refusal on the
first read in some builds. test_server_ca checks the key identifiers,
including a loaded CA without one and one with an 8-byte one.
cli_proto_scoping checks that a --ca-dir server keeps its CA across a
restart, that it renews a certificate it issued only with
--tls-trust-issued, and that wolfcert-server refuses --tls-trust-issued
for SCEP, alone without --ca-dir or with an empty one, and a --ca-dir
that is missing, not a directory, writable by others, holding the
certificate without the key or a CA key others can read, and that the CA
key is saved with mode 0600. Against a wolfSSL without KEEP_PEER_CERT it
expects that refusal instead and skips the renewal.
examples/enroll_tpm.c enrolls, re-enrolls and rotates a key that stays in
a TPM, using wolfTPM's CryptoCb with the key's TPM handle as key_id.
enroll generates the key in the TPM, either persisted at a free persistent
handle or, for 0x80000000, loaded at a transient handle the TPM picks and
the example prints. reenroll rebuilds the key handle from the certificate
with wolfcert_key_from_id in a new process and authenticates
/simplereenroll with it, optionally moving to a new key and evicting or
unloading the old one. It refuses a persistent handle that is in use or
that the TPM cannot check, and any other transient handle for a new key, removes the key it generated
when the enrollment fails, and reports an old key it cannot remove. It
refuses to rotate a persistent key to a transient one, which would not
survive a TPM reset. Key types are ECC P-256 and P-384, RSA-2048 and, with
a wolfTPM built for TPM 2.0 v1.85, ML-DSA-44, -65 and -87. It needs a
wolfTPM whose CryptoCb resolves key ids; it still builds against an older
one, where wolfcert_key_generate refuses the software key it would get.

A certificate is written to a temporary file created exclusively, flushed
and fsynced, then renamed into place, so renewing with OUT_CERT equal to
CERT cannot lose the old certificate. One that cannot be kept goes to
stderr: the renewed certificate when only the write failed, or one to
revoke when its new key was evicted again.

CMake builds it when find_package(wolftpm) succeeds and the wolfTPM has
its CryptoCb and wolfSSL key ids, and otherwise skips it with a message. It runs against a TPM
or wolfTPM's fwTPM, with wolfcert-server --ca-dir DIR --tls-trust-issued
as the CA. A transient key outlives the process only on a TPM without a
resource manager, such as the fwTPM.
examples/enroll_tpm.c only built where a developer had a wolfTPM
installed, and no CI job had one, so a change that broke the example, or
a wolfTPM change that broke key ids, went unnoticed.

tests/interop/tpm_wolftpm.sh drives the example against fwtpm_server and
wolfcert-server for ECC P-256 and P-384, RSA-2048 and ML-DSA-44/65/87:
enroll, an occupied handle refused, a failed enroll that leaves the
handle free, renewal in place after a restart of both servers, a rekey
whose certificate cannot be written, a rekey that evicts the old key,
the evicted key failing to renew, the rotated key renewing, a persistent
key refused a transient successor, and a transient key renewed from
another process. The fwTPM holds 8 persistent objects, so each key type
runs against its own NV state.

scripts/ci/build-wolftpm.sh builds wolfTPM's library and fwtpm_server
with WOLFTPM_V185 forced on, so a wolfSSL without ML-DSA fails the build
instead of the test. build-wolfssl.sh gains the wolftpm config: the
canonical line plus --enable-wolftpm, which exports the sp_* API the
fwTPM links, --enable-pkcallbacks and WC_RSA_NO_PADDING for its raw RSA.

The tpm-interop action runs it all and fails when the example is not
built, so a skipped probe cannot pass. pr.yml runs it against the merge
of wolfTPM #638, the first commit with key ids, until a wolfTPM release
has them; interop.yml runs it nightly against wolfTPM master and seeds
the wolftpm wolfSSL cache the PR job restores.
WOLFCERT_DEVID_SOFTWARE was -1, which wolfCrypt does not treat as "no
device": INVALID_DEVID is -2, so every key, RNG, Cert and PKCS#7 object
wolfCert initialized for software still went through a CryptoCb device
lookup, and a WOLF_CRYPTO_CB_FIND callback was handed -1 as a device id.
It also skipped wolfCrypt's default-device handling, which only kicks
in for INVALID_DEVID.

Drop the wolfCert constant and use wolfSSL's INVALID_DEVID throughout,
which integrators already know from every other wolfSSL API.
wolfcert/types.h now includes <wolfssl/wolfcrypt/types.h> so the macro
is available to applications through <wolfcert/wolfcert.h>.

This is a source break for code that used WOLFCERT_DEVID_SOFTWARE; the
shared library version was already bumped to 1 on this branch.
On a part with a crypto accelerator, such as the NXP EdgeLock (ELS/PKC)
on the RW612, the TLS connection, SCEP's PKCS#7 and the keys wolfCert
generates in software should all run on the accelerator, whether the
private key lives in a key slot or in host memory. wolfCert owns the
WOLFSSL_CTX, so the application could not set its devId, and every
software key, RNG and PKCS#7 object wolfCert created was pinned to
software.

Add wolfcert_set_default_dev_id() / wolfcert_default_dev_id(), next to
the default heap hint. The default starts as WC_USE_DEVID when wolfSSL
defines it with WOLF_CRYPTO_CB, which the EdgeLock port does, so such a
build needs no application change. It does not fall back to
wc_CryptoCb_DefaultDevID(), which without WC_USE_DEVID picks the first
registered device and could hand bulk crypto to a TPM. Setting a devId
on a wolfSSL without WOLF_CRYPTO_CB returns WOLFCERT_ERR_UNSUPPORTED,
and one with no registered device returns WOLFCERT_ERR_BAD_ARG, since
wolfCrypt would otherwise run everything in software without a word.
The check is skipped under WOLF_CRYPTO_CB_FIND, whose find callback may
map an unregistered devId to a device. wolfcert_cleanup() restores the
start value, since wolfCrypt_Cleanup() unregisters every device.

Where it applies:
- A key generated or imported with dev_id = INVALID_DEVID takes the
  default as its device when it is created, so its keygen, CSR
  signature and RNG all use it and wolfcert_key_dev_id() reports it.
  That includes a key_id key, which goes to the default device. A key
  keeps its device when the default changes later.
- The client TLS context gets the default devId, so a PEM or DER client
  key, which wolfSSL decodes onto the context's devId, signs there too.
  The context is left alone when the default is INVALID_DEVID, keeping
  the devId wolfSSL_CTX_new picks for CAAM, ARIA or MAXQ10xx.
- EST /simplereenroll runs the connection of a key without a key_id on
  that key's own dev_id, so it still signs on its device now that
  WOLFCERT_CLIENT_KEY_BUFFER_DEV is gone.
- The SCEP helpers take the devId explicitly: the client signs and
  decrypts on its key's device and encrypts and verifies on the default;
  the built-in server passes INVALID_DEVID, generates its keys through
  the internal wolfcert_key_generate_on(), and stays in software. The
  certs-only PKCS#7 helpers do no private-key work and stay in software.

A key_id key keeps signing in client_key_dev_id through
wolfSSL_CTX_use_PrivateKey_Id, so one device can hold the key while
another accelerates the connection. A client_key_dev_id of INVALID_DEVID
names the default device, as dev_id does in WolfCertKeyCfg.

The new test registers an accelerator mock next to the key store and
checks that it sees no work by default; sees the TLS crypto and the PEM
key's signature once set; becomes the device of a key made with
INVALID_DEVID and signs its CSR; and sees no signature for a key_id key,
which still signs in the store. A key_id key made with INVALID_DEVID
lands in the default device. A SCEP PKCSReq with an accelerator default
runs its RSA signatures, decryption, encryption and verification there,
and an unregistered devId is refused.
INVALID_DEVID in WolfCertKeyCfg.dev_id and client_key_dev_id meant "the
default devId", the opposite of wolfCrypt, where it means software. It
left no way to ask for a software key while a default was set, which is
why the test server needed wolfcert_key_generate_on(), and the devId was
decided in several places with different rules: keys copied the default
when made, connections and PKCS#7 read it on every call, EST reenroll
ran the whole TLS context on a software key's own devId, and the SCEP
client signed on its key's.

Caller devIds are now used as given. dev_id = INVALID_DEVID is software,
and a caller who wants the default device writes dev_id =
wolfcert_default_dev_id(). wolfcert_key_generate() and
wolfcert_key_from_id() refuse a devId no device is registered under,
unless wolfSSL has WOLF_CRYPTO_CB_FIND, with WOLFCERT_ERR_BAD_ARG
(WOLFCERT_ERR_UNSUPPORTED without WOLF_CRYPTO_CB), so a zero-initialized
cfg, which names device 0, fails visibly; a key_id without a devId is
refused as before. wolfcert_key_from_pem() loads a software key, and
wolfcert_key_to_pem() and _to_der() refuse a key whose device keeps the
private half with WOLFCERT_ERR_UNSUPPORTED, instead of failing inside
the wolfCrypt export.

The default devId now covers only what wolfCert creates itself and has
no caller field for: the TLS context and SCEP's PKCS#7 objects and RNGs.
Its start value is WOLFCERT_DEFAULT_DEVID, WC_USE_DEVID with
WOLF_CRYPTO_CB and INVALID_DEVID otherwise, which user_settings.h may
override; any other value without WOLF_CRYPTO_CB is an #error. EST
reenroll and the SCEP client use the default too, so tls_dev_id, the
_dev session opens, in_signer_dev_id, wolfcert_devid_or_default() and
wolfcert_key_generate_on() are gone.

The TLS client key can be given as a key handle instead of bytes:
client_key_obj in WolfCertServerCfg and both HTTP structs, set instead
of client_key and borrowed while the connection opens. A key with a
key_id goes to wolfSSL_CTX_use_PrivateKey_Id() on its own devId, any
other key is loaded as DER. That replaces client_key_src and
client_key_dev_id. wolfSSL signs with a key loaded from a buffer on the
context's devId, the default, and uses privateKeyDevId only for a key
given by id, so a key held in one device still signs there while another
accelerates the connection. client_key_obj next to client_key, without
client_cert or on an http:// URL is WOLFCERT_ERR_BAD_ARG. A key of a
type wolfcert_key_from_id() does not accept, such as a P-224 key in a
TPM, can no longer be the TLS client key by id. EST /simplereenroll
passes the key being renewed as the handle.

Every field and function removed here is new on this branch, so nothing
that shipped changes.

test_est_devid_roundtrip covers a software key handle as the mTLS
identity, with no device signature, and refused next to client_key; a
software key that stays off the default device until its cfg names
wolfcert_default_dev_id(); a key_id without a devId and an unregistered
devId refused; a dev_id key without a key_id signing its renewal CSR on
its device and the handshake on the default; and a software key handle
signing its handshake on the default device. test_http checks the
client_key_obj argument rules, test_keygen registers its device in the
build without key ids so the key-id check is the one that fails, and the
SCEP default-devId check expects a software key while its PKCS#7 work
runs on the default.
@Frauschi

Copy link
Copy Markdown
Member Author

README now lists examples/enroll_tpm.c, with your sentence on building it against wolfTPM.

@Frauschi

Copy link
Copy Markdown
Member Author

4171437 passes on the FRDM-RW612 with the ELS key store: enroll by key_id, wolfcert_key_from_id from the issued cert and reenroll over mTLS, with all 3 signatures in the slot and none on the host. The stock EST sample enrolls too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants