     [file version-guile.texi not included]

GnuTLS-Guile
************

This manual is last updated UPDATED for version VERSION of GnuTLS.

Copyright © 2001-2012, 2014, 2016, 2019 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Preface
*******

This manual describes the GNU Guile (https://www.gnu.org/software/guile/) Scheme programming interface to GnuTLS, which is distributed as part of GnuTLS (https://gnutls.org).  The reader is assumed to have basic knowledge of the protocol and library.  Details missing from this chapter may be found in Function reference, of the C API reference.

At this stage, not all the C functions are available from Scheme, but a large subset thereof is available.

Guile Preparations
******************

The GnuTLS Guile bindings are available for the Guile 3.0 and 2.2 series, as well as the legacy 2.0 and even 1.8 series.

By default they are installed under the GnuTLS installation directory, typically /usr/local/share/guile/site/).  Normally Guile will not find the module there without help.  You may experience something like this:

     $ guile
     ...
     scheme@(guile-user)> (use-modules (gnutls))
     ERROR: no code for module (gnutls)

There are two ways to solve this.  The first is to make sure that when building GnuTLS, the Guile bindings will be installed in the same place where Guile looks.  You may do this by using the --with-guile-site-dir parameter as follows:

     $ ./configure --with-guile-site-dir=no

This will instruct GnuTLS to attempt to install the Guile bindings where Guile will look for them.  It will use guile-config info pkgdatadir to learn the path to use.

If Guile was installed into /usr, you may also install GnuTLS using the same prefix:

     $ ./configure --prefix=/usr

If you want to specify the path to install the Guile bindings you can also specify the path directly:

     $ ./configure --with-guile-site-dir=/opt/guile/share/guile/site

The second solution requires some more work but may be easier to use if you do not have system administrator rights to your machine.  You need to instruct Guile so that it finds the GnuTLS Guile bindings. Either use the GUILE_LOAD_PATH environment variable as follows:

     $ GUILE_LOAD_PATH="/usr/local/share/guile/site:$GUILE_LOAD_PATH" guile
     scheme@(guile-user)> (use-modules (gnutls))
     scheme@(guile-user)>

Alternatively, you can modify Guile's %load-path variable (see Guile's run-time options (The GNU Guile Reference Manual)).

At this point, you might get an error regarding guile-gnutls-v-2 similar to:

     gnutls.scm:361:1: In procedure dynamic-link in expression (load-extension "guile-gnutls-v-2" "scm_init_gnutls"):
     gnutls.scm:361:1: file: "guile-gnutls-v-2", message: "guile-gnutls-v-2.so: cannot open shared object file: No such file or directory"

In this case, you will need to modify the run-time linker path, for example as follows:

     $ LD_LIBRARY_PATH=/usr/local/lib GUILE_LOAD_PATH=/usr/local/share/guile/site guile
     scheme@(guile-user)> (use-modules (gnutls))
     scheme@(guile-user)>

To check that you got the intended GnuTLS library version, you may print the version number of the loaded library as follows:

     $ guile
     scheme@(guile-user)> (use-modules (gnutls))
     scheme@(guile-user)> (gnutls-version)
     "VERSION"
     scheme@(guile-user)>

Guile API Conventions
*********************

This chapter details the conventions used by Guile API, as well as specificities of the mapping of the C API to Scheme.

Enumerates and Constants
========================

Lots of enumerates and constants are used in the GnuTLS C API.  For each C enumerate type, a disjoint Scheme type is used---thus, enumerate values and constants are not represented by Scheme symbols nor by integers.  This makes it impossible to use an enumerate value of the wrong type on the Scheme side: such errors are automatically detected by type-checking.

The enumerate values are bound to variables exported by the (gnutls) module.  These variables are named according to the following convention:

  * All variable names are lower-case; the underscore _ character used in the C API is replaced by hyphen -.

  * All variable names are prepended by the name of the enumerate type and the slash / character.

  * In some cases, the variable name is made more explicit than the one of the C API, e.g., by avoid abbreviations.

