Skip to content
wolfSSLPublic

About

Mbed TLS compatible API backed by wolfCrypt, wolfSSL's crypto library. Implements the PSA Crypto API and TF-PSA-Crypto interfaces for existing Mbed TLS applications, from embedded devices to the cloud.

Topics

Resources

Security policy

Stars

6 stars

Watchers

1 watching

Forks

Repository files navigation

wolfPSA

wolfPSA provides the Mbed TLS 4.x API on top of wolfCrypt, wolfSSL's crypto library. Built with MBEDTLS_COMPAT=1 against wolfSSL master, it lets applications written for Mbed TLS 4.x build without source changes and link libwolfpsa.a in place of Mbed TLS's libraries. Parts of the API are not available yet, such as session tickets, ALPN and DTLS, and some behave differently: see coming soon and the known differences.

wolfPSA also implements the PSA Crypto API and parts of TF-PSA-Crypto, the crypto library of Mbed TLS 4.x. Without the Mbed TLS layer, it serves as a PSA Crypto engine for PSA clients such as wolfSSL compiled with WOLFSSL_HAVE_PSA or the Arm PSA Architecture Test Suite.

What it provides

  • The Mbed TLS 4.x TLS, X.509, PEM and network API, when built with MBEDTLS_COMPAT=1. See Mbed TLS compatibility.
  • PSA Crypto API implemented in C.
  • wolfCrypt as the backend crypto provider.
  • The default make target creates a static library (libwolfpsa.a) built directly from wolfPSA sources plus the required wolfCrypt objects.
  • Parts of TF-PSA-Crypto, in every build: mbedtls/pk.h key parsing, mbedtls/threading.h and mbedtls/platform.h. See currently supported.

Mbed TLS compatibility

MBEDTLS_COMPAT=1 adds the Mbed TLS 4.x TLS, X.509, PEM and network API on top of wolfSSL. wolfPSA already provides the TF-PSA-Crypto side (psa_*, mbedtls_pk_*, mbedtls_psa_crypto_free, mbedtls/platform.h).

Build wolfPSA with MBEDTLS_COMPAT=1 as in Build. Applications then 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.

To run the compatibility tests:

make MBEDTLS_COMPAT=1 mbedtls-compat-test

See docs/mbedtls-compatibility.md for the supported functions, what is coming soon, the known differences from Mbed TLS, and the build and test details.

Build

wolfPSA compiles wolfCrypt, and with MBEDTLS_COMPAT=1 wolfSSL's TLS, from a wolfSSL source tree. By default this is ../wolfssl, a clone of wolfSSL master next to this repository:

git clone https://github.com/wolfSSL/wolfssl ../wolfssl

MBEDTLS_COMPAT=1 needs wolfSSL master. Without it, wolfPSA also builds against the matching wolfSSL release: wolfPSA v5.9.4 is tested against wolfSSL v5.9.4-stable. To use a wolfSSL tree elsewhere, set WOLFSSL_PATH, for example make WOLFSSL_PATH=~/src/wolfssl.

Build with the Mbed TLS API:

make MBEDTLS_COMPAT=1

Or with the PSA Crypto API only:

make

Options, which can be combined (make help lists them all):

  • ASAN=1: AddressSanitizer build.
  • MBEDTLS_THREADING_C=1: thread-safe build, as Mbed TLS with MBEDTLS_THREADING_C: wolfCrypt without SINGLE_THREADED, a mutex around the key store (WOLFPSA_THREAD_SAFE, see src/psa_lock.h) and the TF-PSA-Crypto threading API in mbedtls/threading.h, on pthreads. Applications define MBEDTLS_THREADING_C too, as in their Mbed TLS configuration, and link with -pthread.

The build generates the PSA_WANT_* macros from the wolfCrypt configuration into $(BUILD_DIR)/include/crypto_config_generated.h (build/include by default), using python3. Set PYTHON to use another interpreter. Code that includes <psa/crypto.h> needs that directory on its include path next to wolfpsa/, and builds only after make has generated the header.

Repository layout

  • src/ : wolfPSA implementation sources.
  • wolfpsa/ : public headers.
  • user_settings.h : configuration header.
  • Makefile : build for libwolfpsa.a.

Testing (PSA Architecture Test Suite)

See test-psa-api/README.md for instructions on how to run the tests.

Current PSA crypto test results (wolfSSL v5.9.4-stable):

************ Crypto Suite Report ************
TOTAL TESTS     : 78
TOTAL PASSED    : 65
TOTAL SIM ERROR : 0
TOTAL FAILED    : 0
TOTAL SKIPPED   : 13
******************************************

License

See COPYING.

ChangeLog

See CHANGELOG.md.

About

Mbed TLS compatible API backed by wolfCrypt, wolfSSL's crypto library. Implements the PSA Crypto API and TF-PSA-Crypto interfaces for existing Mbed TLS applications, from embedded devices to the cloud.

Topics

Resources

Security policy

Stars

6 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages