proposal(std.http): provide interface to plug in custom TLS implementation #18963
Labels
proposal
This issue suggests modifications. If it also has the "accepted" label then it is planned.
standard library
This issue involves writing Zig code for the standard library.
Milestone
The Background
The current implementation of
std.http
usesstd.crypto.tls
for its TLS implementation, and that's the only choice. This causes a few problems, mostly around the deficiencies ofstd.crypto.tls
:std.crypto.tls
only provides a Client at the moment.This implementation requires a user to duplicate
std.http
and replace thestd.crypto.tls
usage with their own TLS implementation, which is not ideal and leads to code duplication and maintenance burden. An example of this is zig-tls12.The Proposal
The proposal is to replace the direct
std.crypto.tls
usage instd.http
with aTlsProvider
interface, which will allow users to plug in their own TLS implementation that may provide the above features.A tentative example of what this interface could look like (the following is what
std.http
currently depends on):Such an interface would be duplicated for the server side, and would allow
std.http.Server
to be used with a TLS implementation as it is right now.Changes Introduced
The
Connection
struct will no longer store acrypto.tls.Client
directly. Instead it will use the client/server'sTls(Client/Server)Provider
interface, which will be used to create a TLS connection when needed.Following this change,
std.crypto.tls
will provide this interface and integrate intostd.http
as it does now. However, users will have to initialize and pass this interface intostd.http
if they want to use TLS. This will be a breaking change for existing code.Additionally, existing code will have at least one extra allocation (the context for a connection will have to be allocated, there is no place to store it) and all tls operations will be a virtual function call. This is a small performance hit, but it is necessary to allow for custom TLS implementations.
However, this change will allow users to provide their own TLS implementation as a library that other users can consume and plug into
std.http
.As a side-effect of this change, the
http_disable_tls
std option can be removed, and the special cases forhttp_disable_tls
instd.http
can be removed. As users can simply not pass in the an emptyTlsProvider
if they do not want to use TLS.Terminology Introduced
TLS Provider
A TLS Provider is an interface that provides the necessary persistent state and functions to create a TLS Connection.
An example TLS provider is
std.crypto.tls
. As of the current implementation:std.crypto.tls.Client.init
(asnew_client
) which initializes a local TLS state and performs a handshake along the connection.A TLS Provider is used to obtain a TLS Connection.
TLS Connection
A TLS Connection is an interface that provides the local state and functions to handle, read, write to and close a TLS connection. This local state often includes any session information, read and write buffers, and the underlying TLS state machine.
An example TLS Connection is
std.crypto.tls.Client
. As of the current implementation:*std.crypto.tls.Client
, it must be allocated because there is no place to store it in the TLS Provider.read
,write
, andwriteEnd
(asclose
).A TLS Connection is used to handle a the TLS state on top of a socket, therefore all reads and writes should be done through the TLS Connection.
The text was updated successfully, but these errors were encountered: