Description
Adapts OpenSSL 3.x to Flyology's provider-neutral nonblocking TLS engine.
The adapter loads OpenSSL at run time; Flyology has no link-time crypto dependency. Initialize_Client uses system trust by default and requires hostname verification for every session. Initialize_Server requires a certificate chain and private key. Code modules and contexts are retained while a provider or one of its sessions still refers to them.
Example:
Initialize_Client (Backend);
Take (Backend, Socket, Client, "example.com", Secure);
Create_Session
function Create_Session
(Item : in out OpenSSL_Provider; FD : Descriptor; Side : Role; Server_Name : String)
return Session_Access
Allocate a nonblocking OpenSSL session borrowing FD. Side must match the provider configuration; clients apply Server_Name to SNI and hostname verification.
Parameters
- Item
Initialized provider
- FD
Borrowed connected descriptor
- Side
Role matching the provider configuration
- Server_Name
Verified client DNS name, or empty for a server
Return value
Provider session retained across readiness retries
Raised exceptions
- TLS_Error
OpenSSL session setup fails
- Program_Error
Server_Name contains an embedded NUL
Create_Session
function Create_Session
(Item : in out OpenSSL_Provider;
FD : Descriptor;
Side : Role;
Server_Name : String;
Protocols : ALPN.Protocol_List) return Session_Access
Allocate a nonblocking OpenSSL session and preserve the ordered client ALPN offer. Empty Protocols sends no ALPN extension. A server provider obtains its selection list from the ALPN Initialize_Server overload and therefore accepts only an empty per-session Protocols list.
Parameters
- Item
Initialized provider
- FD
Borrowed connected descriptor
- Side
Role matching the provider configuration
- Server_Name
Verified client DNS name, or empty for a server
- Protocols
Ordered client offer or empty server list
Return value
ALPN-capable provider session retained across readiness retries
Raised exceptions
- TLS_Error
OpenSSL session setup fails
- Program_Error
Server_Name contains an embedded NUL or a server session receives a nonempty Protocols list
Initialize_Client
procedure Initialize_Client
(Item : in out OpenSSL_Provider; CA_File : String := ""; Library_Directory : String := "")
Configure a client provider. An empty CA_File selects OpenSSL's default trust paths. Peer-chain and DNS hostname verification are always on; this API intentionally has no insecure mode. Library_Directory may name one OpenSSL 3 installation containing both libssl and libcrypto; empty selects supported platform locations. OpenSSL 1.x and 4.x are rejected.
Parameters
- Item
Provider to initialize
- CA_File
Optional PEM trust bundle or CA certificate
- Library_Directory
Optional directory containing a matched pair
Raised exceptions
- TLS_Error
Loading or secure configuration fails
- Program_Error
Item is already initialized or a path contains an embedded NUL
Initialize_Server
procedure Initialize_Server
(Item : in out OpenSSL_Provider;
Certificate_File : String;
Private_Key_File : String;
Protocols : ALPN.Protocol_List;
Library_Directory : String := "")
Configure a server provider and its ordered ALPN preference list. During each handshake OpenSSL selects the first configured identifier also offered by the client. No overlap or an empty list yields no selection. Credential, loading, and task-safety behavior match Initialize_Server.
Parameters
- Item
Provider to initialize
- Certificate_File
PEM leaf certificate and optional chain
- Private_Key_File
PEM private key matching Certificate_File
- Protocols
Ordered server protocol preference list
- Library_Directory
Optional directory containing a matched pair
Raised exceptions
- TLS_Error
Loading or credential validation fails
- Program_Error
Item is initialized, a required path is empty, or a path contains an embedded NUL
Initialize_Server
procedure Initialize_Server
(Item : in out OpenSSL_Provider;
Certificate_File : String;
Private_Key_File : String;
Library_Directory : String := "")
Configure a server provider using PEM files. Library selection matches Initialize_Client. The key is read by OpenSSL and is never copied into Flyology-managed storage. The server requests no client certificate; applications needing mutual TLS require another provider or extension.
Parameters
- Item
Provider to initialize
- Certificate_File
PEM leaf certificate and optional chain
- Private_Key_File
PEM private key matching Certificate_File
- Library_Directory
Optional directory containing a matched pair
Raised exceptions
- TLS_Error
Loading or credential validation fails
- Program_Error
Item is initialized, a required path is empty, or a path contains an embedded NUL
Is_Available
function Is_Available (Item : OpenSSL_Provider) return Boolean
Report whether Item has an initialized OpenSSL context.
Parameters
- Item
Provider to inspect
Return value
True after successful initialization and before finalization
Name
function Name (Item : OpenSSL_Provider) return String
Return the stable adapter name used in diagnostics.
Parameters
- Item
Provider to identify
Return value
OpenSSL 3
OpenSSL_Provider
type OpenSSL_Provider is new Ada.Finalization.Limited_Controlled and ALPN.Provider with private;
OpenSSL configuration and session factory. Initialize once before use. Session creation and read-only queries are task-safe. Initialization can load code, trust stores, certificates, and keys synchronously; run it before starting event loops or from a native task. Do not start a new call on a provider after its finalization begins. Sessions already created remain usable after provider finalization.
Retain
function Retain (Item : in out OpenSSL_Provider) return Provider_Access
Retain the refcounted OpenSSL module and configured context.
Parameters
- Item
Initialized provider to retain
Return value
Independently owned provider reference
Raised exceptions
- TLS_Error
Item is unavailable
Version
function Version (Item : OpenSSL_Provider) return String
Return the loaded OpenSSL version text, or an empty String before initialization.
Parameters
- Item
Provider to inspect
Return value
Provider-reported version