Implementation notes:

The library is implemented different libraries per platform. Some platform may not support a particular TLS version(s).

On Windows

The library is implemented atop SChannel (SSP). The supporting TLS versions varies depending on the version of Windows. For the detailed information please refer Microsoft's support page. e.g. Protocols in TLS/SSL (Schannel SSP)

On POSIX / Linux

The library is implemented atop OpenSSL. This library doesn't specify the version of OpenSSL, it detects during the build process. The library specifies to use the latest TLS version, however, it doesn't guarantee using the latest due to the variety of reasons, e.g. older version of OpenSSL.

If you require to use a specific version of TLS, however this library only can do its best effort.

node and service must be string.

Creates a client TLS socket. node, service and opt will be passed to make-client-socket described in (sagittarius socket).

The keyword argument prng specifies which pseudo random algorithm will be used for generating security parameters.

If the keyword argument handshake #f then the procedure won't do TLS handshake after the socket creation so users must do it manually with tls-client-handshake procedure described below.

The keyword argument certificates is for certificate request message. The value must be a list of x509 certificates. If the certificates argument is null, then the procedures send empty certificate list to the server as a response of certificate request message.

The keyword argument private-key specifies which private key is used. The value must be private key object described in "(sagittarius crypto keys)". This is needed if the target server only supports RSA key exchange protocol.

The keyword argument certificate-verifier must be either boolean or a procedure which accepts 3 arguments, certificate depth, previous error and certificate as a bytevector. The procedure should check the passed certificate is valid or not.

Do client side handshake and return a TLS socket. The procedure must NOT be called if the socket is created with handshake keyword argument #t.

CAUTION: This procedure needs to be called only once and calling more than once might cause infinite loop or raise an error.

service must be string. certificates must be a list of x509 certificate.

Creates a server TLS socket. service and opt will be passed to make-server-socket described in (sagittarius socket).

The keyword arguments prng and version are the same meaning as make-client-tls-socket.

The keyword argument private-key is used the same as client socket. The difference is that it is used also for Deffie-Hellman key exchange. If this is not specified, then key exhange is done anonymously.
The private-key should be specified. This is optional due to the backward compatibility.

The keyword argument authorities must be a list of x509 certificate and if this is not empty list then the server socket will send certificate request message to the client.

CAUTION: the authorities keyword argument currently doesn't check the certificate signature but only issuer DN.

tls-socket must be the socket created by the procedure make-client-tls-socket.

flags must be non negative exact integer.

Sends given bytevector to tls-socket. flags are described in the section (sagittarius socket). The packet will be encrypted by tls-socket.

tls-socket must be the socket created by the procedure make-client-tls-socket.

size and flags must be non negative exact integer.

Receives decrypted packet from tls-socket. size indicates how many octets the procedure should receive, however it might return less octet. flags will be passed to socket-recv.

NOTE: tls-socket have its own buffer to return the value, so that the procedure can take size argument.

tls-socket must be the socket created by the procedure make-client-tls-socket.

Sends close notify alert to the socket and close it.

tls-socket must be the socket created by the procedure make-client-tls-socket.

Returns #t if the given socket is closed, otherwise #f.

NOTE: this procedure checks if session is closed. So the real socket might not be closed yet.

tls-socket must be a server TLS socket created by make-server-tls-socket.

Wait for an incoming connection request and returns a fresh connected client socket.

If the keyword argument handshake is #f then the handshake must be done by manually with tls-server-handshake described blow.

The keyword argument raise-error will be passed to tls-server-handshake.

Do server side TLS handshake and returns a TLS socket. The procedure must NOT be called if the socket is created with handshake keyword argument #t.

If the keyword argument raise-error is #f then it won't raise an error when something happens.

Return peer of given tls-socket or #f.

For more details, see (sagittarius socket).

Return peer of given tls-socket or #f. This procedure is TLS version of socket-peer.

For more details, see (sagittarius socket).

Return peer of given tls-socket or #f. This procedure is TLS version of socket-name.

For more details, see (sagittarius socket).

Return peer of given tls-socket or #f. This procedure is TLS version of socket-info-values.

For more details, see (sagittarius socket).

Constant value of #x0303 for TLS 1.2

Constant value of #x0302 for TLS 1.1

Constant value of #x0301 for TLS 1.0

tls-socket must be the socket created by the procedure make-client-tls-socket.

Returns input/output-port of given tls-socket.

If optional argument close? is #f then it won't close the socket when the port is closed or GCed.

Convert the given TLS socket to input and output port, respectively.

The given socket won't be closed when the port is closed or GCed. So it is the users responsibility to close.

Integration methods

The methods listed below are convenience methods to use TLS socket and usual socket without changing code.