SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
SharkSSL AArch64 cryptography (IAR)

Use this backend for native cryptography in a 64-bit Arm SharkSSL application. Select the assembly routines your application needs while retaining the public SharkSSL APIs.

Requirements

  • Little-endian AArch64 with the LP64 data model; big-endian and ILP32 are unsupported.
  • A target TargConfig.h, matching include paths and a consistent ABI for all objects.
  • Keep common C at baseline Armv8-A so optional instructions remain in guarded code.
  • IAR Embedded Workbench for Arm with AArch64 support, such as EWARM 9.70.2.

Build integration

Keep SharkSslCrypto.c and SharkSslBigInt.c in the normal library build. Enable the required algorithms, then add the files for each selected option:

Option Files
SHARKSSL_OPTIMIZED_GCM_ASM SharkSslGcm_ARM64.s, SharkSslGhash_ARM64.s
SHARKSSL_OPTIMIZED_GHASH_ASM SharkSslGhash_ARM64.s
SHARKSSL_OPTIMIZED_AES_ASM SharkSslAes_ARM64.s
SHARKSSL_OPTIMIZED_CHACHA_ASM SharkSslChaCha_ARM64.s
SHARKSSL_OPTIMIZED_POLY1305_ASM SharkSslPoly1305_ARM64.s
SHARKSSL_ARM64_SHA256_INTRINSICS SharkSslSha256_ARM64.s
SHARKSSL_OPTIMIZED_SHA384_ASM SharkSslSha512_ARM64.s
SHARKSSL_X25519_ASM_HOOK SharkSslX25519_ARM64.s, SharkSslX25519_ARM64_Adapter.c
SHARKSSL_OPTIMIZED_BIGINT_ASM SharkSslBigInt_ARM64.s
SHARKSSL_ECC_P256_ASM SharkSslP256_ARM64.s
SHARKSSL_ECC_P384_ASM SharkSslP384_ARM64.s

Compile SharkSslCrypto_ARM64.c whenever AES, AES-GCM, GHASH, ChaCha20 or SHA-256 acceleration is selected. The X25519 option also needs its adapter. Set each desired integer option to 1, or 0 to keep the corresponding C implementation. Pass identical configuration definitions to adapters, common C and assembly. Enable GCM and GHASH together.

Assemble .s with iasmarm --aarch64 --abi lp64 and compile C with iccarm --aarch64 --abi lp64 -e. Include inc and the target configuration directory. The -e option is required for the noinline attribute used by SharkSslECC.c. IASMARM preprocesses the assembly configuration. Link with the IAR toolchain and use the IAR backend objects consistently.

Configuration

AES-GCM layout

Use SHARKSSL_AES_SMALL_FOOTPRINT=0. Pass SHARKSSL_GCM_M0 to assembly with the byte offset matching the C context:

Configuration Offset
AES-256 enabled, or SHARKSSL_NOPACK=1 244
AES-192 is the largest enabled key 212
AES-128 only 180

The adapter checks the C layout and a layout-specific linker symbol checks the assembly agreement. Rebuild all objects after configuration changes. The AES block object needs no layout definition because C passes its round keys and round count. SHARKSSL_OPTIMIZED_AES_ASM and SHARKSSL_PSA_CONSUMER_STANDALONE_AES are mutually exclusive.

X25519 and independent arithmetic options

X25519 requires SHARKSSL_USE_ECC=1, SHARKSSL_ECC_USE_CURVE25519=1, SHARKSSL_X25519_DEDICATED=1, 32-bit BigInt words and SHARKSSL_X25519_ASM=0. Leave SHARKSSL_X25519_TEST undefined. BigInt, P-256 and P-384 options select their own files independently; enable the matching curve algorithms when selecting field assembly. Keep SHARKSSL_OPTIMIZED_BIGINT_WORD_ASM=0 with the full BigInt backend.

Target capabilities

This adapter has no runtime CPU probe. The following integer switches default to 0 and accept 0 or 1. Set a capability to 1 only if every CPU that may execute the image provides it, and pass it to common C and the adapter:

Switch Capability
SHARKSSL_ARM64_IAR_HAS_ASIMD Advanced SIMD (NEON)
SHARKSSL_ARM64_IAR_HAS_AES_PMULL AES and polynomial multiplication; also requires ASIMD
SHARKSSL_ARM64_IAR_HAS_SHA2 SHA-256 instructions; also requires ASIMD

The X25519 assembly hook requires ASIMD; otherwise disable the hook and use C. SHARKSSL_AES_CT_NEON defaults according to the ASIMD setting and can be set explicitly for the bitsliced C AES path.

Behavior and limitations

Hardware AES-GCM and AES block operations require ASIMD, AES and PMULL. Without them, SharkSSL uses bitsliced C AES. SHA-256 uses SHA2 instructions when selected and available, otherwise C. ChaCha20 selects NEON or integer assembly. SHA-512, BigInt, P-256 and P-384 assembly use integer registers. The X25519 kernel uses NEON.

SHARKSSL_AES_CT_NEON enables NEON processing in the bitsliced C AES and software GHASH paths without adding an assembly file. It is independent of the assembly selectors. Keep AES and GCM contexts on processors with the capabilities used when constructing them.

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.

Keep the normal timing protections enabled. An assembly selection is not a guarantee about the timing of surrounding compiled C, the target's instruction latency, or physical side-channel resistance.