guile-gcrypt.texi 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429
  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, 2019, 2020, 2021, 2022 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{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:: 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. You can also refer to one of
  88. the @code{error/} constants exported by @code{(gcrypt common)} when
  89. looking for a specific error:
  90. @lisp
  91. (catch 'gcry-error
  92. (lambda ()
  93. ;; Do something with Guile-Gcrypt...
  94. )
  95. (lambda (key proc err)
  96. (if (error-code=? err error/bad-signature)
  97. (format (current-error-port) "Uh oh, bad signature!\n")
  98. (format (current-error-port) @dots{}))))
  99. @end lisp
  100. @deffn {Scheme Procedure} error-source @var{err}
  101. Return the error source (a string) for @var{err}, an error code as thrown
  102. along with @code{gcry-error}.
  103. @end deffn
  104. @deffn {Scheme Procedure} error-string @var{err}
  105. Return the error description (a string) for @var{err}, an error code as
  106. thrown along with @code{gcry-error}.
  107. @end deffn
  108. @node Hash Functions
  109. @chapter Hash Functions
  110. The @code{(gcrypt hash)} module exports @dfn{cryptographic hash
  111. functions} (@pxref{Hashing,,, gcrypt, The Libgcrypt Library}).
  112. The procedures below all take a @dfn{hash algorithm} as an argument;
  113. these are constructed using the @code{hash-algorithm} macro, as in this
  114. example:
  115. @example
  116. (hash-algorithm sha1)
  117. @end example
  118. Alternately, you can look up a hash algorithm by name using the
  119. @code{lookup-hash-algorithm} procedure:
  120. @example
  121. (lookup-hash-algorithm 'blake2b-512)
  122. @end example
  123. The following macros and procedures allow you to deal with algorithms.
  124. @deffn {Scheme Syntax} hash-algorithm @var{id}
  125. Return the hash algorithm for @var{id}, a lower-case identifier such as
  126. @code{sha1}, @code{whirlpool}, or @code{blake2b-512}. A syntax error
  127. is raised when @var{id} doesn't match any know algorithm.
  128. @end deffn
  129. @deffn {Scheme Procedure} lookup-hash-algorithm @var{id}
  130. Return the hash algorithm corresponding to @var{id}, a symbol, or
  131. @code{#f} if @var{id} does not denote a known hash algorithm.
  132. @end deffn
  133. @deffn {Scheme Procedure} hash-algorithm-name @var{algorithm}
  134. Return the name, a symbol, of @var{algorithm}, a value as returned by
  135. @code{hash-algorithm}.
  136. @end deffn
  137. @deffn {Scheme Procedure} hash-size @var{algorithm}
  138. Return the size in bytes of hashes produced by @var{algorithm}.
  139. @end deffn
  140. The procedures below offer several ways to compute a hash.
  141. @deffn {Scheme Procedure} bytevector-hash @var{bv} @var{algorithm}
  142. @deffnx {Scheme Procedure} crc32 @var{bv}
  143. @deffnx {Scheme Procedure} sha1 @var{bv}
  144. @deffnx {Scheme Procedure} sha256 @var{bv}
  145. @deffnx {Scheme Procedure} sha512 @var{bv}
  146. @deffnx {Scheme Procedure} sha3-512 @var{bv}
  147. Return the hash @var{algorithm} of @var{bv} as a bytevector.
  148. Shorthand procedures like @code{sha256} are available for all the
  149. algorithms that are valid identifiers for @code{hash-algorithm} though
  150. for brevity only a handful are listed here.
  151. @end deffn
  152. @deffn {Scheme Procedure} open-hash-port @var{algorithm}
  153. @deffnx {Scheme Procedure} open-sha256-port
  154. Return two values: an output port, and a thunk. When the thunk is
  155. called, it returns the hash (a bytevector) for @var{algorithm} of all
  156. the data written to the output port.
  157. @end deffn
  158. @deffn {Scheme Procedure} port-hash @var{algorithm} @var{port}
  159. @deffnx {Scheme Procedure} port-sha256 @var{port}
  160. Return the @var{algorithm} hash (a bytevector) of all the data drained
  161. from @var{port}.
  162. @end deffn
  163. @deffn {Scheme Procedure} file-hash @var{algorithm} @var{file}
  164. @deffnx {Scheme Procedure} file-sha256 @var{file}
  165. Return the @var{algorithm} hash (a bytevector) of @var{file}.
  166. @end deffn
  167. @deffn {Scheme Procedure} open-hash-port @var{algorithm} @var{port}
  168. @deffnx {Scheme Procedure} open-sha256-port @var{port}
  169. Return an input port that wraps @var{port} and a thunk to get the hash
  170. of all the data read from @var{port}. The thunk always returns the same
  171. value.
  172. @end deffn
  173. @deffn {Scheme Procedure} open-hash-input-port @var{algorithm} @var{port}
  174. @deffnx {Scheme Procedure} open-sha256-input-port @var{port}
  175. Return an input port that wraps @var{port} and a thunk to get the hash
  176. of all the data read from @var{port}. The thunk always returns the same
  177. value.
  178. @end deffn
  179. @node Message Authentication Codes
  180. @chapter Message Authentication Codes
  181. The @code{(gcrypt mac)} module provides procedures to deal with
  182. @dfn{message authentication codes} or @dfn{MACs} (@pxref{Message
  183. Authentication Codes,,, gcrypt, The Libgcrypt Library}).
  184. @quotation Note
  185. Guile-Gcrypt 0.1.0 provided this functionality in the @code{(gcrypt
  186. hmac)} module. This module is still provided for backward
  187. compatibility, with the same interface as before, but it is deprecated
  188. and will be removed in future versions.
  189. @end quotation
  190. Similar to how hash functions are handled (@pxref{Hash Functions}), the
  191. @code{mac-algorithm} macro can be used to construct a MAC algorithm:
  192. @example
  193. (mac-algorithm hmac-sha3-512)
  194. @end example
  195. The following macros and procedures allow you to deal with algorithms.
  196. @deffn {Scheme Syntax} mac-algorithm @var{id}
  197. Return the MAC algorithm for @var{id}, a lower-case identifier such as
  198. @code{sha256}. A syntax error is raised when @var{id} doesn't match any
  199. know algorithm.
  200. @end deffn
  201. @deffn {Scheme Procedure} lookup-mac-algorithm @var{id}
  202. Return the MAC algorithm corresponding to @var{id}, a symbol, or
  203. @code{#f} if @var{id} does not denote a known MAC algorithm.
  204. @end deffn
  205. @deffn {Scheme Procedure} mac-algorithm-name @var{algorithm}
  206. Return the name, a symbol, of @var{algorithm}, a value as returned by
  207. @code{mac-algorithm}.
  208. @end deffn
  209. @deffn {Scheme Procedure} mac-size @var{algorithm}
  210. Return the size in bytes of MACs produced by @var{algorithm}.
  211. @end deffn
  212. @c TODO
  213. @quotation Warning
  214. This section is incomplete.
  215. @end quotation
  216. @node Public-Key Cryptography
  217. @chapter Public-Key Cryptography
  218. @cindex public-key cryptography
  219. @cindex canonical S-expressions
  220. Tools for @dfn{public-key cryptography} (@pxref{Public Key
  221. cryptography,,, gcrypt, The Libgcrypt Library}) are provided by the
  222. @code{(gcrypt pk-crypto)} module.
  223. This module includes code to deal with @dfn{canonical S-expressions} (or
  224. ``sexps'') @uref{http://people.csail.mit.edu/rivest/Sexp.txt, as defined
  225. by Rivest et al.} They are used to specify public-key cryptography
  226. parameters (@pxref{Used S-expressions,,, gcrypt, The Libgcrypt
  227. Library}). Naturally, there are procedures to convert a Guile sexp to a
  228. Libgcrypt canonical sexp object and @i{vice versa}:
  229. @deffn {Scheme Procedure} canonical-sexp->sexp @var{sexp}
  230. Return a Scheme sexp corresponding to @var{sexp}. This is particularly useful to
  231. compare sexps (since Libgcrypt does not provide an @code{equal?} procedure), or to
  232. use pattern matching.
  233. @end deffn
  234. @deffn {Scheme Procedure} sexp->canonical-sexp @var{sexp}
  235. Return a canonical sexp equivalent to @var{sexp}, a Scheme sexp as returned by
  236. @code{canonical-sexp->sexp}.
  237. @end deffn
  238. @deffn {Scheme Procedure} string->canonical-sexp @var{str}
  239. Parse @var{str} and return the corresponding gcrypt s-expression.
  240. @end deffn
  241. @deffn {Scheme Procedure} canonical-sexp->string @var{sexp}
  242. Return a textual representation of @var{sexp}.
  243. @end deffn
  244. @cindex key pair generation
  245. @cindex generating key pairs
  246. For example, here is how you would generate an Ed25519 key pair and
  247. display its public key as a canonical sexp:
  248. @findex generate-key
  249. @findex find-sexp-token
  250. @lisp
  251. (use-modules (gcrypt pk-crypto))
  252. (let* ((parameters (sexp->canonical-sexp
  253. '(genkey
  254. (ecdsa (curve Ed25519) (flags rfc6979)))))
  255. (pair (generate-key parameters))
  256. (public (find-sexp-token pair 'public-key)))
  257. (display (canonical-sexp->string public)))
  258. @print{}
  259. (public-key
  260. (ecc
  261. (curve Ed25519)
  262. (q #141D9C42@dots{}CE853B#)
  263. )
  264. )
  265. @end lisp
  266. Notice that we did @emph{not} pass @code{pair} to
  267. @code{canonical-sexp->sexp}: that would have worked, but the private key
  268. would have been copied to memory managed by the garbage collector, which
  269. is a security risk---Libgcrypt might have stored the private key in
  270. so-called ``secure memory'' protected from swap, whereas Guile does no
  271. such thing for its objects (@pxref{Initializing the library, secure
  272. memory,, gcrypt, The Libgcrypt Library}). Thus the above example uses
  273. @code{find-sexp-token}, which accesses the canonical sexp directly, in
  274. search for the @code{public-key} symbol.
  275. Those canonical sexps are the basic way to communicate information to
  276. public-key crytography routines. The following procedures, for example,
  277. are available to make and verify cryptographic signatures.
  278. @deffn {Scheme Procedure} bytevector->hash-data @var{bv} @
  279. [@var{hash-algo} "sha256"] [#:key-type 'ecc]
  280. Given @var{bv}, a bytevector containing a hash of type @var{hash-algo},
  281. return an s-expression suitable for use as the @var{data} argument for
  282. @code{sign} (see below). @var{key-type} must be a symbol: @code{'dsa},
  283. @code{'ecc}, or @code{'rsa}.
  284. @end deffn
  285. @deffn {Scheme Procedure} sign @var{data} @var{secret-key}
  286. Sign @var{data}, a canonical s-expression representing a suitable hash,
  287. with @var{secret-key} (a canonical s-expression whose car is
  288. @code{private-key}.) Note that @var{data} must be a @code{data}
  289. s-expression, as returned by @code{bytevector->hash-data}
  290. (@pxref{Cryptographic Functions,,, gcrypt, The Libgcrypt Libgcrypt}).
  291. @end deffn
  292. @deffn {Scheme Procedure} verify @var{signature} @var{data} @var{public-key}
  293. Verify that @var{signature} is a signature of @var{data} with
  294. @var{public-key}, all of which are gcrypt s-expressions; return
  295. @code{#t} if the verification was successful, @code{#f} otherwise.
  296. Raise an error if, for example, one of the given s-expressions is
  297. invalid.
  298. @end deffn
  299. As an example, assuming @var{pair} is bound to the canonical sexp
  300. representation of a key pair (as returned by @code{generate-key}), the
  301. following snippet signs a string and verifies its signature:
  302. @lisp
  303. (let* ((secret (find-sexp-token pair 'private-key))
  304. (public (find-sexp-token pair 'public-key))
  305. (data (bytevector->hash-data
  306. (sha256 (string->utf8 "Hello, world."))
  307. #:key-type (key-type public)))
  308. (sig (sign data secret)))
  309. (verify sig data public))
  310. @result{} #t
  311. @end lisp
  312. @xref{Used S-expressions,,, gcrypt, The Libgcrypt Library}, for more
  313. information on the canonical sexps consumed and produced by public-key
  314. cryptography functions.
  315. @node Random Numbers
  316. @chapter Random Numbers
  317. The @code{(gcrypt random)} module provides tools to generate random
  318. number of different quality levels (@pxref{Random Numbers,,, gcrypt, The
  319. Libgcrypt Library}).
  320. @node Miscellany
  321. @chapter Miscellany
  322. As a bonus, Guile-Gcrypt provides two useful modules:
  323. @itemize
  324. @item @code{(gcrypt base16)} provides procedures to encode and decode
  325. hexadecimal strings;
  326. @item @code{(gcrypt base64)} provides procedures to encode and decode
  327. base64 strings as defined in @uref{https://tools.ietf.org/html/rfc4648,
  328. RFC 4648}.
  329. @end itemize
  330. @c *********************************************************************
  331. @node GNU Free Documentation License
  332. @appendix GNU Free Documentation License
  333. @cindex license, GNU Free Documentation License
  334. @include fdl-1.3.texi
  335. @c *********************************************************************
  336. @node Index
  337. @unnumbered Index
  338. @printindex cp
  339. @syncodeindex tp fn
  340. @syncodeindex vr fn
  341. @printindex fn
  342. @bye
  343. @c Local Variables:
  344. @c ispell-local-dictionary: "american";
  345. @c End: