Description
Adds optional Application-Layer Protocol Negotiation to the TLS SPI.
Providers and sessions opt into these interfaces independently of the core TLS interfaces, so an existing provider remains source-compatible. ALPN identifiers are opaque byte strings; protocol policy belongs to callers.
"&"
function "&" (Left : Protocol_List; Right : String) return Protocol_List
Return a copy of Left with Right appended.
Parameters
- Left
Existing ordered protocol list
- Right
Opaque nonempty protocol identifier
Return value
Extended ordered protocol list
Raised exceptions
- Constraint_Error
Right or total encoded length is invalid
Append
procedure Append (Item : in out Protocol_List; Identifier : String)
Append an identifier while preserving offer order.
Parameters
- Item
Protocol list to extend
- Identifier
Opaque nonempty protocol identifier
Raised exceptions
- Constraint_Error
Identifier or total encoded length is invalid
Count
function Count (Item : Protocol_List) return Natural
Return the number of offered identifiers.
Parameters
- Item
Protocol list to inspect
Return value
Identifier count
Create_Session
function Create_Session
(Item : in out Provider; FD : Descriptor; Side : Role; Server_Name : String; Protocols : Protocol_List)
return Session_Access
Create a nonblocking TLS session with an ordered ALPN offer. The core Create_Session contract also applies. A client sends Protocols in order; an empty list sends no ALPN extension. Server behavior is provider specific unless separately configured by that provider.
Parameters
- Item
Initialized ALPN-capable provider
- FD
Borrowed connected descriptor
- Side
Client or server role
- Server_Name
Verified DNS name for clients; empty for servers
- Protocols
Ordered client offer or an empty list
Return value
Newly allocated ALPN-capable provider session
Raised exceptions
- TLS_Error
Provider setup fails
Empty_Protocol_List
Empty_Protocol_List : constant Protocol_List;
An empty protocol list. Passing it creates an ALPN-capable session that sends no ALPN offer.
Identifier
function Identifier (Item : Protocol_List; Index : Positive) return String
Return one identifier by its one-based offer position.
Parameters
- Item
Protocol list to inspect
- Index
One-based offer position
Return value
Opaque protocol identifier
Raised exceptions
- Constraint_Error
Index is outside the list
Offer
function Offer (Identifier : String) return Protocol_List
Create a one-element ordered protocol list.
Parameters
- Identifier
Opaque nonempty protocol identifier
Return value
List containing Identifier
Raised exceptions
- Constraint_Error
Identifier is empty or longer than 255 bytes
Protocol_List
type Protocol_List is private;
Ordered protocol identifiers offered to a peer. Each identifier is one to 255 bytes and the complete encoded list is at most 65,535 bytes.
Provider
type Provider is limited interface and Flyology.IO.TLS.Provider;
Optional provider capability for per-session ALPN offers. Implementing this interface does not change the core provider primitives. Factories must preserve Protocols order when sending a client offer.
Selected_Protocol
function Selected_Protocol (Item : Session) return String
Copy the identifier selected by the peer after a successful handshake. An empty String means that the peer made no ALPN selection.
Parameters
- Item
Handshaken ALPN-capable session
Return value
Selected opaque identifier or an empty String
Selected_Protocol
function Selected_Protocol (Item : in out Connection) return String
Read the ALPN result under the connection's operation serialization. Call this after Handshake succeeds. It waits for an active operation to drain and is interrupted by concurrent Close.
Parameters
- Item
Open handshaken ALPN connection
Return value
Selected opaque identifier or an empty String
Raised exceptions
- Operation_Cancelled
Concurrent Close interrupts the query
- TLS_Error
The installed session lacks the ALPN capability
- Program_Error
Item is closed
Session
type Session is limited interface;
Optional session capability for reading the ALPN result.
Take
procedure Take
(Backend : in out Provider'Class;
Socket : in out Flyology.IO.Sockets.Socket_Type;
Side : Role;
Server_Name : String;
Protocols : Protocol_List;
Item : in out Connection)
Create an ALPN-capable session and transfer Socket ownership to Item. Core Take validation and ownership behavior apply. Protocols are used only during session creation and need not outlive this call.
Parameters
- Backend
Initialized ALPN-capable provider
- Socket
Connected socket transferred on success
- Side
Client or server handshake role
- Server_Name
DNS name verified by a client; empty for a server
- Protocols
Ordered client offer or an empty list
- Item
Closed connection that receives the socket and session
Raised exceptions
- TLS_Error
Provider setup fails or returns a non-ALPN session
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when preparing socket mode fails
- Program_Error
Core Take arguments are invalid