guile-gcrypt.texi 9.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276
  1. \input texinfo
  2. @c -*-texinfo-*-
  3. @c %**start of header
  4. @setfilename guile-gcrypt.info
  5. @documentencoding UTF-8
  6. @settitle Guile-Gcrypt Reference Manual
  7. @c %**end of header
  8. @include version.texi
  9. @copying
  10. Copyright @copyright{} 2018 Ludovic Courtès@*
  11. Permission is granted to copy, distribute and/or modify this document
  12. under the terms of the GNU Free Documentation License, Version 1.3 or
  13. any later version published by the Free Software Foundation; with no
  14. Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
  15. copy of the license is included in the section entitled ``GNU Free
  16. Documentation License''.
  17. @end copying
  18. @dircategory The Algorithmic Language Scheme
  19. @direntry
  20. * Guile-Gcrypt: (guile-gcrypt). Cryptographic library for Guile.
  21. @end direntry
  22. @titlepage
  23. @title Guile-Gcrypt Reference Manual
  24. @author The Guile-Gcrypt Developers
  25. @page
  26. @vskip 0pt plus 1filll
  27. Edition @value{EDITION} @*
  28. @value{UPDATED} @*
  29. @insertcopying
  30. @end titlepage
  31. @contents
  32. @c *********************************************************************
  33. @node Top
  34. @top Guile-Gcrypt
  35. This manual documents Guile-Gcrypt, a Guile 2.x interface to the
  36. GNU@tie{}Libgcrypt crytographic library, which is itself used by the
  37. GNU@tie{}Privacy Guard (GPG). @xref{Top,,, gcrypt, The Libgcrypt
  38. Library}, for more information on Libgcrypt.
  39. Actually this is very much a stub more than an actual manual. Please
  40. visit @uref{https://notabug.org/cwebber/guile-gcrypt} or email
  41. @email{guile-user@@gnu.org} if you'd like to give a hand!
  42. @menu
  43. * Introduction:: Getting started.
  44. * Hash Functions:: SHA1 and its friends.
  45. * Message Authentication Codes:: HMAC.
  46. * Public-Key Cryptography:: Signing and encrypting.
  47. * Random Numbers:: Generating random numbers.
  48. * Miscellany:: Bonuses!
  49. * GNU Free Documentation License:: The license of this manual.
  50. * Index:: Index of concepts and procedures.
  51. @end menu
  52. @node Introduction
  53. @chapter Introduction
  54. @cindex modules
  55. Libgcrypt functionality is exposed in a set of Guile modules in the
  56. @code{(gcrypt @dots{})} name space (@pxref{Modules,,, guile, The Guile
  57. Reference Manual}). Each module provides specific functionality from
  58. Libgcrypt. For example, the following code imports cryptographic hash
  59. functions:
  60. @lisp
  61. (use-modules (gcrypt hash))
  62. @end lisp
  63. @findex string->canonical-sexp
  64. Procedure names are not a direct mapping of the C function names;
  65. instead, more ``Schemey'' names are chosen for your enjoyment. For
  66. example, the Libgcrypt's C function called @code{gcry_sexp_new} is
  67. exposed in Scheme as the @code{string->canonical-sexp} procedure in the
  68. @code{(gcrypt pk-crypto)}---more pleasant to the eye, no?
  69. @cindex error handling
  70. @cindex exceptions
  71. When an error occurs, Guile-Gcrypt procedures raise an exception with
  72. the key @code{'gcry-error} (@pxref{Exceptions,,, guile, The Guile
  73. Reference Manual}). Exceptions have two arguments: the name of the
  74. procedure that raised it, and an @dfn{error number}. The @code{(gcrypt
  75. common)} modules provides procedures to interpret error numbers:
  76. @code{error-source} and @code{error-string}. Here's an example showing
  77. how you could report Libgcrypt errors to the user:
  78. @lisp
  79. (catch 'gcry-error
  80. (lambda ()
  81. ;; Do something with Guile-Gcrypt...
  82. )
  83. (lambda (key proc err)
  84. (format (current-error-port) "error from '~a': ~a: ~a~%"
  85. proc (error-source err) (error-string err))))
  86. @end lisp
  87. These two procedures are detailed below.
  88. @deffn {Scheme Procedure} error-source @var{err}
  89. Return the error source (a string) for @var{err}, an error code as thrown
  90. along with @code{gcry-error}.
  91. @end deffn
  92. @deffn {Scheme Procedure} error-string @var{err}
  93. Return the error description (a string) for @var{err}, an error code as
  94. thrown along with @code{gcry-error}.
  95. @end deffn
  96. @node Hash Functions
  97. @chapter Hash Functions
  98. The @code{(gcrypt hash)} module exports @dfn{cryptographic hash
  99. functions} (@pxref{Hashing,,, gcrypt, The Libgcrypt Library}).
  100. Currently only a small subset of hash functions is exposed by
  101. Guile-Gcrypt, listed here.
  102. @deffn {Scheme Procedure} sha1 @var{bv}
  103. @deffnx {Scheme Procedure} sha256 @var{bv}
  104. Return the SHA1 or SHA256 hash of the data in @var{bv}, a bytevector.
  105. The returned hash is itself represented as a bytevector
  106. (@pxref{Bytevectors,,, guile, The Guile Reference Manual}).
  107. @end deffn
  108. @deffn {Scheme Procedure} open-sha256-port
  109. Return two values: an output port, and a thunk. When the thunk is called,
  110. it returns the SHA256 hash (a bytevector) of all the data written to the
  111. output port.
  112. @end deffn
  113. @deffn {Scheme Procedure} port-sha256 @var{port}
  114. Return the SHA256 hash (a bytevector) of all the data drained from
  115. @var{port}.
  116. @end deffn
  117. @deffn {Scheme Procedure} file-sha256 @var{file}
  118. Return the SHA256 hash (a bytevector) of @var{file}.
  119. @end deffn
  120. @deffn {Scheme Procedure} open-sha256-input-port @var{port}
  121. Return an input port that wraps @var{port} and a thunk to get the hash of all the
  122. data read from @var{port}. The thunk always returns the same value.
  123. @end deffn
  124. @node Message Authentication Codes
  125. @chapter Message Authentication Codes
  126. The @code{(gcrypt hmac)} module provides procedures to deal with
  127. @dfn{message authentication codes} or @dfn{MACs} (@pxref{Message
  128. Authentication Codes,,, gcrypt, The Libgcrypt Library}).
  129. @node Public-Key Cryptography
  130. @chapter Public-Key Cryptography
  131. @cindex public-key cryptography
  132. @cindex canonical S-expressions
  133. Tools for @dfn{public-key cryptography} (@pxref{Public Key
  134. cryptography,,, gcrypt, The Libgcrypt Library}) are provided by the
  135. @code{(gcrypt pk-crypto)} module.
  136. This module includes code to deal with @dfn{canonical S-expressions} (or
  137. ``sexps'') @uref{http://people.csail.mit.edu/rivest/Sexp.txt, as defined
  138. by Rivest et al.} They are used to specify public-key cryptography
  139. parameters (@pxref{Used S-expressions,,, gcrypt, The Libgcrypt
  140. Library}). Naturally, there are procedures to convert a Guile sexp to a
  141. Libgcrypt canonical sexp object and @i{vice versa}:
  142. @deffn {Scheme Procedure} canonical-sexp->sexp @var{sexp}
  143. Return a Scheme sexp corresponding to @var{sexp}. This is particularly useful to
  144. compare sexps (since Libgcrypt does not provide an @code{equal?} procedure), or to
  145. use pattern matching.
  146. @end deffn
  147. @deffn {Scheme Procedure} sexp->canonical-sexp @var{sexp}
  148. Return a canonical sexp equivalent to @var{sexp}, a Scheme sexp as returned by
  149. @code{canonical-sexp->sexp}.
  150. @end deffn
  151. @deffn {Scheme Procedure} string->canonical-sexp @var{str}
  152. Parse @var{str} and return the corresponding gcrypt s-expression.
  153. @end deffn
  154. @deffn {Scheme Procedure} canonical-sexp->string @var{sexp}
  155. Return a textual representation of @var{sexp}.
  156. @end deffn
  157. @cindex key pair generation
  158. @cindex generating key pairs
  159. For example, here is how you would generate an Ed25519 key pair and
  160. display its public key as a canonical sexp:
  161. @findex generate-key
  162. @findex find-sexp-token
  163. @lisp
  164. (use-modules (gcrypt pk-crypto))
  165. (let* ((parameters (sexp->canonical-sexp
  166. '(genkey
  167. (ecdsa (curve Ed25519) (flags rfc6979)))))
  168. (pair (generate-key parameters))
  169. (public (find-sexp-token pair 'public-key)))
  170. (display (canonical-sexp->string public)))
  171. @print{}
  172. (public-key
  173. (ecc
  174. (curve Ed25519)
  175. (q #141D9C42@dots{}CE853B#)
  176. )
  177. )
  178. @end lisp
  179. Notice that we did @emph{not} pass @code{pair} to
  180. @code{canonical-sexp->sexp}: that would have worked, but the private key
  181. would have been copied to memory managed by the garbage collector, which
  182. is a security risk---Libgcrypt might have stored the private key in
  183. so-called ``secure memory'' protected from swap, whereas Guile does no
  184. such thing for its objects (@pxref{Initializing the library, secure
  185. memory,, gcrypt, The Libgcrypt Library}). Thus the above example uses
  186. @code{find-sexp-token}, which accesses the canonical sexp directly, in
  187. search for the @code{public-key} symbol.
  188. @xref{Used S-expressions,,, gcrypt, The Libgcrypt Library}, for more
  189. information on the canonical sexps consumed and produced by public-key
  190. cryptography functions.
  191. @node Random Numbers
  192. @chapter Random Numbers
  193. The @code{(gcrypt random)} module provides tools to generate random
  194. number of different quality levels (@pxref{Random Numbers,,, gcrypt, The
  195. Libgcrypt Library}).
  196. @node Miscellany
  197. @chapter Miscellany
  198. As a bonus, Guile-Gcrypt provides two useful modules:
  199. @itemize
  200. @item @code{(gcrypt base16)} provides procedures to encode and decode
  201. hexadecimal strings;
  202. @item @code{(gcrypt base64)} provides procedures to encode and decode
  203. base64 strings as defined in @uref{https://tools.ietf.org/html/rfc4648,
  204. RFC 4648}.
  205. @end itemize
  206. @c *********************************************************************
  207. @node GNU Free Documentation License
  208. @appendix GNU Free Documentation License
  209. @cindex license, GNU Free Documentation License
  210. @include fdl-1.3.texi
  211. @c *********************************************************************
  212. @node Index
  213. @unnumbered Index
  214. @printindex cp
  215. @syncodeindex tp fn
  216. @syncodeindex vr fn
  217. @printindex fn
  218. @bye
  219. @c Local Variables:
  220. @c ispell-local-dictionary: "american";
  221. @c End: