documented fixes.

[gnutls.git] / doc / guile.texi

@c Documentation of the GNU Guile bindings.

@node Guile Bindings
@chapter Guile Bindings

This chapter describes the @uref{http://www.gnu.org/software/guile/,
GNU 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 @ref{Function reference,
the C API reference}.

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


@menu
* 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.
@end menu

@c *********************************************************************
@node Guile Preparations
@section Guile Preparations

The GnuTLS Guile bindings are by default installed under the GnuTLS
installation directory (e.g., typically
@file{/usr/local/share/guile/site/}).  Normally Guile will not find
the module there without help.  You may experience something like
this:

@example
$ guile
guile> (use-modules (gnutls))
<unnamed port>: no code for module (gnutls)
guile>
@end example

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
@code{--with-guile-site-dir} parameter as follows:

@example
$ ./configure --with-guile-site-dir=no
@end example

This will instruct GnuTLS to attempt to install the Guile 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 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 GnuTLS Guile 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
guile> (use-modules (gnutls))
guile>
@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{libguile-gnutls-v-0} similar to:

@example
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"
@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
guile> (use-modules (gnutls))
guile>
@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
guile> (use-modules (gnutls))
guile> (gnutls-version)
"@value{VERSION}"
guile> 
@end example


@c *********************************************************************
@node Guile API Conventions
@section 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
* 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 Enumerates and Constants
@subsection 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)} and @code{(gnutls extra)} modules.  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_CRD_IA
@} 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
credentials/ia
@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
@subsection 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
@subsection Representation of Binary Data

Many procedures operate on binary data.  For instance,
@code{pkcs3-import-dh-parameters} expects binary data as input and,
similarly, procedures like @code{pkcs1-export-rsa-parameters} return
binary data.

@cindex SRFI-4
@cindex homogeneous vector

Binary data is represented on the Scheme side using SRFI-4 homogeneous
vectors (@pxref{SRFI-4,,, guile, The GNU Guile Reference Manual}).
Although any type of homogeneous vector may be used, @code{u8vector}s
(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:

@findex make-rsa-parameters
@findex pkcs1-export-rsa-parameters
@vindex x509-certificate-format/pem

@example
(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")))
@end example

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


@node Input and Output
@subsection 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)))
    (write "Hello peer!" i/o)
    (let ((greetings (read i/o)))

      ;; ...

      (bye session close-request/rdwr))))
@end example

@findex record-send
@findex record-receive!

A lower-level I/O API is provided by @code{record-send} and
@code{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.


@node Exception Handling
@subsection 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
@section Guile Examples

This chapter provides examples that illustrate common use cases.

@menu
* Anonymous Authentication Guile Example::    Simplest client and server.
* OpenPGP Authentication Guile Example::      Using OpenPGP-based authentication.
* Importing OpenPGP Keys Guile Example::      Importing keys from files.
@end menu

@node Anonymous Authentication Guile Example
@subsection 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
;; 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))
@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
;; 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)))
@end example

This is it!


@node OpenPGP Authentication Guile Example
@subsection OpenPGP Authentication Guile Example

GnuTLS allows users to authenticate using OpenPGP certificates.  The
relevant procedures are provided by the @code{(gnutls extra)} module.
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
(@pxref{Importing OpenPGP Keys Guile Example}).

Assuming @var{some-socket} is bound to an open socket port and
@var{pub} and @var{sec} are bound to the client's OpenPGP public and
secret key, respectively, client-side code would look like this:

@vindex certificate-type/openpgp

@example
;; 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))
@end example

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

@example
;; 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)))
@end example

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 (@pxref{Core Interface,
@code{pkcs1-export-rsa-parameters} and
@code{pkcs1-import-rsa-parameters}}).

@node Importing OpenPGP Keys Guile Example
@subsection Importing OpenPGP Keys Guile Example

The following example provides a simple way of importing
``ASCII-armored'' OpenPGP keys from files, using the
@code{import-openpgp-certificate} and @code{import-openpgp-private-key}
procedures provided by the @code{(gnutls extra)} module.

@vindex openpgp-certificate-format/base64
@vindex openpgp-certificate-format/raw

@example
(use-modules (srfi srfi-4)
             (gnutls extra))

(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))
@end example

The procedures @code{import-public-key-from-file} and
@code{import-private-key-from-file} can be passed a file name.  They
return an OpenPGP public key and private key object, respectively
(@pxref{Extra Interface, OpenPGP key objects}).


@c *********************************************************************
@node Guile Reference
@section Guile Reference

This chapter documents GnuTLS Scheme procedures available to Guile
programmers.

@menu
* Core Interface::              Bindings for core GnuTLS.
* Extra Interface::             Bindings for GnuTLS-Extra.
@end menu

@node Core Interface
@subsection Core Interface

This section lists the Scheme procedures exported by the
@code{(gnutls)} module (@pxref{The Guile module system,,, guile, The
GNU Guile Reference Manual}).  This module is licenced under the GNU
Lesser General Public Licence, version 2.1 or later.

@include core.c.texi

@node Extra Interface
@subsection Extra Interface

This section lists the Scheme procedures exported by the @code{(gnutls
extra)} module.  This module is licenced under the GNU General Public
Licence, version 3 or later.

@include extra.c.texi



@ignore
;;; arch-tag: ee5f2081-9153-48fc-b4ee-2024381c65d7
@end ignore

@c Local Variables:
@c ispell-local-dictionary: "american"
@c End: