SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
SharkSSL 64-bit x86 cryptography (GCC)

Use this backend to add processor-specific cryptography to a 64-bit SharkSSL application built with GCC or Clang. It provides AES, ChaCha20-Poly1305, SHA-256 and X25519 implementations behind the normal SharkSSL APIs. It also provides SHA-384/SHA-512, P-256/P-384 field arithmetic and BigInt assembly.

Requirements

  • Target the System V AMD64, LP64 ELF application binary interface (ABI). Use objects from this directory only with a matching application and compiler target.
  • Keep common C and feature probes compiled for the oldest supported CPU. Global AVX, AVX2, BMI2 or ADX compiler options can bypass runtime fallback.
  • Enable the required algorithms in the application configuration. Optimization switches select implementations; they do not enable disabled algorithms.
  • Assemble uppercase .S files through the compiler driver so they are preprocessed.

Build integration

Keep the normal SharkSSL C sources, including SharkSslCrypto.c, SharkSslBigInt.c and SharkSslECC.c when elliptic curves are enabled. Add the files for each selected row and set its switches to 1. Include each shared CPU-feature probe only once.

Operation Switches Additional files
AES-GCM and GHASH SHARKSSL_OPTIMIZED_GCM_ASM, SHARKSSL_OPTIMIZED_GHASH_ASM SharkSslCrypto_X64.S, SharkSslCrypto_X64_CPUID.c
AES block API, CBC, CTR, CCM SHARKSSL_OPTIMIZED_AES_ASM SharkSslAes_X64.S
ChaCha20 SHARKSSL_OPTIMIZED_CHACHA_ASM SharkSslCrypto_X64_AVX2.S, SharkSslCrypto_X64_CPUID.c
Poly1305 SHARKSSL_OPTIMIZED_POLY1305_ASM SharkSslCrypto_X64_Poly1305.S, SharkSslCrypto_X64_CPUID.c
SHA-256 SHARKSSL_OPTIMIZED_SHA256_ASM SharkSslSha256_X64.S
X25519 SHARKSSL_X25519_ASM_HOOK SharkSslX25519_X64.S, SharkSslX25519_X64_Adapter.c
VAES AES-GCM SHARKSSL_OPTIMIZED_GCM_VAES_ASM plus both GCM/GHASH switches AES-GCM files above plus SharkSslCrypto_X64_VAES.S, SharkSslCrypto_X64_VAES_CPUID.c
SHA-384 and SHA-512 SHARKSSL_OPTIMIZED_SHA384_ASM SharkSslSha512_X64.S
P-256 field arithmetic SHARKSSL_ECC_P256_ASM SharkSslP256_X64.S
P-384 field arithmetic SHARKSSL_ECC_P384_ASM SharkSslP384_X64.S
BigInt operations SHARKSSL_OPTIMIZED_BIGINT_ASM SharkSslBigInt_X64.S

The X25519 adapter needs src, inc and the selected target configuration directory on its include path. Compile C adapters with the same SharkSSL configuration as the library. Link the selected objects into the application.

For example, from this directory with the normal include paths and matching GCM/GHASH configuration supplied by the application:

# Select the default AES-256 context layout for this assembly object.
gcc -c -DSHARKSSL_GCM_M0=244 SharkSslCrypto_X64.S

Pass matching feature definitions and include paths to all C and assembly files.

Configuration

Algorithm and layout selection

The optimization switches accept integer 0 or 1; the SHARKSSL_OPTIMIZED_* switches in the table default to 0. An undefined or zero SHARKSSL_X25519_ASM_HOOK keeps the C X25519 path. Enable GCM and GHASH together. VAES, where available, also needs the AES-NI GCM files for fallback and partial-block processing.

Use the same AES context layout in C and every AES-GCM assembly object:

Largest enabled AES key SHARKSSL_GCM_M0 byte offset
AES-256, or any build with SHARKSSL_NOPACK=1 244
AES-192, with AES-256 disabled and SHARKSSL_NOPACK=0 212
AES-128 only, with SHARKSSL_NOPACK=0 180

The integer switches SHARKSSL_USE_AES_128, SHARKSSL_USE_AES_192 and SHARKSSL_USE_AES_256 select key sizes and default to 1, 0 and 1. The default algorithms enable AES-128 and AES-256, disable AES-192 and use SHARKSSL_NOPACK=0. Rebuild C and assembly after changing this layout. The separate AES block object needs no SHARKSSL_GCM_M0 definition. Do not combine SHARKSSL_OPTIMIZED_AES_ASM with SHARKSSL_PSA_CONSUMER_STANDALONE_AES.

X25519

Set SHARKSSL_USE_ECC, SHARKSSL_ECC_USE_CURVE25519 and SHARKSSL_X25519_DEDICATED to 1. Use 32-bit BigInt words, and leave SHARKSSL_X25519_ASM undefined or 0; this port uses SHARKSSL_X25519_ASM_HOOK instead. Leave SHARKSSL_X25519_TEST undefined in application builds. Use the public key-exchange API, which retains scalar clamping and zero-secret rejection.

BigInt and prime-field arithmetic

SHARKSSL_OPTIMIZED_BIGINT_ASM=1 selects SharkSslBigInt_X64.S for addition, subtraction, right shift, multiplication and Montgomery reduction. It uses baseline x64 instructions and has no runtime feature probe. Keep SHARKSSL_OPTIMIZED_BIGINT_WORD_ASM=0; the two selectors are exclusive.

P-256 and P-384 assembly can be selected independently of each other and of BigInt. Enable the matching SHARKSSL_ECC_USE_SECP256R1 or SHARKSSL_ECC_USE_SECP384R1 algorithm. These objects accelerate arithmetic modulo the field prime; scalar-order arithmetic and higher-level point operations remain in C. Link an enabled object even if the CPU will use C fallback.

Behavior and limitations

CPU selection

Operation Required capability Fallback
AES-GCM SSSE3, AES-NI and PCLMULQDQ Bitsliced C AES-GCM
AES block API AES-NI Bitsliced C AES
ChaCha20 and Poly1305 AVX2 plus operating-system XMM/YMM state support C
SHA-256 SHA instructions, SSSE3 and SSE2 C SHA-256
VAES AES-GCM VAES, VPCLMULQDQ, AVX2 and the AES-NI GCM capabilities AES-NI GCM, then C
X25519 BMI2 and ADX C X25519
SHA-384/SHA-512, P-256/P-384 field operations BMI2 Corresponding C implementation

AVX2 selection checks AVX, OSXSAVE and enabled XMM/YMM state before using vector instructions. SHA-256 uses XMM instructions without AVX state. Its C fallback honors SHARKSSL_SHA256_SMALL_FOOTPRINT. Each endpoint selects its local implementation independently of TLS cipher negotiation. Keep AES contexts on processors with the same capabilities as the processor that constructed them; do not serialize internal contexts.

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.

Processor-specific assembly does not by itself establish constant-time behavior for every caller or resistance to physical side channels. Keep the normal SharkSSL timing protections enabled and use the public APIs.