|
SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
|
Start with the layer that owns your task. The TLS core processes records; it does not open sockets. The native crypto API performs individual cryptographic operations. The example libraries add socket and application protocols around those facilities.
This reference covers the TLS core, native cryptography, certificate utilities, PSA interfaces, platform ports, and example libraries in the SharkSSL package. Select the matching headers and sources for your application; a feature macro cannot add an omitted source file.
| Public header | Responsibility and starting points |
|---|---|
| SharkSSL.h | SharkSsl configuration and lifetime, SharkSslCon record processing, certificate installation, sessions, status codes, and public-key helpers. Start with Core API and Manage a TLS Connection. |
| SharkSslEx.h | Certificate-name and date helpers, including SharkSslCon_trusted. A client must apply its trust policy and expected server name after the handshake. |
| SharkSslSCMgr.h | Optional client session-cache manager. See SSL Session Management and Client Session Cache Manager; it is not the TLS server's automatic cache. |
| SharkSslASN1.h | Bounded ASN.1 parsing/creation and CSR construction. Parsing a structure does not establish its trust or authorize its contents. |
| SharkSslCSR.h | Issuer-selected certificate profiles, CSR signing, CA-chain validation, and issued-identity validation. See Create and Validate Certificates. |
| SharkSSL_cfg.h | TLS, algorithm, optional API, and implementation configuration. Defaults can be overridden before this header is processed. |
| SharkSSL_opts.h | Application overrides for standalone SharkSSL. The SHARKSSL_TINY preset disables security protections and is not recommended for TLS; use Build for a Constrained Device. |
SharkSslCrypto.h supplies hash, HMAC, AES, ChaCha20, and Poly1305 interfaces. SharkSSL.h also supplies RSA, ECDSA, X25519, key conversion, random-number, and certificate helpers. Start with RayCrypto API.
| Family | Reference and boundary |
|---|---|
| Hashes and HMAC | SHA256, SHA384, SHA512, and HMAC. SHA-224 context operations require the PSA consumer. MD5 and SHA-1 are optional legacy interfaces. |
| Symmetric encryption and authentication | AES, AES-GCM, AES-CCM, CHACHA20, and POLY1305. CBC, CTR, and CCM application APIs do not imply corresponding TLS cipher suites. |
| Public-key operations | RSA encrypt/decrypt functions and ECDSA sign/verify functions; X25519 is documented in SharkSSL.h. Keep raw signature/key formats distinct from DER conversions. |
| Entropy and random output | sharkssl_entropy and sharkssl_rng. Follow the selected native port or PSA provider's initialization contract. |
Native RSA/ECDSA interfaces and the PSA consumer's key-handle APIs have different ownership and build requirements. Do not substitute one based only on a similar function name. See Choose a PSA Integration.
The PSA consumer application APIs calls a selected external provider. The SharkSSL PSA provider APIs implements a subset of PSA Crypto using SharkSSL. They can be linked together as separately built components, or the consumer can use another provider. A provider's API version is not a certification or hardware-isolation claim.
| Header family | Purpose |
|---|---|
inc/psa-consumer/SharkSslPSAConsumer*.h | Application helpers for CMAC, ECDH, ECDSA, EdDSA, hash, key wrapping, PBKDF2, RSA, and SP 800-108. Curves.h supplies identifiers. See SharkSSL PSA consumer for the complete header/source table. |
| crypto.h | The SharkSSL provider's PSA API and supported types. Use the selected provider's own <psa/crypto.h> when building a consumer. |
| SharkSslPSADriver.h | Optional opaque-key driver callbacks for the SharkSSL provider, with their own supported key types and lifecycle. |
| SharkSslPSAStorage.h | Persistent-key storage callbacks for the SharkSSL provider. Storage durability and protection remain backend responsibilities. |
| SharkSslPSAFileStorage.h | Optional encrypted filesystem storage adapter for Windows/Linux; it is not a generic RTOS flash driver. |
These APIs are distributed with the examples and must be built into the application that uses them. Compile the selected example library alongside its socket port and the SharkSSL library.
| Header | Layer |
|---|---|
| selib.h | Socket abstraction and TLS I/O helpers: SharkSSL Socket Example Lib. |
| SeCtx.h | Context manager used by supported bare-metal selib ports: Bare Metal Systems. |
| SMQ.h | SharkMQ publish/subscribe client: SharkMQ. |
| SharkMQTT.h | MQTT client: SharkMQTT. |
| WsClientLib.h | WebSocket client: WebSocket Client Lib. |
| SMTP.h | SMTP client: Simple Mail Transfer Protocol. |
| MSLib.h | Minnow HTTP/WebSocket server: Minnow Server. |
| ZipFileSystem.h | Local Minnow ZIP adapter. Requires the separately supplied ZipFileIterator.h and its implementation; those external APIs are documented with that package. |
Platform TargConfig.h files adapt target types, memory, time, and mutexes. Choose one matching port; do not combine several ports' headers. The list and tree headers are support containers used by the implementation, rather than another TLS integration layer.