Skip to content
Merged
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
28 changes: 24 additions & 4 deletions .github/workflows/mbedtls-compat.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,48 @@ on:

jobs:
# make MBEDTLS_COMPAT=1 mbedtls-compat-test: the Mbed TLS 4.x API on
# wolfCrypt, tested with Mbed TLS's test data. See the README.
# wolfSSL, tested with Mbed TLS's sample programs and test data. See the
# README.
mbedtls-compat:
runs-on: ubuntu-latest
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
wolfssl-ref: [ master, v5.9.4-stable ]
# The compatibility layer needs wolfSSL master, not a release
wolfssl-ref: [ master ]
options: [ "", "MBEDTLS_THREADING_C=1 ASAN=1" ]

steps:
- name: Check out wolfPSA
uses: actions/checkout@v4

- name: Install build dependencies
run: |
sudo apt-get update
sudo apt-get install -y build-essential autoconf automake libtool libtool-bin pkg-config python3-jinja2 faketime

- name: Clone sibling wolfSSL
run: git clone --depth 1 --branch ${{ matrix.wolfssl-ref }} https://github.com/wolfSSL/wolfssl ../wolfssl

# The tests need only framework/data_files
# The tests need framework's data files, and tf-psa-crypto's headers for
# the test certificates
- name: Clone sibling Mbed TLS
run: |
git clone --depth 1 --branch mbedtls-4.2.0 https://github.com/Mbed-TLS/mbedtls ../mbedtls
git -C ../mbedtls submodule update --init --depth 1 framework
git -C ../mbedtls submodule update --init --depth 1 framework tf-psa-crypto

- name: Build and run the compatibility tests
run: make MBEDTLS_COMPAT=1 ${{ matrix.options }} mbedtls-compat-test

# -z defs fails on undefined symbols
- name: Build client-only and server-only
if: matrix.options == ''
env:
LDFLAGS: -Wl,-z,defs
run: |
for side in CLIENT SERVER; do
make -j"$(nproc)" MBEDTLS_COMPAT=1 BUILD_DIR=build-no-$side \
WOLFSSL_CPPFLAGS="-DWOLFSSL_USER_SETTINGS -DNO_WOLFSSL_$side" \
want-surface-test
done
6 changes: 5 additions & 1 deletion .github/workflows/test-psa-api.yml
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,10 @@ jobs:
# master tracks upstream; the -stable tag is the release wolfPSA is
# validated against. Bump it together with the wolfPSA version.
wolfssl-ref: [ master, v5.9.4-stable ]
# MBEDTLS_COMPAT=1 needs wolfSSL master
include:
- wolfssl-ref: v5.9.4-stable
make-args: MBEDTLS_COMPAT=0

steps:
- name: Check out wolfPSA
Expand All @@ -92,7 +96,7 @@ jobs:
- name: Build and run the PSA API tests
env:
LD_LIBRARY_PATH: ${{ github.workspace }}:${{ github.workspace }}/../wolfssl/src/.libs
run: make unit-run
run: make unit-run ${{ matrix.make-args }}

# The crypto callback reads the HMAC key out of Hmac.keyRaw, which
# wolfCrypt borrows rather than copies. Only a sanitizer notices when
Expand Down
54 changes: 41 additions & 13 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -79,10 +79,18 @@ WOLFCRYPT_SRC := \
WOLFCRYPT_OBJ := $(patsubst $(WOLFSSL_PATH)/wolfcrypt/src/%.c,$(OBJDIR)/wolfcrypt_%.o,$(WOLFCRYPT_SRC))
WOLFCRYPT_OBJ_PIC := $(patsubst $(WOLFSSL_PATH)/wolfcrypt/src/%.c,$(OBJDIR_PIC)/wolfcrypt_%.o,$(WOLFCRYPT_SRC))

# MBEDTLS_COMPAT=1 adds the Mbed TLS 4.x X.509 API. See src/mbedtls/.
# MBEDTLS_COMPAT=1 adds the Mbed TLS 4.x TLS, X.509 and network API, on
# wolfSSL's TLS compiled from WOLFSSL_PATH like wolfCrypt. See src/mbedtls/.
WOLFSSL_TLS_SRC :=
ifeq ($(MBEDTLS_COMPAT),1)
CPPFLAGS += -DWOLFPSA_MBEDTLS_COMPAT -I$(CURDIR)/wolfpsa/mbedtls_compat
WOLFSSL_TLS_SRC := $(addprefix $(WOLFSSL_PATH)/src/,internal.c keys.c ssl.c \
tls.c tls13.c wolfio.c)
endif
WOLFSSL_TLS_OBJ := $(patsubst $(WOLFSSL_PATH)/src/%.c,$(OBJDIR)/wolfssl_%.o, \
$(WOLFSSL_TLS_SRC))
WOLFSSL_TLS_OBJ_PIC := $(patsubst $(WOLFSSL_PATH)/src/%.c, \
$(OBJDIR_PIC)/wolfssl_%.o,$(WOLFSSL_TLS_SRC))

