Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions .github/actions/tpm-interop/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# SPDX-License-Identifier: GPL-3.0-or-later
name: tpm-interop
description: >
Build wolfSSL (config `wolftpm`, cached), wolfTPM with its fwTPM at
`wolftpm-ref`, and wolfCert with the examples, then run
tests/interop/tpm_wolftpm.sh.

inputs:
wolfssl-ref:
description: "wolfSSL git ref to build"
required: false
default: master
wolftpm-ref:
description: "wolfTPM git ref to build (branch, tag or SHA)"
required: true
save:
description: "Save the wolfSSL cache after a miss"
required: false
default: "false"

runs:
using: composite
steps:
- name: Install build dependencies
shell: bash
run: |
sudo apt-get update
sudo apt-get install -y build-essential autoconf automake libtool \
cmake pkg-config python3

- name: Build/restore wolfSSL (wolftpm)
uses: ./.github/actions/build-wolfssl
with:
config: wolftpm
ref: ${{ inputs.wolfssl-ref }}
save: ${{ inputs.save }}

- name: Build wolfTPM and its fwTPM
shell: bash
run: |
set -euo pipefail
scripts/ci/build-wolftpm.sh --wolfssl "$WOLFSSL_PREFIX" \
--ref "${{ inputs.wolftpm-ref }}" \
--prefix "$RUNNER_TEMP/wolftpm" --src "$RUNNER_TEMP/wolftpm-src"
echo "WOLFTPM_PREFIX=$RUNNER_TEMP/wolftpm" >> "$GITHUB_ENV"

- name: Build wolfCert with the TPM example
shell: bash
run: |
set -euo pipefail
cmake -S . -B build \
-DWITH_WOLFSSL="$WOLFSSL_PREFIX" \
-DWOLFCERT_ENABLE_EXAMPLES=ON -DWOLFCERT_WERROR=ON \
-Dwolftpm_DIR="$WOLFTPM_PREFIX/lib/cmake/wolftpm"
cmake --build build -j "$(nproc)"
test -x build/examples/example_enroll_tpm

- name: Run tpm_wolftpm.sh
shell: bash
run: |
set -euo pipefail
export LD_LIBRARY_PATH="$WOLFSSL_PREFIX/lib:$WOLFTPM_PREFIX/lib:${LD_LIBRARY_PATH:-}"
FWTPM_SERVER="$WOLFTPM_PREFIX/bin/fwtpm_server" \
WOLFCERT_BUILD="$PWD/build" bash tests/interop/tpm_wolftpm.sh
12 changes: 12 additions & 0 deletions .github/workflows/interop.yml
Original file line number Diff line number Diff line change
Expand Up @@ -143,3 +143,15 @@ jobs:
bash tests/interop/est_stepca.sh; rc=$?
[ "$rc" -eq 77 ] && { echo "::notice::step-ca skipped (dep missing)"; exit 0; }
exit "$rc"

