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

Use this backend to add processor-specific cryptography to a 32-bit SharkSSL application built with MSVC. It provides AES, ChaCha20-Poly1305, SHA-256 and X25519 implementations behind the normal SharkSSL APIs.

Requirements

  • Target the Windows Win32/x86 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.
  • Enable MASM in Visual Studio Build Customizations and select Win32.
  • This backend has no VAES or full BigInt implementation.

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_X86.asm, SharkSslCrypto_X86_CPUID.c
AES block API, CBC, CTR, CCM SHARKSSL_OPTIMIZED_AES_ASM SharkSslAes_X86.asm
ChaCha20 SHARKSSL_OPTIMIZED_CHACHA_ASM SharkSslCrypto_X86_AVX2.asm, SharkSslCrypto_X86_CPUID.c
Poly1305 SHARKSSL_OPTIMIZED_POLY1305_ASM SharkSslCrypto_X86_Poly1305.asm, SharkSslCrypto_X86_CPUID.c
SHA-256 SHARKSSL_OPTIMIZED_SHA256_ASM SharkSslSha256_X86.asm
X25519 SHARKSSL_X25519_ASM_HOOK SharkSslX25519_X86.asm, SharkSslX25519_X86_Adapter.c, SharkSslX25519_X86_AVX2.asm, SharkSslCrypto_X86_CPUID.c

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.

Run the following from this directory in an x86 Native Tools Command Prompt to assemble the AES-GCM object with the default AES layout:

rem Compile the corresponding C sources with both GCM/GHASH switches enabled.
ml /nologo /c /coff /safeseh SharkSslCrypto_X86.asm

Use the same assembler for the other selected files. MASM does not read SharkSSL_cfg.h; put feature switches in the C compiler settings as NAME=1. AES layout definitions belong in the MASM settings. Keep /safeseh on every assembler object and retain the linker SafeSEH setting.

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. Keep SHARKSSL_OPTIMIZED_BIGINT_ASM=0 and SHARKSSL_OPTIMIZED_GCM_VAES_ASM=0.

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 and SSE2 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
X25519 with the hook enabled AVX2 and operating-system vector support Integer X25519 assembly

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.