# MBEDTLS_THREADING_C=1 builds a thread safe library, as in Mbed TLS. See
# user_settings.h. Applications define MBEDTLS_THREADING_C too.
Expand Down Expand Up @@ -141,7 +149,7 @@ LDFLAGS += --coverage
endif

.PHONY: all clean psa-objects unit-run run-tests cov covclean \
want-surface-test mbedtls-compat-test
want-surface-test

all: $(LIBNAME) $(SHLIBNAME)

Expand All @@ -151,11 +159,14 @@ all: $(LIBNAME) $(SHLIBNAME)
# bundled wolfCrypt sources are out of scope.
psa-objects: $(OBJ)

$(LIBNAME): $(OBJ) $(WOLFCRYPT_OBJ)
# Made again, so that objects of another MBEDTLS_COMPAT build are not kept
$(LIBNAME): $(OBJ) $(WOLFCRYPT_OBJ) $(WOLFSSL_TLS_OBJ)
rm -f $@
$(AR) rcs $@ $^
$(RANLIB) $@

$(SHLIBNAME): $(OBJ_PIC) $(WOLFCRYPT_OBJ_PIC) $(EXPORT_MAP)
$(SHLIBNAME): $(OBJ_PIC) $(WOLFCRYPT_OBJ_PIC) $(WOLFSSL_TLS_OBJ_PIC) \
$(EXPORT_MAP)
$(CC) -shared -Wl,--version-script,$(EXPORT_MAP) -Wl,-Bsymbolic-functions -o $@ $(filter-out $(EXPORT_MAP),$^) $(LDFLAGS)

# Build the PSA_WANT_* macros based on what the wolfCrypt build supports.
Expand All @@ -168,7 +179,8 @@ $(PSA_CONFIG): FORCE
$(PYTHON) tools/gen-crypto-config.py $@ "$(CC)" \
tools/psa_want_probe.c $(CPPFLAGS) $(CFLAGS)

$(OBJ) $(OBJ_PIC) $(WOLFCRYPT_OBJ) $(WOLFCRYPT_OBJ_PIC): $(PSA_CONFIG)
$(OBJ) $(OBJ_PIC) $(WOLFCRYPT_OBJ) $(WOLFCRYPT_OBJ_PIC) $(WOLFSSL_TLS_OBJ) \
$(WOLFSSL_TLS_OBJ_PIC): $(PSA_CONFIG)

FORCE:

Expand All @@ -178,7 +190,8 @@ want-surface-test: $(LIBNAME) $(SHLIBNAME)
-lpthread -lm
$(BUILD_DIR)/psa_want_surface_test

$(OBJ) $(WOLFCRYPT_OBJ) $(OBJ_PIC) $(WOLFCRYPT_OBJ_PIC): $(OPTIONS_STAMP)
$(OBJ) $(WOLFCRYPT_OBJ) $(WOLFSSL_TLS_OBJ) $(OBJ_PIC) $(WOLFCRYPT_OBJ_PIC) \
$(WOLFSSL_TLS_OBJ_PIC): $(OPTIONS_STAMP)

$(OPTIONS_STAMP):
@mkdir -p $(@D)
Expand All @@ -201,6 +214,14 @@ $(OBJDIR_PIC)/wolfcrypt_%.o: $(WOLFSSL_PATH)/wolfcrypt/src/%.c
@mkdir -p $(OBJDIR_PIC)
$(CC) $(CPPFLAGS) $(DEPFLAGS) $(CFLAGS) -fPIC -c $< -o $@

$(OBJDIR)/wolfssl_%.o: $(WOLFSSL_PATH)/src/%.c
@mkdir -p $(OBJDIR)
$(CC) $(CPPFLAGS) $(DEPFLAGS) $(CFLAGS) -c $< -o $@

$(OBJDIR_PIC)/wolfssl_%.o: $(WOLFSSL_PATH)/src/%.c
@mkdir -p $(OBJDIR_PIC)
$(CC) $(CPPFLAGS) $(DEPFLAGS) $(CFLAGS) -fPIC -c $< -o $@

# The unit tests. The servers (psa_tls_client, psa_tls_server) and the
# benchmark are not unit tests and are not listed.
UNIT_TESTS := psa_api_test \
Expand Down Expand Up @@ -284,21 +305,27 @@ unit-run: all
@$(MAKE) -C test $(UNIT_TESTS)
@$(MAKE) run-tests

