guile-gcrypt.texi 12 KB

  1. \input texinfo
  2. @c -*-texinfo-*-
  3. @c %**start of header
  4. @setfilename
  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, 2019 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/3.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{} or email
  41. @email{} 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:: MACs.
  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. The procedures below all take a @dfn{hash algorithm} as an argument;
  101. these are constructed using the @code{hash-algorithm} macro, as in this
  102. example:
  103. @example
  104. (hash-algorithm sha1)
  105. @end example
  106. Alternately, you can look up a hash algorithm by name using the
  107. @code{lookup-hash-algorithm} procedure:
  108. @example
  109. (lookup-hash-algorithm 'blake2b-512)
  110. @end example
  111. The following macros and procedures allow you to deal with algorithms.
  112. @deffn {Scheme Syntax} hash-algorithm @var{id}
  113. Return the hash algorithm for @var{id}, a lower-case identifier such as
  114. @code{sha1}, @code{whirlpool}, or @code{blake2b-512}. A syntax error
  115. is raised when @var{id} doesn't match any know algorithm.
  116. @end deffn
  117. @deffn {Scheme Procedure} lookup-hash-algorithm @var{id}
  118. Return the hash algorithm corresponding to @var{id}, a symbol, or
  119. @code{#f} if @var{id} does not denote a known hash algorithm.
  120. @end deffn
  121. @deffn {Scheme Procedure} hash-size @var{algorithm}
  122. Return the size in bytes of hashes produced by @var{algorithm}.
  123. @end deffn
  124. The procedures below offer several ways to compute a hash.
  125. @deffn {Scheme Procedure} bytevector-hash @var{bv} @var{algorithm}
  126. @deffnx {Scheme Procedure} sha1 @var{bv}
  127. @deffnx {Scheme Procedure} sha256 @var{bv}
  128. Return the hash @var{algorithm} of @var{bv} as a bytevector.
  129. @end deffn
  130. @deffn {Scheme Procedure} open-hash-port @var{algorithm}
  131. @deffnx {Scheme Procedure} open-sha256-port
  132. Return two values: an output port, and a thunk. When the thunk is
  133. called, it returns the hash (a bytevector) for @var{algorithm} of all
  134. the data written to the output port.
  135. @end deffn
  136. @deffn {Scheme Procedure} port-hash @var{algorithm}
  137. @deffnx {Scheme Procedure} port-sha256
  138. Return the @var{algorithm} hash (a bytevector) of all the data drained
  139. from @var{port}.
  140. @end deffn
  141. @deffn {Scheme Procedure} file-hash @var{algorithm} @var{file}
  142. @deffnx {Scheme Procedure} file-sha256 @var{file}
  143. Return the @var{algorithm} hash (a bytevector) of @var{file}.
  144. @end deffn
  145. @deffn {Scheme Procedure} open-hash-port @var{algorithm} @var{port}
  146. @deffnx {Scheme Procedure} open-sha256-port @var{port}
  147. Return an input port that wraps @var{port} and a thunk to get the hash
  148. of all the data read from @var{port}. The thunk always returns the same
  149. value.
  150. @end deffn
  151. @deffn {Scheme Procedure} open-hash-input-port @var{algorithm} @var{port}
  152. @deffnx {Scheme Procedure} open-sha256-input-port @var{port}
  153. Return an input port that wraps @var{port} and a thunk to get the hash
  154. of all the data read from @var{port}. The thunk always returns the same
  155. value.
  156. @end deffn
  157. @node Message Authentication Codes
  158. @chapter Message Authentication Codes
  159. The @code{(gcrypt mac)} module provides procedures to deal with
  160. @dfn{message authentication codes} or @dfn{MACs} (@pxref{Message
  161. Authentication Codes,,, gcrypt, The Libgcrypt Library}).
  162. @quotation Note
  163. Guile-Gcrypt 0.1.0 provided this functionality in the @code{(gcrypt
  164. hmac)} module. This module is still provided for backward
  165. compatibility, with the same interface as before, but it is deprecated
  166. and will be removed in future versions.
  167. @end quotation
  168. Similar to how hash functions are handled (@pxref{Hash Functions}), the
  169. @code{mac-algorithm} macro can be used to construct a MAC algorithm:
  170. @example
  171. (mac-algorithm hmac-sha3-512)
  172. @end example
  173. The following macros and procedures allow you to deal with algorithms.
  174. @deffn {Scheme Syntax} mac-algorithm @var{id}
  175. Return the MAC algorithm for @var{id}, a lower-case identifier such as
  176. @code{sha256}. A syntax error is raised when @var{id} doesn't match any
  177. know algorithm.
  178. @end deffn
  179. @deffn {Scheme Procedure} lookup-mac-algorithm @var{id}
  180. Return the MAC algorithm corresponding to @var{id}, a symbol, or
  181. @code{#f} if @var{id} does not denote a known MAC algorithm.
  182. @end deffn
  183. @deffn {Scheme Procedure} mac-size @var{algorithm}
  184. Return the size in bytes of MACs produced by @var{algorithm}.
  185. @end deffn
  186. @c TODO
  187. @quotation Warning
  188. This section is incomplete.
  189. @end quotation
  190. @node Public-Key Cryptography
  191. @chapter Public-Key Cryptography
  192. @cindex public-key cryptography
  193. @cindex canonical S-expressions
  194. Tools for @dfn{public-key cryptography} (@pxref{Public Key
  195. cryptography,,, gcrypt, The Libgcrypt Library}) are provided by the
  196. @code{(gcrypt pk-crypto)} module.
  197. This module includes code to deal with @dfn{canonical S-expressions} (or
  198. ``sexps'') @uref{, as defined
  199. by Rivest et al.} They are used to specify public-key cryptography
  200. parameters (@pxref{Used S-expressions,,, gcrypt, The Libgcrypt
  201. Library}). Naturally, there are procedures to convert a Guile sexp to a
  202. Libgcrypt canonical sexp object and @i{vice versa}:
  203. @deffn {Scheme Procedure} canonical-sexp->sexp @var{sexp}
  204. Return a Scheme sexp corresponding to @var{sexp}. This is particularly useful to
  205. compare sexps (since Libgcrypt does not provide an @code{equal?} procedure), or to
  206. use pattern matching.
  207. @end deffn
  208. @deffn {Scheme Procedure} sexp->canonical-sexp @var{sexp}
  209. Return a canonical sexp equivalent to @var{sexp}, a Scheme sexp as returned by
  210. @code{canonical-sexp->sexp}.
  211. @end deffn
  212. @deffn {Scheme Procedure} string->canonical-sexp @var{str}
  213. Parse @var{str} and return the corresponding gcrypt s-expression.
  214. @end deffn
  215. @deffn {Scheme Procedure} canonical-sexp->string @var{sexp}
  216. Return a textual representation of @var{sexp}.
  217. @end deffn
  218. @cindex key pair generation
  219. @cindex generating key pairs
  220. For example, here is how you would generate an Ed25519 key pair and
  221. display its public key as a canonical sexp:
  222. @findex generate-key
  223. @findex find-sexp-token
  224. @lisp
  225. (use-modules (gcrypt pk-crypto))
  226. (let* ((parameters (sexp->canonical-sexp
  227. '(genkey
  228. (ecdsa (curve Ed25519) (flags rfc6979)))))
  229. (pair (generate-key parameters))
  230. (public (find-sexp-token pair 'public-key)))
  231. (display (canonical-sexp->string public)))
  232. @print{}
  233. (public-key
  234. (ecc
  235. (curve Ed25519)
  236. (q #141D9C42@dots{}CE853B#)
  237. )
  238. )
  239. @end lisp
  240. Notice that we did @emph{not} pass @code{pair} to
  241. @code{canonical-sexp->sexp}: that would have worked, but the private key
  242. would have been copied to memory managed by the garbage collector, which
  243. is a security risk---Libgcrypt might have stored the private key in
  244. so-called ``secure memory'' protected from swap, whereas Guile does no
  245. such thing for its objects (@pxref{Initializing the library, secure
  246. memory,, gcrypt, The Libgcrypt Library}). Thus the above example uses
  247. @code{find-sexp-token}, which accesses the canonical sexp directly, in
  248. search for the @code{public-key} symbol.
  249. @xref{Used S-expressions,,, gcrypt, The Libgcrypt Library}, for more
  250. information on the canonical sexps consumed and produced by public-key
  251. cryptography functions.
  252. @node Random Numbers
  253. @chapter Random Numbers
  254. The @code{(gcrypt random)} module provides tools to generate random
  255. number of different quality levels (@pxref{Random Numbers,,, gcrypt, The
  256. Libgcrypt Library}).
  257. @node Miscellany
  258. @chapter Miscellany
  259. As a bonus, Guile-Gcrypt provides two useful modules:
  260. @itemize
  261. @item @code{(gcrypt base16)} provides procedures to encode and decode
  262. hexadecimal strings;
  263. @item @code{(gcrypt base64)} provides procedures to encode and decode
  264. base64 strings as defined in @uref{,
  265. RFC 4648}.
  266. @end itemize
  267. @c *********************************************************************
  268. @node GNU Free Documentation License
  269. @appendix GNU Free Documentation License
  270. @cindex license, GNU Free Documentation License
  271. @include fdl-1.3.texi
  272. @c *********************************************************************
  273. @node Index
  274. @unnumbered Index
  275. @printindex cp
  276. @syncodeindex tp fn
  277. @syncodeindex vr fn
  278. @printindex fn
  279. @bye
  280. @c Local Variables:
  281. @c ispell-local-dictionary: "american";
  282. @c End: