|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
Use this backend to select arithmetic, cipher and hash assembly for a Cortex-M SharkSSL application. Choose files by processor capability and keep the same configuration in C and assembly.
Use little-endian Cortex-M with a matching target configuration. Select the instruction set and optional Digital Signal Processing (DSP) or M-Profile Vector Extension (MVE, also called Helium) features implemented by the part. The M3 files require Thumb-2; M4 arithmetic files require DSP instructions. M0 files use the baseline Thumb instruction set.
| Processor | -mcpu | DSP | BigInt | Other files |
|---|---|---|---|---|
| Cortex-M3 | cortex-m3 | no | BigInt_M3 | Crypto_M3 |
| Cortex-M4, M4F | cortex-m4 | yes | BigInt_M4 | Crypto_M3, P256_M4, P384_M4, X25519_M4, AesGcmCT_M4 |
| Cortex-M7 | cortex-m7 | yes | BigInt_M4 | Crypto_M3, P256_M4, P384_M4, X25519_M4, AesGcmCT_M4 |
| Cortex-M33 with DSP | cortex-m33 | yes | BigInt_M4 | Crypto_M3, P256_M4, P384_M4, X25519_M4 |
| Cortex-M33 without DSP | cortex-m33+nodsp | no | BigInt_M3 | Crypto_M3 |
| Cortex-M85 | cortex-m85 | yes | BigInt_M4 | Crypto_M3, P256_M4, P384_M4, X25519_M4, AesGcmCT_M4 or AesGcmCT_MVE |
| Cortex-M0, M0+, M23 | cortex-m0, cortex-m0plus, cortex-m23 | no | BigInt_M0 | Crypto_M0, P256_M0, P384_M0, X25519_M0 |
Names in the table abbreviate SharkSsl prefixes and file extensions. DSP is optional on Cortex-M33; choose the no-DSP target when it is absent. The M4 GHASH helper is restricted to M4/M7/M85 even where other M4 files support M33. The AES key-expansion helper also supports M33.
Keep the normal C sources. Link exactly one SharkSslBigInt_M0.S, SharkSslBigInt_M3.S or SharkSslBigInt_M4.S when enabling the BigInt backend. Select the matching M0 or M4 curve files and M0 or M3 crypto file from the table.
| Operation | File family | Integer switches set to 1 |
|---|---|---|
| BigInt | SharkSslBigInt_* | SHARKSSL_OPTIMIZED_BIGINT_ASM |
| P-256 | SharkSslP256_* | SHARKSSL_ECC_USE_SECP256R1, SHARKSSL_ECC_P256_ASM |
| P-384 | SharkSslP384_* | SHARKSSL_ECC_USE_SECP384R1, SHARKSSL_ECC_P384_ASM |
| X25519 | SharkSslX25519_* | SHARKSSL_ECC_USE_CURVE25519, SHARKSSL_X25519_DEDICATED, SHARKSSL_X25519_ASM |
| ChaCha20 | SharkSslCrypto_* | SHARKSSL_USE_CHACHA20, SHARKSSL_OPTIMIZED_CHACHA_ASM |
| Poly1305 | SharkSslCrypto_* | SHARKSSL_USE_POLY1305, SHARKSSL_OPTIMIZED_POLY1305_ASM |
| SHA-256 | SharkSslCrypto_* | SHARKSSL_USE_SHA_256, SHARKSSL_OPTIMIZED_SHA256_ASM |
| SHA-384/SHA-512 | SharkSslCrypto_* | Required hash algorithm and SHARKSSL_OPTIMIZED_SHA384_ASM |
The curve files are independent of the generic BigInt selection. Cortex-M3 and M33 without DSP use the M3 BigInt/crypto files and C curve arithmetic; leave the three curve assembly switches at 0 on those targets.
Assemble .S through arm-none-eabi-gcc with the same -mthumb, -mcpu, -mfpu, -mfloat-abi, feature definitions and include paths as C. Clang and Keil Arm Compiler 6 use their GNU-syntax integrated assembler:
In Keil, select armclang as assembler. Legacy armasm syntax is unsupported.
Set BA_BYTE_ORDER=BA_BYTE_ORDER_LITTLE_ENDIAN. Enable SHARKSSL_UNALIGNED_ACCESS only when the target and memory regions permit it. The Thumb-2 SHA routines use word loads; unaligned input requires UNALIGN_TRP to be clear. The M0 hash and Poly1305 routines read unaligned input byte by byte. Supply a secure entropy source in the application.
SHARKSSL_BIGINT_M4_SQR_MIN sets the dedicated-square threshold in words (default 13, minimum 5); 0x10000 omits that routine. For an M0/M0+ with the iterative 32-cycle multiplier, set SHARKSSL_BIGINT_M0_USE_3MUL=1 in assembly. Its default is 0; only 0 and 1 are accepted. The compiler CPU name does not identify the multiplier configuration. This setting also applies to the M0 curve files.
AES block encryption uses bitsliced C. Add only the helpers applicable to the target, with matching switches in C and assembly:
| Helper | File | Switch | Target |
|---|---|---|---|
| AES key expansion | SharkSslAesCT_M4.S | SHARKSSL_AES_CT_KEY_ASM=1 | M4, M7, M33, M85 |
| Scalar GHASH | SharkSslAesGcmCT_M4.S | SHARKSSL_AES_GCM_CT_M4_ASM=1 | M4, M7, M85 |
| Helium GHASH | SharkSslAesGcmCT_MVE.S | SHARKSSL_AES_GCM_CT_MVE_ASM=1 | M85 with MVE |
The two GHASH options are mutually exclusive and default to 0. GHASH does not replace AES rounds. The scalar helper relies on the supported cores' fixed-latency long multiplication; the configuration rejects M3, M33 and M55 for this helper. M85 acceptance depends on the compiler target macros, including its BTI feature macro where used by SharkSSL_cfg.h. Disabling PACBTI in the compiler target can therefore reject an M85 build.
The M3 crypto file selects four-block MVE ChaCha20 when __ARM_FEATURE_MVE & 1 is set. Short inputs and remaining bytes use the scalar path. Before using MVE, the platform must enable CP10/CP11 access and preserve vector state across interrupts and task switches. SharkSSL does not configure CPACR.
For MVE ChaCha20 with GCC, -mcpu=cortex-m85 -mthumb -mfloat-abi=softfp enables the feature macro. +nomve retains scalar ChaCha20; a soft-float C build does not remove the platform's vector-state obligations when the separate MVE GHASH object is selected.
Use the assembly section options SHARKSSL_X25519_ASM_SECTION, SHARKSSL_ECC_P256_ASM_SECTION, SHARKSSL_ECC_P384_ASM_SECTION, SHARKSSL_SHA256_ASM_SECTION and SHARKSSL_SHA384_ASM_SECTION when placing code in RAM. For example, .RamFunc must have a linker mapping and startup copy. Code placement and flash wait states affect performance.
AES-GCM and the AES block API use the bitsliced C AES in SharkSslAesGcmCT.h. Keep SHARKSSL_OPTIMIZED_AES_ASM, SHARKSSL_OPTIMIZED_GCM_ASM and SHARKSSL_OPTIMIZED_GHASH_ASM at 0: the generic crypto implementation rejects these options on this target.
The optional helpers above have separate selectors. P-256/P-384 assembly replaces prime-field operations, while other curves and scalar-order arithmetic keep their normal implementation. Cortex-M3 has no assembly curve backend; M0/M0+/M23 use their own files.
BigInt M4 uses indirect branches into a kernel table. Review compatibility before enforcing pointer authentication and branch target identification (PACBTI). Compiler runtime multiplication helpers and instruction latency also affect timing on baseline cores; selecting assembly does not establish constant-time behavior for all callers or physical side-channel resistance.
The AES block API, CBC, CTR and CCM use SharkSslAesCtx. These application APIs do not add TLS cipher suites. SharkSSL TLS uses AES-GCM or ChaCha20-Poly1305 for record protection.