# Mbed TLS repo, for its test data
# Mbed TLS repo, for its test data and sample programs
MBEDTLS_PATH ?= ../mbedtls

# mbedtls-compat-test runs mbedtls-compat-unit, our own tests of the API, and
# mbedtls-compat-programs, Mbed TLS's sample programs with wolfSSL peers. Each
# runs the target of the same name in test/mbedtls_compat.
MBEDTLS_COMPAT_TESTS := $(addprefix mbedtls-compat-,test unit programs)
.PHONY: $(MBEDTLS_COMPAT_TESTS)
ifeq ($(MBEDTLS_COMPAT),1)
mbedtls-compat-test: $(LIBNAME)
$(MBEDTLS_COMPAT_TESTS): mbedtls-compat-%: $(LIBNAME)
$(MAKE) -C test/mbedtls_compat WOLFPSA_PATH=$(CURDIR) \
WOLFSSL_PATH=$(abspath $(WOLFSSL_PATH)) \
MBEDTLS_PATH=$(abspath $(MBEDTLS_PATH)) \
BUILD_DIR=$(abspath $(BUILD_DIR))/mbedtls_compat \
PSA_CONFIG_DIR=$(abspath $(dir $(PSA_CONFIG))) \
WOLFSSL_FLAGS="-I$(abspath $(WOLFSSL_PATH)) \
-I$(abspath $(USER_SETTINGS_PATH)) $(WOLFSSL_CPPFLAGS)" \
SANITIZE_FLAGS="$(SANITIZE_FLAGS)" WOLFPSA_LDFLAGS="$(LDFLAGS)" check
SANITIZE_FLAGS="$(SANITIZE_FLAGS)" WOLFPSA_LDFLAGS="$(LDFLAGS)" $*
else
mbedtls-compat-test:
@echo "Run make MBEDTLS_COMPAT=1 mbedtls-compat-test"; exit 1
$(MBEDTLS_COMPAT_TESTS):
@echo "Run make MBEDTLS_COMPAT=1 $@"; exit 1
endif

# Build everything with gcov instrumentation, run the unit tests, and emit an
Expand Down Expand Up @@ -349,5 +376,6 @@ covclean:
clean:
rm -rf $(BUILD_DIR) $(LIBNAME) $(SHLIBNAME)

-include $(OBJ:.o=.d) $(WOLFCRYPT_OBJ:.o=.d)
-include $(OBJ_PIC:.o=.d) $(WOLFCRYPT_OBJ_PIC:.o=.d)
-include $(OBJ:.o=.d) $(WOLFCRYPT_OBJ:.o=.d) $(WOLFSSL_TLS_OBJ:.o=.d)
-include $(OBJ_PIC:.o=.d) $(WOLFCRYPT_OBJ_PIC:.o=.d) \
$(WOLFSSL_TLS_OBJ_PIC:.o=.d)
130 changes: 122 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,36 +90,125 @@ includes `<psa/crypto.h>` needs that directory on its include path next to

## Mbed TLS compatibility

`MBEDTLS_COMPAT=1` adds the Mbed TLS 4.x X.509 API on top of wolfCrypt, so
that applications written for Mbed TLS 4.x build against wolfPSA without
source changes. wolfPSA already provides the TF-PSA-Crypto side (`psa_*`,
`mbedtls_pk_*`, `mbedtls_psa_crypto_free`, `mbedtls/platform.h`).
`MBEDTLS_COMPAT=1` adds the Mbed TLS 4.x TLS, X.509 and network API on top of
wolfSSL, so that applications written for Mbed TLS 4.x build against wolfPSA
without source changes. wolfPSA already provides the TF-PSA-Crypto side
(`psa_*`, `mbedtls_pk_*`, `mbedtls_psa_crypto_free`, `mbedtls/platform.h`).

```
make MBEDTLS_COMPAT=1
```