wolftpm-fwtpm:
name: wolfTPM fwTPM (wolfTPM master)
runs-on: ubuntu-latest
timeout-minutes: 25
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/tpm-interop
with:
wolfssl-ref: ${{ env.WOLFSSL_REF }}
wolftpm-ref: master
save: "true" # the only job on config wolftpm; pr.yml restores it
5 changes: 3 additions & 2 deletions .github/workflows/nightly.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,9 @@ jobs:
- { name: cmake-mldsa-44off, os: ubuntu-latest, build: cmake, wolfssl: mldsa-44off }
- { name: cmake-mldsa-65off, os: ubuntu-latest, build: cmake, wolfssl: mldsa-65off }
- { name: cmake-mldsa-87off, os: ubuntu-latest, build: cmake, wolfssl: mldsa-87off }
# Platform pieces compiled out (transport/store gates)
- { name: cmake-no-builtin-transport, os: ubuntu-latest, build: cmake, wolfssl: full, cmake_extra: "-DWOLFCERT_ENABLE_BUILTIN_TRANSPORT=OFF -DWOLFCERT_ENABLE_POSIX_STORE=OFF -DWOLFCERT_ENABLE_CLI=OFF -DWOLFCERT_ENABLE_SERVER=OFF" }
- { name: cmake-no-cryptocb, os: ubuntu-latest, build: cmake, wolfssl: no-cryptocb, cmake_extra: "-DWOLFCERT_WERROR=ON -DWOLFCERT_ENABLE_EXAMPLES=ON" }
# Platform pieces compiled out (transport gate)
- { name: cmake-no-builtin-transport, os: ubuntu-latest, build: cmake, wolfssl: full, cmake_extra: "-DWOLFCERT_ENABLE_BUILTIN_TRANSPORT=OFF -DWOLFCERT_ENABLE_CLI=OFF -DWOLFCERT_ENABLE_SERVER=OFF" }
# Constrained builds (unit tests only: single-thread / no-malloc)
- { name: cmake-static-mem, os: ubuntu-latest, build: cmake, wolfssl: static-mem, cmake_extra: -DWOLFCERT_ENABLE_SERVER=OFF, ctest_exclude: "http|tls|roundtrip" }
# No TLS and no test server over a static pool; stop_idle and get_cert
Expand Down
22 changes: 19 additions & 3 deletions .github/workflows/pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ jobs:
os: ubuntu-latest
build: cmake
wolfssl: full
cmake_extra: -DWOLFCERT_WERROR=ON
cmake_extra: -DWOLFCERT_WERROR=ON -DWOLFCERT_ENABLE_EXAMPLES=ON
- name: cmake-full-opensslextra
os: ubuntu-latest
build: cmake
Expand Down Expand Up @@ -94,6 +94,11 @@ jobs:
os: ubuntu-latest
build: cmake
wolfssl: rsa-min
- name: cmake-no-cryptocb
os: ubuntu-latest
build: cmake
wolfssl: no-cryptocb
cmake_extra: -DWOLFCERT_WERROR=ON -DWOLFCERT_ENABLE_EXAMPLES=ON
- name: cmake-no-des3
os: ubuntu-latest
build: cmake
Expand All @@ -115,7 +120,7 @@ jobs:
os: ubuntu-latest
build: cmake
wolfssl: mldsa-87off
# Platform pieces compiled out (the transport/store gates)
# Platform pieces compiled out (the transport gate)
- name: cmake-no-builtin-transport
os: ubuntu-latest
build: cmake
Expand All @@ -124,7 +129,6 @@ jobs:
# skip themselves.
cmake_extra: >-
-DWOLFCERT_ENABLE_BUILTIN_TRANSPORT=OFF
-DWOLFCERT_ENABLE_POSIX_STORE=OFF
-DWOLFCERT_ENABLE_CLI=OFF
-DWOLFCERT_ENABLE_SERVER=OFF
# Constrained builds (unit tests only: single-thread / no-malloc)
Expand Down Expand Up @@ -285,3 +289,15 @@ jobs:
run: |
scripts/ci/assert-configure-fails.sh \
--wolfssl-base "${{ github.workspace }}/.wolfssl-install"

tpm-interop:
name: wolfTPM fwTPM interop (pinned wolfTPM)
runs-on: ubuntu-latest
timeout-minutes: 25
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/tpm-interop
with:
wolfssl-ref: ${{ env.WOLFSSL_REF }}
# Merge of wolfTPM #638 (key ids); no release has it before v4.3.0.
wolftpm-ref: fe01b8ee096c862897c7efb4aa963c312e2bcc46
2 changes: 1 addition & 1 deletion .github/workflows/sanitizers.yml
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ jobs:
# No roundtrips: wolfSSL's asm crypto gives false Memcheck reports
# without a suppression file.
rc=0
for bin in test_smoke test_keygen test_csr test_store test_parse_negative \
for bin in test_smoke test_keygen test_csr test_parse_negative \
test_scep_msg; do
path="build/tests/$bin"
[ -x "$path" ] || { echo "skip (not built): $bin"; continue; }
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/zephyr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ jobs:
"${{ github.workspace }}/scripts/ci/twister-assert-ran.py" \
"$HOME/twister-unit/twister.json" \
wolfcert.unit.smoke wolfcert.unit.keygen wolfcert.unit.csr \
wolfcert.unit.csr_attrs wolfcert.unit.store \
wolfcert.unit.csr_attrs \
wolfcert.unit.parse_negative wolfcert.unit.scep_msg

