|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
#include "SharkSslConfigEndian.h"Go to the source code of this file.
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_PSA_CONSUMER_SECRET_HANDLES 0 |
| Select 1 to use an external PSA Crypto provider for TLS operations. More... | |
| #define | SHARKSSL_PSA_CONSUMER_STRICT_IDENTITY 0 |
| Select 1 to require a PSA signing key for every local TLS identity. 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_USE_SHA_384 1 |
| Enable/disable SHA256 support for certificate signatures (SHA256 ciphersuites are not included). More... | |
| #define | SHARKSSL_USE_POLY1305 1 |
| Enable/disable SHA512 support; Note SHA512 is not required by SSL/TLS. 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_ENABLE_RSASSA_PSS 1 |
| sanity defines — do not edit below this line! More... | |
SharkSSL feature defaults and dependency checks.
Start with a working project for your platform. Keep the TLS library, crypto implementation, application, and any assembly sources on the same configuration. Rebuild them together after changing options that affect interfaces or context layouts.
| Build | Where settings come from |
|---|---|
| Standalone SharkSSL | The selected TargConfig.h supplies platform adaptation. SharkSSL_cfg.h includes SharkSSL_opts.h, then supplies missing defaults. Use project compiler definitions or the selected options file. |
| PSA consumer | Set SHARKSSL_PSA_CONSUMER=1, select the provider headers, and compile the consumer adapters. Link one provider; the flag alone does not supply it. |
| SharkSSL PSA provider | Build src/psa separately. Its storage, driver, slot, and algorithm settings belong to the provider, not an arbitrary external provider used by a consumer. |
Most feature switches are integer booleans, 0 or 1. Size/count/selector macros have their own ranges and units in SharkSSL_cfg.h. Use numeric #if tests for numeric switches. The SHARKSSL_TINY block in SharkSSL_opts.h uses a presence test and includes unsafe security/algorithm choices; follow Build for a Constrained Device instead of enabling that recipe.
Normal applications include SharkSSL.h. It loads the selected platform's TargConfig.h, then configuration options and byte-order validation before any crypto implementation uses them. Direct configuration consumers, including preprocessed assembly, must receive the same settings as the C sources.
| Macro | Type, values, and default |
|---|---|
BA_BYTE_ORDER | Integer selector describing the actual target representation. Normally derived from a recognized compiler or platform fact. If neither is available, the application must select one of the two named constants below before configuration validation. |
BA_BYTE_ORDER_LITTLE_ENDIAN | Fixed integer constant 1234; applications must not redefine it. |
BA_BYTE_ORDER_BIG_ENDIAN | Fixed integer constant 4321; applications must not redefine it. |
For a port whose compiler cannot report byte order, put the following in SharkSSL_opts.h or an equivalent shared compiler definition, after confirming the target representation:
BA_BYTE_ORDER is the single byte-order selector. Ports with a known platform byte order set it when absent or reject a conflicting value directly. SharkSslConfigEndian.h supplies the two fixed constants, loads SharkSSL_opts.h once, resolves any remaining compiler-derived default and validates the selected value. The supplied BareMetal, INTEGRITY, MDK, MQX, Windows and embOS ports supply their default before including this header, then check the final selection against their platform facts.
An options-file override uses #undef BA_BYTE_ORDER before its #define, as shown above, because the port may already have supplied a default. Both options-file and command-line selections must agree with the port and recognized compiler facts. Unknown or unsupported values, altered constants, and conflicting selections cause compilation errors. Vendor CPU/RTOS constants keep their names.
Remove legacy B_LITTLE_ENDIAN and B_BIG_ENDIAN compiler definitions; they are rejected. Use numeric comparisons such as #if BA_BYTE_ORDER == BA_BYTE_ORDER_LITTLE_ENDIAN in application adaptations. Rebuild C and assembly sources together after changing target settings.
| Option family | What it selects |
|---|---|
SHARKSSL_SSL_CLIENT_CODE, SHARKSSL_SSL_SERVER_CODE | Compiled TLS roles. The SharkSsl constructor then chooses a role present in that build. These do not create sockets or start an application server. |
SHARKSSL_TLS_1_2, SHARKSSL_TLS_1_3 | Protocol implementations. Negotiation still depends on the peer and enabled algorithms. |
SHARKSSL_ENABLE_CLIENT_AUTH, SHARKSSL_ENABLE_POST_HANDSHAKE_AUTH | TLS certificate-authentication capabilities. Applications still install identities and apply peer authorization. |
SHARKSSL_ENABLE_CA_LIST, SHARKSSL_CHECK_DATE | CA-validation support and certificate-date checking. Expected-name checks and application trust decisions remain required. |
SHARKSSL_ENABLE_PEM_API, SHARKSSL_ENABLE_CERTSTORE_API | Runtime key/certificate conversion and CA-list assembly. These are separate from generating a CSR or issuing a certificate. |
SHARKSSL_ENABLE_CSR_CREATION, SHARKSSL_ENABLE_CSR_SIGNING, SHARKSSL_ENABLE_ASN1_KEY_CREATION | Optional ASN.1/CSR utilities declared in SharkSslASN1.h and SharkSslCSR.h. These selectors are not defined by SharkSSL_cfg.h; undefined selectors behave as 0. A project can supply earlier definitions. Link the corresponding src/util/SharkSslCSR.c implementation. |
SHARKSSL_ENABLE_RSAKEY_CREATE, SHARKSSL_ENABLE_ECCKEY_CREATE | Native key generation. A PSA consumer uses provider key generation and key-handle APIs instead. |
SHARKSSL_ENABLE_RSA_API, SHARKSSL_ENABLE_ECDSA_API, SHARKSSL_ENABLE_X25519_API | Standalone public-key interfaces. Availability of an algorithm inside TLS does not automatically select every standalone API. |
| AES/GCM, ChaCha20/Poly1305, hashes, curves, and TLS signature flags | Native algorithm and TLS capabilities, subject to their dependencies. A PSA build additionally needs provider support. |
SHARKSSL_ENABLE_AES_CBC, SHARKSSL_ENABLE_AES_CCM, SHARKSSL_ENABLE_AES_CTR_MODE, SHARKSSL_USE_AES_192 | Application crypto and applicable key-conversion support. Current TLS does not offer CBC/CCM suites or AES-192 suites. |
SHARKSSL_ENABLE_SESSION_CACHE | TLS session-resumption support. The separate client cache manager needs its implementation and application integration. |
SHARKSSL_PSA_KEY_SLOTS, SHARKSSL_PSA_DYNAMIC_KEY_SLOTS | Capacity/allocation policy of the SharkSSL PSA provider. They do not configure another vendor's PSA provider. |
SHARKSSL_PSA_CONSUMER_* | TLS consumer policy and optional application crypto adapters. See SharkSSL PSA consumer. |
Dependencies are checked by the selected headers. Passing those checks establishes only the encoded compile-time prerequisites; it does not prove that all source files, provider algorithms, or target services are present. For macro defaults use the header reference, then check earlier overrides. The documentation build exposes optional APIs for discovery and is not a compiler-settings recipe for a product.
SHARKSSL_DISABLE_INBUF_EXPANSION is an optional integer boolean. When undefined it behaves as 0: the TLS input buffer can grow. Value 1 prevents that expansion; incoming records/handshakes must fit the supplied capacity. It is used by SharkSslCon.c and SharkSslCon.h, rather than defined among the public configuration defaults. Follow the SharkSslCon_getBuf and SharkSslCon_getBufLen contracts for every receive.
SHARKSSL_X25519_ASM is a port-specific integer boolean, normally left undefined (0). The dedicated X25519 code in SharkSslBigInt.c checks that it is used with SHARKSSL_X25519_DEDICATED=1 and a supported Cortex-M DSP or little-endian RX target. Other assembly adapters use SHARKSSL_X25519_ASM_HOOK; these switches are not interchangeable. Follow the matching Ports guide for source files and compiler options.
Selecting a macro does not add assembly files, an entropy source, a socket adapter, or persistent storage to the build.
| #define SHARKSSL_ENABLE_RSASSA_PSS 1 |
sanity defines — do not edit below this line!
The SHARKSSL_BIGINT_TIMING_RESISTANT option has been removed. Reject configurations that still select its former variable-time mode. TLS 1.3 sanity #defines