     [file version-guile.texi not included]

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

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

Copyright © 2001-2012, 2014 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 (http://www.gnu.org/software/guile/) Scheme programming interface to GnuTLS.  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 both the 1.8 and 2.0 stable series of Guile.

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
     guile> (use-modules (gnutls))
     <unnamed port>: no code for module (gnutls)
     guile>

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
     guile> (use-modules (gnutls))
     guile>

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 libguile-gnutls-v-0 similar to:

     gnutls.scm:361:1: In procedure dynamic-link in expression (load-extension "libguile-gnutls-v-0" "scm_init_gnutls"):
     gnutls.scm:361:1: file: "libguile-gnutls-v-0", message: "libguile-gnutls-v-0.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
     guile> (use-modules (gnutls))
     guile>

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

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

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 and, similarly, procedures like pkcs1-export-rsa-parameters return binary data.

Binary data is represented on the Scheme side using SRFI-4 homogeneous vectors (see SRFI-4 (The GNU Guile Reference Manual)). Although any type of homogeneous vector may be used, u8vectors (i.e., vectors of bytes) are highly recommended.

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

     (let* ((rsa-params (make-rsa-parameters 1024))
            (raw-data
             (pkcs1-export-rsa-parameters rsa-params
                                          x509-certificate-format/pem)))
       (uniform-vector-write raw-data (open-output-file "some-file.pem")))

For an example of OpenPGP key import from a file, see Importing OpenPGP Keys Guile Example.

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)))
         (write "Hello peer!" i/o)
         (let ((greetings (read i/o)))

           ;; ...

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

A lower-level I/O API is provided by record-send and record-receive! which take an SRFI-4 vector to represent the data sent or received.  While it might improve performance, it is much less convenient than the above 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!

OpenPGP Authentication Guile Example
====================================

GnuTLS allows users to authenticate using OpenPGP certificates. Using OpenPGP-based authentication is not more complicated than using anonymous authentication.  It requires a bit of extra work, though, to import the OpenPGP public and private key of the client/server.  Key import is omitted here and is left as an exercise to the reader (see Importing OpenPGP Keys Guile Example).

Assuming SOME-SOCKET is bound to an open socket port and PUB and SEC are bound to the client's OpenPGP public and secret key, respectively, client-side code would look like this:

     ;; Client-side.

     (define %certs (list certificate-type/openpgp))

     (let ((client (make-session connection-end/client))
           (cred   (make-certificate-credentials)))
       (set-session-default-priority! client)

       ;; Choose OpenPGP certificates.
       (set-session-certificate-type-priority! client %certs)

       ;; Prepare appropriate client credentials.
       (set-certificate-credentials-openpgp-keys! cred pub sec)
       (set-session-credentials! client cred)

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

       (handshake client)
       (write "hello, world!" (session-record-port client))
       (bye client close-request/rdwr))

Similarly, server-side code would be along these lines:

     ;; Server-side.

     (define %certs (list certificate-type/openpgp))

     (let ((server (make-session connection-end/server))
           (rsa    (make-rsa-parameters 1024))
           (dh     (make-dh-parameters 1024)))
       (set-session-default-priority! server)

       ;; Choose OpenPGP certificates.
       (set-session-certificate-type-priority! server %certs)

       (let ((cred (make-certificate-credentials)))
         ;; Prepare credentials with RSA and Diffie-Hellman parameters.
         (set-certificate-credentials-dh-parameters! cred dh)
         (set-certificate-credentials-rsa-export-parameters! cred rsa)
         (set-certificate-credentials-openpgp-keys! cred pub sec)
         (set-session-credentials! server cred))

       (set-session-transport-fd! server (fileno some-socket))

       (handshake server)
       (let ((msg (read (session-record-port server))))
         (format #t "received: ~a~%" msg)

         (bye server close-request/rdwr)))

In practice, generating RSA parameters (and Diffie-Hellman parameters) can time a long time.  Thus, you may want to generate them once and store them in a file for future re-use (see pkcs1-export-rsa-parameters and pkcs1-import-rsa-parameters).

Importing OpenPGP Keys Guile Example
====================================

The following example provides a simple way of importing ``ASCII-armored'' OpenPGP keys from files, using the import-openpgp-certificate and import-openpgp-private-key procedures.

     (use-modules (srfi srfi-4)
                  (gnutls))

     (define (import-key-from-file import-proc file)
       ;; Import OpenPGP key from FILE using IMPORT-PROC.

       ;; Prepare a u8vector large enough to hold the raw
       ;; key contents.
       (let* ((size (stat:size (stat path)))
              (raw  (make-u8vector size)))

         ;; Fill in the u8vector with the contents of FILE.
         (uniform-vector-read! raw (open-input-file file))

         ;; Pass the u8vector to the import procedure.
         (import-proc raw openpgp-certificate-format/base64)))

     (define (import-public-key-from-file file)
       (import-key-from-file import-openpgp-certificate file))

     (define (import-private-key-from-file file)
       (import-key-from-file import-openpgp-private-key file))

The procedures import-public-key-from-file and import-private-key-from-file can be passed a file name.  They return an OpenPGP public key and private key object, respectively (see OpenPGP key objects).

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]