Consider for instance this C-side enumerate:

     typedef enum
     {
       GNUTLS_CRD_CERTIFICATE = 1,
       GNUTLS_CRD_ANON,
       GNUTLS_CRD_SRP,
       GNUTLS_CRD_PSK
     } gnutls_credentials_type_t;

The corresponding Scheme values are bound to the following variables exported by the (gnutls) module:

     credentials/certificate
     credentials/anonymous
     credentials/srp
     credentials/psk

Hopefully, most variable names can be deduced from this convention.

Scheme-side ``enumerate'' values can be compared using eq? (see equality predicates (The GNU Guile Reference Manual)).  Consider the following example:

     (let ((session (make-session connection-end/client)))

       ;;
       ;; ...
       ;;

       ;; Check the ciphering algorithm currently used by SESSION.
       (if (eq? cipher/arcfour (session-cipher session))
           (format #t "We're using the ARCFOUR algorithm")))

In addition, all enumerate values can be converted to a human-readable string, in a type-specific way.  For instance, (cipher->string cipher/arcfour) yields "ARCFOUR 128", while (key-usage->string key-usage/digital-signature) yields "digital-signature".  Note that these strings may not be sufficient for use in a user interface since they are fairly concise and not internationalized.

Procedure Names
===============

Unlike C functions in GnuTLS, the corresponding Scheme procedures are named in a way that is close to natural English.  Abbreviations are also avoided.  For instance, the Scheme procedure corresponding to gnutls_certificate_set_dh_params is named set-certificate-credentials-dh-parameters!.  The gnutls_ prefix is always omitted from variable names since a similar effect can be achieved using Guile's nifty binding renaming facilities, should it be needed (see Using Guile Modules (The GNU Guile Reference Manual)).

Often Scheme procedure names differ from C function names in a way that makes it clearer what objects they operate on.  For example, the Scheme procedure named set-session-transport-port! corresponds to gnutls_transport_set_ptr, making it clear that this procedure applies to session.

Representation of Binary Data
=============================

Many procedures operate on binary data.  For instance, pkcs3-import-dh-parameters expects binary data as input.

Binary data is represented on the Scheme side using bytevectors (see Bytevectors (The GNU Guile Reference Manual)). Homogeneous vectors such as SRFI-4 u8vectors can also be used (Historically, SRFI-4 u8vectors are the closest thing to bytevectors that Guile 1.8 and earlier supported.).

As an example, generating and then exporting Diffie-Hellman parameters in the PEM format can be done as follows:

     (let* ((dh  (make-dh-parameters 1024))
            (pem (pkcs3-export-dh-parameters dh
                                             x509-certificate-format/pem)))
       (call-with-output-file "some-file.pem"
         (lambda (port)
           (uniform-vector-write pem port))))

Input and Output
================

The underlying transport of a TLS session can be any Scheme input/output port (see Ports and File Descriptors (The GNU Guile Reference Manual)).  This has to be specified using set-session-transport-port!.

However, for better performance, a raw file descriptor can be specified, using set-session-transport-fd!.  For instance, if the transport layer is a socket port over an OS-provided socket, you can use the port->fdes or fileno procedure to obtain the underlying file descriptor and pass it to set-session-transport-fd!  (see port->fdes and fileno (The GNU Guile Reference Manual)).  This would work as follows:

     (let ((socket (socket PF_INET SOCK_STREAM 0))
           (session (make-session connection-end/client)))

       ;;
       ;; Establish a TCP connection...
       ;;

       ;; Use the file descriptor that underlies SOCKET.
       (set-session-transport-fd! session (fileno socket)))

Once a TLS session is established, data can be communicated through it (i.e., via the TLS record layer) using the port returned by session-record-port:

     (let ((session (make-session connection-end/client)))

       ;;
       ;; Initialize the various parameters of SESSION, set up
       ;; a network connection, etc.
       ;;

       (let ((i/o (session-record-port session)))
         (display "Hello peer!" i/o)
         (let ((greetings (read i/o)))

           ;; ...

           (bye session close-request/rdwr))))

Note that each write to the session record port leads to the transmission of an encrypted TLS ``Application Data'' packet.  In the above example, we create an Application Data packet for the 11 bytes for the string that we write.  This is not efficient both in terms of CPU usage and bandwidth (each packet adds at least 5 bytes of overhead and can lead to one write system call), so we recommend that applications do their own buffering.

A lower-level I/O API is provided by record-send and record-receive! which take a bytevector (or a SRFI-4 vector) to represent the data sent or received.  While it might improve performance, it is much less convenient than the session record port and should rarely be needed.

Exception Handling
==================

GnuTLS errors are implemented as Scheme exceptions (see exceptions in Guile (The GNU Guile Reference Manual)).  Each time a GnuTLS function returns an error, an exception with key gnutls-error is raised.  The additional arguments that are thrown include an error code and the name of the GnuTLS procedure that raised the exception.  The error code is pretty much like an enumerate value: it is one of the error/ variables exported by the (gnutls) module (see Enumerates and Constants).  Exceptions can be turned into error messages using the error->string procedure.

The following examples illustrates how GnuTLS exceptions can be handled:

     (let ((session (make-session connection-end/server)))

       ;;
       ;; ...
       ;;

       (catch 'gnutls-error
         (lambda ()
           (handshake session))
         (lambda (key err function . currently-unused)
           (format (current-error-port)
                   "a GnuTLS error was raised by `~a': ~a~%"
                   function (error->string err)))))

Again, error values can be compared using eq?:

         ;; `gnutls-error' handler.
         (lambda (key err function . currently-unused)
           (if (eq? err error/fatal-alert-received)
               (format (current-error-port)
                       "a fatal alert was caught!~%")
               (format (current-error-port)
                       "something bad happened: ~a~%"
                       (error->string err))))

Note that the catch handler is currently passed only 3 arguments but future versions might provide it with additional arguments.  Thus, it must be prepared to handle more than 3 arguments, as in this example.

Guile Examples
**************

This chapter provides examples that illustrate common use cases.

Anonymous Authentication Guile Example
======================================

Anonymous authentication is very easy to use.  No certificates are needed by the communicating parties.  Yet, it allows them to benefit from end-to-end encryption and integrity checks.

The client-side code would look like this (assuming SOME-SOCKET is bound to an open socket port):

     ;; Client-side.

     (let ((client (make-session connection-end/client)))
       ;; Use the default settings.
       (set-session-default-priority! client)

       ;; Don't use certificate-based authentication.
       (set-session-certificate-type-priority! client '())

       ;; Request the "anonymous Diffie-Hellman" key exchange method.
       (set-session-kx-priority! client (list kx/anon-dh))

       ;; Specify the underlying socket.
       (set-session-transport-fd! client (fileno some-socket))

       ;; Create anonymous credentials.
       (set-session-credentials! client
                                 (make-anonymous-client-credentials))

       ;; Perform the TLS handshake with the server.
       (handshake client)

       ;; Send data over the TLS record layer.
       (write "hello, world!" (session-record-port client))

       ;; Terminate the TLS session.
       (bye client close-request/rdwr))

The corresponding server would look like this (again, assuming SOME-SOCKET is bound to a socket port):

     ;; Server-side.

     (let ((server (make-session connection-end/server)))
       (set-session-default-priority! server)
       (set-session-certificate-type-priority! server '())
       (set-session-kx-priority! server (list kx/anon-dh))

       ;; Specify the underlying transport socket.
       (set-session-transport-fd! server (fileno some-socket))

       ;; Create anonymous credentials.
       (let ((cred (make-anonymous-server-credentials))
             (dh-params (make-dh-parameters 1024)))
         ;; Note: DH parameter generation can take some time.
         (set-anonymous-server-dh-parameters! cred dh-params)
         (set-session-credentials! server cred))

       ;; Perform the TLS handshake with the client.
       (handshake server)

       ;; Receive data over the TLS record layer.
       (let ((message (read (session-record-port server))))
         (format #t "received the following message: ~a~%"
                 message)

         (bye server close-request/rdwr)))

This is it!

Guile Reference
***************

This chapter lists the GnuTLS Scheme procedures exported by the (gnutls) module (see The Guile module system (The GNU Guile Reference Manual)).

     [file core.c.texi not included]

     [file cha-copying.texi not included]