|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
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.
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:
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.
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.
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.
| 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.