SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
SharkSSL Nordic CRACEN 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.

Requirements

  • Nordic nRF Connect SDK (NCS) 3.4.1 and an nRF54L15 Zephyr application, such as target nrf54l15dk/nrf54l15/cpuapp.
  • A matching Zephyr GNU or IAR toolchain and the Nordic security libraries.
  • Review compatibility when changing SDK or SoC: these sources depend on CRACEN/SilexPK driver internals, not only the public PSA API.

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.

Build integration

Standalone primitives

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 ...):

# Add only the direct primitives used by this application.
set(SHARKSSL_ROOT "/absolute/path/to/SharkSSL")
set(SHARKSSL_NORDIC_DIR "${SHARKSSL_ROOT}/src/crypto/Nordic")
set(CRACEN_DRIVER_DIR "${ZEPHYR_NRF_MODULE_DIR}/subsys/nrf_security/src/drivers/cracen")
target_include_directories(app PRIVATE
"${SHARKSSL_NORDIC_DIR}"
"${CRACEN_DRIVER_DIR}/silexpk/include"
"${CRACEN_DRIVER_DIR}/sxsymcrypt/include"
"${CRACEN_DRIVER_DIR}/sxsymcrypt/src")
target_sources(app PRIVATE
"${SHARKSSL_NORDIC_DIR}/SharkSslCRACENFF.c"
"${SHARKSSL_NORDIC_DIR}/SharkSslCRACENECKCDSA.c"
"${SHARKSSL_NORDIC_DIR}/SharkSslCRACENDSA.c"
"${SHARKSSL_NORDIC_DIR}/SharkSslCRACENSHAKE256.c"
"${SHARKSSL_NORDIC_DIR}/SharkSslCRACENSM4.c")

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.

TLS through the PSA consumer

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.

Configuration

Nordic driver settings

Use the SDK's Zephyr build so it supplies CRACEN driver libraries and generated configuration. The common driver selection is:

# Route PSA operations to the Nordic CRACEN driver.
CONFIG_PSA_CRYPTO=y
CONFIG_PSA_CRYPTO_DRIVER_CRACEN=y
CONFIG_PSA_CRYPTO_DRIVER_OBERON=n

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:

#include <psa/crypto.h>
/* Stop initialization if the hardware provider is unavailable. */
if (status != PSA_SUCCESS)
{
/* Report the error and do not call a CRACEN primitive. */
}
See Choose a SharkSSL API for build scope and the owning API layer.
int32_t psa_status_t
SharkSSL PSA Crypto API 1.4.1/1.5.0 configurable subset.
Definition: crypto.h:57
#define PSA_SUCCESS
Definition: crypto.h:161
psa_status_t psa_crypto_init(void)
Initialize the provider random source.

Ed448 PSA driver integration for NCS 3.4.1

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:

nrf/subsys/nrf_security/src/drivers/cracen/cracenpsa/src/internal/ecc
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 ...):

# Replace both SDK sources so each implementation is linked exactly once.
set(SHARKSSL_NORDIC_DIR "/absolute/path/to/SharkSSL/src/crypto/Nordic")
get_target_property(cracen_sources cracen_psa_driver SOURCES)
set(replacement_count 0)
foreach(source IN LISTS cracen_sources)
if(source MATCHES "/cracen_ecc_(key_management|signature)\\.c>?$")
list(REMOVE_ITEM cracen_sources "${source}")
math(EXPR replacement_count "${replacement_count}+1")
endif()
endforeach()
if(NOT replacement_count EQUAL 2)
message(FATAL_ERROR "Expected two CRACEN ECC sources; found ${replacement_count}")
endif()
list(APPEND cracen_sources
"${SHARKSSL_NORDIC_DIR}/SharkSslCRACENECCKeyMgmt.c"
"${SHARKSSL_NORDIC_DIR}/SharkSslCRACENECCSignature.c")
set_property(TARGET cracen_psa_driver PROPERTY SOURCES "${cracen_sources}")

These target-source substitutions leave the installed SDK unchanged. Recheck the source interfaces when upgrading NCS. For TLS using Ed448, enable:

CONFIG_PSA_CRYPTO=y
CONFIG_PSA_CRYPTO_DRIVER_CRACEN=y
CONFIG_PSA_CRYPTO_DRIVER_OBERON=n
CONFIG_PSA_WANT_ALG_PURE_EDDSA=y
CONFIG_PSA_WANT_ECC_TWISTED_EDWARDS_448=y
CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT=y
CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_EXPORT=y
CONFIG_PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY=y

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:

# Expose the SHAKE256 descriptor required by this SDK's Ed448ph message path.
target_compile_definitions(psa_core PRIVATE PSA_WANT_ALG_SHAKE256_512=1)

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.

Behavior and limitations

  • FF takes unsigned big-endian operands and a caller-owned, trusted odd prime. It checks encoding and the hardware operand-size limit, not primality or DH peer-key validity. The hardware operand-size limit must be checked for the selected device.
  • EC-KCDSA accepts 32-byte big-endian P-256 values. The application must generate a fresh secret nonce for each signature and separately calculate r and h as documented in SharkSslCRACENECKCDSA.h. On RETRY_NONCE, generate a new nonce and corresponding r.
  • DSA accepts trusted 2048/256 domain parameters and a SHA-256 digest. It checks the public key's range and subgroup membership, but does not validate the primality/order of the domain. The application owns nonce generation; on RETRY_NONCE, generate a new secret nonce.
  • SHAKE256 is one-shot with 1-512 output bytes. It does not support SHAKE128 or streaming/squeeze. It uses the SDK's internal sxhashalg layout and therefore needs a compatibility review after any NCS upgrade.
  • SM4 uses a caller-supplied 128-bit key and a one-shot ECB, CBC or CTR call. ECB and CBC require complete 16-byte blocks; CTR accepts any nonzero length. CBC and CTR require a 16-byte IV. The output must be separate from the input, key and IV. Valid output is cleared if CRACEN cannot be reserved or the hardware operation fails. The key passes through DMA from caller memory; this is not a PSA or KMU-key API. No padding, AEAD or TLS cipher suite is provided.
  • Input and output buffers must not overlap. Check each function's return code; there is no automatic software fallback. The PKE modules do not use PSA key handles or KMU keys. Clear application-owned private scalars, nonces and buffers after use; releasing a PKE request does not promise physical CryptoRAM zeroization.

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.