guile-gcrypt/guile-gcrypt.texi

\input texinfo
@c -*-texinfo-*-

@c %**start of header
@setfilename guile-gcrypt.info
@documentencoding UTF-8
@settitle Guile-Gcrypt Reference Manual
@c %**end of header

@include version.texi

@copying
Copyright @copyright{} 2018, 2019, 2020, 2021, 2022 Ludovic Courtès@*

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 copying

@dircategory The Algorithmic Language Scheme
@direntry
* Guile-Gcrypt: (guile-gcrypt).   Cryptographic library for Guile.
@end direntry

@titlepage
@title Guile-Gcrypt Reference Manual
@author The Guile-Gcrypt Developers

@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*

@insertcopying
@end titlepage

@contents

@c *********************************************************************
@node Top
@top Guile-Gcrypt

This manual documents Guile-Gcrypt, a Guile 2.x/3.x interface to the
GNU@tie{}Libgcrypt crytographic library, which is itself used by the
GNU@tie{}Privacy Guard (GPG).  @xref{Top,,, gcrypt, The Libgcrypt
Library}, for more information on Libgcrypt.

Actually this is very much a stub more than an actual manual.  Please
visit @uref{https://notabug.org/cwebber/guile-gcrypt} or email
@email{guile-user@@gnu.org} if you'd like to give a hand!

@menu
* Introduction::                      Getting started.
* Hash Functions::                    SHA1 and its friends.
* Message Authentication Codes::      MACs.
* Public-Key Cryptography::           Signing and encrypting.
* Random Numbers::                    Generating random numbers.
* Miscellany::                        Bonuses!

* GNU Free Documentation License::    The license of this manual.
* Index::                             Index of concepts and procedures.
@end menu

@node Introduction
@chapter Introduction

@cindex modules
Libgcrypt functionality is exposed in a set of Guile modules in the
@code{(gcrypt @dots{})} name space (@pxref{Modules,,, guile, The Guile
Reference Manual}).  Each module provides specific functionality from
Libgcrypt.  For example, the following code imports cryptographic hash
functions:

@lisp
(use-modules (gcrypt hash))
@end lisp

@findex string->canonical-sexp
Procedure names are not a direct mapping of the C function names;
instead, more ``Schemey'' names are chosen for your enjoyment.  For
example, the Libgcrypt's C function called @code{gcry_sexp_new} is
exposed in Scheme as the @code{string->canonical-sexp} procedure in the
@code{(gcrypt pk-crypto)}---more pleasant to the eye, no?

@cindex error handling
@cindex exceptions
When an error occurs, Guile-Gcrypt procedures raise an exception with
the key @code{'gcry-error} (@pxref{Exceptions,,, guile, The Guile
Reference Manual}).  Exceptions have two arguments: the name of the
procedure that raised it, and an @dfn{error number}.  The @code{(gcrypt
common)} modules provides procedures to interpret error numbers:
@code{error-source} and @code{error-string}.  Here's an example showing
how you could report Libgcrypt errors to the user:

@lisp
(catch 'gcry-error
  (lambda ()
    ;; Do something with Guile-Gcrypt...
    )
  (lambda (key proc err)
    (format (current-error-port) "error from '~a': ~a: ~a~%"
            proc (error-source err) (error-string err))))
@end lisp

These two procedures are detailed below.  You can also refer to one of
the @code{error/} constants exported by @code{(gcrypt common)} when
looking for a specific error:

@lisp
(catch 'gcry-error
  (lambda ()
    ;; Do something with Guile-Gcrypt...
    )
  (lambda (key proc err)
    (if (error-code=? err error/bad-signature)
        (format (current-error-port) "Uh oh, bad signature!\n")
        (format (current-error-port) @dots{}))))
@end lisp

@deffn {Scheme Procedure} error-source @var{err}
Return the error source (a string) for @var{err}, an error code as thrown
along with @code{gcry-error}.
@end deffn

@deffn {Scheme Procedure} error-string @var{err}
Return the error description (a string) for @var{err}, an error code as
thrown along with @code{gcry-error}.
@end deffn

@node Hash Functions
@chapter Hash Functions

The @code{(gcrypt hash)} module exports @dfn{cryptographic hash
functions} (@pxref{Hashing,,, gcrypt, The Libgcrypt Library}).
The procedures below all take a @dfn{hash algorithm} as an argument;
these are constructed using the @code{hash-algorithm} macro, as in this
example:

@example
(hash-algorithm sha1)
@end example

Alternately, you can look up a hash algorithm by name using the
@code{lookup-hash-algorithm} procedure:

