|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
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.
.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_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:
Pass matching feature definitions and include paths to all C and assembly files.
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.
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.
| 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.