|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
The TLS adapters in this directory call the PSA Crypto provider selected by the application. They do not implement the psa_* API. The provider's public header must be available as <psa/crypto.h>; build the consumer separately and link it with that provider and any required platform libraries.
Build the provider and consumer into separate directories. They must use the same SHARKSSL_PSA_PROFILE_1_4_1, SHARKSSL_USE_SHA_512 and SHARKSSL_USE_CHACHA20 settings because the public PSA operation types depend on the enabled algorithms. On Linux or WSL, for the default 1.5 profile:
For 1.4.1, add XCFLAGS=-DSHARKSSL_PSA_PROFILE_1_4_1=1 to the provider command and append -DSHARKSSL_PSA_PROFILE_1_4_1=1 to the consumer command's existing XCFLAGS value. Use matching architecture flags, such as -m32 in XCFLAGS, when building both archives for x86. The psa-consumer-client target links the example client with the consumer and provider archives.
Pass the external provider's include directory to PSA_PROVIDER_INC. The directory must contain psa/crypto.h; list any additional provider include directories in PSA_PROVIDER_INC_EXTRA. For example:
This builds the consumer archive only. Set feature options compatible with the selected provider's PSA headers, then link the application with that provider's library and platform dependencies. To build the example client, also set PSA_PROVIDER_LIB and XCFLAGS=-I../examples/certificates, and run psa-consumer-client.
The TLS consumer archive contains SharkSslPSAConsumerCrypto.c and SharkSslPSAConsumerECDSAAdapter.c. The latter is the TLS/X.509 adapter; SharkSslPSAConsumerECDSA.c below implements the separate application API. Compile only the standalone sources needed by the application, using the same SHARKSSL_PSA_CONSUMER=1 configuration and PSA headers as the TLS archive. Put the selected provider's include directories before inc. When linking static archives, list the standalone objects or extras archive first, then the TLS consumer archive, the provider archive and its platform libraries. SharkSslPSAConsumerCurves.h defines ECDH/ECDSA identifiers and has no matching .c file.
| Application API | Source in src/psa-consumer | Header | Additional requirement |
|---|---|---|---|
| AES block, CBC, CTR, GCM and CCM | SharkSslPSAConsumerAES.c | inc/SharkSslCrypto.h | SHARKSSL_PSA_CONSUMER_STANDALONE_AES=1; enable each selected mode in SharkSSL and the provider; link the TLS core for sharkssl_clear |
| ChaCha20 and ChaCha20-Poly1305 | SharkSslPSAConsumerChaCha.c | inc/SharkSslCrypto.h | SHARKSSL_PSA_CONSUMER_STANDALONE_CHACHA20=1 and SHARKSSL_USE_CHACHA20=1; the GNU Make TLS archive already includes this source when that standalone switch is 1, so do not link a second copy |
| CMAC | SharkSslPSAConsumerCMAC.c | inc/psa-consumer/SharkSslPSAConsumerCMAC.h | Provider support for CMAC MAC operations |
| ECDH | SharkSslPSAConsumerECDH.c | inc/psa-consumer/SharkSslPSAConsumerECDH.h | Provider support for the selected curve and psa_raw_key_agreement |
| ECDSA key and DER conversions | SharkSslPSAConsumerECDSA.c | inc/psa-consumer/SharkSslPSAConsumerECDSA.h | Provider support for the selected curve, hash and ECDSA policy |
| Ed25519/Ed448 | SharkSslPSAConsumerEdDSA.c | inc/psa-consumer/SharkSslPSAConsumerEdDSA.h | Provider support for the selected Edwards curve and PureEdDSA/prehash policy |
| Hash | SharkSslPSAConsumerHash.c | inc/psa-consumer/SharkSslPSAConsumerHash.h | Provider support for the requested hash |
| AES-KW/KWP | SharkSslPSAConsumerKeyWrap.c | inc/psa-consumer/SharkSslPSAConsumerKeyWrap.h | Provider headers and library must expose PSA_ALG_KW/PSA_ALG_KWP, psa_wrap_key and psa_unwrap_key |
| PBKDF2 | SharkSslPSAConsumerPBKDF2.c | inc/psa-consumer/SharkSslPSAConsumerPBKDF2.h | Provider PBKDF2 derivation with the selected PRF |
| RSA | SharkSslPSAConsumerRSA.c | inc/psa-consumer/SharkSslPSAConsumerRSA.h | Provider RSA key management and the selected sign/encrypt algorithms |
| SP 800-108 counter KDF | SharkSslPSAConsumerSP800108.c | inc/psa-consumer/SharkSslPSAConsumerSP800108.h | Provider context-input and SP 800-108 counter HMAC/CMAC definitions and operations |
Private EdDSA keys request signing and verification usage. If the provider rejects that policy, key import or generation retries with signing usage only. Verification first tries the private handle; when it is unsupported or rejects the signature, the consumer exports the public key and verifies through a temporary PSA public-key handle. The public-key API verifies with its existing handle. Both paths use PSA for the cryptographic verification.
For a Zephyr application, add the chosen sources to target_sources(app
PRIVATE ...) and link the provider selected by the Zephyr configuration. For a static-link application, place the selected object files before libSharkSSLPSAConsumer.a and the provider library. Each source is independent of the other standalone sources. KeyWrap and SP 800-108 compile as rejecting stubs when their optional PSA definitions are absent; a successful link alone does not establish those provider capabilities.
The source list was checked with GCC x64 in WSL: all eleven standalone objects compiled against TF-PSA-Crypto 1.2.0 headers and linked with its provider and the TLS consumer archive. KeyWrap and SP 800-108 were also compiled against the SharkSSL PSA headers and linked with a freshly built SharkSSL provider to check their non-stub symbol dependencies. These were compile and link checks, not algorithm runtime tests. The local commands and outputs are in build/psa-consumer/extras-manifest-lab.