@example
(lookup-hash-algorithm 'blake2b-512)
@end example

The following macros and procedures allow you to deal with algorithms.

@deffn {Scheme Syntax} hash-algorithm @var{id}
Return the hash algorithm for @var{id}, a lower-case identifier such as
@code{sha1}, @code{whirlpool}, or @code{blake2b-512}.  A syntax error
is raised when @var{id} doesn't match any know algorithm.
@end deffn

@deffn {Scheme Procedure} lookup-hash-algorithm @var{id}
Return the hash algorithm corresponding to @var{id}, a symbol, or
@code{#f} if @var{id} does not denote a known hash algorithm.
@end deffn

@deffn {Scheme Procedure} hash-algorithm-name @var{algorithm}
Return the name, a symbol, of @var{algorithm}, a value as returned by
@code{hash-algorithm}.
@end deffn

@deffn {Scheme Procedure} hash-size @var{algorithm}
Return the size in bytes of hashes produced by @var{algorithm}.
@end deffn

The procedures below offer several ways to compute a hash.

@deffn {Scheme Procedure} bytevector-hash @var{bv} @var{algorithm}
@deffnx {Scheme Procedure} crc32 @var{bv}
@deffnx {Scheme Procedure} sha1 @var{bv}
@deffnx {Scheme Procedure} sha256 @var{bv}
@deffnx {Scheme Procedure} sha512 @var{bv}
@deffnx {Scheme Procedure} sha3-512 @var{bv}
Return the hash @var{algorithm} of @var{bv} as a bytevector.

Shorthand procedures like @code{sha256} are available for all the
algorithms that are valid identifiers for @code{hash-algorithm} though
for brevity only a handful are listed here.
@end deffn

@deffn {Scheme Procedure} open-hash-port @var{algorithm}
@deffnx {Scheme Procedure} open-sha256-port
Return two values: an output port, and a thunk.  When the thunk is
called, it returns the hash (a bytevector) for @var{algorithm} of all
the data written to the output port.
@end deffn

@deffn {Scheme Procedure} port-hash @var{algorithm} @var{port}
@deffnx {Scheme Procedure} port-sha256 @var{port}
Return the @var{algorithm} hash (a bytevector) of all the data drained
from @var{port}.
@end deffn

@deffn {Scheme Procedure} file-hash @var{algorithm} @var{file}
@deffnx {Scheme Procedure} file-sha256 @var{file}
Return the @var{algorithm} hash (a bytevector) of @var{file}.
@end deffn

@deffn {Scheme Procedure} open-hash-port @var{algorithm} @var{port}
@deffnx {Scheme Procedure} open-sha256-port @var{port}
Return an input port that wraps @var{port} and a thunk to get the hash
of all the data read from @var{port}.  The thunk always returns the same
value.
@end deffn

@deffn {Scheme Procedure} open-hash-input-port @var{algorithm} @var{port}
@deffnx {Scheme Procedure} open-sha256-input-port @var{port}
Return an input port that wraps @var{port} and a thunk to get the hash
of all the data read from @var{port}.  The thunk always returns the same
value.
@end deffn

@node Message Authentication Codes
@chapter Message Authentication Codes

The @code{(gcrypt mac)} module provides procedures to deal with
@dfn{message authentication codes} or @dfn{MACs} (@pxref{Message
Authentication Codes,,, gcrypt, The Libgcrypt Library}).

@quotation Note
Guile-Gcrypt 0.1.0 provided this functionality in the @code{(gcrypt
hmac)} module.  This module is still provided for backward
compatibility, with the same interface as before, but it is deprecated
and will be removed in future versions.
@end quotation

Similar to how hash functions are handled (@pxref{Hash Functions}), the
@code{mac-algorithm} macro can be used to construct a MAC algorithm:

@example
(mac-algorithm hmac-sha3-512)
@end example

The following macros and procedures allow you to deal with algorithms.

@deffn {Scheme Syntax} mac-algorithm @var{id}
Return the MAC algorithm for @var{id}, a lower-case identifier such as
@code{sha256}.  A syntax error is raised when @var{id} doesn't match any
know algorithm.
@end deffn

@deffn {Scheme Procedure} lookup-mac-algorithm @var{id}
Return the MAC algorithm corresponding to @var{id}, a symbol, or
@code{#f} if @var{id} does not denote a known MAC algorithm.
@end deffn

@deffn {Scheme Procedure} mac-algorithm-name @var{algorithm}
Return the name, a symbol, of @var{algorithm}, a value as returned by
@code{mac-algorithm}.
@end deffn

@deffn {Scheme Procedure} mac-size @var{algorithm}
Return the size in bytes of MACs produced by @var{algorithm}.
@end deffn

@c TODO
@quotation Warning
This section is incomplete.
@end quotation


@node Public-Key Cryptography
@chapter Public-Key Cryptography

@cindex public-key cryptography
@cindex canonical S-expressions
Tools for @dfn{public-key cryptography} (@pxref{Public Key
cryptography,,, gcrypt, The Libgcrypt Library}) are provided by the
@code{(gcrypt pk-crypto)} module.

This module includes code to deal with @dfn{canonical S-expressions} (or
``sexps'') @uref{http://people.csail.mit.edu/rivest/Sexp.txt, as defined
by Rivest et al.}  They are used to specify public-key cryptography
parameters (@pxref{Used S-expressions,,, gcrypt, The Libgcrypt
Library}).  Naturally, there are procedures to convert a Guile sexp to a
Libgcrypt canonical sexp object and @i{vice versa}:

@deffn {Scheme Procedure} canonical-sexp->sexp @var{sexp}
Return a Scheme sexp corresponding to @var{sexp}.  This is particularly useful to
compare sexps (since Libgcrypt does not provide an @code{equal?} procedure), or to
use pattern matching.
@end deffn

@deffn {Scheme Procedure} sexp->canonical-sexp @var{sexp}
Return a canonical sexp equivalent to @var{sexp}, a Scheme sexp as returned by
@code{canonical-sexp->sexp}.
@end deffn

@deffn {Scheme Procedure} string->canonical-sexp @var{str}
Parse @var{str} and return the corresponding gcrypt s-expression.
@end deffn

@deffn {Scheme Procedure} canonical-sexp->string @var{sexp}
Return a textual representation of @var{sexp}.
@end deffn

@cindex key pair generation
@cindex generating key pairs
For example, here is how you would generate an Ed25519 key pair and
display its public key as a canonical sexp:

@findex generate-key
@findex find-sexp-token
@lisp
(use-modules (gcrypt pk-crypto))

(let* ((parameters (sexp->canonical-sexp
                     '(genkey
                        (ecdsa (curve Ed25519) (flags rfc6979)))))
       (pair       (generate-key parameters))
       (public     (find-sexp-token pair 'public-key)))
  (display (canonical-sexp->string public)))

@print{} 
(public-key 
 (ecc 
  (curve Ed25519)
  (q #141D9C42@dots{}CE853B#)
  )
 )
@end lisp

Notice that we did @emph{not} pass @code{pair} to
@code{canonical-sexp->sexp}: that would have worked, but the private key
would have been copied to memory managed by the garbage collector, which
is a security risk---Libgcrypt might have stored the private key in
so-called ``secure memory'' protected from swap, whereas Guile does no
such thing for its objects (@pxref{Initializing the library, secure
memory,, gcrypt, The Libgcrypt Library}).  Thus the above example uses
@code{find-sexp-token}, which accesses the canonical sexp directly, in
search for the @code{public-key} symbol.

Those canonical sexps are the basic way to communicate information to
public-key crytography routines.  The following procedures, for example,
are available to make and verify cryptographic signatures.

@deffn {Scheme Procedure} bytevector->hash-data @var{bv} @
  [@var{hash-algo} "sha256"] [#:key-type 'ecc]
Given @var{bv}, a bytevector containing a hash of type @var{hash-algo},
return an s-expression suitable for use as the @var{data} argument for
@code{sign} (see below).  @var{key-type} must be a symbol: @code{'dsa},
@code{'ecc}, or @code{'rsa}.
@end deffn

@deffn {Scheme Procedure} sign @var{data} @var{secret-key}
Sign @var{data}, a canonical s-expression representing a suitable hash,
with @var{secret-key} (a canonical s-expression whose car is
@code{private-key}.)  Note that @var{data} must be a @code{data}
s-expression, as returned by @code{bytevector->hash-data}
(@pxref{Cryptographic Functions,,, gcrypt, The Libgcrypt Libgcrypt}).
@end deffn

@deffn {Scheme Procedure} verify @var{signature} @var{data} @var{public-key}
Verify that @var{signature} is a signature of @var{data} with
@var{public-key}, all of which are gcrypt s-expressions; return
@code{#t} if the verification was successful, @code{#f} otherwise.
Raise an error if, for example, one of the given s-expressions is
invalid.
@end deffn

As an example, assuming @var{pair} is bound to the canonical sexp
representation of a key pair (as returned by @code{generate-key}), the
following snippet signs a string and verifies its signature:

@lisp
(let* ((secret (find-sexp-token pair 'private-key))
       (public (find-sexp-token pair 'public-key))
       (data   (bytevector->hash-data
                (sha256 (string->utf8 "Hello, world."))
                #:key-type (key-type public)))
       (sig    (sign data secret)))
  (verify sig data public))

@result{} #t
@end lisp

@xref{Used S-expressions,,, gcrypt, The Libgcrypt Library}, for more
information on the canonical sexps consumed and produced by public-key
cryptography functions.

@node Random Numbers
@chapter Random Numbers
The @code{(gcrypt random)} module provides tools to generate random
number of different quality levels (@pxref{Random Numbers,,, gcrypt, The
Libgcrypt Library}).

@node Miscellany
@chapter Miscellany

As a bonus, Guile-Gcrypt provides two useful modules:

@itemize
@item @code{(gcrypt base16)} provides procedures to encode and decode
hexadecimal strings;

@item @code{(gcrypt base64)} provides procedures to encode and decode
base64 strings as defined in @uref{https://tools.ietf.org/html/rfc4648,
RFC 4648}.
@end itemize

@c *********************************************************************
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@cindex license, GNU Free Documentation License
@include fdl-1.3.texi

@c *********************************************************************
@node Index
@unnumbered Index
@printindex cp
@syncodeindex tp fn
@syncodeindex vr fn
@printindex fn

@bye

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