wolfPSA is a PSA Crypto engine that implements the PSA Crypto API on
top of wolfCrypt. It is meant to be used by PSA clients (e.g. wolfSSL compiled with WOLFSSL_HAVE_PSA,
or the Arm PSA Architecture Test Suite).
- PSA Crypto API entry points 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. - TF-PSA-Crypto's
mbedtls/pk.hfor private keys:mbedtls_pk_init,free,parse_key,parse_keyfileandcan_do_psa. The context has the key's DER and type. RSA and EC keys, PEM or DER, traditional or PKCS #8. Encrypted keys and EC keys with a compressed public key are not supported.
src/: wolfPSA implementation sources.wolfpsa/: public headers.user_settings.h: configuration header.Makefile: build forlibwolfpsa.a.
wolfPSA follows wolfSSL version numbering: wolfPSA v5.9.4 is tested against
wolfSSL v5.9.4-stable. To build against the matching release:
git clone --branch v5.9.4-stable https://github.com/wolfSSL/wolfssl
CI also tests against wolfSSL master.
The build system assumes that wolfSSL is available in a sibling directory under the same path as this repository, e.g:
.
├── wolfPSA/
├── wolfssl/
If this is not the case, provide the path to wolfSSL sources via:
export WOLFSSL_PATH=../wolfssl
Default build:
make
AddressSanitizer build:
make ASAN=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:
make MBEDTLS_THREADING_C=1
Applications define MBEDTLS_THREADING_C too, as in their Mbed TLS
configuration, and link with -pthread.
You can override the wolfSSL source location:
make wolfPSA WOLFSSL_PATH=~/src/wolfssl
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.
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_PATHintolibwolfpsa.a, like wolfCrypt, with the TLS settings inuser_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_compatand-I<wolfPSA>/build/include, and linklibwolfpsa.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_CandMBEDTLS_PEM_PARSE_C, are in the generated config inbuild/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=1applies 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'suser_settings.hdefines. A build with its ownUSER_SETTINGS_PATHdefines it too, or rejects such certificates, for example Mbed TLS'stest-ca2.crt. - The X.509 API needs wolfCrypt's certificate parsing: without it (
NO_ASNorNO_CERTS),MBEDTLS_X509_CRT_PARSE_Cis not defined. - TLS needs the X.509 API and wolfSSL's TLS with
HAVE_SNI: without them, for example withWOLFCRYPT_ONLY,MBEDTLS_SSL_TLS_Cis not defined.MBEDTLS_NET_Cneeds TLS and wolfSSL's socket I/O (noWOLFSSL_USER_IO).MBEDTLS_PEM_PARSE_Cneeds wolfCrypt's Base64 decoding (noNO_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_verifyandmbedtls_ssl_set_verifyare 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, andmbedtls_ssl_get_verify_resulthas 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_endpointandmbedtls_ssl_conf_transportcannot change the endpoint and transport it set:mbedtls_ssl_setupand the handshake then returnMBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE. wolfSSL makes its config for one endpoint and transport. mbedtls_ssl_conf_ca_chainrefuses a CRL:mbedtls_ssl_setupand the handshake then returnMBEDTLS_ERR_SSL_FEATURE_UNAVAILABLEuntil a CA list without one is set.- A server's config needs its
mbedtls_ssl_conf_own_certbeforembedtls_ssl_setup, which fails without it withMBEDTLS_ERR_SSL_BAD_CONFIG: wolfSSL makes a server connection only with a certificate and key. - A second
mbedtls_ssl_conf_own_certreplaces the first. Mbed TLS keeps both and picks one for each handshake. After a failed one,mbedtls_ssl_setupand the handshake return its error until one succeeds, where Mbed TLS keeps the certificates set before. mbedtls_net_acceptis 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_chainleaves out a CA that wolfSSL does not load, such as an expired one. A peer certificate from that CA then fails asNOT_TRUSTED, where Mbed TLS reportsEXPIRED.- 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 certificatecli2.crthas issuerPolarSSL Test EC CA, and its CAtest-ca2.crthas subjectPolarssl 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 withMBEDTLS_ERR_SSL_BAD_INPUT_DATAfrommbedtls_ssl_set_hostname, or frommbedtls_ssl_setupwhen set before it. wolfSSL takes only a fully qualified name, an IP address orlocalhost. mbedtls_ssl_set_hostnameduring a handshake applies from the nextmbedtls_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 reportsMBEDTLS_X509_BADCERT_MISSINGfor 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_dbgandmbedtls_ssl_conf_cert_profileare accepted and ignored.mbedtls_pem_read_bufferreturnsMBEDTLS_ERR_PEM_FEATURE_UNAVAILABLEfor encrypted PEM. Nombedtls_pem_write_buffer.mbedtls_x509_crthas one node per certificate, with no parsed fields apart fromraw. Parse errors areMBEDTLS_ERR_X509_INVALID_FORMATorMBEDTLS_ERR_X509_ALLOC_FAILED.mbedtls_x509_crt_parse_pathneeds<dirent.h>. On Windows, or withNO_WOLFSSL_DIR, it returnsMBEDTLS_ERR_X509_FILE_IO_ERROR.- The profiles are not applied: wolfSSL's own limits hold.
mbedtls_x509_crt_profileis opaque, so applications cannot define their own. - 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.
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.candpem_test.cparse Mbed TLS's test certificates and keys.ssl_test.cchecks 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. WithMBEDTLS_THREADING_C=1,ssl_pthread_serverserves clients at the same time.
Notes:
MBEDTLS_PATH(default../mbedtls) is an Mbed TLS 4.x checkout with itsframeworkandtf-psa-cryptosubmodules, 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 itscerts/. This needs autoconf, automake and libtool. - Also needs python3 with jinja2. Without faketime, the case that needs it is skipped.
WRAPprefixes each test program, for exampleWRAP=valgrind. Server programs are stopped by the script, so their exit codes are not checked.libwolfpsa.ahas no Mbed TLS code. The tests link Mbed TLS's test certificate data.
See test-psa-api/README.md for instructions on how to run the tests.
************ Crypto Suite Report ************
TOTAL TESTS : 78
TOTAL PASSED : 65
TOTAL SIM ERROR : 0
TOTAL FAILED : 0
TOTAL SKIPPED : 13
******************************************
See COPYING.
See CHANGELOG.md.