- name: Start the host EST server
Expand Down
25 changes: 15 additions & 10 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ file. Changes to wolfCert itself follow `CONTRIBUTING.md`.
Most integration failures are a wolfSSL built without what wolfCert needs.
wolfCert requires **wolfSSL >= 5.9.4** and **hard-fails at configure time**
if the wolfSSL it finds lacks any of `HAVE_PKCS7`, `WOLFSSL_CERT_GEN`,
`WOLFSSL_CERT_REQ`, `WOLFSSL_CERT_EXT`, `WOLFSSL_KEY_GEN`, `WOLF_CRYPTO_CB`,
`WOLFSSL_CERT_REQ`, `WOLFSSL_CERT_EXT`, `WOLFSSL_KEY_GEN`,
`WOLFSSL_BASE64_ENCODE`, `WOLFSSL_ALT_NAMES` or `WOLFSSL_CERT_NAME_ALL`, was
built with `NO_AES` / `NO_SHA256`, or provides neither TLS 1.2 nor TLS 1.3.

Expand All @@ -41,6 +41,8 @@ built with `NO_AES` / `NO_SHA256`, or provides neither TLS 1.2 nor TLS 1.3.
`OPENSSL_EXTRA`, `OPENSSL_EXTRA_X509_SMALL` or `WOLFSSL_TEST_CERT`. A static
libwolfssl links them regardless. The OpenSSL compatibility layer itself is
not required.
- **Hardware keys** need `WOLF_CRYPTO_CB` (`--enable-cryptocb`). Without it
wolfCert builds, but keys always run in software.
- **ML-DSA** additionally needs `WOLFSSL_MLDSA_CHECK_KEY`, which
`--enable-mldsa` gives by default; it is lost with
`WOLFSSL_DILITHIUM_NO_CHECK_KEY` or `WOLFSSL_MLDSA_VERIFY_ONLY`.
Expand Down Expand Up @@ -91,12 +93,11 @@ install provides the library, the public headers, a generated
| `WOLFCERT_ENABLE_SERVER` | `--enable-server` | on | Minimal EST/SCEP test server |
| `WOLFCERT_ENABLE_CLI` | `--enable-cli` | on | `wolfcert-client`, `wolfcert-server` |
| `WOLFCERT_ENABLE_BUILTIN_TRANSPORT` | `--enable-builtin-transport` | on | POSIX socket transport; turn off on targets with no sockets |
| `WOLFCERT_ENABLE_POSIX_STORE` | `--enable-posix-store` | on | File-based cert/key store |
| `WOLFCERT_BUILD_SHARED` | (libtool `--enable-shared`) | on | Shared vs static library |
| `WOLFCERT_USER_SETTINGS` | `--enable-user-settings` | off | Read features from `user_settings.h` instead of the generated `options.h` |

A device build usually turns off the server and CLI, and the built-in
transport and POSIX store where the target has no sockets or filesystem.
transport where the target has no sockets.

## Configuration model

Expand Down Expand Up @@ -148,7 +149,7 @@ WolfCertServerCfg srv = {
.verify_server = 1,
};
WolfCertKeyCfg kcfg = { .type = WOLFCERT_KEY_ECC, .param = 256,
.dev_id = WOLFCERT_DEVID_SOFTWARE };
.dev_id = INVALID_DEVID };
WolfCertCertMeta meta = { .subject_dn = "CN=device-0001" };
WolfCertKey* key = NULL;
WolfCertBuffer cert = { 0 };
Expand Down Expand Up @@ -176,7 +177,8 @@ wolfcert_cleanup();
`wolfcert_client_reenroll` return `WOLFCERT_ERR_PENDING`.
- **Renewal:** `wolfcert_client_reenroll` (EST, authenticates with the
certificate being renewed) or `wolfcert_scep_renewal_req`.
- **Hardware keys:** `examples/enroll_cryptocb.c`.
- **Hardware keys:** `examples/enroll_cryptocb.c`, and `examples/enroll_tpm.c`
for a TPM through wolfTPM.

