12.50 rfc.tls - Transport layer security

Module: rfc.tls

This module handles secure connection over TCP socket. This module is used by rfc.http to realize https connection (see HTTP).

CA certificates

You need CA certificates to verify server certificates properly. Gauche doesn’t have its own CA certificates, and relies on the system’s certificate store by default. On Unix-based systems, we search several known locations: On popular Linux distributions we recommend you to install ca-certificates package (or similar one). On OSX, we recommend to install openssl via Homebrew. On Windows, we use system’s certificate store via Wincrypt API.

With the default configuration, Gauche checks the availability of the system’s certificate store at initilization and use one if available. You can explicitly give the path of CA certificate bundle, or disable it and provide individual certificate per connection.

If, for some reasons, you cannot install system-wide CA certificate bundle, you can also download Curl’s CA certificate bundle https://curl.haxx.se/ca/cacert.pem, and install it in Gauche installation directory. We have a convenience script. After installing Gauche, run the following command:

gosh rfc/tls/get-cacert.scm

You need curl installed on your system. If you’ve installed Gauche with root priviledge, you’ll be asked sudo password to install the CA bundle file.

If you decided to do this, make sure you run the above command occasionally to get updated CA certificate bundles, for certificates may expire or be revoked.

Parameter: tls-ca-bundle-path :optional path

{rfc.tls} Holds CA certificate bundle to be used. The value can be either a string path to a CA bundle file, a symbol system, or #f.

If it is system, Gauche uses system’s default bundle. An error is signaled on connection if Gauche can’t find one.

If it is #f, CA certificate won’t be loaded automatically, and you have to manually load one using tls-load-object. (Note: This option is only valid with <ax-tls>. If you’re using <mbed-tls>, you need valid CA certificate bundle.)

With the default configuration, Gauche scans the system CA bundle when rfc.tls module is initialized, and if it finds one, tls-ca-bundle-path is set to system; otherwise, tls-ca-bundle-path is set to #f. So if you’re using with default configuration and you see its value is system, you can count on the system CA certificate bundle.

This default behavior may be altered if Gauche is configured with --with-ca-bundle option. You can execute gauche-config --reconfigure command to see if special --with-ca-bundle option is given.

Supported TLS subsystems

Gauche supports two TLS subsystems - one based on AxTLS (http://axtls.sourceforge.net/), and the other based on MbedTLS (https://tls.mbed.org/). Whether they’re included depends on the configuration options. By default, AxTLS support is compiled in, and MbedTLS support is included if the build platform has MbedTLS library installed.

AxTLS library has advanage of being included in Gauche, so that it won’t depend on external library, however, its supported ciphers are limited, and it can’t connect to some https sites. MbedTLS has wider cipher support, but it requires MbedTLS dynamic libraries (e.g. libmbedtls.so) at runtime.

Gauche chooses available TLS subsystem at runtime, so the user usually does not need to worry about the difference. If you’re building Gauche by yourself, we recommend to use the default configuration, on a system that has MbedTLS installed. That will give you the most flexible choice.

Whether the running Gauche has any of TLS support can be checked with a feature identifier gauche.net.tls. Availability of each individual subsystems can be checked with feature identifiers gauche.net.tls.axtls and gauche.net.tls.mbedtls, respectively. See Feature conditional, for more about feature identifiers.

Class: <tls>

{rfc.tls} An abstract base class of TLS implementations.

Class: <ax-tls>

{rfc.tls} A class that implements axTLS subsystem interface.

Class: <mbed-tls>

{rfc.tls} A class that implements mbedTLS subsystem interface.

Parameter: default-tls-class :optional class

{rfc.tls} Set/get the default TLS subsystem to be used. Without arguments, it return a class (either <ax-tls> or <mbed-tls> to be used. With one argument, which must be either <ax-tls> or <mbed-tls>, changes the default and returns the previous value.

TLS interface

Function: make-tls initargs …

{rfc.tls} Creates and returns a new TLS instance of the class default-tls-class. The returned TLS instance can be used for the tls procedures below.

The arguments must be a keyword-value list, and passed to the constructor of the TLS class.

:server-name

Server name to be used for TLS Server Name Indication extension.

:num-sessions

[AxTLS only] The number of sessions ot be used for session caching. 0 indicates no sessino caching.

:options

[AxTLS only] Bitflags of options. Logical OR of the following numeric constants.

SSL_SERVER_VERIFY_LATER

(client only) Let handshake success even the server authentication fails.

SSL_CLIENT_AUTHENTICATION

(server only) Request client sertificate to be authenticated.

Function: tls-connect tls host port proto

Function: tls-connect tls socket

{rfc.tls} Establishes TLS connection as a client. The first form is the recommended API. The second form is only kept for the backward compatibility, may not work on the newer MbedTLS, and will be removed in future.

The tls argument must be an unconnected TLS object. The host and port arguments are strings to specify server’s hostname and port. Besides the common hostname, IP notation (e.g. "127.0.0.1" or "[::1]") are allowed in host. Numeric notation (e.g. "443") or service name (e.g. "https") are allowed in port. The proto argument must be either one of the symbols tcp or udp.

On success, it returns tls, which is in connected state. It can be used to read/write data from/to the connected peer.

In the second, deprecated form, the socket argument must be a connected socket. The socket is owned by tls object and should not be directly accessed after calling this procedure.

Function: tls-accept tls socket

{rfc.tls} NB: This API is deprecated. It is incompatible to the newer MbedTLS. We plan to provide an alternative API, with which you can “bind” a tls object and then “accept” the client connection, without touching the underlying sockets.

Establishes TLS connection as a server. The tls argument must be an unconnected TLS object, and the socket argument must be a listening socket. On success, it returns tls, which is in connected state. It can be used to read/write data from/to the connected peer.

Function: tls-close tls

{rfc.tls} Shuts down the underling connection. The peer will notified the connection is closed. Once tls is closed, it can no longer be used, but the reosurces won’t be collected until tls is GC-ed or tls-destroy is called. We recommend the user call tls-destroy explicitly.

Function: tls-destroy tls

{rfc.tls} Releases resources associated to tls.

Function: tls-input-port tls

Function: tls-output-port tls

{rfc.tls} If tls is connected, it returns input and output port to communicate with the peer, respectively.

If tls is not connected, #f is returned.

Function: tls-load-object tls type filename :optional password

{rfc.tls} This procedure is only meaningful for <axl-tls>. For <mbed-tls>, this procedure does nothing.

Load private keys or certificates stored in a file specified by filenames. The type of object is specified by type argument with one of the following numberic constants. If the file requires a password, it should be given to password.

SSL_OBJ_X509_CERT

SSL_OBJ_X509_CACERT

SSL_OBJ_RSA_KEY

SSL_OBJ_PKCS8

SSL_OBJ_PKC12

Constant: SSL_OBJ_X509_CERT

Constant: SSL_OBJ_X509_CACERT

Constant: SSL_OBJ_RSA_KEY

Constant: SSL_OBJ_PKCS8

Constant: SSL_OBJ_PKCS12

{rfc.tls}