- wolfSSL's TLS sources are compiled from `WOLFSSL_PATH` into
`libwolfpsa.a`, like wolfCrypt, with the TLS settings in `user_settings.h`.
Changing the option rebuilds everything.
- Needs a current wolfSSL built from its master branch. wolfSSL releases,
such as v5.9.4-stable, are not supported.
- Applications use `-I<wolfPSA>/wolfpsa`,
`-I<wolfPSA>/wolfpsa/mbedtls_compat` and `-I<wolfPSA>/build/include`, and
link `libwolfpsa.a`, in place of Mbed TLS's libraries. The headers include
no wolfSSL header.
- The feature macros, such as `MBEDTLS_SSL_TLS_C`, `MBEDTLS_NET_C` and
`MBEDTLS_PEM_PARSE_C`, are in the generated config in `build/include`, so
a build without the option does not define them.
- The functions have the Mbed TLS names, so code that finds them by symbol
name (`dlsym`, language bindings) works too.
- With `MBEDTLS_THREADING_C=1`, TLS is thread safe too.
- TLS uses wolfPSA's constant-time AES. `AES_FAST=1` applies to TLS too.
- As in Mbed TLS, certificates may have NULL parameters after an ECDSA
signature OID. This needs `WOLFSSL_ECC_SIGALG_PARAMS_NULL_ALLOWED`, which
wolfPSA's `user_settings.h` defines. A build with its own
`USER_SETTINGS_PATH` defines it too, or rejects such certificates, for
example Mbed TLS's `test-ca2.crt`.
- The X.509 API needs wolfCrypt's certificate parsing: without it (`NO_ASN`
or `NO_CERTS`), `MBEDTLS_X509_CRT_PARSE_C` is not defined.
- TLS needs the X.509 API and wolfSSL's TLS with `HAVE_SNI`: without them,
for example with `WOLFCRYPT_ONLY`, `MBEDTLS_SSL_TLS_C` is not defined.
`MBEDTLS_NET_C` needs TLS and wolfSSL's socket I/O (no `WOLFSSL_USER_IO`).
`MBEDTLS_PEM_PARSE_C` needs wolfCrypt's Base64 decoding (no `NO_CODING`).

Mapped so far:

- net: init, connect, bind, accept, close, free, recv, send, usleep
- pem: init, read_buffer, get_buffer, free
- x509_crt: init, free, parse, parse_der, parse_file, parse_path; the
default, next and suiteb profiles, as names only
- ssl_config: init, free, defaults; ssl_conf: authmode, ca_chain, own_cert,
min_tls_version, max_tls_version, ciphersuites, cert_profile, dbg,
endpoint, transport, get_endpoint, set_user_data_p, set_user_data_n,
get_user_data_p, get_user_data_n
- ssl: init, free, setup, context_get_config, session_reset, set_bio,
set_hostname, set_session, get_session, handshake, is_handshake_over,
get_verify_result, get_ciphersuite, get_ciphersuite_id_from_ssl,
get_version, get_version_number, get_bytes_avail, read, write,
close_notify, set_user_data_p, set_user_data_n, get_user_data_p,
get_user_data_n; list_ciphersuites, get_ciphersuite_name,
get_ciphersuite_id
- ssl_session: init, free; save and load return
`MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`

Known differences from Mbed TLS:

