|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
Add/remove SharkSSL features and/or optimize for speed versus size.
Set configuration macros consistently for all C and assembly files in your build. Begin with the shipped defaults, establish a working connection, and then measure individual changes on your target.
Modules | |
| PSA consumer | |
| HASH algorithms | |
Files | |
| file | SharkSSL_opts.h |
| See Choose a SharkSSL API for build scope and the owning API layer. | |
Macros | |
| #define | SHARKSSL_TLS_1_3 1 |
| TLS 1.3 stack Disable by setting SHARKSSL_TLS_1_3=0. More... | |
| #define | SHARKSSL_TLS_1_2 1 |
| TLS 1.2 stack Disable by setting SHARKSSL_TLS_1_2=0. More... | |
| #define | SHARKSSL_PSA_KEY_SLOTS 12 |
| Number of volatile key slots in the SharkSSL PSA provider. More... | |
| #define | SHARKSSL_PSA_DYNAMIC_KEY_SLOTS 0 |
| Select 1 to allocate SharkSSL PSA provider key slots on demand. More... | |
| #define | SHARKSSL_RFC_9846_CONFORMANCE_PROFILE 0 |
| Select 1 to enforce the compile-time feature set required by the general RFC 9846 profile. More... | |
| #define | SHARKSSL_USE_AES_256 1 |
| Enable/disable AES 256. More... | |
| #define | SHARKSSL_USE_AES_128 1 |
| Enable/disable AES 128. More... | |
| #define | SHARKSSL_USE_AES_192 0 |
| AES-192 is not used in SSL/TLS enable only if needed in application using the crypto API. More... | |
| #define | SHARKSSL_ENABLE_AES_GCM 1 |
| AES-GCM require AES: relevant ciphersuites are included. More... | |
| #define | SHARKSSL_AES_GCM_SOFTWARE_CT 0 |
| Select fixed-access software AES encryption and GHASH for AES-GCM. More... | |
| #define | SHARKSSL_USE_CHACHA20 1 |
| AES-CCM require AES: only for crypto functions - CCM TLS ciphersuites removed. More... | |
| #define | SHARKSSL_SSL_SERVER_CODE 1 |
| Select 1 to enable SERVER side TLS. More... | |
| #define | SHARKSSL_ENABLE_CLIENT_AUTH 1 |
| Select 1 to enable client authentication from server. More... | |
| #define | SHARKSSL_MAX_HANDSHAKE_LENGTH 0x00004000UL |
| Select 1 to enable support for Post Handshake Authentication (RFC 8446 sections 4.2.6 and 4.6.2) More... | |
| #define | SHARKSSL_ENABLE_HELLO_RETRY_REQUEST SHARKSSL_TLS_1_3 |
| Compile TLS 1.3 HelloRetryRequest handling. More... | |
| #define | SHARKSSL_TLS_1_3_INITIAL_KEY_SHARE_X25519_ONLY 0 |
| Select 1 to send only an X25519 key share in the initial TLS 1.3 ClientHello. More... | |
| #define | SHARKSSL_TLS_1_3_INITIAL_BRAINPOOL_GROUP 0 |
| Select one RFC 8734 Brainpool group as the initial TLS 1.3 key share Set to TLS_NAMEDGROUP_BRAINPOOLP256R1TLS13, P384R1TLS13, or P512R1TLS13 Zero retains the usual initial key shares. More... | |
| #define | SHARKSSL_ENABLE_KEY_UPDATE SHARKSSL_TLS_1_3 |
| Select 1 to enable TLS 1.3 KeyUpdate support (RFC 9846 section 4.7.3; RFC 8446 section 4.6.3). More... | |
| #define | SHARKSSL_TLS_1_3_AES_GCM_KEY_UPDATE_THRESHOLD 0x00800000UL |
| Number of TLS 1.3 records that may be encrypted with one AES-GCM key before SharkSSL proactively sends a KeyUpdate. More... | |
| #define | SHARKSSL_SSL_CLIENT_CODE 1 |
| Select 1 to enable CLIENT side TLS. More... | |
| #define | SHARKSSL_RANDOMIZE_EXTENSIONS 1 |
| Select 1 to randomize the order of extensions in ClientHello. More... | |
| #define | SHARKSSL_ENABLE_SNI 1 |
| Select 1 to enable support for Server Name Indication. More... | |
| #define | SHARKSSL_ENABLE_CA_EXTENSION 1 |
| Select 1 to enable support for Certificate Authorities extension (RFC 8446 section 4.2.4) Note: SHARKSSL_TLS_1_3 must be enabled. More... | |
| #define | SHARKSSL_ENABLE_RSA 1 |
| Select 0 to disable RSA ciphersuites. More... | |
| #define | SHARKSSL_ENABLE_SESSION_CACHE 1 |
| Select 1 to enable session caching. More... | |
| #define | SHARKSSL_ENABLE_SECURE_RENEGOTIATION SHARKSSL_TLS_1_2 |
| Select 1 to enable renegotiation Only secure renegotiation (RFC 5746) is supported Note: with the default define below, it is enabled whenever TLS 1.2 is NOTE: IMPLEMENTED ONLY ON THE SERVER SIDE. More... | |
| #define | SHARKSSL_ENABLE_DHE_RSA 0 |
| Enable legacy TLS 1.2 DHE_RSA ciphersuites. More... | |
| #define | SHARKSSL_USE_SHA_256 1 |
| TLS 1.2/1.3 require SHA-256, do not modify the following settings DES and ClientHello v2.0 are deprecated in TLS 1.2 - RFC5246. More... | |
| #define | SHARKSSL_ENABLE_SELECT_CIPHERSUITE 1 |
| Enable/disable the SharkSslCon_selectCiphersuite API. More... | |
| #define | SHARKSSL_SELECT_CIPHERSUITE_LIST_DEPTH 8 |
| Determine the number of ciphersuites that can be selected, in decreasing order of preference; this value is only in effect if the SHARKSSL_ENABLE_SELECT_CIPHERSUITE is selected. More... | |
| #define | SHARKSSL_ENABLE_ALPN_EXTENSION 1 |
| Enable/disable ALPN API (support for ALPN extension, RFC 7301) More... | |
| #define | SHARKSSL_ENABLE_RSA_API 1 |
| Enable/disable RSA API (sharkssl_RSA_public_encrypt, sharkssl_RSA_private_decrypt, sharkssl_RSA_private_encrypt, sharkssl_RSA_public_decrypt, SharkSslRSAKey_size) More... | |
| #define | SHARKSSL_ENABLE_RSA_PKCS1 1 |
| Enable the native RSA key generator. More... | |
| #define | SHARKSSL_ENABLE_ECDSA_API 1 |
| Enable/disable RSASSA-PSS padding in RSA API (RFC 8017) (SHARKSSL_ENABLE_RSA_API must be enabled to use RSASSA-PSS through the RSA API) More... | |
| #define | SHARKSSL_ECDSA_ONLY_VERIFY 0 |
| Disable ECDSA sign API functions (sharkssl_ECDSA_sign, SharkSslECDSA_siglen) - effective only if ECDSA API is compiled (SHARKSSL_ENABLE_ECDSA_API must be enabled) and no SSL/TLS library used (only RayCrypto); used to achieve minimum code size. More... | |
| #define | SHARKSSL_ENABLE_PEM_API 1 |
| Select 1 to enable PEM certs/keys decoding If RSA_API is enabled, then also the functions sharkssl_PEM_to_RSAKey and SharkSslRSAKey_free are available If ECDSA_API is enabled, then also the functions sharkssl_PEM_to_ECCKey and SharkSslECCKey_free are available. More... | |
| #define | SHARKSSL_ENABLE_INFO_API 1 |
| Enable/disable support for encrypted PKCS#8 certificates in sharkssl_PEM function (requires SHARKSSL_ENABLE_AES_CBC) More... | |
| #define | SHARKSSL_ENABLE_CERT_CHAIN 1 |
| Select 1 to enable certificate chain support. More... | |
| #define | SHARKSSL_ENABLE_CA_LIST 1 |
| Select 1 to enable CA check (client or server with client auth) More... | |
| #define | SHARKSSL_ENABLE_CERTSTORE_API 1 |
| Select 1 to enable certificate storage. More... | |
| #define | SHARKSSL_ENABLE_CERT_KEYUSAGE 0 |
| Select 1 to enable SharkSslCertInfo_parseCert for local DER certificates. More... | |
| #define | SHARKSSL_MD5_SMALL_FOOTPRINT 0 |
| Select 1 (small ROM footprint, slow) or 0 (large, fast) More... | |
| #define | SHARKSSL_SHA1_SMALL_FOOTPRINT 0 |
| #define | SHARKSSL_SHA256_SMALL_FOOTPRINT 0 |
| Select 1 for smaller, but slower SHA256. More... | |
| #define | SHARKSSL_BIGINT_EXP_SLIDING_WINDOW_K 4 |
| Select a window size between 1 (slower, less RAM) and 5. More... | |
| #define | SHARKSSL_BIGINT_MULT_LOOP_UNROLL 1 |
| Select 0 (slower, less ROM) or 1 (20% faster, more ROM) More... | |
| #define | SHARKSSL_ENABLE_AES_CTR_MODE 1 |
| Select 1 to include AES CTR mode (USE_AES_xxx must be enabled) More... | |
| #define | SHARKSSL_AES_CIPHER_LOOP_UNROLL 1 |
| Select 0 (35% less ROM) or 1 (10-15% faster) More... | |
| #define | SHARKSSL_UNALIGNED_ACCESS 0 |
| Select 1 if your architecture supports unaligned memory access (x86, ARM-Cortex-M3, ColdFire) More... | |
| #define | SHARKSSL_BIGINT_WORDSIZE 32 |
| Select 8, 16 or 32 according to your architecture. More... | |
| #define | SHARKSSL_USE_ECC 1 |
| Elliptic Curve Cryptography. More... | |
| #define | SHARKSSL_ENABLE_ECDSA 1 |
| Select 1 to enable generation and verification of elliptic curve digital signatures. More... | |
| #define | SHARKSSL_ECC_VERIFY_POINT 1 |
| Select 1 to verify that a point lies on a curve; TLS 1.3 always enables this verification for peer key shares. More... | |
| #define | SHARKSSL_ECC_TIMING_RESISTANT 1 |
| Enable Ed25519/Ed448 support (RFC 8032). More... | |
| #define | SHARKSSL_ECC_FIXED_BASE_COMB 1 |
| Compute k*G, for G the base point of SECP256R1 and SECP384R1 (key generation, ECDSA signing), with a fixed-base comb and a table of 16 precomputed points per curve in flash: about 1 KB for SECP256R1 and 1.5 KB for SECP384R1 with 32-bit words. More... | |
| #define | SHARKSSL_ECC_MULT_FIXED_WINDOW 4 |
| Compute k*Q for any other point Q of SECP256R1, SECP384R1 and SECP521R1 (ECDH shared secret) with a fixed window of this many bits and the same timing resistance: about 35% faster than the generic multiplication. More... | |
| #define | SHARKSSL_ECC_USE_SECP256R1 1 |
| Enable/disable the SECP256R1 curve. More... | |
| #define | SHARKSSL_ECC_USE_SECP384R1 1 |
| Enable/disable the SECP384R1 curve. More... | |
| #define | SHARKSSL_ECC_USE_SECP521R1 1 |
| Enable/disable the SECP521R1 curve. More... | |
| #define | SHARKSSL_ECC_USE_BRAINPOOLP256R1 1 |
| Enable/disable the brainpoolP256r1 curve (RFC 5639) More... | |
| #define | SHARKSSL_ECC_USE_BRAINPOOLP384R1 1 |
| Enable/disable the brainpoolP384r1 curve (RFC 5639) More... | |
| #define | SHARKSSL_ECC_USE_BRAINPOOLP512R1 1 |
| Enable/disable the brainpoolP512r1 curve (RFC 5639) More... | |
| #define | SHARKSSL_ECC_USE_CURVE25519 1 |
| Enable/disable the Curve25519 curve (RFC 7748) More... | |
| #define | SHARKSSL_ENABLE_X25519_API 1 |
| Enable/disable the X25519 public API (sharkssl_X25519_createKeyPair, sharkssl_X25519_sharedSecret) More... | |
| #define | SHARKSSL_X25519_DEDICATED 1 |
| Select 1 to use dedicated Curve25519 field arithmetic (SharkSslBigInt.c) modulo p = 2^255 - 19, with a fixed inversion chain. More... | |
| #define | SHARKSSL_ECC_USE_CURVE448 0 |
| Enable/disable the Curve448 curve (RFC 7748) More... | |
| #define | SHARKSSL_ENABLE_ECDHE_RSA 1 |
| Select 1 to enable ECDHE_RSA ciphersuites (RFC 4492) Elliptic Curve Cryptography (SHARKSSL_USE_ECC) must be enabled RSA (SHARKSSL_ENABLE_RSA) must be enabled. More... | |
| #define | SHARKSSL_ENABLE_ECDHE_ECDSA 1 |
| Select 1 to enable ECDHE_ECDSA ciphersuites (RFC 4492) Elliptic Curve Cryptography (SHARKSSL_USE_ECC) must be enabled SHARKSSL_ENABLE_ECDSA must be set. More... | |
| #define | SHARKSSL_OPTIMIZED_BIGINT_ASM 0 |
| Enabling big integer assembler library requires SharkSslBigInt_XX.s. More... | |
| #define | SHARKSSL_ECC_P256_ASM 0 |
| Select 1 to use the assembly for the P-256 (secp256r1) field arithmetic: on Cortex-M4/M7 SharkSslP256_M4.S for GCC, SharkSslP256_M4.s for IAR and Keil; on RXv2/RXv3 SharkSslP256_RX.S for GCC, SharkSslP256_RX.s for IAR. More... | |
| #define | SHARKSSL_ECC_P384_ASM 0 |
| Select 1 to use the assembly for the P-384 (secp384r1) field arithmetic: on Cortex-M4/M7 SharkSslP384_M4.S for GCC, SharkSslP384_M4.s for IAR and Keil; on RXv2/RXv3 SharkSslP384_RX.S for GCC, SharkSslP384_RX.s for IAR. More... | |
| #define | SHARKSSL_OPTIMIZED_CHACHA_ASM 0 |
| Enabling assembler optimized CHACHA requires SharkSslCrypto_XX.s. More... | |
| #define | SHARKSSL_OPTIMIZED_POLY1305_ASM 0 |
| Enabling assembler optimized POLY requires SharkSslCrypto_XX.s. More... | |
| #define | SHARKSSL_OPTIMIZED_SHA256_ASM 0 |
| Enabling assembler optimized SHA-256 requires SharkSslCrypto_XX.s. More... | |
| #define | SHARKSSL_OPTIMIZED_SHA384_ASM 0 |
| Enabling assembler optimized SHA-384 and SHA-512 requires SharkSslCrypto_XX.s. More... | |
| #define | SHARKSSL_OPTIMIZED_GHASH_ASM 0 |
| Enabling assembler optimized GHASH requires SharkSslCrypto_XX.s. More... | |
| #define | SHARKSSL_OPTIMIZED_GCM_ASM 0 |
| Enabling the combined assembler AES-GCM block kernel requires SharkSslCrypto_XX.s. More... | |
| #define | SHARKSSL_OPTIMIZED_GCM_VAES_ASM 0 |
| Enabling the VAES/VPCLMULQDQ AES-GCM backend requires the VAES assembly file (SharkSslCrypto_X64_VAES.asm) and its CPUID probe to be linked in addition to the AES-NI kernel. More... | |
| #define | SHARKSSL_USE_RNG_TINYMT 0 |
| Setting this macro to 1 enables TinyMT32 and disables other RNGs. More... | |
| #define | SHARKSSL_USE_RNG_FORTUNA 0 |
| Setting this macro to 1 enables the Fortuna RNG. More... | |
| #define | SHARKSSL_RNG_MULTITHREADED 1 |
| Setting this macro to 1 enables the usage of sharkssl_rng in a multithreaded environment. More... | |
| #define | SHARKSSL_NOPACK 0 |
| Do not pack option. More... | |
| #define | SHARKSSL_CHECK_DATE 0 |
| SharkSslCon_trusted also checks certificate expiration and returns SharkSslConTrust_CertCnDate if date(s) are within: timeFrom <= now and timeTo >= now This setting requires baGetUnixTime() returning the correct time. More... | |
| #define SHARKSSL_AES_CIPHER_LOOP_UNROLL 1 |
Select 0 (35% less ROM) or 1 (10-15% faster)
| #define SHARKSSL_AES_GCM_SOFTWARE_CT 0 |
Select fixed-access software AES encryption and GHASH for AES-GCM.
The AES-GCM context layout and public API stay unchanged. Other AES modes retain their selected backend. Hardware or assembler GCM backends use their own security properties. The option is disabled by default because it uses more cycles and stack. SHARKSSL_AES_CIPHER_LOOP_UNROLL also selects the faster (1) or the smaller (0) code for this option.
| #define SHARKSSL_BIGINT_EXP_SLIDING_WINDOW_K 4 |
Select a window size between 1 (slower, less RAM) and 5.
| #define SHARKSSL_BIGINT_MULT_LOOP_UNROLL 1 |
Select 0 (slower, less ROM) or 1 (20% faster, more ROM)
| #define SHARKSSL_BIGINT_WORDSIZE 32 |
Select 8, 16 or 32 according to your architecture.
| #define SHARKSSL_CHECK_DATE 0 |
SharkSslCon_trusted also checks certificate expiration and returns SharkSslConTrust_CertCnDate if date(s) are within: timeFrom <= now and timeTo >= now This setting requires baGetUnixTime() returning the correct time.
| #define SHARKSSL_ECC_FIXED_BASE_COMB 1 |
Compute k*G, for G the base point of SECP256R1 and SECP384R1 (key generation, ECDSA signing), with a fixed-base comb and a table of 16 precomputed points per curve in flash: about 1 KB for SECP256R1 and 1.5 KB for SECP384R1 with 32-bit words.
ECDSA signing is 2.4 to 3.3 times faster than with the generic multiplication, with the same timing resistance. Set it to 0 to save the tables and about 3 KB of code.
| #define SHARKSSL_ECC_MULT_FIXED_WINDOW 4 |
Compute k*Q for any other point Q of SECP256R1, SECP384R1 and SECP521R1 (ECDH shared secret) with a fixed window of this many bits and the same timing resistance: about 35% faster than the generic multiplication.
The window holds 2^(bits - 1) precomputed points in RAM during the multiplication: with 4, 768 bytes for SECP256R1, 1152 for SECP384R1 and 1632 for SECP521R1; 5 doubles them for 0 to 4% more speed. Set it to 0 to use the generic multiplication, which needs less RAM and about 2.5 KB less code.
| #define SHARKSSL_ECC_P256_ASM 0 |
Select 1 to use the assembly for the P-256 (secp256r1) field arithmetic: on Cortex-M4/M7 SharkSslP256_M4.S for GCC, SharkSslP256_M4.s for IAR and Keil; on RXv2/RXv3 SharkSslP256_RX.S for GCC, SharkSslP256_RX.s for IAR.
Multiplication, addition and subtraction modulo the P-256 prime then run in assembly and in constant time; the other curves are not affected. Independent of SHARKSSL_OPTIMIZED_BIGINT_ASM.
| #define SHARKSSL_ECC_P384_ASM 0 |
Select 1 to use the assembly for the P-384 (secp384r1) field arithmetic: on Cortex-M4/M7 SharkSslP384_M4.S for GCC, SharkSslP384_M4.s for IAR and Keil; on RXv2/RXv3 SharkSslP384_RX.S for GCC, SharkSslP384_RX.s for IAR.
Multiplication, addition and subtraction modulo the P-384 prime then run in assembly and in constant time; the other curves are not affected. Independent of SHARKSSL_ECC_P256_ASM and SHARKSSL_OPTIMIZED_BIGINT_ASM.
| #define SHARKSSL_ECC_TIMING_RESISTANT 1 |
Enable Ed25519/Ed448 support (RFC 8032).
Certificate parsing is available; signature verification currently requires the PSA consumer. Native verification and TLS signature scheme integration are not implemented. Enable timing resistant ECC algorithms DISABLE AT YOUR OWN RISK!
| #define SHARKSSL_ECC_USE_BRAINPOOLP256R1 1 |
Enable/disable the brainpoolP256r1 curve (RFC 5639)
| #define SHARKSSL_ECC_USE_BRAINPOOLP384R1 1 |
Enable/disable the brainpoolP384r1 curve (RFC 5639)
| #define SHARKSSL_ECC_USE_BRAINPOOLP512R1 1 |
Enable/disable the brainpoolP512r1 curve (RFC 5639)
| #define SHARKSSL_ECC_USE_CURVE25519 1 |
Enable/disable the Curve25519 curve (RFC 7748)
| #define SHARKSSL_ECC_USE_CURVE448 0 |
Enable/disable the Curve448 curve (RFC 7748)
| #define SHARKSSL_ECC_USE_SECP256R1 1 |
Enable/disable the SECP256R1 curve.
| #define SHARKSSL_ECC_USE_SECP384R1 1 |
Enable/disable the SECP384R1 curve.
| #define SHARKSSL_ECC_USE_SECP521R1 1 |
Enable/disable the SECP521R1 curve.
| #define SHARKSSL_ECC_VERIFY_POINT 1 |
Select 1 to verify that a point lies on a curve; TLS 1.3 always enables this verification for peer key shares.
Verification requires more ROM for curve parameters and code, and slightly increases execution time.
| #define SHARKSSL_ECDSA_ONLY_VERIFY 0 |
Disable ECDSA sign API functions (sharkssl_ECDSA_sign, SharkSslECDSA_siglen) - effective only if ECDSA API is compiled (SHARKSSL_ENABLE_ECDSA_API must be enabled) and no SSL/TLS library used (only RayCrypto); used to achieve minimum code size.
| #define SHARKSSL_ENABLE_AES_CTR_MODE 1 |
Select 1 to include AES CTR mode (USE_AES_xxx must be enabled)
| #define SHARKSSL_ENABLE_AES_GCM 1 |
AES-GCM require AES: relevant ciphersuites are included.
| #define SHARKSSL_ENABLE_ALPN_EXTENSION 1 |
Enable/disable ALPN API (support for ALPN extension, RFC 7301)
| #define SHARKSSL_ENABLE_CA_EXTENSION 1 |
Select 1 to enable support for Certificate Authorities extension (RFC 8446 section 4.2.4) Note: SHARKSSL_TLS_1_3 must be enabled.
| #define SHARKSSL_ENABLE_CA_LIST 1 |
Select 1 to enable CA check (client or server with client auth)
| #define SHARKSSL_ENABLE_CERT_CHAIN 1 |
Select 1 to enable certificate chain support.
| #define SHARKSSL_ENABLE_CERT_KEYUSAGE 0 |
Select 1 to enable SharkSslCertInfo_parseCert for local DER certificates.
Requires RSA or ECDSA and certificate parsing for TLS, CSR signing, or tools. Automatic certificate cloning - always enabled Select 1 to expose parsed KeyUsage and ExtendedKeyUsage information; TLS 1.3 always parses KeyUsage to enforce certificate signing policy.
| #define SHARKSSL_ENABLE_CERTSTORE_API 1 |
Select 1 to enable certificate storage.
| #define SHARKSSL_ENABLE_CLIENT_AUTH 1 |
Select 1 to enable client authentication from server.
| #define SHARKSSL_ENABLE_DHE_RSA 0 |
Enable legacy TLS 1.2 DHE_RSA ciphersuites.
RFC 10015 requires clients not to offer and servers not to select these ciphersuites. Keep disabled for RFC 10015 compliance.
| #define SHARKSSL_ENABLE_ECDHE_ECDSA 1 |
Select 1 to enable ECDHE_ECDSA ciphersuites (RFC 4492) Elliptic Curve Cryptography (SHARKSSL_USE_ECC) must be enabled SHARKSSL_ENABLE_ECDSA must be set.
| #define SHARKSSL_ENABLE_ECDHE_RSA 1 |
Select 1 to enable ECDHE_RSA ciphersuites (RFC 4492) Elliptic Curve Cryptography (SHARKSSL_USE_ECC) must be enabled RSA (SHARKSSL_ENABLE_RSA) must be enabled.
| #define SHARKSSL_ENABLE_ECDSA 1 |
Select 1 to enable generation and verification of elliptic curve digital signatures.
| #define SHARKSSL_ENABLE_ECDSA_API 1 |
Enable/disable RSASSA-PSS padding in RSA API (RFC 8017) (SHARKSSL_ENABLE_RSA_API must be enabled to use RSASSA-PSS through the RSA API)
RSASSA-PSS is automatically enabled for RSA CertificateVerify signatures when TLS 1.3 and RSA are enabled Enable/disable OAEP padding in RSA API (SHARKSSL_ENABLE_RSA_API must be enabled) Enable/disable ECDSA API (sharkssl_ECDSA_sign, sharkssl_ECDSA_verify, SharkSslECDSA_siglen)
| #define SHARKSSL_ENABLE_HELLO_RETRY_REQUEST SHARKSSL_TLS_1_3 |
Compile TLS 1.3 HelloRetryRequest handling.
It is enabled by default when TLS 1.3 is enabled. Set this to 0 to omit the retry path on constrained targets; an unsupported HelloRetryRequest is rejected explicitly.
| #define SHARKSSL_ENABLE_INFO_API 1 |
Enable/disable support for encrypted PKCS#8 certificates in sharkssl_PEM function (requires SHARKSSL_ENABLE_AES_CBC)
Enable/disable SharkSslCon_getCiphersuite
| #define SHARKSSL_ENABLE_KEY_UPDATE SHARKSSL_TLS_1_3 |
Select 1 to enable TLS 1.3 KeyUpdate support (RFC 9846 section 4.7.3; RFC 8446 section 4.6.3).
Note: with the default define below, it is enabled whenever TLS 1.3 is. Disabling this option reduces the per-connection RAM and code footprint, but receiving a TLS 1.3 peer KeyUpdate then closes the connection with a fatal unexpected_message alert. The resulting constrained profile is not fully TLS 1.3 conformant.
| #define SHARKSSL_ENABLE_PEM_API 1 |
Select 1 to enable PEM certs/keys decoding If RSA_API is enabled, then also the functions sharkssl_PEM_to_RSAKey and SharkSslRSAKey_free are available If ECDSA_API is enabled, then also the functions sharkssl_PEM_to_ECCKey and SharkSslECCKey_free are available.
| #define SHARKSSL_ENABLE_RSA 1 |
Select 0 to disable RSA ciphersuites.
| #define SHARKSSL_ENABLE_RSA_API 1 |
Enable/disable RSA API (sharkssl_RSA_public_encrypt, sharkssl_RSA_private_decrypt, sharkssl_RSA_private_encrypt, sharkssl_RSA_public_decrypt, SharkSslRSAKey_size)
| #define SHARKSSL_ENABLE_RSA_PKCS1 1 |
Enable the native RSA key generator.
PSA library builds enable this option. Enable/disable PKCS1 padding in RSA API (SHARKSSL_ENABLE_RSA_API must be enabled) note: always enabled when SSL client or server enabled
| #define SHARKSSL_ENABLE_SECURE_RENEGOTIATION SHARKSSL_TLS_1_2 |
Select 1 to enable renegotiation Only secure renegotiation (RFC 5746) is supported Note: with the default define below, it is enabled whenever TLS 1.2 is NOTE: IMPLEMENTED ONLY ON THE SERVER SIDE.
| #define SHARKSSL_ENABLE_SELECT_CIPHERSUITE 1 |
Enable/disable the SharkSslCon_selectCiphersuite API.
| #define SHARKSSL_ENABLE_SESSION_CACHE 1 |
Select 1 to enable session caching.
| #define SHARKSSL_ENABLE_SNI 1 |
Select 1 to enable support for Server Name Indication.
| #define SHARKSSL_ENABLE_X25519_API 1 |
Enable/disable the X25519 public API (sharkssl_X25519_createKeyPair, sharkssl_X25519_sharedSecret)
| #define SHARKSSL_MAX_HANDSHAKE_LENGTH 0x00004000UL |
Select 1 to enable support for Post Handshake Authentication (RFC 8446 sections 4.2.6 and 4.6.2)
EXPERIMENTAL! Application encrypted data returned by SharkSslCon_encrypt() must be sent before calling SharkSslCon_decrypt() again. Maximum accepted body length of one incoming TLS handshake message. The 16-KiB default preserves the embedded memory profile. Host builds may select, for example, 0x00040000UL (256 KiB); 0x00FFFFFFUL enables the full uint24 range defined by RFC 9846 section 4. Values above the default widen three internal buffer counters from U16 to U32. Input-buffer expansion must also be enabled for those values.
| #define SHARKSSL_MD5_SMALL_FOOTPRINT 0 |
Select 1 (small ROM footprint, slow) or 0 (large, fast)
SHA 384 is only available in small footprint version, being the fast version only 20% faster at the expense of an 8x code size (benchmarked on ARM Cortex M3)
| #define SHARKSSL_NOPACK 0 |
Do not pack option.
| #define SHARKSSL_OPTIMIZED_BIGINT_ASM 0 |
Enabling big integer assembler library requires SharkSslBigInt_XX.s.
| #define SHARKSSL_OPTIMIZED_CHACHA_ASM 0 |
Enabling assembler optimized CHACHA requires SharkSslCrypto_XX.s.
| #define SHARKSSL_OPTIMIZED_GCM_ASM 0 |
Enabling the combined assembler AES-GCM block kernel requires SharkSslCrypto_XX.s.
GHASH may use either its C or assembler implementation.
| #define SHARKSSL_OPTIMIZED_GCM_VAES_ASM 0 |
Enabling the VAES/VPCLMULQDQ AES-GCM backend requires the VAES assembly file (SharkSslCrypto_X64_VAES.asm) and its CPUID probe to be linked in addition to the AES-NI kernel.
Microsoft x64 only.
| #define SHARKSSL_OPTIMIZED_GHASH_ASM 0 |
Enabling assembler optimized GHASH requires SharkSslCrypto_XX.s.
| #define SHARKSSL_OPTIMIZED_POLY1305_ASM 0 |
Enabling assembler optimized POLY requires SharkSslCrypto_XX.s.
| #define SHARKSSL_OPTIMIZED_SHA256_ASM 0 |
Enabling assembler optimized SHA-256 requires SharkSslCrypto_XX.s.
| #define SHARKSSL_OPTIMIZED_SHA384_ASM 0 |
Enabling assembler optimized SHA-384 and SHA-512 requires SharkSslCrypto_XX.s.
| #define SHARKSSL_PSA_DYNAMIC_KEY_SLOTS 0 |
Select 1 to allocate SharkSSL PSA provider key slots on demand.
The static mode remains the default for deterministic embedded memory use.
| #define SHARKSSL_PSA_KEY_SLOTS 12 |
Number of volatile key slots in the SharkSSL PSA provider.
In the default static mode, all slots reserve memory even when unused; in dynamic mode, this value limits the number of allocated slots. Twelve covers one TLS 1.3 RSA/X25519 handshake with session caching and PSA secret handles, including a subsequent KeyUpdate. Increase it for concurrent handshakes or other keys kept alive by the application. This does not configure an external PSA provider used by SHARKSSL_PSA_CONSUMER.
| #define SHARKSSL_RANDOMIZE_EXTENSIONS 1 |
Select 1 to randomize the order of extensions in ClientHello.
| #define SHARKSSL_RFC_9846_CONFORMANCE_PROFILE 0 |
Select 1 to enforce the compile-time feature set required by the general RFC 9846 profile.
This verifies configuration prerequisites only; it is not a certification statement and does not replace protocol conformance tests.
| #define SHARKSSL_RNG_MULTITHREADED 1 |
Setting this macro to 1 enables the usage of sharkssl_rng in a multithreaded environment.
Please remember to initialize the RNG by calling sharkssl_entropy at least once before calling sharkssl_rng
| #define SHARKSSL_SELECT_CIPHERSUITE_LIST_DEPTH 8 |
Determine the number of ciphersuites that can be selected, in decreasing order of preference; this value is only in effect if the SHARKSSL_ENABLE_SELECT_CIPHERSUITE is selected.
| #define SHARKSSL_SHA1_SMALL_FOOTPRINT 0 |
| #define SHARKSSL_SHA256_SMALL_FOOTPRINT 0 |
Select 1 for smaller, but slower SHA256.
| #define SHARKSSL_SSL_CLIENT_CODE 1 |
Select 1 to enable CLIENT side TLS.
| #define SHARKSSL_SSL_SERVER_CODE 1 |
Select 1 to enable SERVER side TLS.
| #define SHARKSSL_TLS_1_2 1 |
TLS 1.2 stack Disable by setting SHARKSSL_TLS_1_2=0.
| #define SHARKSSL_TLS_1_3 1 |
TLS 1.3 stack Disable by setting SHARKSSL_TLS_1_3=0.
| #define SHARKSSL_TLS_1_3_AES_GCM_KEY_UPDATE_THRESHOLD 0x00800000UL |
Number of TLS 1.3 records that may be encrypted with one AES-GCM key before SharkSSL proactively sends a KeyUpdate.
Every record is counted as a full-size record, which is conservative for smaller records. The value may be reduced, but must not exceed the default 2^23-record threshold; this leaves ample room below the RFC 9846 section 5.5 usage limit for a pending split write and the KeyUpdate record itself. This value is effective only when SHARKSSL_ENABLE_KEY_UPDATE is 1.
| #define SHARKSSL_TLS_1_3_INITIAL_BRAINPOOL_GROUP 0 |
Select one RFC 8734 Brainpool group as the initial TLS 1.3 key share Set to TLS_NAMEDGROUP_BRAINPOOLP256R1TLS13, P384R1TLS13, or P512R1TLS13 Zero retains the usual initial key shares.
| #define SHARKSSL_TLS_1_3_INITIAL_KEY_SHARE_X25519_ONLY 0 |
Select 1 to send only an X25519 key share in the initial TLS 1.3 ClientHello.
This setting is effective only when HelloRetryRequest and X25519 are enabled; otherwise the client sends every available TLS 1.3 key share as before. The PSA consumer sends one P-256 share when X25519 is disabled.
| #define SHARKSSL_UNALIGNED_ACCESS 0 |
Select 1 if your architecture supports unaligned memory access (x86, ARM-Cortex-M3, ColdFire)
| #define SHARKSSL_USE_AES_128 1 |
Enable/disable AES 128.
| #define SHARKSSL_USE_AES_192 0 |
AES-192 is not used in SSL/TLS enable only if needed in application using the crypto API.
| #define SHARKSSL_USE_AES_256 1 |
Enable/disable AES 256.
| #define SHARKSSL_USE_CHACHA20 1 |
AES-CCM require AES: only for crypto functions - CCM TLS ciphersuites removed.
AES-CBC require AES: CBC TLS ciphersuites removed for crypto functions and PEM certificate decryption Enable/disable CHACHA20 support and also include CHACHA20-POLY1305 ciphersuites when TLS1.2 and POLY1305 are enabled (SHARKSSL_USE_POLY1305)
| #define SHARKSSL_USE_ECC 1 |
Elliptic Curve Cryptography.
| #define SHARKSSL_USE_RNG_FORTUNA 0 |
Setting this macro to 1 enables the Fortuna RNG.
It is suitable for cryptographic applications. SHARKSSL_USE_RNG_TINYMT must be disabled. AES-256 and SHA-256 must be enabled. The SharkSSL implementation passes the bbattery_FIPS_140_2 test of TestU01 (http://simul.iro.umontreal.ca/testu01/tu01.html)
| #define SHARKSSL_USE_RNG_TINYMT 0 |
Setting this macro to 1 enables TinyMT32 and disables other RNGs.
TinyMT32 is not suitable for cryptographic applications. The SharkSSL implementation passes TestU01's bbattery_FIPS_140_2 statistical test, but that result does not make the generator cryptographically secure. A TLS 1.3 build using TinyMT32 is a reduced profile and is not generally conformant with the RFC 9846 CSPRNG requirement.
| #define SHARKSSL_USE_SHA_256 1 |
TLS 1.2/1.3 require SHA-256, do not modify the following settings DES and ClientHello v2.0 are deprecated in TLS 1.2 - RFC5246.
| #define SHARKSSL_X25519_DEDICATED 1 |
Select 1 to use dedicated Curve25519 field arithmetic (SharkSslBigInt.c) modulo p = 2^255 - 19, with a fixed inversion chain.
If SHARKSSL_X25519_ASM is also enabled, the dedicated whole-ASM backend is used instead. Select 0 for the generic BigInt ladder, which may use optional BigInt assembly kernels. This will reduce code size in flash at the cost of slower X25519 operations. This option has no effect unless Curve25519 (SHARKSSL_ECC_USE_CURVE25519) is enabled. The dedicated implementation requires 32-bit BigInt words. It is the default for 32-bit words; the generic ladder is the only supported implementation for 8- and 16-bit words.