## Where to look

Expand All @@ -185,12 +187,11 @@ wolfcert_cleanup();
| `wolfcert/wolfcert.h` | Umbrella header, `wolfcert_init` / `wolfcert_cleanup` |
| `wolfcert/client.h` | High-level `wolfcert_client_*` API |
| `wolfcert/est.h`, `wolfcert/scep.h` | Protocol one-shots, sessions, non-blocking `_nb` sessions |
| `wolfcert/types.h` | `WolfCertServerCfg`, `WolfCertKeyCfg`, `WolfCertCertMeta`, `WolfCertEncoding` (PEM or DER output), `WolfCertTransport`, `wolfcert_buffer_free` |
| `wolfcert/types.h` | `WolfCertServerCfg`, `WolfCertKeyCfg`, `WolfCertCertMeta`, `WolfCertEncoding` (PEM or DER output), `WolfCertTransport`, `wolfcert_buffer_free` / `_secure` |
| `wolfcert/keygen.h`, `wolfcert/csr.h` | Key generation, import / export, CSR building |
| `wolfcert/store.h` | `WolfCertStoreOps` storage vtable, POSIX and in-memory backends |
| `wolfcert/errors.h`, `wolfcert/status.h`, `wolfcert/log.h` | Error codes, last-error detail, log callback |
| `wolfcert/memory.h` | Default heap hint, allocation macros |
| `examples/` | `enroll_est.c`, `enroll_scep.c`, `enroll_cryptocb.c`, `user_settings.h.example` |
| `examples/` | `enroll_est.c`, `enroll_scep.c`, `enroll_cryptocb.c`, `enroll_tpm.c`, `user_settings.h.example` |
| `examples/certs/` | Test credentials; never ship them |
| `zephyr/samples/wolfcert_est_client/` | EST client on Zephyr (qemu_x86, FRDM-MCXN947) |
| `src/` | Implementation; `src/internal.h` is not for applications |
Expand All @@ -204,9 +205,10 @@ contract, alone or in a group comment.
|---|---|---|
| Static memory / custom heap | `wolfcert_init(heap)` sets the default heap hint; per-call `heap` fields override it, and the hint reaches every wolfSSL call | `wolfcert/memory.h`, README "Integrating with a wolfSSL static-memory pool" |
| Network stack without BSD sockets (lwIP, NetX, FreeRTOS+TCP, wolfIP) | Fill `WolfCertServerCfg.transport` (`WolfCertTransport`); TLS records go through it too | `wolfcert/types.h`, `docs/EMBEDDED.md` section 7 |
| Persistence in flash / NVM | Implement `WolfCertStoreOps` (`read` / `write` / `remove`) | `wolfcert/store.h` |
| Keys in a TPM, HSM, PKCS#11 token or secure element | Register a backend with `wc_CryptoCb_RegisterDevice`, pass its id as `WolfCertKeyCfg.dev_id` | `docs/ARCHITECTURE.md` section 4.2, `examples/enroll_cryptocb.c` |
| Persistence in flash / NVM | Store the buffers from `wolfcert_key_to_pem` / `_to_der` and the enroll result; wolfCert does no storage | `wolfcert/keygen.h` |
| Keys in a TPM, HSM, PKCS#11 token or secure element | Register a backend with `wc_CryptoCb_RegisterDevice`, pass its id as `WolfCertKeyCfg.dev_id`, and the key's backend id as `key_id`; a key handle in `WolfCertServerCfg.client_key_obj` uses such a key for mTLS | `docs/ARCHITECTURE.md` section 4.2, `examples/enroll_cryptocb.c` |
| Event loop / no blocking | `wolfcert_est_session_open` / `wolfcert_scep_session_open`, then the `_nb` calls until they stop returning `WOLFCERT_ERR_WANT_READ` / `_WANT_WRITE`; `*_session_fd` gives the descriptor to poll | `wolfcert/est.h`, `wolfcert/scep.h` |
| Crypto accelerator for TLS and PKCS#7 | `wolfcert_set_default_dev_id`, starting at `WOLFCERT_DEFAULT_DEVID` (wolfSSL's `WC_USE_DEVID` when set); a key uses it with `dev_id = wolfcert_default_dev_id()` | `wolfcert/types.h`, `docs/ARCHITECTURE.md` section 4.2 |
| Logging | `wolfcert_set_log_cb` (e.g. to a UART) | `wolfcert/log.h` |
| RAM budget | `max_response_bytes`, HTTP stack buffers, wolfSSL `Cert` / `CertName` sizing | `docs/EMBEDDED.md` |

