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

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.
  • GCC or Clang targeting ELF, with the platform CPU-capability adapter available.

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 uppercase .S files through GCC or Clang so preprocessing reads SharkSSL_cfg.h. Compile common C and the adapter with -march=armv8-a; the assembly files select their own optional instruction extensions.

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.

PSA provider build

From the root of a checkout that supplies the provider and its build directory:

# Keep the accelerated provider's objects separate from a portable C build.
make -C build PSA_CRYPTO=1 PSA_ARM64_GCC=1 ODIR=obj-psa-arm64

The recipe uses the default AES-256 layout. Supply the matching SHARKSSL_GCM_M0 value when changing the layout, and rebuild all objects.

Behavior and limitations

The adapter selects optional instructions from operating-system CPU capabilities.

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.