|
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 GCC or Clang. It provides AES, ChaCha20-Poly1305, SHA-256 and X25519 implementations behind the normal SharkSSL APIs.
.S files through the compiler driver so they are preprocessed.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.S, SharkSslCrypto_X86_CPUID.c |
| AES block API, CBC, CTR, CCM | SHARKSSL_OPTIMIZED_AES_ASM | SharkSslAes_X86.S |
| ChaCha20 | SHARKSSL_OPTIMIZED_CHACHA_ASM | SharkSslCrypto_X86_AVX2.S, SharkSslCrypto_X86_CPUID.c |
| Poly1305 | SHARKSSL_OPTIMIZED_POLY1305_ASM | SharkSslCrypto_X86_Poly1305.S, SharkSslCrypto_X86_CPUID.c |
| SHA-256 | SHARKSSL_OPTIMIZED_SHA256_ASM | SharkSslSha256_X86.S |
| X25519 | SHARKSSL_X25519_ASM_HOOK | SharkSslX25519_X86.S, SharkSslX25519_X86_Adapter.c, SharkSslX25519_X86_AVX2.S, 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.
For example, from this directory with the normal include paths and matching GCM/GHASH configuration supplied by the application:
Pass matching feature definitions and include paths to all C and assembly files. The cipher and X25519 kernels use absolute constant addresses. Compile with -fno-pie -fno-pic and link with -no-pie; those kernels are unsuitable for shared libraries and position-independent executables. The AES block object SharkSslAes_X86.S has no such restriction.
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.