Expand Down Expand Up @@ -237,6 +239,9 @@ contract, alone or in a group comment.
which every EST call and SCEP over `https://` refuse with
`WOLFCERT_ERR_TLS`. Plain-HTTP SCEP ignores it and relies on the CA
fingerprint check instead.
- **Set `dev_id` on every `WolfCertKeyCfg`.** `INVALID_DEVID` is software;
a zero-initialized config names CryptoCb device 0, which keygen refuses
with `WOLFCERT_ERR_BAD_ARG` unless such a device is registered.
- **The `wolfcert_client_*` calls are EST-only except `get_ca`.** For SCEP
they return `WOLFCERT_ERR_UNSUPPORTED`; use `wolfcert_scep_*`.
- **SCEP rejects non-RSA keys** with `WOLFCERT_ERR_UNSUPPORTED`, and an ECC
Expand Down
23 changes: 13 additions & 10 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,6 @@ option(WOLFCERT_ENABLE_SERVER "Build the minimal EST/SCEP test server" ON)
option(WOLFCERT_ENABLE_CLI "Build wolfcert-client / wolfcert-server" ON)
option(WOLFCERT_ENABLE_TESTS "Build unit and integration tests" OFF)
option(WOLFCERT_ENABLE_EXAMPLES "Build example programs" OFF)
option(WOLFCERT_ENABLE_POSIX_STORE "Build the POSIX file storage backend" ON)
option(WOLFCERT_ENABLE_BUILTIN_TRANSPORT
"Build the built-in POSIX socket transport" ON)
option(WOLFCERT_WERROR "Treat warnings as errors" OFF)
Expand Down Expand Up @@ -85,7 +84,7 @@ if(NOT wolfssl_FOUND)
"wolfSSL >= 5.9.4 not found via CMake config or pkg-config. "
"wolfCert requires wolfSSL 5.9.4 or newer, built with: HAVE_PKCS7, "
"WOLFSSL_CERT_GEN, WOLFSSL_CERT_REQ, WOLFSSL_CERT_EXT, "
"WOLFSSL_KEY_GEN, HAVE_ECC, WOLF_CRYPTO_CB, WOLFSSL_BASE64_ENCODE, "
"WOLFSSL_KEY_GEN, HAVE_ECC, WOLFSSL_BASE64_ENCODE, "
"WOLFSSL_ALT_NAMES, WOLFSSL_CERT_NAME_ALL; a shared wolfSSL also "
"needs WOLFSSL_PUBLIC_ASN.")
endif()
Expand Down Expand Up @@ -120,7 +119,7 @@ if(NOT _have_wolfssl_floor)
message(FATAL_ERROR "wolfCert requires wolfSSL 5.9.4 or newer.")
endif()
foreach(sym IN ITEMS HAVE_PKCS7 WOLFSSL_CERT_GEN WOLFSSL_CERT_REQ WOLFSSL_CERT_EXT
WOLFSSL_KEY_GEN WOLF_CRYPTO_CB WOLFSSL_BASE64_ENCODE
WOLFSSL_KEY_GEN WOLFSSL_BASE64_ENCODE
WOLFSSL_ALT_NAMES WOLFSSL_CERT_NAME_ALL)
unset(_have_${sym} CACHE)
check_c_source_compiles("${_wc_wolfssl_prologue}
Expand All @@ -134,11 +133,18 @@ foreach(sym IN ITEMS HAVE_PKCS7 WOLFSSL_CERT_GEN WOLFSSL_CERT_REQ WOLFSSL_CERT_E
"wolfSSL was built without ${sym}. Rebuild with the appropriate "
"wolfSSL configure flag. For all the symbols wolfCert requires: "
"./configure --enable-pkcs7 --enable-certgen --enable-certreq "
"--enable-certext --enable-keygen --enable-ecc --enable-cryptocb "
"--enable-certext --enable-keygen --enable-ecc "
"--enable-base64encode "
"CPPFLAGS=\"-DWOLFSSL_ALT_NAMES -DWOLFSSL_CERT_NAME_ALL\"")
endif()
endforeach()
unset(_have_WOLF_CRYPTO_CB CACHE)
check_c_source_compiles("${_wc_wolfssl_prologue}
#ifndef WOLF_CRYPTO_CB
#error missing
#endif
int main(void) { return 0; }
" _have_WOLF_CRYPTO_CB)

# Link the WOLFSSL_ASN_API helpers wolfCert calls, without wolfSSL's headers.
if(TARGET PkgConfig::WOLFSSL)
Expand Down Expand Up @@ -312,8 +318,6 @@ if(NOT WOLFCERT_USER_SETTINGS)
_wc_opt(WOLFCERT_OPT_EST "${WOLFCERT_ENABLE_EST}" WOLFCERT_HAVE_EST)
_wc_opt(WOLFCERT_OPT_SCEP "${WOLFCERT_ENABLE_SCEP}" WOLFCERT_HAVE_SCEP)
_wc_opt(WOLFCERT_OPT_SERVER "${WOLFCERT_ENABLE_SERVER}" WOLFCERT_HAVE_SERVER)
_wc_plat(WOLFCERT_OPT_POSIX_STORE "${WOLFCERT_ENABLE_POSIX_STORE}"
WOLFCERT_HAVE_POSIX_STORE WOLFCERT_NO_POSIX_STORE)
_wc_plat(WOLFCERT_OPT_BUILTIN_TRANSPORT
"${WOLFCERT_ENABLE_BUILTIN_TRANSPORT}"
WOLFCERT_HAVE_BUILTIN_TRANSPORT WOLFCERT_NO_BUILTIN_TRANSPORT)
Expand All @@ -335,7 +339,6 @@ set(WOLFCERT_SOURCES
src/key_algs.c
src/keygen.c
src/csr.c
src/store.c
src/http.c
src/client.c)

Expand Down Expand Up @@ -370,8 +373,8 @@ endif()
add_library(wolfCert::wolfcert ALIAS wolfcert)

set_target_properties(wolfcert PROPERTIES
VERSION ${PROJECT_VERSION}
SOVERSION ${PROJECT_VERSION_MAJOR}
VERSION 1.0.0
SOVERSION 1
C_VISIBILITY_PRESET hidden)

target_include_directories(wolfcert
Expand Down Expand Up @@ -641,6 +644,6 @@ endif()

message(STATUS "wolfCert ${PROJECT_VERSION}: EST=${WOLFCERT_ENABLE_EST}, "
"SCEP=${WOLFCERT_ENABLE_SCEP}, server=${WOLFCERT_ENABLE_SERVER}, "
"cli=${WOLFCERT_ENABLE_CLI}, posix_store=${WOLFCERT_ENABLE_POSIX_STORE}, "
"cli=${WOLFCERT_ENABLE_CLI}, "
"builtin_transport=${WOLFCERT_ENABLE_BUILTIN_TRANSPORT}, "
"user_settings=${WOLFCERT_USER_SETTINGS}")
Loading
Loading