- `MBEDTLS_SSL_VERIFY_OPTIONAL`, `mbedtls_ssl_conf_verify` and
`mbedtls_ssl_set_verify` are not available yet, so an application that
uses them does not build.
- With `MBEDTLS_SSL_VERIFY_REQUIRED`, the handshake stops at the first check
of the peer's chain that fails, and `mbedtls_ssl_get_verify_result` has
only its flag. Mbed TLS checks the whole chain first and reports the flag
of each failure.
- A wolfSSL error with no Mbed TLS match returns a general code for the
call, such as `MBEDTLS_ERR_SSL_INTERNAL_ERROR`. wolfSSL's own codes are not
returned: some Mbed TLS 4.x codes are PSA values (-128 to -160), which
overlap wolfCrypt codes.
- A config needs `mbedtls_ssl_config_defaults`. `mbedtls_ssl_conf_endpoint`
and `mbedtls_ssl_conf_transport` cannot change the endpoint and transport
it set: `mbedtls_ssl_setup` and the handshake then return
`MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`. wolfSSL makes its config for one
endpoint and transport.
- `mbedtls_ssl_conf_ca_chain` refuses a CRL: `mbedtls_ssl_setup` and the
handshake then return `MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE` until a CA
list without one is set.
- A server's config needs its `mbedtls_ssl_conf_own_cert` before
`mbedtls_ssl_setup`, which fails without it with
`MBEDTLS_ERR_SSL_BAD_CONFIG`: wolfSSL makes a server connection only with
a certificate and key.
- A second `mbedtls_ssl_conf_own_cert` replaces the first. Mbed TLS keeps
both and picks one for each handshake. After a failed one,
`mbedtls_ssl_setup` and the handshake return its error until one
succeeds, where Mbed TLS keeps the certificates set before.
- `mbedtls_net_accept` is TCP only.
- RSA keys are limited to 3072 bits, so a certificate chain with an RSA-4096
CA does not verify.
- `mbedtls_ssl_conf_ca_chain` leaves out a CA that wolfSSL does not load,
such as an expired one. A peer certificate from that CA then fails as
`NOT_TRUSTED`, where Mbed TLS reports `EXPIRED`.
- A certificate's issuer name must match its CA's subject name exactly, as
encoded. Mbed TLS also takes names that differ only in letter case or in
string type (PrintableString or UTF8String). Such a certificate fails as
`NOT_TRUSTED`. For example, Mbed TLS's test certificate `cli2.crt` has
issuer `PolarSSL Test EC CA`, and its CA `test-ca2.crt` has subject
`Polarssl Test EC CA`.
- An IP address host name is matched against the certificate's IP address
SANs only. Mbed TLS also matches a DNS SAN with the same text, or the CN
of a certificate without SANs. It is not sent as the server name, which
RFC 6066 does not allow and Mbed TLS does.
- A host name without a dot, such as `router`, fails with
`MBEDTLS_ERR_SSL_BAD_INPUT_DATA` from `mbedtls_ssl_set_hostname`, or from
`mbedtls_ssl_setup` when set before it. wolfSSL takes only a fully
qualified name, an IP address or `localhost`.
- `mbedtls_ssl_set_hostname` during a handshake applies from the next
`mbedtls_ssl_session_reset`. Mbed TLS uses the new name for the rest of
that handshake.
- A server resumes sessions from wolfSSL's session cache, where Mbed TLS
needs `mbedtls_ssl_conf_session_cache`. A server that verifies client
certificates reports `MBEDTLS_X509_BADCERT_MISSING` for a resumed session.
- wolfSSL keeps the intermediate CAs of a chain that verifies, for the
config's later handshakes. A peer that then leaves them out still
verifies, where Mbed TLS reports `NOT_TRUSTED`.
- `mbedtls_ssl_conf_dbg` and `mbedtls_ssl_conf_cert_profile` are accepted
and ignored.
- `mbedtls_pem_read_buffer` returns `MBEDTLS_ERR_PEM_FEATURE_UNAVAILABLE`
for encrypted PEM. No `mbedtls_pem_write_buffer`.
- `mbedtls_x509_crt` has one node per certificate, with no parsed fields
apart from `raw`. Parse errors are `MBEDTLS_ERR_X509_INVALID_FORMAT` or
`MBEDTLS_ERR_X509_ALLOC_FAILED`.
Expand All @@ -131,17 +220,42 @@ Known differences from Mbed TLS:
- wolfSSL parses some certificates differently. For example, it rejects
serial number 0 and a pathlen above `WOLFSSL_MAX_PATH_LEN`, and accepts
spaces in PEM.
- No global mutexes such as `mbedtls_threading_gmtime_mutex`.

`test/mbedtls_compat/x509_crt_test.c` and `pk_test.c` parse Mbed TLS's test
certificates and keys. To run them:
### Mbed TLS compatibility tests

```
make MBEDTLS_COMPAT=1 mbedtls-compat-test
```

runs these against `libwolfpsa.a`. Each is also a target of its own.

- `mbedtls-compat-unit`: `test/mbedtls_compat/x509_crt_test.c`,
`pk_test.c` and `pem_test.c` parse Mbed TLS's test certificates and keys.
`ssl_test.c` checks return codes and verify results, client and server in
one process.
- `mbedtls-compat-programs`: the Mbed TLS migration guide client
(`test/mbedtls_compat/client-tls-mbedtls.c`) and Mbed TLS's sample
programs, built unchanged, run against the wolfSSL example server. Mbed
TLS's server programs run against the wolfSSL example client. With
`MBEDTLS_THREADING_C=1`, `ssl_pthread_server` serves clients at the same
time.

Notes:

- `MBEDTLS_PATH` (default `../mbedtls`) is an Mbed TLS 4.x checkout with
its `framework` submodule. Only its test data files are used.
- `WRAP` prefixes each test program, for example `WRAP=valgrind`.
its `framework` and `tf-psa-crypto` submodules, for its test data and
sample programs.
- The example server and client come from a wolfSSL configured out of tree
from `WOLFSSL_PATH`, which must not be configured in place. The tests use
the certificates in its `certs/`. This needs autoconf, automake and
libtool.
- Also needs python3 with jinja2. Without faketime, the case that needs it
is skipped.
- `WRAP` prefixes each test program, for example `WRAP=valgrind`. Server
programs are stopped by the script, so their exit codes are not checked.
- `libwolfpsa.a` has no Mbed TLS code. The tests link Mbed TLS's test
certificate data.

## Testing (PSA Architecture Test Suite)

Expand Down
Loading
Loading