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

Use this backend to add processor-specific cryptography to a 64-bit SharkSSL application built with MSVC. 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 Windows x64 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 x64.

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.asm, SharkSslCrypto_X64_CPUID.c
AES block API, CBC, CTR, CCM SHARKSSL_OPTIMIZED_AES_ASM SharkSslAes_X64.asm
ChaCha20 SHARKSSL_OPTIMIZED_CHACHA_ASM SharkSslCrypto_X64_AVX2.asm, SharkSslCrypto_X64_CPUID.c
Poly1305 SHARKSSL_OPTIMIZED_POLY1305_ASM SharkSslCrypto_X64_Poly1305.asm, SharkSslCrypto_X64_CPUID.c
SHA-256 SHARKSSL_OPTIMIZED_SHA256_ASM SharkSslSha256_X64.asm
X25519 SHARKSSL_X25519_ASM_HOOK SharkSslX25519_X64.asm, 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.asm, SharkSslCrypto_X64_VAES_CPUID.c
SHA-384 and SHA-512 SHARKSSL_OPTIMIZED_SHA384_ASM SharkSslSha512_X64.asm
P-256 field arithmetic SHARKSSL_ECC_P256_ASM SharkSslP256_X64.asm
P-384 field arithmetic SHARKSSL_ECC_P384_ASM SharkSslP384_X64.asm
BigInt operations SHARKSSL_OPTIMIZED_BIGINT_ASM SharkSslBigInt_X64.asm

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 x64 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.
ml64 /nologo /c SharkSslCrypto_X64.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.

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.asm 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.