\input texinfo @c -*-texinfo-*- @comment %**start of header @setfilename gnutls-guile.info @include version-guile.texi @include abs-top-srcdir.texi @settitle Guile-GnuTLS @value{VERSION} @c don't indent the paragraphs. @paragraphindent 0 @c Unify some of the indices. @syncodeindex tp fn @syncodeindex pg cp @comment %**end of header @finalout @copying This manual is last updated @value{UPDATED} for version @value{VERSION} of Guile-GnuTLS. Copyright @copyright{} 2001--2025 Free Software Foundation, Inc. @quotation 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''. @end quotation @end copying @dircategory Software libraries @direntry * Guile-GnuTLS: (gnutls-guile). Guile bindings for GNU Transport Layer Security Library. @end direntry @titlepage @title Guile-GnuTLS @subtitle Guile binding for GnuTLS @subtitle for version @value{VERSION}, @value{UPDATED} @author Ludovic Courtès @page @vskip 0pt plus 1filll @insertcopying @end titlepage @macro xcite{ref} [\ref\] (@pxref{Bibliography}) @end macro @contents @node Top @top Guile-GnuTLS @insertcopying @menu * Preface:: Preface. * Guile Preparations:: Note on installation and environment. * Guile API Conventions:: Naming conventions and other idiosyncrasies. * Guile Examples:: Quick start. * Guile Reference:: The Scheme GnuTLS programming interface. * Copying Information:: You can copy and modify this manual. * Procedure Index:: * Concept Index:: @end menu @node Preface @chapter Preface This manual describes @code{Guile-GnuTLS}, the @uref{https://www.gnu.org/software/guile/, GNU Guile} Scheme programming interface to @uref{https://gnutls.org,GnuTLS}. The reader is assumed to have basic knowledge of the TLS protocol and GnuTLS library (@pxref{Introduction to GnuTLS, GnuTLS intro,, gnutls, GnuTLS Manual}). At this stage, not all the C functions are available from Scheme, but a large subset thereof is available. @c ********************************************************************* @node Guile Preparations @chapter Guile Preparations The Guile bindings for GnuTLS are available for the Guile 3.0 and 2.2 series, as well as the legacy 2.0 series. By default they are installed into @file{/usr/local/share/guile/site/}). Normally Guile will not find the module there without help. You may experience something like this: @example $ guile @dots{} scheme@@(guile-user)> (use-modules (gnutls)) ERROR: no code for module (gnutls) @end example There are two ways to solve this. The first is to make sure that when building Guile-GnuTLS, the bindings will be installed in the same place where Guile looks. You may do this by using the @code{--with-guile-site-dir} parameter as follows: @example $ ./configure --with-guile-site-dir=no @end example This will instruct Guile-GnuTLS to attempt to install the bindings where Guile will look for them. It will use @code{guile-config info pkgdatadir} to learn the path to use. If Guile was installed into @code{/usr}, you may also install Guile-GnuTLS using the same prefix: @example $ ./configure --prefix=/usr @end example If you want to specify the path to install the Guile bindings you can also specify the path directly: @example $ ./configure --with-guile-site-dir=/opt/guile/share/guile/site @end example 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 Guile-GnuTLS bindings. Either use the @code{GUILE_LOAD_PATH} environment variable as follows: @example $ GUILE_LOAD_PATH="/usr/local/share/guile/site:$GUILE_LOAD_PATH" guile scheme@@(guile-user)> (use-modules (gnutls)) scheme@@(guile-user)> @end example Alternatively, you can modify Guile's @code{%load-path} variable (@pxref{Build Config, Guile's run-time options,, guile, The GNU Guile Reference Manual}). At this point, you might get an error regarding @file{guile-gnutls-v-2} similar to: @example 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" @end example In this case, you will need to modify the run-time linker path, for example as follows: @example $ LD_LIBRARY_PATH=/usr/local/lib GUILE_LOAD_PATH=/usr/local/share/guile/site guile scheme@@(guile-user)> (use-modules (gnutls)) scheme@@(guile-user)> @end example To check that you got the intended GnuTLS library version, you may print the version number of the loaded library as follows: @example $ guile scheme@@(guile-user)> (use-modules (gnutls)) scheme@@(guile-user)> (gnutls-version) "@value{VERSION}" scheme@@(guile-user)> @end example @c ********************************************************************* @node Guile API Conventions @chapter 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. @menu * Living on the cutting edge:: Checking for newer functions. * Enumerates and Constants:: Representation of C-side constants. * Procedure Names:: Naming conventions. * Representation of Binary Data:: Binary data buffers. * Input and Output:: Input and output. * Exception Handling:: Exceptions. @end menu @node Living on the cutting edge @section Living on the cutting edge Some GnuTLS features have been introduced recently. To keep compatibility with older GnuTLS versions, they may not all be available. If a GnuTLS feature is not available, then its corresponding variable will not be exported by the @code{(gnutls)} module. @node Enumerates and Constants @section Enumerates and Constants @cindex enumerate @cindex constant 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 @code{(gnutls)} module. These variables are named according to the following convention: @itemize @item All variable names are lower-case; the underscore @code{_} character used in the C API is replaced by hyphen @code{-}. @item All variable names are prepended by the name of the enumerate type and the slash @code{/} character. @item In some cases, the variable name is made more explicit than the one of the C API, e.g., by avoid abbreviations. @end itemize Consider for instance this C-side enumerate: @example typedef enum @{ GNUTLS_CRD_CERTIFICATE = 1, GNUTLS_CRD_ANON, GNUTLS_CRD_SRP, GNUTLS_CRD_PSK @} gnutls_credentials_type_t; @end example The corresponding Scheme values are bound to the following variables exported by the @code{(gnutls)} module: @example credentials/certificate credentials/anonymous credentials/srp credentials/psk @end example Hopefully, most variable names can be deduced from this convention. Scheme-side ``enumerate'' values can be compared using @code{eq?} (@pxref{Equality, equality predicates,, guile, The GNU Guile Reference Manual}). Consider the following example: @findex session-cipher @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"))) @end example In addition, all enumerate values can be converted to a human-readable string, in a type-specific way. For instance, @code{(cipher->string cipher/arcfour)} yields @code{"ARCFOUR 128"}, while @code{(key-usage->string key-usage/digital-signature)} yields @code{"digital-signature"}. Note that these strings may not be sufficient for use in a user interface since they are fairly concise and not internationalized. @node Procedure Names @section 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 @code{gnutls_certificate_set_dh_params} is named @code{set-certificate-credentials-dh-parameters!}. The @code{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 (@pxref{Using Guile Modules,,, guile, 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 @code{set-session-transport-port!} corresponds to @code{gnutls_transport_set_ptr}, making it clear that this procedure applies to session. @node Representation of Binary Data @section Representation of Binary Data Many procedures operate on binary data. For instance, @code{pkcs3-import-dh-parameters} expects binary data as input. @cindex bytevectors @cindex SRFI-4 @cindex homogeneous vector Binary data is represented on the Scheme side using bytevectors (@pxref{Bytevectors,,, guile, The GNU Guile Reference Manual}). Homogeneous vectors such as SRFI-4 @code{u8vector}s can also be used@footnote{Historically, SRFI-4 @code{u8vector}s 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: @findex make-dh-parameters @findex pkcs3-export-dh-parameters @vindex x509-certificate-format/pem @example (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)))) @end example @node Input and Output @section Input and Output @findex set-session-transport-port! @findex set-session-transport-fd! The underlying transport of a TLS session can be any Scheme input/output port (@pxref{Ports and File Descriptors,,, guile, The GNU Guile Reference Manual}). This has to be specified using @code{set-session-transport-port!}. However, for better performance, a raw file descriptor can be specified, using @code{set-session-transport-fd!}. For instance, if the transport layer is a socket port over an OS-provided socket, you can use the @code{port->fdes} or @code{fileno} procedure to obtain the underlying file descriptor and pass it to @code{set-session-transport-fd!} (@pxref{Ports and File Descriptors, @code{port->fdes} and @code{fileno},, guile, The GNU Guile Reference Manual}). This would work as follows: @example (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))) @end example @findex session-record-port Once a TLS session is established, data can be communicated through it (i.e., @emph{via} the TLS record layer) using the port returned by @code{session-record-port}: @example (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))) ;; @dots{} (bye session close-request/rdwr)))) @end example @c See for details. @cindex buffering 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 @code{write} system call), so we recommend that applications do their own buffering. @findex record-send @findex record-receive! A lower-level I/O API is provided by @code{record-send} and @code{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. @node Exception Handling @section Exception Handling @cindex exceptions @cindex errors @cindex @code{gnutls-error} @findex error->string GnuTLS errors are implemented as Scheme exceptions (@pxref{Exceptions, exceptions in Guile,, guile, The GNU Guile Reference Manual}). Each time a GnuTLS function returns an error, an exception with key @code{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 @code{error/} variables exported by the @code{(gnutls)} module (@pxref{Enumerates and Constants}). Exceptions can be turned into error messages using the @code{error->string} procedure. The following examples illustrates how GnuTLS exceptions can be handled: @example (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))))) @end example Again, error values can be compared using @code{eq?}: @example ;; `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)))) @end example Note that the @code{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. @c ********************************************************************* @node Guile Examples @chapter Guile Examples This chapter provides examples that illustrate common use cases. @menu * Anonymous Authentication Guile Example:: Simplest client and server. * Using GnuTLS as a cryptography library:: Use the lower-level API. @end menu @node Anonymous Authentication Guile Example @section Anonymous Authentication Guile Example @dfn{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 @var{some-socket} is bound to an open socket port): @vindex connection-end/client @vindex kx/anon-dh @vindex close-request/rdwr @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/anonymous-client.scm @end example The corresponding server would look like this (again, assuming @var{some-socket} is bound to a socket port): @vindex connection-end/server @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/anonymous-server.scm @end example This is it! @node Using GnuTLS as a cryptography library @section Using GnuTLS as a cryptography library The low-level functions in GnuTLS can be accessed for various tasks. @menu * Hash Message Authentication Code:: Hashing with a secret. * Hash Digest Algorithms:: Hashes. * Authenticated Encryption:: The AEAD API. * Low-lovel encryption API:: Block-by-block encryption of data. * Public key cryptography:: Using private and public keys. * Generating random numbers:: Pseudo-random number generation. * Encoding binary data:: Base16, base64. @end menu @node Hash Message Authentication Code @subsection Hash Message Authentication Code The library provides support for @dfn{Hash Message Authentication Code} (@emph{hmac}). This API provides a way to hash a message in a way that is only reproducible with the knowledge of a secret. This first example demonstrates how to use @code{hmac-fast} to hash a bytevector in memory. @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/hmac-example-1.scm @end example The next example shows how to hash a whole file that might not fit in memory. @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/hmac-example-2.scm @end example The final example shows how you can reuse a state to continue hashing different inputs. This requires the @code{hmac-copy} function, which is not always available (@pxref{Living on the cutting edge}). @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/hmac-example-3.scm @end example @node Hash Digest Algorithms @subsection Hash Digest Algorithms The API for hash algorithm is similar to that for hmac, except that there is no secret data to reproduce the hash. So for instance, the second hmac example becomes (@pxref{Hash Message Authentication Code}): @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/hash-example.scm @end example @node Authenticated Encryption @subsection Authenticated Encryption The goal of authenticated encryption is to make sure that the data has been encrypted by a party that knows a shared secret. The encryption and decryption procedures are very similar. Both parties must know a shared secret key and a nonce. The nonce is a value that must only be used once to encrypt data. The nonce may be as long as you want, but the secret key must be the exact size expected by the cipher algorithm. The API can also use extra authentication data, that can change on a packet-by-packet basis, whatever your definition for a packet is. To use the API, the cipher algorithm must be compatible with AEAD. When it is, it defines a default tag size. You can override the tag size, or use the 0 value to use the default tag size. This example encrypts a file: @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/aead-encrypt-example.scm @end example And this example decrypts the same file. Please note that the decrypted file is written to disk, which is acceptable for this simple example: @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/aead-decrypt-example.scm @end example @node Low-lovel encryption API @subsection Low-lovel encryption API In some cases, you may want to use a lower-level encryption API. In this example, the data to encrypt spans an integer number of blocks. You need to specify the initialization vector, to seed the encryption, and a private key. @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/low-level-cipher-example.scm @end example @node Public key cryptography @subsection Public key cryptography The following example shows how to use elliptic curve cryptography with a private key. @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/use-private-key.scm @end example The next example shows how to generate a private key. @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/generate-private-key.scm @end example In addition, abstract public or private keys can be obtained from X509 certificate and private key, with @code{x509-certificate->public-key} and @code{x509-private-key->private-key}. @node Generating random numbers @subsection Generating random numbers Gnutls lets you generate different kinds of pseudo-random numbers, depending on the implications if it is guessed. Here is how you generate a random number with the lowest security requirements: @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/random-example.scm @end example @node Encoding binary data @subsection Encoding binary data When working with gnutls, you may come across a lot of binary data, in the form of guile bytevectors. Base16 and base64 are popular encoding schemes for binary data. This example shows how to encode and decode binary data to and from base16. @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/base16-example.scm @end example This example shows how to encode and decode binary data to and from base64. @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/base64-example.scm @end example Unfortunately, gnutls does not provide an API to encode data to the popular base64-url encoding. However, it is possible to convert from base64 to base64-url and back. @example @verbatiminclude @value{abs_top_srcdir}/guile/examples/base64url-example.scm @end example @c ********************************************************************* @node Guile Reference @chapter Guile Reference This chapter lists the Scheme procedures exported by the @code{(gnutls)} module (@pxref{Using the Guile Module System,,, guile, The GNU Guile Reference Manual}). @include core.c.texi @c Local Variables: @c ispell-local-dictionary: "american" @c End: @include cha-copying.texi @node Procedure Index @unnumbered Procedure Index @printindex fn @node Concept Index @unnumbered Concept Index @printindex cp @bye