Manage a TLS Connection

Use one SharkSsl configuration object for connections sharing its role, identity, and trust settings. Create one SharkSslCon for each transport connection. The application owns the transport and schedules TLS processing.

Create, use, and release

1. Initialize the selected platform and crypto backend, including its random source. A PSA consumer needs its provider ready before cryptography begins.
2. Construct SharkSsl with the role, session capacity, and buffer sizes. Install the local identity and trusted CA list before creating connections.
3. Open or accept a transport connection, then call SharkSsl_createCon and check for a null result. Configure SNI and other per-connection settings before handshake processing where the relevant API requires it.
4. Drive SharkSslCon_decrypt according to its returned state, or use selib's seSec_handshake, seSec_read, and seSec_write integration.
5. For a client, apply the trust result and expected server name before sending application secrets. Receiving decrypted data alone does not express your application's authorization decision.
6. Release each TLS connection with SharkSsl_terminateCon and close its transport. Release acquired sessions as documented. Destroy the SharkSsl object when its connections and application-held resources are no longer used.

Use Transport Agnostic API for the state flow and ExampleIntro for complete programs. This sequence describes lifecycle; it is not a replacement for the partial-I/O and error handling in selib.c.

Ownership and error conventions

Resource or API	Contract to preserve
TLS input/output pointers	Borrowed from the connection. Use the documented capacities and consume/send data before subsequent operations invalidate it. Never free these buffers yourself.
Identity certificate and CA list	Keep the installed data alive and unchanged for its documented SharkSSL lifetime. A certificate containing a private key must be handled as secret material.
PSA TLS signing key	SharkSsl_addCertificatePSA borrows the caller's key handle. Keep it valid until the SharkSSL object and its connections are destroyed.
Certificate/CSR creation	Follow the individual return and allocation contract. For example, SharkSslCert_signCSR returns an allocated certificate through its output pointer; release it with baFree.
SharkSslCon_RetVal	A state enumeration, not a generic zero/nonzero success code. Dispatch every relevant state, including alerts and allocation failures.
Boolean-style SharkSSL calls	Check the documented TRUE/FALSE result; do not apply PSA's status convention to them.
PSA psa_* calls	Return psa_status_t; success is PSA_SUCCESS. Consumer convenience APIs can instead use 0/-1 or length results. Read their declaration and guide.

Scheduling and synchronization

Serialize operations on a connection and protect shared configuration and resource lifetime. In particular, replacing a CA list requires no active connections and serialization with connection/session use; follow SharkSsl_setCAList. A port mutex does not make arbitrary concurrent calls on the same connection safe.

PSA provider storage and driver callbacks have separate lock/re-entry restrictions documented in SharkSslPSAStorage.h and SharkSslPSADriver.h.