module TLS:Netsys_crypto_types.TLS_PROVIDER
GNUTLS
, but without the extra gnutls_*
functions
Users should not call functions of the provider directly, but use
Netsys_tls
, or another higher-level layer.
type
config
type
credentials
type
endpoint
module Exc:Netsys_crypto_types.TLS_EXCEPTIONS
val error_message : string -> string
typedh_params =
[ `Generate of int | `PKCS3_DER of string | `PKCS3_PEM_file of string ]
`PKCS3_PEM_file name
: points to a PEM-encoded PKCS3-file
("BEGIN DH PARAMETERS")`PKCS3_DER data
: the parameters are in a DER-encoded PKCS3
structure`Generate bits
: the parameters are generated with the
passed number of bitsval create_config : ?algorithms:string ->
?dh_params:dh_params ->
?verify:(endpoint -> bool -> bool -> bool) ->
peer_auth:[ `None | `Optional | `Required ] ->
credentials:credentials ->
unit -> config
algorithms
: a string specifying which cryptographic algorithms,
protocols and protocol options
are enabled, and in which priority they are used in the negotiation.
(GnuTLS calls this "priority string".) The syntax is
implementation-defined.dh_params
: parameters for Diffie-Hellman key exchange (used for
DH-based authentication, but only on the server side)peer_auth
: controls whether the peer is requested to authenticate.
This can be set to `None
meaning not to request authentication
and to ignore credentials, or to `Optional
meaning not to request
authentication but to check credentials if they are sent
nevertheless, or to `Required
meaning to request and check
credentials. For "standard clients" you should set this to
`Required
, and for "standard servers" to `None
or
`Required
.credentials
describes our own credentials, and the accepted
credentials of the peer.verify
is a function called to verify the peer certificate
in addition to the actions of peer_auth
. The function must
return true
in order to be successful. The arguments of the
function are the TLS endpoint, and two bools indicating the
success of previous checks. The first bool says whether the
certificate is trusted (based on peer_auth
, trust
and
system_trust
), and the second bool says whether the host name
of the peer matches the name in the certificate. If not
passed, verify
defaults to (fun _ cert_ok name_ok ->
cert_ok && name_ok)
, i.e. both bools must be true.typecrt_list =
[ `DER of string list | `PEM_file of string ]
`PEM_file name
: The certs are stored in this file, and are
PEM-encoded.`DER l
: The certs are given directly in their DER-encoded formtypecrl_list =
[ `DER of string list | `PEM_file of string ]
`PEM_file name
: The CRLs are stored in this file, and are
PEM-encoded.`DER l
: The CRLs are given directly in their DER-encoded formtypeprivate_key =
[ `DSA of string
| `EC of string
| `PEM_file of string
| `PKCS8 of string
| `PKCS8_encrypted of string
| `RSA of string ]
`PEM_file name
: The key is stored PEM-encoded in this file.
The PEM header indicates the format.`RSA data
: The key is a PKCS1 RSA key`DSA data
: The key is a DSA key`EC data
: The key is for an elliptic curve`PKCS8 data
: The key is in a PKCS8 data structure`PKCS8_encrypted data
: The key is in a PKCS8 data structure,
and is additionally encrypted.val create_x509_credentials : ?system_trust:bool ->
?trust:crt_list list ->
?revoke:crl_list list ->
?keys:(crt_list *
private_key * string option)
list ->
unit -> credentials
system_trust
: if set, the system certificates are trustedtrust
specifies the CAs of peers to trust (default: empty)revoke
specifies CRLs for revocation of peer certificates
(default: empty)keys
are our own certificates, as triples
(cert_path, private_key, password)
(default: empty)trust
to the list of CAs it can accept on
the server side. It is not required to specify a key.
A server must specify a key (but can also specify several keys).
If a server requests authentication from the client, it must also
set trust
.
The keys must include the certificate path cert_path
, starting
with the endpoint certificate, and followed by all middle
certificates, but omitting the certificate of the CA.
The private_key
is the key of the endpoint. If it is password-encrypted, the
password must be given.
val create_endpoint : role:[ `Client | `Server ] ->
recv:(Netsys_types.memory -> int) ->
send:(Netsys_types.memory -> int -> int) ->
peer_name:string option ->
config ->
endpoint
peer_name
is the expected common name or DNS name of the
peer. peer_name
has an option type as it is not always
required to pass it. However, keep in mind that clients
normally authenticate servers (peer_auth=`Required
). In
order to do so, they need to check whether the name in the
server certificate equals the DNS name of the service they
are connected to. This check is done by comparing peer_name
with the name in the certificate.
peer_name
is also used for the SNI extension.
Servers normally need not to set peer_name
. You can also omit it
when there is no name-driven authentication at all.
The endpoint will use the functions recv
and send
for I/O, which
must be user-supplied. recv buf
is expected to read data into the
buffer, and to return the number of bytes, or 0 for EOF.
send buf n
is expected to send the n
first bytes in buf
.
Both functions may raise Unix_error
. The codes Unix.EAGAIN
and
Unix.EINTR
are specially interpreted.
val stash_endpoint : endpoint -> exn
recv
and send
functions.
The endpoint passed in to stash_endpoint
must no longer be used!
val restore_endpoint : recv:(Netsys_types.memory -> int) ->
send:(Netsys_types.memory -> int -> int) ->
exn -> endpoint
recv
and send
functionsval resume_client : recv:(Netsys_types.memory -> int) ->
send:(Netsys_types.memory -> int -> int) ->
peer_name:string option ->
config ->
string -> endpoint
The session data is passed as string, which must have been retrieved
with get_session_data
.
typestate =
[ `Accepting
| `Data_r
| `Data_rs
| `Data_rw
| `Data_w
| `End
| `Handshake
| `Refusing
| `Start
| `Switching ]
`Start
: Before the session is started`Handshake
: The handshake is being done (and hello
needs to
be called again)`Data_rw
: The connection exists, and is read/write`Data_r
: The connection exists, and is read-only`Data_w
: The connection exists, and is write-only`Data_rs
: The connection exists, and data can be read.
There was a switch request (initiated by us), and a response
is awaited. No data can be sent in the moment.`Switching
: A rehandshake is being negotiated (and switch
needs to be called again)`Accepting
: A rehandshake is being accepted (and accept_switch
needs to be called again)`Refusing
: A rehandshake is being refused (and refuse_switch
needs to be called again)`End
: After finishing the sessionval get_state : endpoint ->
state
typeraw_credentials =
[ `Anonymous | `X509 of string ]
`X509 s
: The X509 certificate in DER encoding`Anonymous
: no certificate or other key is availableval at_transport_eof : endpoint -> bool
recv
or mem_recv
returned 0 to
check whether only the TLS enf-of-input message has been read,
or the underlying channel (usually the file descriptor) has
indicated EOF.val hello : endpoint -> unit
hello
doesn't verify the peer. Use verify
for that.
May raise EAGAIN_RD
, EAGAIN_WR
,
Unix_error(EINTR,_,_)
, Error
or Warning
.
val bye : endpoint -> Unix.shutdown_command -> unit
If SHUTDOWN_SEND
is set, the close request is sent to the peer, and
the TLS tunnel is considered as closed for writing. The application
can receive further data until recv
returns zero bytes meaning
that the peer responded with another close request.
If SHUTDOWN_ALL
is passed, it is additionally waited until the peer
responds with a close request.
A simple SHUTDOWN_RECEIVE
is unimplemented and ignored.
In no case the underlying transport is closed or shut down!
May raise EAGAIN_RD
, EAGAIN_WR
,
Unix_error(EINTR,_,_)
, Error
or Warning
.
val verify : endpoint -> unit
verify ep peer_name
: Checks that:peer_name
is the common name of the certificate subject,
or an alternate namepeer_auth=`None
is set in the
configuration!
Additionally, the verify
function in the endpoint configuration
is called back, and a failure is indicated if this function returns
false
. This callback is useful to get the certificate of the peer
and to perform further checks.
The verify
function will raise Failure
on failed checks
(and Error
for internal processing errors).
val get_config : endpoint ->
config
val get_endpoint_creds : endpoint ->
raw_credentials
val get_peer_creds : endpoint ->
raw_credentials
Not_found
if not applicable/no credentials present.val get_peer_creds_list : endpoint ->
raw_credentials list
val switch : endpoint ->
config -> unit
`Data_rs
meaning that we can still read data,
and at some point recv
will raise TLS_switch_response
.
On the client side, the request will by returned as exception
TLS_switch_request
by recv
. The client should respond with
accept_switch
if it accepts the handshake, or refuse_switch
if
not.
May raise EAGAIN_RD
, EAGAIN_WR
,
Unix_error(EINTR,_,_)
, Error
or Warning
.
val accept_switch : endpoint ->
config -> unit
May raise EAGAIN_RD
, EAGAIN_WR
,
Unix_error(EINTR,_,_)
, Error
or Warning
.
val refuse_switch : endpoint -> unit
May raise EAGAIN_RD
, EAGAIN_WR
,
Unix_error(EINTR,_,_)
, Error
or Warning
.
val send : endpoint ->
Netsys_types.memory -> int -> int
send ep buffer n
: Sends the first n
bytes in the buffer over
the endpoint, and returns the actual number of processed bytes.
May raise EAGAIN_RD
, EAGAIN_WR
,
Unix_error(EINTR,_,_)
, Error
or Warning
.
val recv : endpoint -> Netsys_types.memory -> int
recv ep buffer n
: Receives data, and puts them into the memory
buffer, and returns the actual number of received bytes. If 0
is returned, a close request was received by the peer. For closing
the tunnel properly this request should be responded by another
close request with bye
(unless this has already been done).
May raise EAGAIN_RD
, EAGAIN_WR
,
Unix_error(EINTR,_,_)
, Error
or Warning
.
The exception TLS_switch_request
can only occur on the client
side, and should be responded by accept_switch
or refuse_switch
.
The exception TLS_switch_response
can only occur on the server
side.
val recv_will_not_block : endpoint -> bool
recv
is guaranteed not to block or raise EAGAIN
.val get_session_id : endpoint -> string
val get_session_data : endpoint -> string
resume_client
val get_cipher_suite_type : endpoint -> string
val get_cipher_algo : endpoint -> string
val get_kx_algo : endpoint -> string
val get_mac_algo : endpoint -> string
val get_compression_algo : endpoint -> string
val get_cert_type : endpoint -> string
val get_protocol : endpoint -> string
typeserver_name =
[ `Domain of string ]
val get_addressed_servers : endpoint ->
server_name list
Not_found
if there is nothing appropriate. This information is
only available after a handshake, and if the client submitted it.val set_session_cache : store:(string -> string -> unit) ->
remove:(string -> unit) ->
retrieve:(string -> string) ->
endpoint -> unit
val implementation_name : string
val implementation : unit -> exn