|
SharkSSL™ Embedded SSL/TLS Stack
|
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 | |
Macros | |
| #define | SHARKSSL_TLS_1_3 1 |
| TLS 1.3 stack Disable by setting SHARKSSL_TLS_1_3=0. | |
| #define | SHARKSSL_TLS_1_2 1 |
| TLS 1.2 stack Disable by setting SHARKSSL_TLS_1_2=0. | |
| #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. | |
| #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_ENABLE_AES_GCM 1 |
| AES-GCM require AES: relevant ciphersuites are included. | |
| #define | SHARKSSL_ENABLE_AES_CCM 0 |
| AES-CCM require AES: only for crypto functions - CCM TLS ciphersuites removed. | |
| #define | SHARKSSL_ENABLE_AES_CBC 0 |
| AES-CBC require AES: CBC TLS ciphersuites removed for crypto functions and PEM certificate decryption. | |
| #define | SHARKSSL_USE_CHACHA20 1 |
| Enable/disable CHACHA20 support and also include CHACHA20-POLY1305 ciphersuites when TLS1.2 and POLY1305 are enabled (SHARKSSL_USE_POLY1305) | |
| #define | SHARKSSL_SSL_SERVER_CODE 1 |
| Select 1 to enable SERVER side TLS. | |
| #define | SHARKSSL_ENABLE_CLIENT_AUTH 1 |
| Select 1 to enable client authentication from server. | |
| #define | SHARKSSL_ENABLE_POST_HANDSHAKE_AUTH 0 |
| Select 1 to enable support for Post Handshake Authentication (RFC 8446 sections 4.2.6 and 4.6.2) More... | |
| #define | SHARKSSL_MAX_HANDSHAKE_LENGTH 0x00004000UL |
| Maximum accepted body length of one incoming TLS handshake message. 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_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. | |
| #define | SHARKSSL_RANDOMIZE_EXTENSIONS 1 |
| Select 1 to randomize the order of extensions in ClientHello. | |
| #define | SHARKSSL_ENABLE_SNI 1 |
| Select 1 to enable support for Server Name Indication. | |
| #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_RSA 1 |
| Select 0 to disable RSA ciphersuites. | |
| #define | SHARKSSL_ENABLE_SESSION_CACHE 1 |
| Select 1 to enable session caching. | |
| #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_DHE_RSA 0 |
| Enable legacy TLS 1.2 DHE_RSA ciphersuites. More... | |
| #define | SHARKSSL_ENABLE_SELECT_CIPHERSUITE 1 |
| Enable/disable the SharkSslCon_selectCiphersuite API. | |
| #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_ENABLE_ALPN_EXTENSION 1 |
| Enable/disable ALPN API (support for ALPN extension, RFC 7301) | |
| #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. More... | |
| #define | SHARKSSL_ENABLE_RSASSA_PSS 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_ENABLE_RSASSA_PSS 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_ENABLE_RSA_OAEP 0 |
| Enable/disable OAEP padding in RSA API (SHARKSSL_ENABLE_RSA_API must be enabled) | |
| #define | SHARKSSL_ENABLE_ECDSA_API 1 |
| Enable/disable ECDSA API (sharkssl_ECDSA_sign, sharkssl_ECDSA_verify, SharkSslECDSA_siglen) | |
| #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_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_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. | |
| #define | SHARKSSL_ENABLE_CA_LIST 1 |
| Select 1 to enable CA check (client or server with client auth) | |
| #define | SHARKSSL_ENABLE_CERTSTORE_API 1 |
| Select 1 to enable certificate storage. | |
| #define | SHARKSSL_ENABLE_CERTINFO_PARSE_API 0 |
| Select 1 to enable #SharkSslCertInfo_parseCert for local DER certificates. More... | |
| #define | SHARKSSL_ENABLE_CERT_KEYUSAGE 0 |
| Automatic certificate cloning - always enabled. More... | |
| #define | SHARKSSL_MD5_SMALL_FOOTPRINT 0 |
| Select 1 (small ROM footprint, slow) or 0 (large, fast) More... | |
| #define | SHARKSSL_SHA256_SMALL_FOOTPRINT 0 |
| Select 1 for smaller, but slower SHA256. | |
| #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_ENABLE_AES_CTR_MODE 1 |
| Select 1 to include AES CTR mode (USE_AES_xxx must be enabled) | |
| #define | SHARKSSL_AES_CIPHER_LOOP_UNROLL 1 |
| Select 0 (35% less ROM) or 1 (10-15% faster) | |
| #define | SHARKSSL_UNALIGNED_ACCESS 0 |
| Select 1 if your architecture supports unaligned memory access (x86, ARM-Cortex-M3, ColdFire) | |
| #define | SHARKSSL_BIGINT_WORDSIZE 32 |
| Select 8, 16 or 32 according to your architecture. | |
| #define | SHARKSSL_USE_ECC 1 |
| Elliptic Curve Cryptography. | |
| #define | SHARKSSL_ENABLE_ECDSA 1 |
| Select 1 to enable generation and verification of elliptic curve digital signatures. | |
| #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_ENABLE_EDDSA 0 |
| Reserved for future Edwards-curve digital signature support (RFC 8032). More... | |
| #define | SHARKSSL_ECC_TIMING_RESISTANT 1 |
| Enable timing resistant ECC algorithms DISABLE AT YOUR OWN RISK! | |
| #define | SHARKSSL_BIGINT_TIMING_RESISTANT 1 |
| Enable timing resistant big integer functions Enabled by default when the above is enabled DISABLE AT YOUR OWN RISK! More... | |
| #define | SHARKSSL_BIGINT_TIMING_RESISTANT 1 |
| Enable timing resistant big integer functions Enabled by default when the above is enabled DISABLE AT YOUR OWN RISK! More... | |
| #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_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_ENABLE_X25519_API 1 |
| Enable/disable the X25519 public API (sharkssl_X25519_createKeyPair, sharkssl_X25519_sharedSecret) | |
| #define | SHARKSSL_X25519_DEDICATED 1 |
| Select 1 (the default) 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) | |
| #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_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_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_POLY1305_ASM 0 |
| Enabling assembler optimized POLY requires SharkSslCrypto_XX.s. | |
| #define | SHARKSSL_OPTIMIZED_GHASH_ASM 0 |
| Enabling assembler optimized GHASH requires SharkSslCrypto_XX.s. | |
| #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. | |
| #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_BIGINT_TIMING_RESISTANT 1 |
Enable timing resistant big integer functions Enabled by default when the above is enabled DISABLE AT YOUR OWN RISK!
sanity defines — do not edit below this line!
| #define SHARKSSL_BIGINT_TIMING_RESISTANT 1 |
Enable timing resistant big integer functions Enabled by default when the above is enabled DISABLE AT YOUR OWN RISK!
sanity defines — do not edit below this line!
| #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_ENABLE_CERT_KEYUSAGE 0 |
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_CERTINFO_PARSE_API 0 |
Select 1 to enable #SharkSslCertInfo_parseCert for local DER certificates.
Requires RSA or ECDSA and certificate parsing for TLS, CSR signing, or tools.
| #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_EDDSA 0 |
Reserved for future Edwards-curve digital signature support (RFC 8032).
EdDSA is not implemented.
| #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_POST_HANDSHAKE_AUTH 0 |
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.
| #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_RSASSA_PSS 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)
TLS 1.3 sanity #defines.
RSASSA-PSS is automatically enabled for RSA CertificateVerify signatures when TLS 1.3 and RSA are enabled
| #define SHARKSSL_ENABLE_RSASSA_PSS 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)
TLS 1.3 sanity #defines.
RSASSA-PSS is automatically enabled for RSA CertificateVerify signatures when TLS 1.3 and RSA are enabled
| #define SHARKSSL_MAX_HANDSHAKE_LENGTH 0x00004000UL |
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_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_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_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_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.
| #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_X25519_DEDICATED 1 |
Select 1 (the default) 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.