1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header
3 @setfilename gnutls-guile.info
4 @include version-guile.texi
5 @settitle GnuTLS-Guile @value{VERSION}
7 @c don't indent the paragraphs.
10 @c Unify some of the indices.
14 @comment %**end of header
17 This manual is last updated @value{UPDATED} for version
18 @value{VERSION} of GnuTLS.
20 Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
23 Permission is granted to copy, distribute and/or modify this document
24 under the terms of the GNU Free Documentation License, Version 1.3 or
25 any later version published by the Free Software Foundation; with no
26 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
27 copy of the license is included in the section entitled ``GNU Free
28 Documentation License''.
32 @dircategory Software libraries
34 * GnuTLS-Guile: (gnutls-guile). GNU Transport Layer Security Library. Guile bindings.
39 @subtitle Guile binding for GNU TLS
40 @subtitle for version @value{VERSION}, @value{UPDATED}
42 @image{gnutls-logo,6cm,6cm}
44 @vskip 0pt plus 1filll
49 [\ref\] (@pxref{Bibliography})
63 * Guile Preparations:: Note on installation and environment.
64 * Guile API Conventions:: Naming conventions and other idiosyncrasies.
65 * Guile Examples:: Quick start.
66 * Guile Reference:: The Scheme GnuTLS programming interface.
67 * Copying Information:: Copying information.
73 This manual describes the @uref{http://www.gnu.org/software/guile/,
74 GNU Guile} Scheme programming interface to GnuTLS. The reader is
75 assumed to have basic knowledge of the protocol and library. Details
76 missing from this chapter may be found in Function reference,
77 of the C API reference.
79 At this stage, not all the C functions are available from Scheme, but
80 a large subset thereof is available.
82 @c *********************************************************************
83 @node Guile Preparations
84 @chapter Guile Preparations
86 The GnuTLS Guile bindings are available for both the 1.8 and 2.0 stable
89 By default they are installed under the GnuTLS installation directory,
90 typically @file{/usr/local/share/guile/site/}). Normally Guile
91 will not find the module there without help. You may experience
96 guile> (use-modules (gnutls))
97 <unnamed port>: no code for module (gnutls)
101 There are two ways to solve this. The first is to make sure that when
102 building GnuTLS, the Guile bindings will be installed in the same
103 place where Guile looks. You may do this by using the
104 @code{--with-guile-site-dir} parameter as follows:
107 $ ./configure --with-guile-site-dir=no
110 This will instruct GnuTLS to attempt to install the Guile bindings
111 where Guile will look for them. It will use @code{guile-config info
112 pkgdatadir} to learn the path to use.
114 If Guile was installed into @code{/usr}, you may also install GnuTLS
115 using the same prefix:
118 $ ./configure --prefix=/usr
121 If you want to specify the path to install the Guile bindings you can
122 also specify the path directly:
125 $ ./configure --with-guile-site-dir=/opt/guile/share/guile/site
128 The second solution requires some more work but may be easier to use
129 if you do not have system administrator rights to your machine. You
130 need to instruct Guile so that it finds the GnuTLS Guile bindings.
131 Either use the @code{GUILE_LOAD_PATH} environment variable as follows:
134 $ GUILE_LOAD_PATH="/usr/local/share/guile/site:$GUILE_LOAD_PATH" guile
135 guile> (use-modules (gnutls))
139 Alternatively, you can modify Guile's @code{%load-path} variable
140 (@pxref{Build Config, Guile's run-time options,, guile, The GNU Guile
143 At this point, you might get an error regarding
144 @file{libguile-gnutls-v-0} similar to:
147 gnutls.scm:361:1: In procedure dynamic-link in expression (load-extension "libguile-gnutls-v-0" "scm_init_gnutls"):
148 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"
151 In this case, you will need to modify the run-time linker path, for
155 $ LD_LIBRARY_PATH=/usr/local/lib GUILE_LOAD_PATH=/usr/local/share/guile/site guile
156 guile> (use-modules (gnutls))
160 To check that you got the intended GnuTLS library version, you may
161 print the version number of the loaded library as follows:
165 guile> (use-modules (gnutls))
166 guile> (gnutls-version)
172 @c *********************************************************************
173 @node Guile API Conventions
174 @chapter Guile API Conventions
176 This chapter details the conventions used by Guile API, as well as
177 specificities of the mapping of the C API to Scheme.
180 * Enumerates and Constants:: Representation of C-side constants.
181 * Procedure Names:: Naming conventions.
182 * Representation of Binary Data:: Binary data buffers.
183 * Input and Output:: Input and output.
184 * Exception Handling:: Exceptions.
187 @node Enumerates and Constants
188 @section Enumerates and Constants
193 Lots of enumerates and constants are used in the GnuTLS C API. For
194 each C enumerate type, a disjoint Scheme type is used---thus,
195 enumerate values and constants are not represented by Scheme symbols
196 nor by integers. This makes it impossible to use an enumerate value
197 of the wrong type on the Scheme side: such errors are automatically
198 detected by type-checking.
200 The enumerate values are bound to variables exported by the
201 @code{(gnutls)} module. These variables
202 are named according to the following convention:
205 @item All variable names are lower-case; the underscore @code{_}
206 character used in the C API is replaced by hyphen @code{-}.
207 @item All variable names are prepended by the name of the enumerate
208 type and the slash @code{/} character.
209 @item In some cases, the variable name is made more explicit than the
210 one of the C API, e.g., by avoid abbreviations.
213 Consider for instance this C-side enumerate:
218 GNUTLS_CRD_CERTIFICATE = 1,
223 @} gnutls_credentials_type_t;
226 The corresponding Scheme values are bound to the following variables
227 exported by the @code{(gnutls)} module:
230 credentials/certificate
231 credentials/anonymous
237 Hopefully, most variable names can be deduced from this convention.
239 Scheme-side ``enumerate'' values can be compared using @code{eq?}
240 (@pxref{Equality, equality predicates,, guile, The GNU Guile Reference
241 Manual}). Consider the following example:
243 @findex session-cipher
246 (let ((session (make-session connection-end/client)))
252 ;; Check the ciphering algorithm currently used by SESSION.
253 (if (eq? cipher/arcfour (session-cipher session))
254 (format #t "We're using the ARCFOUR algorithm")))
257 In addition, all enumerate values can be converted to a human-readable
258 string, in a type-specific way. For instance, @code{(cipher->string
259 cipher/arcfour)} yields @code{"ARCFOUR 128"}, while
260 @code{(key-usage->string key-usage/digital-signature)} yields
261 @code{"digital-signature"}. Note that these strings may not be
262 sufficient for use in a user interface since they are fairly concise
263 and not internationalized.
266 @node Procedure Names
267 @section Procedure Names
269 Unlike C functions in GnuTLS, the corresponding Scheme procedures are
270 named in a way that is close to natural English. Abbreviations are
271 also avoided. For instance, the Scheme procedure corresponding to
272 @code{gnutls_certificate_set_dh_params} is named
273 @code{set-certificate-credentials-dh-parameters!}. The @code{gnutls_}
274 prefix is always omitted from variable names since a similar effect
275 can be achieved using Guile's nifty binding renaming facilities,
276 should it be needed (@pxref{Using Guile Modules,,, guile, The GNU
277 Guile Reference Manual}).
279 Often Scheme procedure names differ from C function names in a way
280 that makes it clearer what objects they operate on. For example, the
281 Scheme procedure named @code{set-session-transport-port!} corresponds
282 to @code{gnutls_transport_set_ptr}, making it clear that this
283 procedure applies to session.
285 @node Representation of Binary Data
286 @section Representation of Binary Data
288 Many procedures operate on binary data. For instance,
289 @code{pkcs3-import-dh-parameters} expects binary data as input and,
290 similarly, procedures like @code{pkcs1-export-rsa-parameters} return
294 @cindex homogeneous vector
296 Binary data is represented on the Scheme side using SRFI-4 homogeneous
297 vectors (@pxref{SRFI-4,,, guile, The GNU Guile Reference Manual}).
298 Although any type of homogeneous vector may be used, @code{u8vector}s
299 (i.e., vectors of bytes) are highly recommended.
301 As an example, generating and then exporting RSA parameters in the PEM
302 format can be done as follows:
304 @findex make-rsa-parameters
305 @findex pkcs1-export-rsa-parameters
306 @vindex x509-certificate-format/pem
309 (let* ((rsa-params (make-rsa-parameters 1024))
311 (pkcs1-export-rsa-parameters rsa-params
312 x509-certificate-format/pem)))
313 (uniform-vector-write raw-data (open-output-file "some-file.pem")))
316 For an example of OpenPGP key import from a file, see @ref{Importing
317 OpenPGP Keys Guile Example}.
320 @node Input and Output
321 @section Input and Output
323 @findex set-session-transport-port!
324 @findex set-session-transport-fd!
326 The underlying transport of a TLS session can be any Scheme
327 input/output port (@pxref{Ports and File Descriptors,,, guile, The GNU
328 Guile Reference Manual}). This has to be specified using
329 @code{set-session-transport-port!}.
331 However, for better performance, a raw file descriptor can be
332 specified, using @code{set-session-transport-fd!}. For instance, if
333 the transport layer is a socket port over an OS-provided socket, you
334 can use the @code{port->fdes} or @code{fileno} procedure to obtain the
335 underlying file descriptor and pass it to
336 @code{set-session-transport-fd!} (@pxref{Ports and File Descriptors,
337 @code{port->fdes} and @code{fileno},, guile, The GNU Guile Reference
338 Manual}). This would work as follows:
341 (let ((socket (socket PF_INET SOCK_STREAM 0))
342 (session (make-session connection-end/client)))
345 ;; Establish a TCP connection...
348 ;; Use the file descriptor that underlies SOCKET.
349 (set-session-transport-fd! session (fileno socket)))
352 @findex session-record-port
354 Once a TLS session is established, data can be communicated through it
355 (i.e., @emph{via} the TLS record layer) using the port returned by
356 @code{session-record-port}:
359 (let ((session (make-session connection-end/client)))
362 ;; Initialize the various parameters of SESSION, set up
363 ;; a network connection, etc...
366 (let ((i/o (session-record-port session)))
367 (write "Hello peer!" i/o)
368 (let ((greetings (read i/o)))
372 (bye session close-request/rdwr))))
376 @findex record-receive!
378 A lower-level I/O API is provided by @code{record-send} and
379 @code{record-receive!} which take an SRFI-4 vector to represent the
380 data sent or received. While it might improve performance, it is much
381 less convenient than the above and should rarely be needed.
384 @node Exception Handling
385 @section Exception Handling
389 @cindex @code{gnutls-error}
390 @findex error->string
392 GnuTLS errors are implemented as Scheme exceptions (@pxref{Exceptions,
393 exceptions in Guile,, guile, The GNU Guile Reference Manual}). Each
394 time a GnuTLS function returns an error, an exception with key
395 @code{gnutls-error} is raised. The additional arguments that are
396 thrown include an error code and the name of the GnuTLS procedure that
397 raised the exception. The error code is pretty much like an enumerate
398 value: it is one of the @code{error/} variables exported by the
399 @code{(gnutls)} module (@pxref{Enumerates and Constants}). Exceptions
400 can be turned into error messages using the @code{error->string}
403 The following examples illustrates how GnuTLS exceptions can be
407 (let ((session (make-session connection-end/server)))
416 (lambda (key err function . currently-unused)
417 (format (current-error-port)
418 "a GnuTLS error was raised by `~a': ~a~%"
419 function (error->string err)))))
422 Again, error values can be compared using @code{eq?}:
425 ;; `gnutls-error' handler.
426 (lambda (key err function . currently-unused)
427 (if (eq? err error/fatal-alert-received)
428 (format (current-error-port)
429 "a fatal alert was caught!~%")
430 (format (current-error-port)
431 "something bad happened: ~a~%"
432 (error->string err))))
435 Note that the @code{catch} handler is currently passed only 3
436 arguments but future versions might provide it with additional
437 arguments. Thus, it must be prepared to handle more than 3 arguments,
441 @c *********************************************************************
443 @chapter Guile Examples
445 This chapter provides examples that illustrate common use cases.
448 * Anonymous Authentication Guile Example:: Simplest client and server.
449 * OpenPGP Authentication Guile Example:: Using OpenPGP-based authentication.
450 * Importing OpenPGP Keys Guile Example:: Importing keys from files.
453 @node Anonymous Authentication Guile Example
454 @section Anonymous Authentication Guile Example
456 @dfn{Anonymous authentication} is very easy to use. No certificates
457 are needed by the communicating parties. Yet, it allows them to
458 benefit from end-to-end encryption and integrity checks.
460 The client-side code would look like this (assuming @var{some-socket}
461 is bound to an open socket port):
463 @vindex connection-end/client
465 @vindex close-request/rdwr
470 (let ((client (make-session connection-end/client)))
471 ;; Use the default settings.
472 (set-session-default-priority! client)
474 ;; Don't use certificate-based authentication.
475 (set-session-certificate-type-priority! client '())
477 ;; Request the "anonymous Diffie-Hellman" key exchange method.
478 (set-session-kx-priority! client (list kx/anon-dh))
480 ;; Specify the underlying socket.
481 (set-session-transport-fd! client (fileno some-socket))
483 ;; Create anonymous credentials.
484 (set-session-credentials! client
485 (make-anonymous-client-credentials))
487 ;; Perform the TLS handshake with the server.
490 ;; Send data over the TLS record layer.
491 (write "hello, world!" (session-record-port client))
493 ;; Terminate the TLS session.
494 (bye client close-request/rdwr))
497 The corresponding server would look like this (again, assuming
498 @var{some-socket} is bound to a socket port):
500 @vindex connection-end/server
505 (let ((server (make-session connection-end/server)))
506 (set-session-default-priority! server)
507 (set-session-certificate-type-priority! server '())
508 (set-session-kx-priority! server (list kx/anon-dh))
510 ;; Specify the underlying transport socket.
511 (set-session-transport-fd! server (fileno some-socket))
513 ;; Create anonymous credentials.
514 (let ((cred (make-anonymous-server-credentials))
515 (dh-params (make-dh-parameters 1024)))
516 ;; Note: DH parameter generation can take some time.
517 (set-anonymous-server-dh-parameters! cred dh-params)
518 (set-session-credentials! server cred))
520 ;; Perform the TLS handshake with the client.
523 ;; Receive data over the TLS record layer.
524 (let ((message (read (session-record-port server))))
525 (format #t "received the following message: ~a~%"
528 (bye server close-request/rdwr)))
534 @node OpenPGP Authentication Guile Example
535 @section OpenPGP Authentication Guile Example
537 GnuTLS allows users to authenticate using OpenPGP certificates.
538 Using OpenPGP-based authentication is not more complicated than using
539 anonymous authentication. It requires a bit of extra work, though, to
540 import the OpenPGP public and private key of the client/server. Key
541 import is omitted here and is left as an exercise to the reader
542 (@pxref{Importing OpenPGP Keys Guile Example}).
544 Assuming @var{some-socket} is bound to an open socket port and
545 @var{pub} and @var{sec} are bound to the client's OpenPGP public and
546 secret key, respectively, client-side code would look like this:
548 @vindex certificate-type/openpgp
553 (define %certs (list certificate-type/openpgp))
555 (let ((client (make-session connection-end/client))
556 (cred (make-certificate-credentials)))
557 (set-session-default-priority! client)
559 ;; Choose OpenPGP certificates.
560 (set-session-certificate-type-priority! client %certs)
562 ;; Prepare appropriate client credentials.
563 (set-certificate-credentials-openpgp-keys! cred pub sec)
564 (set-session-credentials! client cred)
566 ;; Specify the underlying transport socket.
567 (set-session-transport-fd! client (fileno some-socket))
570 (write "hello, world!" (session-record-port client))
571 (bye client close-request/rdwr))
574 Similarly, server-side code would be along these lines:
579 (define %certs (list certificate-type/openpgp))
581 (let ((server (make-session connection-end/server))
582 (rsa (make-rsa-parameters 1024))
583 (dh (make-dh-parameters 1024)))
584 (set-session-default-priority! server)
586 ;; Choose OpenPGP certificates.
587 (set-session-certificate-type-priority! server %certs)
589 (let ((cred (make-certificate-credentials)))
590 ;; Prepare credentials with RSA and Diffie-Hellman parameters.
591 (set-certificate-credentials-dh-parameters! cred dh)
592 (set-certificate-credentials-rsa-export-parameters! cred rsa)
593 (set-certificate-credentials-openpgp-keys! cred pub sec)
594 (set-session-credentials! server cred))
596 (set-session-transport-fd! server (fileno some-socket))
599 (let ((msg (read (session-record-port server))))
600 (format #t "received: ~a~%" msg)
602 (bye server close-request/rdwr)))
605 In practice, generating RSA parameters (and Diffie-Hellman parameters)
606 can time a long time. Thus, you may want to generate them once and
607 store them in a file for future re-use (@pxref{Guile Reference,
608 @code{pkcs1-export-rsa-parameters} and @code{pkcs1-import-rsa-parameters}}).
610 @node Importing OpenPGP Keys Guile Example
611 @section Importing OpenPGP Keys Guile Example
613 The following example provides a simple way of importing
614 ``ASCII-armored'' OpenPGP keys from files, using the
615 @code{import-openpgp-certificate} and @code{import-openpgp-private-key}
618 @vindex openpgp-certificate-format/base64
619 @vindex openpgp-certificate-format/raw
622 (use-modules (srfi srfi-4)
625 (define (import-key-from-file import-proc file)
626 ;; Import OpenPGP key from FILE using IMPORT-PROC.
628 ;; Prepare a u8vector large enough to hold the raw
630 (let* ((size (stat:size (stat path)))
631 (raw (make-u8vector size)))
633 ;; Fill in the u8vector with the contents of FILE.
634 (uniform-vector-read! raw (open-input-file file))
636 ;; Pass the u8vector to the import procedure.
637 (import-proc raw openpgp-certificate-format/base64)))
640 (define (import-public-key-from-file file)
641 (import-key-from-file import-openpgp-certificate file))
643 (define (import-private-key-from-file file)
644 (import-key-from-file import-openpgp-private-key file))
647 The procedures @code{import-public-key-from-file} and
648 @code{import-private-key-from-file} can be passed a file name. They
649 return an OpenPGP public key and private key object, respectively
650 (@pxref{Guile Reference, OpenPGP key objects}).
653 @c *********************************************************************
654 @node Guile Reference
655 @chapter Guile Reference
657 This chapter lists the GnuTLS Scheme procedures exported by the
658 @code{(gnutls)} module (@pxref{The Guile module system,,, guile, The
659 GNU Guile Reference Manual}).
664 @c ispell-local-dictionary: "american"
667 @include cha-copying.texi