|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
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.