|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
Use this guide for the nRF54L15 CRACEN cryptographic accelerator. This directory supplies standalone primitives and SDK-specific driver replacements. SharkSSL TLS uses CRACEN through the separately built PSA consumer and the Nordic PSA provider.
See the Nordic primitive API reference for argument sizes, buffer ownership and return codes.
nrf54l15dk/nrf54l15/cpuapp.The standalone primitives are not selected by SHARKSSL_* feature macros and are not automatically wired into TLS. SHARKSSL_PSA_CONSUMER=1 is neither required nor sufficient to enable them. Headers specify their argument sizes and return codes.
| API | Compile | Additional source | Scope |
|---|---|---|---|
SharkSslCRACENFF_init, SharkSslCRACENFF_modExp | SharkSslCRACENFF.c | None | Finite-field modular exponentiation; not a complete DH protocol |
sharkssl_CRACENECKCDSA_*P256 | SharkSslCRACENECKCDSA.c | None | P-256 public key, signature component and prehashed verification; not a complete signer |
sharkssl_CRACENDSA_*2048_256 | SharkSslCRACENDSA.c | SharkSslCRACENFF.c | DSA 2048/256 prehashed sign/verify |
sharkssl_CRACENSHAKE256_digest | SharkSslCRACENSHAKE256.c | None | One-shot SHAKE256, 1-512 output bytes |
sharkssl_CRACENSM4_crypt | SharkSslCRACENSM4.c | None | SM4-128 ECB/CBC/CTR with a caller-owned key |
Add this directory to the application's include paths and include the matching header, for example #include "SharkSslCRACENFF.h". Do not compile the same source twice if FF is used both directly and through DSA. A Zephyr application that uses all five modules can use this CMake fragment after find_package(Zephyr ...):
Remove unused source lines; keep SharkSslCRACENFF.c when using DSA. Use the SDK's Zephyr build so its CRACEN driver libraries and generated configuration are linked. Adding these C files to an unrelated SharkSSL build is insufficient.
Follow the PSA consumer guide to compile SharkSSL against the Nordic provider's <psa/crypto.h> and libraries. Enable SHARKSSL_PSA_CONSUMER=1 and the matching algorithms in both the SharkSSL configuration and Nordic prj.conf. Include the consumer source for every standalone API the application uses; a macro alone does not link that implementation.
SHARKSSL_PSA_CONSUMER_SECRET_HANDLES=1 selects PSA handles for TLS 1.3 secrets. SHARKSSL_PSA_CONSUMER_STRICT_IDENTITY=1 requires a matching certificate identity; for RSA this needs public-key export from the private handle, including CONFIG_PSA_WANT_KEY_TYPE_RSA_KEY_PAIR_EXPORT=y.
For the standalone AES adapter, enable SHARKSSL_PSA_CONSUMER_STANDALONE_AES=1, compile src/psa-consumer/SharkSslPSAConsumerAES.c, and enable the required provider algorithms. This is separate from the direct CRACEN primitives above.
For certificate signing requests (CSRs) using PSA handles, enable SHARKSSL_ENABLE_CSR_CREATION=1 and SHARKSSL_ENABLE_CSR_SIGNING=1 and include src/util/SharkSslCSR.c with the appropriate consumer signing adapters. P-521 ECDSA requires SHARKSSL_ECC_USE_SECP521R1=1, SHARKSSL_USE_SHA_512=1, CONFIG_PSA_WANT_ECC_SECP_R1_521=y and CONFIG_PSA_WANT_ALG_SHA_512=y in the corresponding configurations.
Use the SDK's Zephyr build so it supplies CRACEN driver libraries and generated configuration. The common driver selection is:
Enable provider algorithms and key types according to the operations the application uses. EC-KCDSA verification calls SHA-256 through psa_hash_compute; enable CONFIG_PSA_WANT_ALG_SHA_256=y. Keep CONFIG_CRACEN_RSA_COUNTERMEASURES=y for public-key accelerator use.
For SHAKE256, CONFIG_PSA_WANT_ALG_SHAKE256_512=y exposes the SDK's sxhashalg_shake256_64 descriptor. The standalone module adapts that descriptor for its requested output length; this does not add a PSA XOF API.
For SM4, CONFIG_PSA_WANT_KEY_TYPE_AES=y enables the SDK's symmetric countermeasure-mask loading. The SM4 module addresses the accelerator directly; this setting does not add a PSA SM4 key type or dispatch path.
Initialize the Nordic PSA/CRACEN subsystem before calling a primitive:
This SDK release treats an Ed448 key with 448 PSA bits as 56 bytes in two places. An Ed448 private seed and encoded public key are both 57 bytes. The unmodified CRACEN driver can generate a short private key and report an incorrect public-key output length. SharkSslCRACENECCKeyMgmt.c is the corrected NCS 3.4.1 key-management source. It retains Nordic's license; the only behavioral changes are the two length calculations.
The same SDK's cracen_ecc_signature.c selects Ed25519 public-key derivation for any PureEdDSA private key when Ed25519 support is enabled. Consequently, PureEdDSA verification with an Ed448 key-pair handle fails. The corrected SharkSslCRACENECCSignature.c selects the Ed25519 or Ed448 branch by both algorithm and PSA key bits. Both replacements follow the layout of the other SharkSSL Nordic sources. Do not compile them as application sources or alongside their original driver sources.
For TLS 1.3 Ed448, replace the key-management source in the cracen_psa_driver target. To verify PureEdDSA Ed448 with a private key-pair handle, also replace the signature source. The NCS sources are in this directory, relative to the SDK root:
| NCS source | Replacement from this directory |
|---|---|
cracen_ecc_key_management.c | SharkSslCRACENECCKeyMgmt.c |
cracen_ecc_signature.c | SharkSslCRACENECCSignature.c |
For example, after find_package(Zephyr ...):
These target-source substitutions leave the installed SDK unchanged. Recheck the source interfaces when upgrading NCS. For TLS using Ed448, enable:
Enable CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE=y if the application also generates Ed448 keys through PSA. TLS uses an imported 57-byte Ed448 seed with PSA_ALG_PURE_EDDSA; certificate verification uses a PSA public-key handle.
For direct Ed448ph psa_sign_message and psa_verify_message, also enable CONFIG_PSA_WANT_ALG_ED448PH=y and CONFIG_PSA_WANT_ALG_SHAKE256_512=y. In NCS 3.4.1, the generated nrf-psa-crypto-config.h does not define PSA_WANT_ALG_SHAKE256_512, even when both Kconfig options are enabled. The PSA core then rejects PSA_ALG_ED448PH with PSA_ERROR_INVALID_ARGUMENT before calling CRACEN. Add the missing definition to the psa_core target after find_package(Zephyr ...) when using this SDK release:
The standalone Ed448ph consumer calls psa_hash_compute(PSA_ALG_SHAKE256_512) followed by psa_sign_hash(PSA_ALG_ED448PH). It does not depend on the psa_sign_message configuration setting. With the signature-source replacement, PureEdDSA verification supports an Ed448 private key-pair handle. Without it, import a public-key handle for verification.
r and h as documented in SharkSslCRACENECKCDSA.h. On RETRY_NONCE, generate a new nonce and corresponding r.RETRY_NONCE, generate a new secret nonce.sxhashalg layout and therefore needs a compatibility review after any NCS upgrade.The primitives have no automatic software fallback. Their direct hardware calls are distinct from PSA key-handle and hardware-key-storage interfaces. The Ed448 replacement files belong in the SDK's cracen_psa_driver target, replacing the originals; do not also compile them as application sources.
For AES in a PSA consumer application, select the required consumer API and provider algorithms. This directory supplies no native SharkSslAesCtx AES backend. Native builds use bitsliced C AES; the x86/AArch64 SHARKSSL_OPTIMIZED_AES_ASM, SHARKSSL_OPTIMIZED_GCM_ASM and SHARKSSL_OPTIMIZED_GHASH_ASM selectors are unavailable on Cortex-M33. The Cortex-M guide describes the separate native assembly options applicable to this core.