1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
|
\input texinfo @c -*-texinfo-*-
@comment %**start of header
@setfilename gnutls-guile.info
@include version-guile.texi
@settitle GnuTLS-Guile @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 GnuTLS.
Copyright @copyright{} 2001-2012, 2014, 2016 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
* GnuTLS-Guile: (gnutls-guile). GNU Transport Layer Security Library. Guile bindings.
@end direntry
@titlepage
@title GnuTLS-Guile
@subtitle Guile binding for GNU TLS
@subtitle for version @value{VERSION}, @value{UPDATED}
@sp 7
@image{gnutls-logo,6cm,6cm}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@macro xcite{ref}
[\ref\] (@pxref{Bibliography})
@end macro
@contents
@node Top
@top GnuTLS-Guile
@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 the @uref{http://www.gnu.org/software/guile/,
GNU Guile} Scheme programming interface to GnuTLS, which is distributed
as part of @uref{http://gnutls.org,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.
@c *********************************************************************
@node Guile Preparations
@chapter Guile Preparations
The GnuTLS Guile bindings are available for Guile's 2.0 stable series,
as well as the forthcoming 2.2 series and the legacy 1.8 series.
By default they are installed under the GnuTLS installation directory,
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
@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 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
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
* 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
@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
For an example of OpenPGP key import from a file, see @ref{Importing
OpenPGP Keys Guile 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 <http://bugs.gnu.org/22966> 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.
* OpenPGP Authentication Guile Example:: Using OpenPGP-based authentication.
* Importing OpenPGP Keys Guile Example:: Importing keys from files.
@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
;; 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
@section 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
(@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))
(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 Diffie-Hellman parameters.
(set-certificate-credentials-dh-parameters! cred dh)
(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
@node Importing OpenPGP Keys Guile Example
@section 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.
@vindex openpgp-certificate-format/base64
@vindex openpgp-certificate-format/raw
@example
(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))
@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{Guile Reference, OpenPGP key objects}).
@c *********************************************************************
@node Guile Reference
@chapter Guile Reference
This chapter lists the GnuTLS Scheme procedures exported by the
@code{(gnutls)} module (@pxref{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
|