12.41 rfc.tls - Transport layer security

Module: rfc.tls

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

We haven’t yet got other use cases than https connections, so we’re not sure how API of this layer should look like. At this moment, we document the minimal features you need to know to use the TLS layer with rfc.http.

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 only included if the build platform has mbedTLS library installed. And axTLS is set to be used by default.

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.

In the current version, we don’t verify certificates by default in axTLS, but we do in mbedTLS. You need to specify the location of CA certificates explicitly when you want to verify, unless the CA certificate location is specified at the configuration time. In future, we might set the default CA certificate file automatically so that users don’t need to bother by default, but not now.

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.

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

{rfc.tls} Set/get the CA certificate bundle path to be used. Without arguments, it returns the current path. With one argument, a pathname to the CA bundle file, updates the parameter to the new value and returns the previous value.

If you use mbedTLS, you need to set this value to the valid CA bundle file. Unfortunately there’s no globally agreed location for such file. If you need one, one choice is to fetch it from https://curl.haxx.se/ca/cacert.pem, store it locally and set its path to tls-ca-bundle-path. (We can’t automatically do that, since we can’t securely fetch the file before we get valid CA certs!)