Debian Codegraph @

doc/ironclad.html

raw
1 <!DOCTYPE html>
2 <html lang="en">
3 <head>
4 <!-- 2024-08-20 mar. 10:03 -->
5 <meta charset="utf-8" />
6 <meta name="viewport" content="width=device-width, initial-scale=1" />
7 <title>Ironclad</title>
8 <meta name="author" content="The Ironclad developers" />
9 <meta name="generator" content="Org Mode" />
10 <style type="text/css">
11 body { margin: 1em 5% 1em 5%; }
12 p { margin-top: 0.5em; margin-bottom: 0.5em; }
13 pre { padding: 0; margin: 0; }
14 h1, h2 { border-bottom: 2px solid #449977; }
15 h1, h2, h3, h4, h5, h6 { font-family: sans-serif; line-height: 1.3; }
16 a:link { color: #449977; }
17 a:visited { color: purple; }
18 a { text-decoration: none; padding: 1px 2px; }
19 a:hover { text-decoration: none; padding: 1px; border: 1px solid #000000; }
20 pre.src-lisp { margin-right: 10%; margin-top: 1.5em; margin-bottom: 1.5em; border: 1px solid #449977; background: #eeeeee; padding: 1em; }
21 pre.example { margin-right: 10%; margin-top: 1.5em; margin-bottom: 1.5em; border: 1px solid black; padding: 1em; }
22 .underline { margin-top: 1.5em; margin-bottom: 1.5em; font-family: sans-serif; font-size: 1.1em; font-weight: bold; text-decoration: underline; }
23 </style>
24 </head>
25 <body>
26 <div id="content" class="content">
27 <h1 class="title">Ironclad</h1>
28
29 <div id="orge8f24ca" class="figure">
30 <p><a href="https://github.com/sharplispers/ironclad/workflows/CI/badge.svg?branch=master" style="width: 0; height: 0; padding: 0; margin: 0; border: 0; overflow: hidden;"><img src="https://github.com/sharplispers/ironclad/workflows/CI/badge.svg?branch=master" alt="badge.svg?branch=master" style="width: 0; height: 0; padding: 0; margin: 0; border: 0; overflow: hidden;"></a>
31 </p>
32 </div>
33
34 <p>
35 Ironclad is a cryptography library written entirely in Common Lisp. It
36 includes support for several popular <a href="#ciphers">ciphers</a>, <a href="#digests">digests</a>, <a href="#message-authentication-codes">MACs</a> and
37 <a href="#public-key-cryptography">public key cryptography</a> algorithms. For several implementations that
38 support Gray streams, support is included for convenient <a href="#gray-streams">stream wrappers</a>.
39 </p>
40
41 <p>
42 Most of the algorithms were written with efficiency for specific
43 Common Lisp implementations in mind, although portable code is
44 provided as an alternative in nearly all instances. The framework
45 should be flexible enough to accommodate implementation-specific
46 optimizations when possible.
47 </p>
48
49 <p>
50 Test vectors for many of the algorithms are included to provide
51 a level of confidence in the correctness of the implementations.
52 </p>
53
54 <div id="table-of-contents" role="doc-toc">
55 <h2>Table of Contents</h2>
56 <div id="text-table-of-contents" role="doc-toc">
57 <ul>
58 <li><a href="#warning">Warnings</a></li>
59 <li><a href="#installation">Installation</a></li>
60 <li><a href="#license">License</a></li>
61 <li><a href="#ciphers">Ciphers</a></li>
62 <li><a href="#digests">Digests</a></li>
63 <li><a href="#message-authentication-codes">Message authentication codes</a></li>
64 <li><a href="#authenticated-encryption">Authenticated encryption</a></li>
65 <li><a href="#key-derivation-functions">Key derivation functions</a></li>
66 <li><a href="#public-key-cryptography">Public key cryptography</a></li>
67 <li><a href="#pseudo-random-number-generation">Pseudo-random number generation</a></li>
68 <li><a href="#gray-streams">Gray streams</a></li>
69 <li><a href="#utility-functions">Utility functions</a></li>
70 <li><a href="#conditions">Conditions</a></li>
71 <li><a href="#subsystems">Subsystems (experimental)</a></li>
72 </ul>
73 </div>
74 </div>
75 <div id="outline-container-warning" class="outline-2">
76 <h2 id="warning">Warnings</h2>
77 <div class="outline-text-2" id="text-warning">
78 <p>
79 <b>Ironclad should not be considered safe against side channel attacks.</b>
80 </p>
81
82 <p>
83 Some algorithms can be safe against side channel attacks on some
84 architectures using some Common Lisp implementations, but in the
85 general case it can't be guaranteed. This is due to the fact that
86 integers and arithmetic functions of Common Lisp implementations are
87 usually not safe against side channel attacks.
88 </p>
89
90
91 <p>
92 <b>Ironclad's digest, MAC and cipher objects should not be considered thread
93 safe.</b>
94 </p>
95
96 <p>
97 Creating a digest, a MAC or a cipher object and using it in several threads at
98 the same time can lead to an undefined result. If you need to do that, you must
99 put locks in your application where necessary.
100 </p>
101
102
103 <p>
104 <b>Ironclad's pseudo random number generation should only be considered thread
105 safe with bordeaux-threads.</b>
106 </p>
107
108 <p>
109 If you have a multi-threaded application in which you want to use functions
110 requiring some random numbers (key derivation, key generation, public key
111 encryption, signature, etc.) in several threads, each of these threads must have
112 its own PRNG, or they might generate the same "random" numbers. If the threads
113 are created using the <b>bordeaux-threads</b> library (or by a library using
114 <b>bordeaux-threads</b>, like <b>lparallel</b>), this is done automatically. However, if
115 you are using the threading functions of your Common Lisp implementation
116 directly, you have to bind the <code>*prng*</code> special variable to a new PRNG in each
117 thread. There is an example showing how it can be done in the section about
118 <a href="#org4ee888f">make-prng</a>.
119 </p>
120 </div>
121 </div>
122 <div id="outline-container-installation" class="outline-2">
123 <h2 id="installation">Installation</h2>
124 <div class="outline-text-2" id="text-installation">
125 <p>
126 The current version of Ironclad is 0.61. It can be downloaded
127 at <a href="https://github.com/sharplispers/ironclad/archive/v0.61.tar.gz">https://github.com/sharplispers/ironclad/archive/v0.61.tar.gz</a>.
128 If you are feeling adventurous, you can download a bleeding-edge version
129 at <a href="https://github.com/sharplispers/ironclad">https://github.com/sharplispers/ironclad</a>.
130 </p>
131
132 <p>
133 It comes with an ASDF system definition, so <code>(asdf:load-system "ironclad")</code>
134 should be all that you need to get started. The testsuite can be run
135 by substituting <code>asdf:test-system</code> for <code>asdf:load-system</code> in the form above.
136 </p>
137
138 <p>
139 If you are using <a href="https://www.quicklisp.org">Quicklisp</a> to manage your libraries, just use
140 <code>(ql:quickload "ironclad")</code>.
141 </p>
142
143 <p>
144 When Ironclad is loaded, its functions are in the <code>ironclad</code> package (e.g.
145 <code>(ironclad:make-cipher ...)</code>). If you prefer, you can also use the <code>crypto</code>
146 nickname (e.g. <code>(crypto:make-cipher ...)</code>).
147 </p>
148
149 <p>
150 Ironclad has been tested in the following implementations:
151 </p>
152 <ul class="org-ul">
153 <li>SBCL x86/linux, x86-64/linux (primary development platforms)</li>
154 <li>SBCL x86-64/solaris, x86/darwin</li>
155 <li>CMUCL x86/linux</li>
156 <li>ABCL with Sun's 1.5.0 JVM</li>
157 <li>Lispworks 5.0.1 x86/linux</li>
158 <li>Lispworks 5.1.2 x86-64/darwin x86/windows</li>
159 <li>Allegro 8.0 x86/linux</li>
160 <li>Allegro 8.1 x86/linux, x86-64/linux, sparc/solaris</li>
161 <li>CLISP 2.41 x86/linux, x86/cygwin</li>
162 <li>Clozure Common Lisp 1.11 x86-64/Linux</li>
163 <li>Clozure Common Lisp 1.10 x86-64/darwin</li>
164 <li>ECL 16.1.3 x86-64/linux</li>
165 </ul>
166
167 <p>
168 All included tests should pass successfully. If you use a platform not
169 listed above, please send your platform information so that it can be
170 added to the above list. If the tests do not all pass, you have found
171 a bug; please report it.
172 </p>
173
174 <p>
175 By default, Ironclad uses some implementation dependent low-level code to make
176 some functions run much faster (currently, some assembly for SBCL and CCL, some
177 C code for ECL). If for some reason you want to disable these optimisations and
178 use the generic Lisp code, it can be achieved by commenting out the
179 <code>(pushnew :ironclad-assembly *features*)</code> line in the <i>src/package.lisp</i> file.
180 </p>
181 </div>
182 </div>
183 <div id="outline-container-license" class="outline-2">
184 <h2 id="license">License</h2>
185 <div class="outline-text-2" id="text-license">
186 <p>
187 Ironclad is released under a MIT-like license; you can do pretty much
188 anything you want to with the code except claim that you wrote it.
189 </p>
190 </div>
191 </div>
192 <div id="outline-container-ciphers" class="outline-2">
193 <h2 id="ciphers">Ciphers</h2>
194 <div class="outline-text-2" id="text-ciphers">
195 <div class="org-src-container">
196 <pre class="src src-lisp" id="orga194874">(make-cipher name <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> key mode initialization-vector padding tweak) =&gt; cipher
197 </pre>
198 </div>
199
200 <p>
201 Return a cipher object suitable for use for both encryption and decryption.
202 </p>
203
204 <p>
205 <i>name</i> denotes the encryption algorithm to use. <a href="#orgd644b3b">list-all-ciphers</a> will tell you
206 the names of all supported ciphers. They are:
207 </p>
208 <ul class="org-ul">
209 <li>3des</li>
210 <li>aes</li>
211 <li>arcfour (rc4)</li>
212 <li>aria</li>
213 <li>blowfish</li>
214 <li>camellia</li>
215 <li>cast5</li>
216 <li>chacha</li>
217 <li>chacha/12</li>
218 <li>chacha/8</li>
219 <li>des</li>
220 <li>idea</li>
221 <li>kalyna128</li>
222 <li>kalyna256</li>
223 <li>kalyna512</li>
224 <li>kuznyechik</li>
225 <li>misty1</li>
226 <li>rc2</li>
227 <li>rc5</li>
228 <li>rc6</li>
229 <li>salsa20</li>
230 <li>salsa20/12</li>
231 <li>salsa20/8</li>
232 <li>seed</li>
233 <li>serpent</li>
234 <li>sm4</li>
235 <li>sosemanuk</li>
236 <li>square</li>
237 <li>tea</li>
238 <li>threefish1024</li>
239 <li>threefish256</li>
240 <li>threefish512</li>
241 <li>twofish</li>
242 <li>xchacha</li>
243 <li>xchacha/12</li>
244 <li>xchacha/8</li>
245 <li>xor (not a real cipher, use only for testing)</li>
246 <li>xsalsa20</li>
247 <li>xsalsa20/12</li>
248 <li>xsalsa20/8</li>
249 <li>xtea</li>
250 </ul>
251
252 <p>
253 <i>name</i> can be a symbol in the <code>keyword</code> package or in the <code>ironclad</code> package;
254 <code>:aes</code> for AES, <code>ironclad:arcfour</code> for RC4, and so forth.
255 </p>
256
257 <p>
258 <i>mode</i> describes the mode of operation for the cipher. Stream ciphers
259 such as Arcfour can operate in only one mode, <code>stream</code>. Block ciphers
260 such as AES and DES can operate in several different modes:
261 </p>
262 <ul class="org-ul">
263 <li>ecb</li>
264 <li>cbc</li>
265 <li>ofb</li>
266 <li>cfb (note that Ironclad's CFB mode is <i>n</i>-bit CFB, where <i>n</i> is the <a href="#org32e5f3d">block-length</a> of the cipher)</li>
267 <li>cfb8 (this seems to be the mode other crypto packages call CFB)</li>
268 <li>ctr</li>
269 </ul>
270
271 <p>
272 <i>mode</i> should be a symbol in the <code>keyword</code> or <code>ironclad</code> packages;
273 <code>:stream</code>, <code>ironclad:ofb</code>, and so forth. An error will be signaled if
274 <i>mode</i> is not appropriate for the cipher <i>name</i>.
275 </p>
276
277 <p>
278 <i>initialization-vector</i> (IV) should be supplied only if <i>mode</i> requires one.
279 <i>initialization-vector</i> should be a <code>(simple-array (unsigned-byte 8) (*))</code>.
280 The supplied IV should be the same length as the <a href="#org32e5f3d">block-length</a> of <i>name</i>.
281 The Chacha and Salsa20 stream ciphers also use an initialization
282 vector (nonce). It should be 8 or 12 bytes long for Chacha, 8 bytes long
283 for Salsa20, and 24 bytes long for XChacha and XSalsa20.
284 </p>
285
286 <p>
287 <i>key</i> is, of course, the key for the cipher.
288 <i>key</i> should be a <code>(simple-array (unsigned-byte 8) (*))</code>.
289 </p>
290
291 <p>
292 If <i>padding</i> is supplied, the specified padding method will be used by <a href="#orga0c509f">encrypt</a>
293 and <a href="#org8d3dffc">decrypt</a> to handle short blocks when the <code>:handle-final-block</code> argument is
294 supplied. <i>padding</i> will only be used if the mode is ECB or CBC. The possible
295 values for <i>padding</i> are <code>:pkcs7</code>, <code>:ansi-x923</code> and <code>:iso-7816-4</code>.
296 </p>
297
298 <p>
299 If the cipher can use a tweak (e.g. threefish), it can be specified
300 with the <i>tweak</i> key parameter.
301 </p>
302
303
304 <div class="org-src-container">
305 <pre class="src src-lisp" id="orga0c509f">(encrypt cipher plaintext ciphertext <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> plaintext-start plaintext-end ciphertext-start handle-final-block) =&gt; n-bytes-consumed, n-bytes-produced
306 </pre>
307 </div>
308
309 <p>
310 Encrypts data according to <i>cipher</i> from <i>plaintext</i> starting at
311 <i>plaintext-start</i> and continuing until <i>plaintext-end</i>. The encrypted
312 data is placed in <i>ciphertext</i> starting at <i>ciphertext-start</i>.
313 </p>
314
315
316 <div class="org-src-container">
317 <pre class="src src-lisp" id="org8d3dffc">(decrypt cipher ciphertext plaintext <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> ciphertext-start ciphertext-end plaintext-start handle-final-block) =&gt; n-bytes-consumed, n-bytes-produced
318 </pre>
319 </div>
320
321 <p>
322 Decrypts data according to <i>cipher</i> from <i>ciphertext</i> starting at
323 <i>ciphertext-start</i> and continuing until <i>ciphertext-end</i>. The decrypted
324 data is placed in <i>plaintext</i> starting at <i>plaintext-start</i>.
325 </p>
326
327
328 <div class="org-src-container">
329 <pre class="src src-lisp" id="org1eeb930">(encrypt-in-place cipher text <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end) =&gt; n-bytes-consumed, n-bytes-produced
330 </pre>
331 </div>
332 <div class="org-src-container">
333 <pre class="src src-lisp" id="orgb24e31a">(decrypt-in-place cipher text <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end) =&gt; n-bytes-consumed, n-bytes-produced
334 </pre>
335 </div>
336
337 <p>
338 Encrypts or decrypts data in <i>text</i> between <i>start</i> and <i>end</i> "in-place"
339 according to <i>cipher</i>. These functions are shorthand for:
340 </p>
341 <pre class="example" id="org63313bc">
342 (encrypt cipher text text :plaintext-start start :plaintext-end end :ciphertext-start start)
343 (decrypt cipher text text :ciphertext-start start :ciphertext-end end :plaintext-start start)
344 </pre>
345
346 <p>
347 <span class="underline">Note:</span> <a href="#org1eeb930">encrypt-in-place</a> and <a href="#orgb24e31a">decrypt-in-place</a> do not support
348 a <i>handle-final-block</i> parameter as <a href="#orga0c509f">encrypt</a> and <a href="#org8d3dffc">decrypt</a> do. If you
349 need the functionality that <i>handle-final-block</i> provides, then you
350 need to use <a href="#orga0c509f">encrypt</a> and <a href="#org8d3dffc">decrypt</a>.
351 </p>
352
353 <p>
354 <span class="underline">Note:</span> <i>n-bytes-consumed</i> and <i>n-bytes-produced</i> may not always be
355 equal to the length of the data specified in the call to
356 <a href="#org1eeb930">encrypt-in-place</a> or <a href="#orgb24e31a">decrypt-in-place</a>. This subtlely is also present in
357 <a href="#orga0c509f">encrypt</a> or <a href="#org8d3dffc">decrypt</a>.
358 </p>
359
360
361 <div class="org-src-container">
362 <pre class="src src-lisp">(encrypt-message cipher message <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; encrypted-message
363 </pre>
364 </div>
365
366 <p>
367 Return the <i>message</i> between <i>start</i> and <i>end</i> encrypted with the <i>cipher</i>; the
368 class of <i>cipher</i> determines the algorithm used to encrypt the message.
369 </p>
370
371
372 <div class="org-src-container">
373 <pre class="src src-lisp">(decrypt-message cipher message <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; decrypted-message
374 </pre>
375 </div>
376
377 <p>
378 Return the <i>message</i> between <i>start</i> and <i>end</i> decrypted by the <i>cipher</i>; the
379 class of <i>cipher</i> determines the algorithm used to decrypt the message.
380 </p>
381 </div>
382 <div id="outline-container-orgb6b9101" class="outline-3">
383 <h3 id="orgb6b9101">Inquiry functions</h3>
384 <div class="outline-text-3" id="text-orgb6b9101">
385 <div class="org-src-container">
386 <pre class="src src-lisp" id="orgd644b3b">(list-all-ciphers) =&gt; list
387 </pre>
388 </div>
389
390 <p>
391 Returns a list of cipher-names that may be validly passed to <a href="#orga194874">make-cipher</a>.
392 </p>
393
394
395 <div class="org-src-container">
396 <pre class="src src-lisp" id="orgaef3ba6">(cipher-supported-p name) =&gt; boolean
397 </pre>
398 </div>
399
400 <p>
401 Returns <code>t</code> if <i>name</i> would be in the list returned by <a href="#orgd644b3b">list-all-ciphers</a>,
402 <code>nil</code> otherwise.
403 </p>
404
405
406 <div class="org-src-container">
407 <pre class="src src-lisp" id="org016f0ae">(key-lengths cipher) =&gt; list
408 </pre>
409 </div>
410
411 <p>
412 Return a list of valid key lengths for <i>cipher</i>.
413 </p>
414
415
416 <div class="org-src-container">
417 <pre class="src src-lisp" id="org32e5f3d">(block-length cipher) =&gt; number
418 </pre>
419 </div>
420
421 <p>
422 Return the number of octets <i>cipher</i> processes at a time. This
423 function always returns 1 for stream ciphers.
424 </p>
425 </div>
426 </div>
427 <div id="outline-container-orgf14df47" class="outline-3">
428 <h3 id="orgf14df47">Key stream position</h3>
429 <div class="outline-text-3" id="text-orgf14df47">
430 <p>
431 Block ciphers in CTR mode and some stream ciphers have the ability to change the
432 current position within the key stream in constant time instead of having to
433 consume all the bytes until the desired position is reached.
434 </p>
435
436 <div class="org-src-container">
437 <pre class="src src-lisp" id="org93fb9e3">(keystream-position cipher <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> position) =&gt; number or boolean
438 </pre>
439 </div>
440
441 <p>
442 Return or change the current <i>position</i> within the key stream of a <i>cipher</i>.
443 When <i>position</i> is not supplied, <a href="#org93fb9e3">keystream-position</a> returns the current position
444 in the key stream, or <i>nil</i> if it can't be determined. When <i>position</i> is
445 supplied, the key stream position of the <i>cipher</i> is set to that <i>position</i> if
446 possible. <a href="#org93fb9e3">keystream-position</a> returns <i>t</i> if the repositioning is performed
447 successfully, or <i>nil</i> otherwise.
448 </p>
449
450 <p>
451 <a href="#org93fb9e3">keystream-position</a> can be used with the following ciphers:
452 </p>
453 <ul class="org-ul">
454 <li>all the block ciphers (aes, twofish, etc.) in CTR mode</li>
455 <li>chacha</li>
456 <li>chacha/12</li>
457 <li>chacha/8</li>
458 <li>salsa20</li>
459 <li>salsa20/12</li>
460 <li>salsa20/8</li>
461 <li>xchacha</li>
462 <li>xchacha/12</li>
463 <li>xchacha/8</li>
464 <li>xsalsa20</li>
465 <li>xsalsa20/12</li>
466 <li>xsalsa20/8</li>
467 </ul>
468 </div>
469 </div>
470 </div>
471 <div id="outline-container-digests" class="outline-2">
472 <h2 id="digests">Digests</h2>
473 <div class="outline-text-2" id="text-digests">
474 <p>
475 Digest functions, also known as hash functions, produce fixed-length
476 output (a <i>digest</i> or <i>hash</i>) from a variable-length message. The
477 simplest example of a digest function is one that adds up all the
478 bytes in the message modulo 256. This digest function fails one test
479 of a cryptographically secure hash function: it must be difficult to
480 find a message with a given digest. It also fails the other test: it
481 must be difficult to find two messages with the same digest.
482 </p>
483
484 <p>
485 Ironclad provides several cryptographically secure digest functions
486 and several non-cryptographically secure digest functions.
487 </p>
488
489 <p>
490 <span class="underline">Note:</span> In the functions below, messages or parts thereof are provided
491 as octet vectors; Ironclad has no facilities for producing digests of
492 strings. If you need to obtain the digest of a string, then you need
493 to figure out how to convert it to an octet vector first. This is
494 a deliberate design decision. Characters are not equivalent to bytes.
495 See your local Unicode guru for more details.
496 </p>
497
498
499 <div class="org-src-container">
500 <pre class="src src-lisp" id="org0aca191">(make-digest digest-name <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> keys <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; digester
501 </pre>
502 </div>
503
504 <p>
505 Returns a digest object. <i>digest-name</i> is a keyword naming the
506 algorithm you wish <i>digester</i> to use. The supported digest names can be found
507 by calling <a href="#org2ccff16">list-all-digests</a>. They are:
508 </p>
509 <ul class="org-ul">
510 <li>adler32</li>
511 <li>blake2</li>
512 <li>blake2/160</li>
513 <li>blake2/256</li>
514 <li>blake2/384</li>
515 <li>blake2s</li>
516 <li>blake2s/128</li>
517 <li>blake2s/160</li>
518 <li>blake2s/224</li>
519 <li>crc24</li>
520 <li>crc32</li>
521 <li>crc32c</li>
522 <li>groestl</li>
523 <li>groestl/224</li>
524 <li>groestl/256</li>
525 <li>groestl/384</li>
526 <li>jh</li>
527 <li>jh/224</li>
528 <li>jh/256</li>
529 <li>jh/384</li>
530 <li>keccak</li>
531 <li>keccak/224</li>
532 <li>keccak/256</li>
533 <li>keccak/384</li>
534 <li>kupyna</li>
535 <li>kupyna/256</li>
536 <li>md2</li>
537 <li>md4</li>
538 <li>md5</li>
539 <li>ripemd-128</li>
540 <li>ripemd-160</li>
541 <li>sha1</li>
542 <li>sha224</li>
543 <li>sha256</li>
544 <li>sha3</li>
545 <li>sha3/224</li>
546 <li>sha3/256</li>
547 <li>sha3/384</li>
548 <li>sha384</li>
549 <li>sha512</li>
550 <li>shake128</li>
551 <li>shake256</li>
552 <li>skein1024</li>
553 <li>skein1024/384</li>
554 <li>skein1024/512</li>
555 <li>skein256</li>
556 <li>skein256/128</li>
557 <li>skein256/160</li>
558 <li>skein256/224</li>
559 <li>skein512</li>
560 <li>skein512/128</li>
561 <li>skein512/160</li>
562 <li>skein512/224</li>
563 <li>skein512/256</li>
564 <li>skein512/384</li>
565 <li>sm3</li>
566 <li>streebog</li>
567 <li>streebog/256</li>
568 <li>tiger</li>
569 <li>tree-hash</li>
570 <li>whirlpool</li>
571 </ul>
572
573 <p>
574 Like for <a href="#orga194874">make-cipher</a>, <i>digest-name</i> should be a symbol in the
575 <code>keyword</code> or <code>ironclad</code> packages.
576 </p>
577
578 <p>
579 Some algorithms (e.g. shake128 and shake256) can produce digests of
580 any size. The size of the digest in bytes can be specified with the
581 <i>output-length</i> key parameter:
582 </p>
583
584 <pre class="example" id="org4d40d35">
585 (make-digest :shake256 :output-length 123)
586 </pre>
587
588
589 <div class="org-src-container">
590 <pre class="src src-lisp" id="org9ba11b9">(update-digest digester thing <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; (values)
591 </pre>
592 </div>
593
594 <p>
595 Updates the internal state of <i>digester</i> with the contents of <i>thing</i>.
596 The exact method is determined by the type of <i>thing</i>.
597 </p>
598
599 <p>
600 There are several methods defined on this generic function that take
601 a particular digester and a <code>(simple-array (unsigned-byte 8) (*))</code> as
602 well as the usual <i>start</i> and <i>end</i> keyword arguments. These methods
603 update the state of <i>digester</i> with the subsequence of the array
604 denoted by <i>start</i> and <i>end</i>. They are not listed here because there's
605 one method for every type of digest that Ironclad provides, and
606 listing them would get very tedious for no benefit. An example should
607 suffice.
608 </p>
609
610 <pre class="example" id="org4595f34">
611 (let ((digester (ironclad:make-digest :sha1))
612 (array (make-array 16 :element-type '(unsigned-byte 8) :initial-element 0)))
613 ;; Update with 16 zeroes.
614 (ironclad:update-digest digester array)
615 ;; Update with 8 ones.
616 (fill array 1 :start 2 :end 10)
617 (ironclad:update-digest digester array :start 2 :end 10))
618 </pre>
619
620
621 <div class="org-src-container">
622 <pre class="src src-lisp">(update-digest digester (stream stream) <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> buffer start end <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; digester
623 </pre>
624 </div>
625
626 <p>
627 Update the internal state of <i>digester</i> with the contents of <i>stream</i>,
628 which must respond to <code>read-byte</code> or <code>read-sequence</code> with
629 a <code>(simple-array (unsigned-byte 8) (*))</code> and return <i>digester</i>. It
630 differs from <a href="#org4fb38fd">digest-stream</a>, below, in that you may need to digest data
631 before or after the contents of <i>stream</i> (this happens, for instance,
632 when signing the contents of some file).
633 </p>
634
635
636 <div class="org-src-container">
637 <pre class="src src-lisp" id="orgebfad7a">(produce-digest digester <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> digest digest-start) =&gt; digest
638 </pre>
639 </div>
640
641 <p>
642 Return the digest of the data processed by <i>digester</i> so far.
643 </p>
644
645 <p>
646 If <i>digest</i> is provided, the computed digest will be placed into
647 <i>digest</i> starting at <i>digest-start</i>. <i>digest</i> must be a
648 <code>(simple-array (unsigned-byte 8) (*))</code>. An <a href="#org701dd62">insufficient-buffer-space</a>
649 error will be signaled if there is insufficient space in <i>digest</i>.
650 </p>
651 </div>
652 <div id="outline-container-org15f4a95" class="outline-3">
653 <h3 id="org15f4a95">High-level convenience functions</h3>
654 <div class="outline-text-3" id="text-org15f4a95">
655 <p>
656 Several high-level convenience functions that encapsulate common
657 sequences of <a href="#org0aca191">make-digest</a>, <a href="#org9ba11b9">update-digest</a> and <a href="#orgebfad7a">produce-digest</a> are
658 provided by Ironclad as well. They come in two flavors: the first
659 takes a digest name as would be provided to <a href="#org0aca191">make-digest</a>. The second
660 way to call these functions is to provide an actual digest object as
661 the first argument. So one can say:
662 </p>
663
664 <pre class="example" id="org92e50e2">
665 (ironclad:digest-sequence :md5 *buffer*)
666 </pre>
667
668 <p>
669 or, equivalently:
670 </p>
671
672 <pre class="example" id="org1cea259">
673 (let ((digester (ironclad:make-digest :md5)))
674 (ironclad:digest-sequence digester *buffer*))
675 </pre>
676
677 <p>
678 The second form comes in handy if you plan on <a href="#org9d66bdc">reusing the digest object</a>.
679 </p>
680
681
682 <div class="org-src-container">
683 <pre class="src src-lisp" id="orgbd0777b">(digest-sequence digest-spec sequence <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> args <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end digest digest-start) =&gt; digest
684 </pre>
685 </div>
686
687 <p>
688 Returns the digest of the subsequence of <i>sequence</i> bounded by <i>start</i>
689 and <i>end</i>, according to <i>digest-name</i>. <i>sequence</i> must be
690 a <code>(vector (unsigned-byte 8))</code>. <i>digest</i> and <i>digest-start</i>
691 are as in <a href="#orgebfad7a">produce-digest</a>.
692 </p>
693
694
695 <div class="org-src-container">
696 <pre class="src src-lisp" id="org4fb38fd">(digest-stream digest-spec stream <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> args <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> buffer start end digest digest-start) =&gt; digest
697 </pre>
698 </div>
699
700 <p>
701 Returns the digest of the contents of the stream specified by
702 <i>stream</i>. <code>read-byte</code> must be a legal operation on <i>stream</i> and return
703 an <code>(unsigned-byte 8)</code>. In a similar fashion, <code>read-sequence</code> on
704 <i>stream</i> must support reading into a <code>(simple-array (unsigned-byte 8) (*))</code>.
705 <i>digest</i> and <i>digest-start</i> are as in <a href="#orgebfad7a">produce-digest</a>.
706 </p>
707
708 <p>
709 If <i>buffer</i> is provided, it must be a <code>(simple-array (unsigned-byte 8) (*))</code>;
710 the portion of <i>buffer</i> between <i>start</i> and <i>end</i> will be used to read
711 the data from the stream.
712 </p>
713
714
715 <div class="org-src-container">
716 <pre class="src src-lisp" id="org7c78769">(digest-file digest-spec pathname <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> args <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> buffer start end digest digest-start) =&gt; digest
717 </pre>
718 </div>
719
720 <p>
721 Returns the digest of the contents of the file named by <i>pathname</i>.
722 <i>digest</i> and <i>digest-start</i> are as in <a href="#orgebfad7a">produce-digest</a>.
723 </p>
724
725 <p>
726 If <i>buffer</i> is provided, it must be a <code>(simple-array (unsigned-byte 8) (*))</code>;
727 the portion of <i>buffer</i> between <i>start</i> and <i>end</i> will be used to read
728 the data from the stream.
729 </p>
730 </div>
731 </div>
732 <div id="outline-container-orgff3b3d6" class="outline-3">
733 <h3 id="orgff3b3d6">Inquiry functions</h3>
734 <div class="outline-text-3" id="text-orgff3b3d6">
735 <div class="org-src-container">
736 <pre class="src src-lisp" id="org2ccff16">(list-all-digests) =&gt; list
737 </pre>
738 </div>
739
740 <p>
741 Returns a list whose elements may be validly passed to <a href="#org0aca191">make-digest</a>.
742 </p>
743
744
745 <div class="org-src-container">
746 <pre class="src src-lisp" id="org1786607">(digest-supported-p name) =&gt; boolean
747 </pre>
748 </div>
749
750 <p>
751 Returns <code>t</code> if <i>name</i> would be in the list returned by <a href="#org2ccff16">list-all-digests</a>,
752 <code>nil</code> otherwise.
753 </p>
754
755
756 <div class="org-src-container">
757 <pre class="src src-lisp" id="orgdb90ebb">(digest-length digest) =&gt; number
758 </pre>
759 </div>
760
761 <p>
762 Returns the length of the digest computed by <i>digest</i>, which may be
763 a digest-name or a digest instance.
764 </p>
765 </div>
766 </div>
767 <div id="outline-container-org9d66bdc" class="outline-3">
768 <h3 id="org9d66bdc">Miscellaneous</h3>
769 <div class="outline-text-3" id="text-org9d66bdc">
770 <p>
771 Ironclad digests are CLOS objects; the interesting thing about this
772 for most purposes is that functions like <code>reinitialize-instance</code> are
773 supported. This means one can write a fairly efficient clone of the
774 <code>md5sum</code> program like so:
775 </p>
776
777 <pre class="example" id="orgc953f23">
778 (defun digest-sum-files (digest-name &amp;rest files)
779 (unless files
780 (error "no files given to digest"))
781 (loop with buffer = (make-array 8192 :element-type '(unsigned-byte 8))
782 with digest = (make-array (ironclad:digest-length digest-name)
783 :element-type '(unsigned-byte 8))
784 for file in files
785 for digester = (ironclad:make-digest digest-name)
786 then (reinitialize-instance digester)
787 do (ironclad:digest-file digester file :buffer buffer :digest digest)
788 (format t "~A ~A~%" (file-namestring file)
789 (ironclad:byte-array-to-hex-string digest))))
790 </pre>
791 </div>
792 </div>
793 <div id="outline-container-org631e0c2" class="outline-3">
794 <h3 id="org631e0c2">Tree hashes</h3>
795 <div class="outline-text-3" id="text-org631e0c2">
796 <p>
797 Ironclad supports tree hashes, as described in <a href="http://web.archive.org/web/20080316033726/http://www.open-content.net/specs/draft-jchapweske-thex-02.html">Tree Hash EXchange format</a>.
798 You create tree hashes as if you were creating a digest:
799 </p>
800
801 <pre class="example" id="org1c3219b">
802 (ironclad:make-digest :tree-hash)
803 </pre>
804
805 <p>
806 By default, this creates a tree hash that uses the Tiger digest
807 algorithm internally and a segment size of 1024. Since using the Tiger
808 digest algorithm is so common, a convenience function that makes your
809 intent obvious has also been provided:
810 </p>
811
812 <pre class="example" id="orgb990c13">
813 (ironclad:make-tiger-tree-hash)
814 </pre>
815
816 <p>
817 You may indicate that you wish to use a different algorithm than
818 Tiger:
819 </p>
820
821 <pre class="example" id="org10cf356">
822 (ironclad:make-digest '(:treehash :digest :sha256))
823 </pre>
824
825 <p>
826 Or you might wish to use a different segment size:
827 </p>
828
829 <pre class="example" id="org42828ef">
830 (ironclad:make-digest '(:tree-hash :block-length 16384))
831 </pre>
832
833 <p>
834 There is currently no interface for obtaining the intermediate hashes
835 computed while computing the final tree hash.
836 </p>
837 </div>
838 </div>
839 </div>
840 <div id="outline-container-message-authentication-codes" class="outline-2">
841 <h2 id="message-authentication-codes">Message authentication codes</h2>
842 <div class="outline-text-2" id="text-message-authentication-codes">
843 <p>
844 A message authentication code is a cryptographic function of some data
845 and a user-specified key. Only a person knowing the key can recompute
846 the MAC for the given message. A MAC is useful where maintaining data
847 integrity is required, but the secrecy of the data is not paramount.
848 </p>
849
850 <p>
851 Ironclad provides different kinds of MACs:
852 </p>
853 <ul class="org-ul">
854 <li>HMAC, specified in <a href="http://www.ietf.org/rfc/rfc2104.txt">RFC 2104</a></li>
855 <li>CMAC, specified in <a href="http://www.ietf.org/rfc/rfc4493.txt">RFC 4493</a> and NIST document 800-38B</li>
856 <li>GMAC, specified in NIST document 800-38D</li>
857 <li>Blake2 and Blake2s MAC</li>
858 <li>Poly1305</li>
859 <li>SipHash</li>
860 <li>Skein MAC</li>
861 </ul>
862
863
864 <div class="org-src-container">
865 <pre class="src src-lisp" id="orgbc2a39c">(make-mac mac-name key <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> args) =&gt; mac
866 </pre>
867 </div>
868
869 <p>
870 Return a MAC object initialized with a secret <i>key</i>. <i>mac-name</i> is
871 a keyword naming the algorithm you wish <i>mac</i> to use. The supported
872 MACs can be found by calling <a href="#org73970a8">list-all-macs</a>. They are:
873 </p>
874 <ul class="org-ul">
875 <li>blake2-mac</li>
876 <li>blake2s-mac</li>
877 <li>cmac</li>
878 <li>gmac</li>
879 <li>hmac</li>
880 <li>poly1305</li>
881 <li>siphash</li>
882 <li>skein-mac</li>
883 </ul>
884
885 <p>
886 Like for <a href="#org0aca191">make-digest</a>, <i>mac-name</i> should be a symbol in the <code>keyword</code>
887 or <code>ironclad</code> packages.
888 </p>
889
890 <p>
891 Some MACs take extra arguments that can be specified in <i>args</i>.
892 </p>
893
894 <pre class="example" id="orgc279203">
895 (make-mac :blake2-mac key &amp;key digest-length)
896 (make-mac :blake2s-mac key &amp;key digest-length)
897 (make-mac :cmac key cipher-name)
898 (make-mac :gmac key cipher-name initialization-vector)
899 (make-mac :hmac key digest-name)
900 (make-mac :poly1305 key)
901 (make-mac :siphash key &amp;key compression-rounds finalization-rounds digest-length)
902 (make-mac :skein-mac key &amp;key block-length digest-length)
903 </pre>
904
905 <p>
906 When making a Blake2 MAC, the length of the <i>key</i> passed to <a href="#orgbc2a39c">make-mac</a>
907 must be 64 bytes.
908 </p>
909
910 <p>
911 When making a Blake2s MAC, the length of the <i>key</i> passed to <a href="#orgbc2a39c">make-mac</a>
912 must be 32 bytes.
913 </p>
914
915 <p>
916 When making a CMAC, <i>cipher-name</i> must have a <a href="#org32e5f3d">block-length</a> of either 8, 16, 32,
917 64 or 128; this restriction is satisfied by many ciphers in Ironclad with the
918 notable exception of stream ciphers. <i>key</i> must be an acceptable key for
919 <i>cipher-name</i>.
920 </p>
921
922 <p>
923 When making a GMAC, <i>cipher-name</i> must have a <a href="#org32e5f3d">block-length</a> of 16. <i>key</i> must be
924 an acceptable key for <i>cipher-name</i>.
925 </p>
926
927 <p>
928 When making a Poly1305 MAC, the length of the <i>key</i> passed to <a href="#orgbc2a39c">make-mac</a> must be
929 32 bytes.
930 </p>
931
932 <p>
933 When making a SipHash MAC, the length of the <i>key</i> passed to <a href="#orgbc2a39c">make-mac</a> must be 16
934 bytes. <i>digest-length</i> is 8 by default, but it can also be set to 16. By
935 default, <i>compression-rounds</i> is 2 and <i>finalization-rounds</i> is 4.
936 </p>
937
938 <p>
939 When making a Skein MAC, <i>block-length</i> can be 32 (to use the Skein256
940 hash function internally), 64 (to use Skein512) or 128 (to use
941 Skein1024). <i>digest-length</i> can be any length you want the computed
942 digest to be. By default, <i>block-length</i> is 64 and <i>digest-length</i>
943 is 64.
944 </p>
945
946
947 <p>
948 MAC objects support <code>reinitialize-instance</code>:
949 </p>
950
951 <div class="org-src-container">
952 <pre class="src src-lisp">(reinitialize-instance mac <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> initargs <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> key <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; mac
953 </pre>
954 </div>
955
956 <p>
957 The <i>:key</i> argument is the secret key, as provided to <a href="#orgbc2a39c">make-mac</a>.
958 </p>
959
960
961 <div class="org-src-container">
962 <pre class="src src-lisp" id="org91341ca">(update-mac mac thing <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; (values)
963 </pre>
964 </div>
965
966 <p>
967 Updates the internal state of <i>mac</i> with the contents of <i>thing</i>.
968 The exact method is determined by the type of <i>thing</i>.
969 </p>
970
971 <p>
972 There are several methods defined on this generic function that take
973 a particular MAC and a <code>(simple-array (unsigned-byte 8) (*))</code> as
974 well as the usual <i>start</i> and <i>end</i> keyword arguments. These methods
975 update the state of <i>mac</i> with the subsequence of the array
976 denoted by <i>start</i> and <i>end</i>. They are not listed here because there's
977 one method for every type of MAC that Ironclad provides, and
978 listing them would get very tedious for no benefit. An example should
979 suffice.
980 </p>
981
982 <pre class="example" id="org23a2d97">
983 (let* ((key (random-data 32))
984 (mac (ironclad:make-mac :hmac key :sha256))
985 (array (make-array 16 :element-type '(unsigned-byte 8) :initial-element 0)))
986 ;; Update with 16 zeroes.
987 (ironclad:update-mac mac array)
988 ;; Update with 8 ones.
989 (fill array 1 :start 2 :end 10)
990 (ironclad:update-mac mac array :start 2 :end 10))
991 </pre>
992
993
994 <div class="org-src-container">
995 <pre class="src src-lisp" id="org967004b">(produce-mac mac <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> digest digest-start) =&gt; digest
996 </pre>
997 </div>
998
999 <p>
1000 Return the digest of the data processed by <i>mac</i> so far. The internal
1001 state of <i>mac</i> is not modified; this feature makes it possible to
1002 compute a "rolling MAC" of a document.
1003 </p>
1004
1005 <p>
1006 If <i>digest</i> is provided, the computed digest will be placed into
1007 <i>digest</i> starting at <i>digest-start</i>. <i>digest</i> must be a
1008 <code>(simple-array (unsigned-byte 8) (*))</code>. An <a href="#org701dd62">insufficient-buffer-space</a>
1009 error will be signaled if there is insufficient space in <i>digest</i>.
1010 </p>
1011
1012 <p>
1013 The length of the digest returned by <a href="#org967004b">produce-mac</a> is determined by the
1014 kind of MAC and the extra arguments passed to <a href="#orgbc2a39c">make-mac</a>:
1015 </p>
1016 <ul class="org-ul">
1017 <li>blake2-mac: from 1 to 64 bytes (64 by default)</li>
1018 <li>blake2s-mac: from 1 to 32 bytes (32 by default)</li>
1019 <li>cmac: <a href="#org32e5f3d">block-length</a> of the <i>cipher-name</i> passed to <a href="#orgbc2a39c">make-mac</a></li>
1020 <li>gmac: 16 bytes</li>
1021 <li>hmac: <a href="#orgdb90ebb">digest-length</a> of the <i>digest-name</i> passed to <a href="#orgbc2a39c">make-mac</a></li>
1022 <li>poly1305: 16 bytes</li>
1023 <li>siphash: <i>digest-length</i> passed to <a href="#orgbc2a39c">make-mac</a> (8 by default)</li>
1024 <li>skein-mac: <i>digest-length</i> passed to <a href="#orgbc2a39c">make-mac</a> (64 by default)</li>
1025 </ul>
1026 </div>
1027 <div id="outline-container-org898454b" class="outline-3">
1028 <h3 id="org898454b">Inquiry functions</h3>
1029 <div class="outline-text-3" id="text-org898454b">
1030 <div class="org-src-container">
1031 <pre class="src src-lisp" id="org73970a8">(list-all-macs) =&gt; list
1032 </pre>
1033 </div>
1034
1035 <p>
1036 Returns a list whose elements may be validly passed to <a href="#orgbc2a39c">make-mac</a>.
1037 </p>
1038
1039
1040 <div class="org-src-container">
1041 <pre class="src src-lisp" id="orgfe5f676">(mac-supported-p name) =&gt; boolean
1042 </pre>
1043 </div>
1044
1045 <p>
1046 Returns <code>t</code> if <i>name</i> would be in the list returned by <a href="#org73970a8">list-all-macs</a>,
1047 <code>nil</code> otherwise.
1048 </p>
1049 </div>
1050 </div>
1051 </div>
1052 <div id="outline-container-authenticated-encryption" class="outline-2">
1053 <h2 id="authenticated-encryption">Authenticated encryption</h2>
1054 <div class="outline-text-2" id="text-authenticated-encryption">
1055 <div class="org-src-container">
1056 <pre class="src src-lisp" id="org44e9414">(make-authenticated-encryption-mode name <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> args) =&gt; mode
1057 </pre>
1058 </div>
1059
1060 <p>
1061 Return an authenticated encryption object suitable for use for both encryption
1062 and decryption.
1063 </p>
1064
1065 <p>
1066 <i>name</i> denotes the mode to use. <a href="#orga5e1f4c">list-all-authenticated-encryption-modes</a> will
1067 tell you the names of all the supported modes. They are:
1068 </p>
1069 <ul class="org-ul">
1070 <li>eax (Encrypt then authenticate then translate)</li>
1071 <li>etm (Encrypt then MAC)</li>
1072 <li>gcm (Galois counter mode)</li>
1073 </ul>
1074
1075 <p>
1076 <i>name</i> can be a symbol in the <code>keyword</code> or <code>ironclad</code> packages.
1077 </p>
1078
1079 <p>
1080 <i>args</i> depends on the chosen authenticated encryption mode.
1081 </p>
1082
1083 <pre class="example" id="orgbacd74f">
1084 (make-authenticated-encryption-mode :eax &amp;key tag cipher-name key initialization-vector)
1085 (make-authenticated-encryption-mode :etm &amp;key tag cipher mac)
1086 (make-authenticated-encryption-mode :gcm &amp;key tag cipher-name key initialization-vector)
1087 </pre>
1088
1089 <p>
1090 If <i>tag</i> is specified, it will be used at the end of decryption (when the
1091 <i>handle-final-block</i> flag is <code>t</code>) to check the authenticity of the data.
1092 A <code>bad-authentication-tag</code> error will be signaled if the data is not authentic.
1093 If you don't specify it, you will have to call <a href="#org2949cbe">produce-tag</a> after decryption and
1094 check that the tags match (e.g. using <a href="#org9ca5d87">constant-time-equal</a>).
1095 </p>
1096
1097 <p>
1098 When using EAX, <i>key</i> must be a suitable key for the chosen <i>cipher-name</i>.
1099 </p>
1100
1101 <p>
1102 When using ETM, <i>cipher</i> must be a cipher object created by <a href="#orga194874">make-cipher</a>.
1103 <i>mac</i> must be a mac object created by <a href="#orgbc2a39c">make-mac</a>.
1104 </p>
1105
1106 <p>
1107 When using GCM, <i>cipher-name</i> must have a <a href="#org32e5f3d">block-length</a> of 16 bytes. <i>key</i> must be a suitable key
1108 for the chosen cipher.
1109 </p>
1110
1111
1112 <div class="org-src-container">
1113 <pre class="src src-lisp" id="org0172765">(process-associated-data mode data <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end) =&gt; (values)
1114 </pre>
1115 </div>
1116
1117 <p>
1118 Update the internal state of <i>mode</i> with the contents of <i>data</i> between <i>start</i>
1119 and <i>end</i> so that they are taken into consideration in the authentication tag.
1120 </p>
1121
1122
1123 <p>
1124 An authenticated encryption object can be used with the <a href="#orga0c509f">encrypt</a>, <a href="#org8d3dffc">decrypt</a>,
1125 <a href="#org6424db2">encrypt-message</a> and <a href="#org13a3a49">decrypt-message</a> functions.
1126 </p>
1127
1128 <pre class="example" id="org15664f4">
1129 (encrypt mode plaintext ciphertext &amp;key plaintext-start plaintext-end ciphertext-start handle-final-block)
1130 (decrypt mode ciphertext plaintext &amp;key ciphertext-start ciphertext-end plaintext-start handle-final-block)
1131 (encrypt-message mode message &amp;key start end associated-data associated-data-start associated-data-end)
1132 (decrypt-message mode message &amp;key start end associated-data associated-data-start associated-data-end)
1133 </pre>
1134
1135
1136 <div class="org-src-container">
1137 <pre class="src src-lisp" id="org2949cbe">(produce-tag mode <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> tag tag-start) =&gt; tag
1138 </pre>
1139 </div>
1140
1141 <p>
1142 Return the authentication tag of the data processed by <i>mode</i> so far. If <i>tag</i>
1143 is provided, the computed tag will be placed into <i>tag</i> starting at <i>tag-start</i>.
1144 <i>tag</i> must be a <code>(simple-array (unsigned-byte 8) (*))</code>. An
1145 <a href="#org701dd62">insufficient-buffer-space</a> error will be signaled if there is insufficient space
1146 in <i>tag</i>.
1147 </p>
1148 </div>
1149 <div id="outline-container-org9d6ac20" class="outline-3">
1150 <h3 id="org9d6ac20">Inquiry functions</h3>
1151 <div class="outline-text-3" id="text-org9d6ac20">
1152 <div class="org-src-container">
1153 <pre class="src src-lisp" id="orga5e1f4c">(list-all-authenticated-encryption-modes) =&gt; list
1154 </pre>
1155 </div>
1156
1157 <p>
1158 Returns a list whose elements may be validly passed to
1159 <a href="#org44e9414">make-authenticated-encryption-mode</a>.
1160 </p>
1161
1162
1163 <div class="org-src-container">
1164 <pre class="src src-lisp" id="org60f6656">(authenticated-encryption-mode-supported-p name) =&gt; boolean
1165 </pre>
1166 </div>
1167
1168 <p>
1169 Returns <code>t</code> if <i>name</i> would be in the list returned by
1170 <a href="#orga5e1f4c">list-all-authenticated-encryption-modes</a> <code>nil</code> otherwise.
1171 </p>
1172 </div>
1173 </div>
1174 </div>
1175 <div id="outline-container-key-derivation-functions" class="outline-2">
1176 <h2 id="key-derivation-functions">Key derivation functions</h2>
1177 <div class="outline-text-2" id="text-key-derivation-functions">
1178 <p>
1179 Ironclad comes with a few key derivation functions:
1180 </p>
1181 <ul class="org-ul">
1182 <li>Argon2 (only variants without parallelism are implemented)</li>
1183 <li>Bcrypt</li>
1184 <li>Bcrypt-pbkdf</li>
1185 <li>PBKDF1</li>
1186 <li>PBKDF2</li>
1187 <li>Scrypt</li>
1188 <li>HMAC</li>
1189 </ul>
1190
1191
1192 <div class="org-src-container">
1193 <pre class="src src-lisp" id="org9813827">(derive-key kdf passphrase salt iteration-count key-length) =&gt; digest
1194 </pre>
1195 </div>
1196
1197 <p>
1198 Given a key derivation function object (produced by <a href="#orgc3724fd">make-kdf</a>),
1199 a password and salt (both must be of type
1200 <code>(simple-array (unsigned-byte 8) (*))</code>), and number of iterations,
1201 returns the password digest as a byte array of length <i>key-length</i>.
1202 </p>
1203
1204 <p>
1205 For bcrypt, the <i>salt</i> must be 16 bytes long, the <i>iteration-count</i> must be
1206 a power of 2 between 2<sup>4</sup> and 2<sup>31</sup>, and the <i>key-length</i> must be 24.
1207 Scrypt and HMAC ignore the <i>iteration-count</i> parameter.
1208 </p>
1209
1210 <p>
1211 For bcrypt-pbkdf, the <i>key-length</i> must be between 1 and 1024.
1212 </p>
1213
1214
1215 <div class="org-src-container">
1216 <pre class="src src-lisp" id="orgc3724fd">(make-kdf kind <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> digest n r p block-count additional-key additional-data) =&gt; kdf
1217 </pre>
1218 </div>
1219
1220 <p>
1221 Returns a key derivation function instance.
1222 </p>
1223
1224 <p>
1225 <i>kind</i> denotes the key derivation function to use. They are:
1226 </p>
1227 <ul class="org-ul">
1228 <li>argon2d</li>
1229 <li>argon2i</li>
1230 <li>argon2id</li>
1231 <li>bcrypt</li>
1232 <li>bcrypt-pbkdf</li>
1233 <li>pbkdf1</li>
1234 <li>pbkdf2</li>
1235 <li>scrypt-kdf</li>
1236 <li>hmac-kdf</li>
1237 </ul>
1238
1239 <p>
1240 <i>kind</i> can be a symbol in the <code>keyword</code> or <code>ironclad</code> packages.
1241 </p>
1242
1243 <p>
1244 The Argon2 key derivations use the <i>block-count</i>, <i>additional-key</i>
1245 and <i>additional-data</i> parameters (<i>block-count</i> is the number of 1 KiB
1246 memory blocks used by the function and it must be at least 8,
1247 <i>additional-key</i> and <i>additional-data</i> are optional).
1248 The PBKDF algorithms use <i>digest</i>.
1249 The Scrypt key derivation uses cost parameters <i>N</i>, <i>r</i> and <i>p</i> (<i>N</i>
1250 is a CPU cost parameter that must be a power of 2, <i>r</i> and <i>p</i> are
1251 memory cost parameters that must be defined such that
1252 <i>r</i> * <i>p</i> &lt;= 2<sup>30</sup>).
1253 </p>
1254
1255 <p>
1256 The default Scrypt parameters are <i>N</i> = 4096, <i>r</i> = 8, and <i>p</i> = 2.
1257 Please note that depending on the values of <i>N</i> and <i>r</i>,
1258 <a href="#org9813827">derive-key</a> may not be able to allocate sufficient space for its
1259 temporary arrays.
1260 </p>
1261
1262 <p>
1263 The HMAC-KDF algorithm uses the <i>digest</i> parameter to precise what
1264 hash function is used. It also optionally uses the <i>additional-data</i>
1265 to precise the <code>info</code> vector from the <a href="https://tools.ietf.org/html/rfc5869">RFC</a>.
1266 </p>
1267
1268
1269 <div class="org-src-container">
1270 <pre class="src src-lisp" id="org3509dc1">(list-all-kdfs) =&gt; list
1271 </pre>
1272 </div>
1273
1274 <p>
1275 Returns a list of KDF kinds that may be validly passed to <a href="#orgc3724fd">make-kdf</a>.
1276 </p>
1277 </div>
1278 <div id="outline-container-org9f9093d" class="outline-3">
1279 <h3 id="org9f9093d">PBKDF convenience functions</h3>
1280 <div class="outline-text-3" id="text-org9f9093d">
1281 <p>
1282 Ironclad comes with convenience functions for using PBKDF1 and PBKDF2
1283 to store passwords.
1284 </p>
1285
1286
1287 <div class="org-src-container">
1288 <pre class="src src-lisp" id="org7012f46">(pbkdf2-hash-password password <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> salt digest iterations) =&gt; password
1289 </pre>
1290 </div>
1291
1292 <p>
1293 Convenience function for hashing passwords using the PBKDF2 algorithm.
1294 Returns the derived hash of the password, and the original salt, as
1295 byte vectors.
1296 </p>
1297
1298
1299 <div class="org-src-container">
1300 <pre class="src src-lisp" id="org57ce335">(pbkdf2-hash-password-to-combined-string password <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> salt digest iterations) =&gt; password
1301 </pre>
1302 </div>
1303
1304 <p>
1305 Convenience function for hashing passwords using the PBKDF2 algorithm.
1306 Returns the derived hash of the password as a single string that
1307 encodes the given salt and PBKDF2 algorithm parameters.
1308 </p>
1309
1310
1311 <div class="org-src-container">
1312 <pre class="src src-lisp" id="orgf7339d5">(pbkdf2-check-password password combined-salt-and-digest) =&gt; boolean
1313 </pre>
1314 </div>
1315
1316 <p>
1317 Given a <i>password</i> byte vector and a combined salt and digest string
1318 produced by <a href="#org57ce335">pbkdf2-hash-password-to-combined-string</a>, checks whether
1319 the password is valid.
1320 </p>
1321 </div>
1322 </div>
1323 </div>
1324 <div id="outline-container-public-key-cryptography" class="outline-2">
1325 <h2 id="public-key-cryptography">Public key cryptography</h2>
1326 <div class="outline-text-2" id="text-public-key-cryptography">
1327 <p>
1328 Ironclad includes support for a few public key cryptography algorithms.
1329 </p>
1330
1331 <p>
1332 Encryption algorithms:
1333 </p>
1334 <ul class="org-ul">
1335 <li>Elgamal</li>
1336 <li>RSA</li>
1337 </ul>
1338
1339 <p>
1340 Signature algorithms:
1341 </p>
1342 <ul class="org-ul">
1343 <li>DSA</li>
1344 <li>Ed25519</li>
1345 <li>Ed448</li>
1346 <li>Elgamal</li>
1347 <li>RSA</li>
1348 <li>Secp256k1</li>
1349 <li>Secp256r1 (a.k.a. NIST P-256)</li>
1350 <li>Secp384r1 (a.k.a. NIST P-384)</li>
1351 <li>Secp521r1 (a.k.a. NIST P-521)</li>
1352 </ul>
1353
1354 <p>
1355 Diffie-Hellman key exchange:
1356 </p>
1357 <ul class="org-ul">
1358 <li>Curve25519</li>
1359 <li>Curve448</li>
1360 <li>Elgamal</li>
1361 <li>Secp256k1</li>
1362 <li>Secp256r1 (a.k.a. NIST P-256)</li>
1363 <li>Secp384r1 (a.k.a. NIST P-384)</li>
1364 <li>Secp521r1 (a.k.a. NIST P-521)</li>
1365 </ul>
1366 </div>
1367 <div id="outline-container-orgf7c1959" class="outline-3">
1368 <h3 id="orgf7c1959">Key pair generation</h3>
1369 <div class="outline-text-3" id="text-orgf7c1959">
1370 <div class="org-src-container">
1371 <pre class="src src-lisp" id="org3dec0c7">(generate-key-pair kind <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> num-bits <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; private-key, public-key
1372 </pre>
1373 </div>
1374
1375 <p>
1376 Return a key pair according to <i>kind</i>. The generation of DSA, Elgamal
1377 and RSA key pairs can take some time. If <i>kind</i> is <code>:dsa</code> or <code>:rsa</code>,
1378 the <i>num-bits</i> key argument indicating the size of the keys to
1379 generate must be specified. If <i>kind</i> is <code>:elgamal</code>, <i>num-bits</i> must
1380 be specified unless <i>compatible-with-key</i> is specified, in which case
1381 the group parameters are taken from the specified key instead of being
1382 generated.
1383 </p>
1384
1385 <p>
1386 For example, if Alice wants to generate a key pair for
1387 a Diffie-Hellman exchange with Bob's Elgamal key pair:
1388 </p>
1389 <pre class="example" id="org68b3971">
1390 (generate-key-pair :elgamal :compatible-with-key bob-public-key)
1391 </pre>
1392
1393
1394 <div class="org-src-container">
1395 <pre class="src src-lisp" id="org7158eaf">(list-all-key-pair-kinds) =&gt; list
1396 </pre>
1397 </div>
1398
1399 <p>
1400 Returns a list of key pair kinds that may be validly passed to
1401 <a href="#org3dec0c7">generate-key-pair</a>.
1402 </p>
1403 </div>
1404 <div id="outline-container-org0191a1b" class="outline-4">
1405 <h4 id="org0191a1b">Key construction</h4>
1406 <div class="outline-text-4" id="text-org0191a1b">
1407 <div class="org-src-container">
1408 <pre class="src src-lisp" id="org6bca683">(make-public-key kind <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; public-key
1409 </pre>
1410 </div>
1411
1412 <p>
1413 Return a public key according to <i>kind</i>. The <i>&amp;key</i>
1414 arguments vary according to <i>kind</i>. The interesting bits are in the
1415 methods that specialize on <i>kind</i>, below.
1416 </p>
1417
1418 <pre class="example" id="org3e6e3b5">
1419 (make-public-key :curve25519 &amp;key y) =&gt; public-key
1420 (make-public-key :curve448 &amp;key y) =&gt; public-key
1421 (make-public-key :dsa &amp;key p q g y) =&gt; public-key
1422 (make-public-key :ed25519 &amp;key y) =&gt; public-key
1423 (make-public-key :ed448 &amp;key y) =&gt; public-key
1424 (make-public-key :elgamal &amp;key p g y) =&gt; public-key
1425 (make-public-key :rsa &amp;key e n) =&gt; public-key
1426 (make-public-key :secp256k1 &amp;key y) =&gt; public-key
1427 (make-public-key :secp256r1 &amp;key y) =&gt; public-key
1428 (make-public-key :secp384r1 &amp;key y) =&gt; public-key
1429 (make-public-key :secp521r1 &amp;key y) =&gt; public-key
1430 </pre>
1431
1432
1433 <div class="org-src-container">
1434 <pre class="src src-lisp" id="org59929bc">(make-private-key kind <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; private-key
1435 </pre>
1436 </div>
1437
1438 <p>
1439 Return a private key according to <i>kind</i>. The <i>&amp;key</i> arguments vary
1440 according to <i>kind</i>. The interesting bits are in the methods that
1441 specialize on <i>kind</i>, below.
1442 </p>
1443
1444 <pre class="example" id="org96ff947">
1445 (make-private-key :curve25519 &amp;key x y) =&gt; private-key
1446 (make-private-key :curve448 &amp;key x y) =&gt; private-key
1447 (make-private-key :dsa &amp;key p q g y x) =&gt; private-key
1448 (make-private-key :ed25519 &amp;key x y) =&gt; private-key
1449 (make-private-key :ed448 &amp;key x y) =&gt; private-key
1450 (make-private-key :elgamal &amp;key p g y x) =&gt; private-key
1451 (make-private-key :rsa &amp;key d n p q) =&gt; private-key
1452 (make-private-key :secp256k1 &amp;key x y) =&gt; private-key
1453 (make-private-key :secp256r1 &amp;key x y) =&gt; private-key
1454 (make-private-key :secp384r1 &amp;key x y) =&gt; private-key
1455 (make-private-key :secp521r1 &amp;key x y) =&gt; private-key
1456 </pre>
1457
1458
1459 <p>
1460 For Curve25519, Curve448, Ed25519, Ed448 keys, Secp256k1, Secp256r1, Secp384r1
1461 and Secp521r1, the type of the parameters is
1462 <code>(simple-array (unsigned-byte 8) (*))</code>:
1463 </p>
1464 <ul class="org-ul">
1465 <li><i>x</i>, the secret key</li>
1466 <li><i>y</i>, the public key</li>
1467 </ul>
1468
1469 <p>
1470 For DSA and Elgamal keys, the type of the parameters is <code>integer</code>:
1471 </p>
1472 <ul class="org-ul">
1473 <li><i>p</i>, the prime number defining the DL group</li>
1474 <li><i>q</i>, the prime number defining the DL sub-group</li>
1475 <li><i>g</i>, the generator</li>
1476 <li><i>y</i>, the public key</li>
1477 <li><i>x</i>, the private key</li>
1478 </ul>
1479
1480 <p>
1481 For RSA keys, the type of the parameters is <code>integer</code>:
1482 </p>
1483 <ul class="org-ul">
1484 <li><i>n</i>, the modulus</li>
1485 <li><i>e</i>, the public key</li>
1486 <li><i>d</i>, the private key</li>
1487 <li><i>p</i>, the first prime factor of <i>n</i></li>
1488 <li><i>q</i>, the second prime factor of <i>n</i></li>
1489 </ul>
1490 </div>
1491 </div>
1492 <div id="outline-container-org3ab9605" class="outline-4">
1493 <h4 id="org3ab9605">Key destructuring</h4>
1494 <div class="outline-text-4" id="text-org3ab9605">
1495 <p>
1496 The <a href="#org35e890d">destructure-public-key</a> and <a href="#orgf52139e">destructure-private-key</a> functions can
1497 be useful if you need to store keys somewhere for future use.
1498 </p>
1499
1500 <div class="org-src-container">
1501 <pre class="src src-lisp" id="org35e890d">(destructure-public-key public-key) =&gt; plist
1502 </pre>
1503 </div>
1504
1505 <p>
1506 Return the elements of a public key in a plist. The indicators of the
1507 plist match the <i>&amp;key</i> arguments of the <a href="#org6bca683">make-public-key</a> method.
1508 </p>
1509
1510
1511 <div class="org-src-container">
1512 <pre class="src src-lisp" id="orgf52139e">(destructure-private-key private-key) =&gt; plist
1513 </pre>
1514 </div>
1515
1516 <p>
1517 Return the elements of a private key in a plist. The indicators of the
1518 plist match the <i>&amp;key</i> arguments of the <a href="#org59929bc">make-private-key</a> method.
1519 </p>
1520 </div>
1521 </div>
1522 </div>
1523 <div id="outline-container-orgc179c55" class="outline-3">
1524 <h3 id="orgc179c55">Digital signatures</h3>
1525 <div class="outline-text-3" id="text-orgc179c55">
1526 <div class="org-src-container">
1527 <pre class="src src-lisp" id="org6d2558f">(sign-message key message <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; signature
1528 </pre>
1529 </div>
1530
1531 <p>
1532 Return a signature of <i>message</i> between <i>start</i> and <i>end</i> signed with
1533 <i>key</i>; the class of <i>key</i> determines the algorithm used to create the
1534 <i>signature</i>.
1535 </p>
1536
1537 <p>
1538 <span class="underline">Note:</span> The <a href="#org6d2558f">sign-message</a> does not perform the hashing of the data. You
1539 should hash your data using your favorite hash function, and then use
1540 this hash as the <i>message</i> passed to <a href="#org6d2558f">sign-message</a>.
1541 </p>
1542
1543
1544 <div class="org-src-container">
1545 <pre class="src src-lisp" id="orgf029208">(verify-signature key message signature <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; boolean
1546 </pre>
1547 </div>
1548
1549 <p>
1550 Verify whether <i>signature</i> is a valid signature of <i>message</i> between
1551 <i>start</i> and <i>end</i> using <i>key</i>. Return <code>t</code> is the signature is valid
1552 and <code>nil</code> otherwise.
1553 </p>
1554 </div>
1555 <div id="outline-container-org5339bb4" class="outline-4">
1556 <h4 id="org5339bb4">Padding</h4>
1557 <div class="outline-text-4" id="text-org5339bb4">
1558 <p>
1559 To be secure, RSA signature requires the message to be padded.
1560 The <i>pss</i> key parameter is provided to pad (or unpad) the message
1561 during signature (or verification) with the PSS scheme of PKCS-1.
1562 The value of the <i>pss</i> key parameter can be either a digest name
1563 or <code>t</code> (which will use the sha1 digest).
1564 </p>
1565
1566 <pre class="example" id="org34ea6e9">
1567 (sign-message rsa-private-key message :pss t) =&gt; signature
1568 (verify-signature rsa-public-key message signature :pss t) =&gt; boolean
1569 </pre>
1570
1571 <p>
1572 The functions <i>pss-encode</i> and <i>pss-decode</i> can also be used by hand if
1573 necessary.
1574 </p>
1575 </div>
1576 </div>
1577 <div id="outline-container-org35d622b" class="outline-4">
1578 <h4 id="org35d622b">Signature nonce</h4>
1579 <div class="outline-text-4" id="text-org35d622b">
1580 <p>
1581 DSA, Elgamal and ECDSA (Secp256k1, Secp256r1, Secp384r1 and Secp521r1)
1582 signatures require the generation of a nonce. You must never sign two different
1583 messages with the same key and the same nonce, or anyone having these two
1584 signatures will be able compute your private key. Ironclad uses the
1585 <a href="#org432e2f4">generate-signature-nonce</a> method which by default generates random nonces.
1586 </p>
1587
1588 <div class="org-src-container">
1589 <pre class="src src-lisp" id="org432e2f4">(generate-signature-nonce (key message <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> parameters)) =&gt; nonce
1590 </pre>
1591 </div>
1592
1593 <p>
1594 For DSA, <i>parameters</i> is <i>q</i>. For Elgamal, <i>parameters</i> is <i>p</i>. For ECDSA,
1595 <i>parameters</i> is <code>nil</code>.
1596 </p>
1597
1598
1599 <p>
1600 If instead of random nonces, you want to have deterministic nonces (e.g. like
1601 in RFC 6979), you will have to redefine <a href="#org432e2f4">generate-signature-nonce</a>. For example,
1602 to have deterministic nonces for Secp256k1 ECDSA signatures, you could do
1603 something like:
1604 </p>
1605
1606 <pre class="example" id="org3692b97">
1607 (defmethod generate-signature-nonce ((key secp256k1-private-key) message &amp;optional parameters)
1608 (declare (ignore parameters))
1609 (compute-deterministic-nonce key message))
1610 </pre>
1611 </div>
1612 </div>
1613 <div id="outline-container-orgf19958c" class="outline-4">
1614 <h4 id="orgf19958c">Format of signatures</h4>
1615 <div class="outline-text-4" id="text-orgf19958c">
1616 <p>
1617 <a href="#org6d2558f">sign-message</a> returns signatures as octet vectors. When the signature
1618 contains several values (e.g. the R and S values of DSA signatures),
1619 the octet vector is the concatenation of these values (e.g. the first
1620 half of the vector is the R value, the second half is the S value).
1621 You can use the <a href="#orgfa225d8">make-signature</a> and <a href="#orgc5506b9">destructure-signature</a> functions if
1622 you need access to the elements of a signature (e.g. to use
1623 a different kind of serialization).
1624 </p>
1625
1626
1627 <div class="org-src-container">
1628 <pre class="src src-lisp" id="orgfa225d8">(make-signature kind <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; signature
1629 </pre>
1630 </div>
1631
1632 <p>
1633 Return an octet vector representing a signature. The <i>&amp;key</i> arguments
1634 vary according to <i>kind</i>. The interesting bits are in the methods that
1635 specialize on <i>kind</i>, below.
1636 </p>
1637
1638 <pre class="example" id="org090baba">
1639 (make-signature :dsa &amp;key r s n-bits) =&gt; signature
1640 (make-signature :ed25519 &amp;key r s) =&gt; signature
1641 (make-signature :ed448 &amp;key r s) =&gt; signature
1642 (make-signature :elgamal &amp;key r s n-bits) =&gt; signature
1643 (make-signature :rsa &amp;key s n-bits) =&gt; signature
1644 (make-signature :secp256k1 &amp;key r s) =&gt; signature
1645 (make-signature :secp256r1 &amp;key r s) =&gt; signature
1646 (make-signature :secp384r1 &amp;key r s) =&gt; signature
1647 (make-signature :secp521r1 &amp;key r s) =&gt; signature
1648 </pre>
1649
1650 <p>
1651 For Ed25519, Ed448, Secp256k1, Secp256r1, Secp384r1 and Secp521r1 signatures,
1652 the type of the parameters <i>r</i> and <i>s</i> is
1653 <code>(simple-array (unsigned-byte 8) (*))</code>.
1654 </p>
1655
1656 <p>
1657 For DSA and Elgamal signatures, the type of the parameters <i>r</i>, <i>s</i>
1658 and <i>n-bits</i> is <code>integer</code>.
1659 </p>
1660
1661 <p>
1662 For RSA signatures, the type of the parameters <i>s</i> and <i>n-bits</i> is
1663 <code>integer</code>.
1664 </p>
1665
1666
1667 <div class="org-src-container">
1668 <pre class="src src-lisp" id="orgc5506b9">(destructure-signature kind signature) =&gt; plist
1669 </pre>
1670 </div>
1671
1672 <p>
1673 Return the elements of a signature in a plist. The indicators of the
1674 plist match the <i>&amp;key</i> arguments of the <a href="#orgfa225d8">make-signature</a> method.
1675 </p>
1676 </div>
1677 </div>
1678 </div>
1679 <div id="outline-container-org2a13b46" class="outline-3">
1680 <h3 id="org2a13b46">Encryption and decryption</h3>
1681 <div class="outline-text-3" id="text-org2a13b46">
1682 <div class="org-src-container">
1683 <pre class="src src-lisp" id="org6424db2">(encrypt-message key message <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; encrypted-message
1684 </pre>
1685 </div>
1686
1687 <p>
1688 Return the <i>message</i> between <i>start</i> and <i>end</i> encrypted with the <i>key</i>;
1689 the class of <i>key</i> determines the algorithm used to encrypt the message.
1690 </p>
1691
1692
1693 <div class="org-src-container">
1694 <pre class="src src-lisp" id="org13a3a49">(decrypt-message key message <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end n-bits <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; decrypted-message
1695 </pre>
1696 </div>
1697
1698 <p>
1699 Return the <i>message</i> between <i>start</i> and <i>end</i> decrypted by the <i>key</i>;
1700 the class of <i>key</i> determines the algorithm used to decrypt the message.
1701 <i>n-bits</i> can be used to indicate the expected size of the decrypted
1702 message (e.g. a small byte vector starting with zeros encrypted
1703 without padding, which is probably a bad idea, c.f. Padding section).
1704 </p>
1705 </div>
1706 <div id="outline-container-org113df61" class="outline-4">
1707 <h4 id="org113df61">Padding</h4>
1708 <div class="outline-text-4" id="text-org113df61">
1709 <p>
1710 To be secure, RSA encryption requires the message to be padded. The
1711 <i>oaep</i> key parameter is provided to pad (or unpad) the message during
1712 encryption (or decryption) with the OAEP scheme of PKCS-1.
1713 The value of the <i>oaep</i> key parameter can be either a digest name
1714 or <code>t</code> (which will use the sha1 digest).
1715 </p>
1716
1717 <pre class="example" id="org2c2f3ec">
1718 (encrypt-message rsa-public-key message :oaep t) =&gt; encrypted-message
1719 (decrypt-message rsa-private-key message :oaep t) =&gt; decrypted-message
1720 </pre>
1721
1722 <p>
1723 The functions <i>oaep-encode</i> and <i>oaep-decode</i> can also be used by hand if
1724 necessary.
1725 </p>
1726 </div>
1727 </div>
1728 <div id="outline-container-orgea18398" class="outline-4">
1729 <h4 id="orgea18398">Format of messages</h4>
1730 <div class="outline-text-4" id="text-orgea18398">
1731 <p>
1732 <a href="#org6424db2">encrypt-message</a> returns encrypted messages as octet vectors. When the
1733 message contains several values (e.g. the C1 and C2 values of Elgamal
1734 messages), the octet vector is the concatenation of these values (e.g.
1735 the first half of the vector is the big-endian representation of the
1736 C1 value, the second half is the C2 value). You can use the
1737 <a href="#org83c91f2">make-message</a> and <a href="#orgc65f9d9">destructure-message</a> functions if you need access to
1738 the elements of a message (e.g. to use a different kind of
1739 serialization).
1740 </p>
1741
1742
1743 <div class="org-src-container">
1744 <pre class="src src-lisp" id="org83c91f2">(make-message kind <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; message
1745 </pre>
1746 </div>
1747
1748 <p>
1749 Return an octet vector representing a message. The <i>&amp;key</i> arguments
1750 vary according to <i>kind</i>. The interesting bits are in the methods that
1751 specialize on <i>kind</i>, below.
1752 </p>
1753
1754 <pre class="example" id="org7b37e36">
1755 (make-message :elgamal &amp;key c1 c2 n-bits) =&gt; message
1756 (make-message :rsa &amp;key m n-bits) =&gt; message
1757 </pre>
1758
1759 <p>
1760 For Elgamal messages, the type of the parameters <i>c1</i>, <i>c2</i> and
1761 <i>n-bits</i> is <code>integer</code>.
1762 </p>
1763
1764 <p>
1765 For RSA signatures, the type of the parameters <i>m</i> and <i>n-bits</i> is
1766 <code>integer</code>.
1767 </p>
1768
1769
1770 <div class="org-src-container">
1771 <pre class="src src-lisp" id="orgc65f9d9">(destructure-message kind message) =&gt; plist
1772 </pre>
1773 </div>
1774
1775 <p>
1776 Return the elements of a message in a plist. The indicators of the
1777 plist match the <i>&amp;key</i> arguments of the <a href="#org83c91f2">make-message</a> method.
1778 </p>
1779 </div>
1780 </div>
1781 </div>
1782 <div id="outline-container-org0cacffc" class="outline-3">
1783 <h3 id="org0cacffc">Diffie-Hellman key exchange</h3>
1784 <div class="outline-text-3" id="text-org0cacffc">
1785 <div class="org-src-container">
1786 <pre class="src src-lisp" id="org548e6ec">(diffie-hellman private-key public-key) =&gt; bytes
1787 </pre>
1788 </div>
1789
1790 <p>
1791 Return a secret shared by two users Alice and Bob, computed from
1792 Alice's private key and Bob's public key (these keys must be
1793 compatible, i.e. have the same group parameters).
1794 </p>
1795 </div>
1796 </div>
1797 <div id="outline-container-orge1daa32" class="outline-3">
1798 <h3 id="orge1daa32">Elliptic curve operations</h3>
1799 <div class="outline-text-3" id="text-orge1daa32">
1800 <div class="org-src-container">
1801 <pre class="src src-lisp" id="orgd4c1351">(ec-make-point kind <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> <span style="font-weight: bold; text-decoration: underline;">&amp;allow-other-keys</span>) =&gt; point
1802 </pre>
1803 </div>
1804
1805 <p>
1806 Return a point of <i>kind</i>, initialized according to the specified coordinates.
1807 The interesting bits are in the methods that specialize on <i>kind</i>, below.
1808 </p>
1809
1810 <pre class="example" id="org52b7109">
1811 (ec-make-point :curve25519 &amp;key x)
1812 (ec-make-point :curve448 &amp;key x)
1813 (ec-make-point :ed25519 &amp;key x y)
1814 (ec-make-point :ed448 &amp;key x y)
1815 (ec-make-point :secp256k1 &amp;key x y)
1816 (ec-make-point :secp256r1 &amp;key x y)
1817 (ec-make-point :secp384r1 &amp;key x y)
1818 (ec-make-point :secp521r1 &amp;key x y)
1819 </pre>
1820
1821 <p>
1822 The <i>x</i> and <i>y</i> parameters must be integers.
1823 </p>
1824
1825
1826 <div class="org-src-container">
1827 <pre class="src src-lisp" id="org8a1d525">(ec-destructure-point p) =&gt; plist
1828 </pre>
1829 </div>
1830
1831 <p>
1832 Return a plist containing the coordinates of the point <i>P</i>. The indicators of
1833 the plist match the <i>&amp;key</i> arguments of the <a href="#orgd4c1351">ec-make-point</a> method.
1834 </p>
1835
1836
1837 <div class="org-src-container">
1838 <pre class="src src-lisp" id="orgfe46874">(ec-point-on-curve p) =&gt; boolean
1839 </pre>
1840 </div>
1841
1842 <p>
1843 Return <code>t</code> if the point <i>P</i> is on the curve.
1844 </p>
1845
1846
1847 <div class="org-src-container">
1848 <pre class="src src-lisp" id="org8492328">(ec-point-equal p q) =&gt; boolean
1849 </pre>
1850 </div>
1851
1852 <p>
1853 Return <code>t</code> if <i>P</i> and <i>Q</i> represent the same point.
1854 </p>
1855
1856
1857 <div class="org-src-container">
1858 <pre class="src src-lisp" id="orgf27adea">(ec-double p) =&gt; point
1859 </pre>
1860 </div>
1861
1862 <p>
1863 Return the point 2 * <i>P</i>.
1864 </p>
1865
1866
1867 <div class="org-src-container">
1868 <pre class="src src-lisp" id="org57afb21">(ec-add p q) =&gt; point
1869 </pre>
1870 </div>
1871
1872 <p>
1873 Return the point <i>P</i> + <i>Q</i>.
1874 </p>
1875
1876
1877 <div class="org-src-container">
1878 <pre class="src src-lisp" id="orgd5e5266">(ec-scalar-mult p e) =&gt; point
1879 </pre>
1880 </div>
1881
1882 <p>
1883 Return the point <i>e</i> * <i>P</i>.
1884 </p>
1885
1886
1887 <div class="org-src-container">
1888 <pre class="src src-lisp" id="orgb624683">(ec-scalar-inv kind n) =&gt; integer
1889 </pre>
1890 </div>
1891
1892 <p>
1893 Return the modular inverse of <i>n</i>.
1894 </p>
1895
1896
1897 <div class="org-src-container">
1898 <pre class="src src-lisp" id="org9986a7c">(ec-encode-scalar kind n) =&gt; vector
1899 </pre>
1900 </div>
1901
1902 <p>
1903 Return an octet vector representing the integer <i>n</i>.
1904 </p>
1905
1906
1907 <div class="org-src-container">
1908 <pre class="src src-lisp" id="org03dc66c">(ec-decode-scalar kind octets) =&gt; integer
1909 </pre>
1910 </div>
1911
1912 <p>
1913 Return the integer represented by the <i>octets</i>.
1914 </p>
1915
1916
1917 <div class="org-src-container">
1918 <pre class="src src-lisp" id="org57b8ed7">(ec-encode-point p) =&gt; vector
1919 </pre>
1920 </div>
1921
1922 <p>
1923 Return an octet vector representing the point <i>P</i>.
1924 </p>
1925
1926
1927 <div class="org-src-container">
1928 <pre class="src src-lisp" id="orga0fac6b">(ec-decode-point kind octets) =&gt; point
1929 </pre>
1930 </div>
1931
1932 <p>
1933 Return the point represented by the <i>octets</i>.
1934 </p>
1935 </div>
1936 </div>
1937 </div>
1938 <div id="outline-container-pseudo-random-number-generation" class="outline-2">
1939 <h2 id="pseudo-random-number-generation">Pseudo-random number generation</h2>
1940 <div class="outline-text-2" id="text-pseudo-random-number-generation">
1941 <p>
1942 The <code>*prng*</code> special variable indicates which pseudo-random number
1943 generator is used by default by functions that need to generate some
1944 random data. It defaults to a sensible OS-specific value.
1945 </p>
1946
1947 <p>
1948 The vast, vast vast number of users should just use the default
1949 <code>os-prng</code> (which uses <code>/dev/urandom</code> on Unix and <code>CryptGenRandom</code> on
1950 Windows). For users who need <i>deterministic</i>,
1951 high-quality-random-seeming numbers (e.g. for Monte Carlo
1952 simulations), <code>fortuna-generator</code> is provided. Finally, if you're
1953 running on a platform without a decent PRNG (these are few and far
1954 between now), you may require the full <code>fortuna-prng</code>. When in doubt,
1955 use <code>os-prng</code>, which is the default.
1956 </p>
1957
1958
1959 <div class="org-src-container">
1960 <pre class="src src-lisp" id="org4ee888f">(make-prng name <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> seed) =&gt; prng
1961 </pre>
1962 </div>
1963
1964 <p>
1965 Create a pseudo-random number generator.
1966 </p>
1967
1968 <p>
1969 <i>name</i> denotes the style of PRNG to use. <a href="#org9a97a96">list-all-prngs</a> will tell you
1970 the names of all supported PRNGs. Currently supported PRNGs are:
1971 </p>
1972 <ul class="org-ul">
1973 <li>OS</li>
1974 <li>Fortuna</li>
1975 <li>Fortuna-generator</li>
1976 </ul>
1977
1978 <p>
1979 <i>name</i> can be a symbol in the <code>keyword</code> package or in the <code>ironclad</code>
1980 package.
1981 </p>
1982
1983 <p>
1984 <i>seed</i> is a <b>seed descriptor</b>. If <code>nil</code>, the PRNG will not be seeded
1985 (which may prevent it from generating output until it is seeded,
1986 depending on the PRNG in question). If <code>:random</code> then the PRNG will be
1987 seeded with the OS's cryptographically-secure PRNG. If <code>:urandom</code> then
1988 the PRNG will be seeded with the OS's fast-but-potentially-less-secure
1989 PRNG, if available (if not, will fallback to <code>:random</code>). If it is
1990 a pathname indicator, a seed will be read from the indicated file,
1991 then a new seed will be generated and written back to the file
1992 (over-writing the old seed). Finally, if it is a byte vector, it will
1993 be used to seed the PRNG.
1994 </p>
1995
1996 <p>
1997 In single-threaded applications, you should very rarely need to call <a href="#org4ee888f">make-prng</a>;
1998 the default OS-provided PRNG should be appropriate in nearly all cases.
1999 </p>
2000
2001 <p>
2002 In multi-threaded applications, each thread that will use functions requiring
2003 random data must have its own PRNG, or several threads might generate the same
2004 "random" data. If the threads are created using the <b>bordeaux-threads</b> library
2005 (or by a library using <b>bordeaux-threads</b>, like <b>lparallel</b>), this is done
2006 automatically. However, if you are using the threading functions of your Common
2007 Lisp implementation directly, you have to bind the <code>*prng*</code> special variable to
2008 a new PRNG in each thread. For example:
2009 </p>
2010
2011 <pre class="example" id="org1e42bc7">
2012 (make-thread (lambda ()
2013 (let ((crypto:*prng* (crypto:make-prng :os)))
2014 (forms-for-thread-1))))
2015
2016 (make-thread (lambda ()
2017 (let ((crypto:*prng* (crypto:make-prng :os)))
2018 (forms-for-thread-2))))
2019 </pre>
2020
2021
2022 <div class="org-src-container">
2023 <pre class="src src-lisp" id="org9a97a96">(list-all-prngs) =&gt; list
2024 </pre>
2025 </div>
2026
2027 <p>
2028 List all known PRNG types.
2029 </p>
2030
2031
2032 <div class="org-src-container">
2033 <pre class="src src-lisp" id="orgfd526f2">(random-data num-bytes <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> prng) =&gt; bytes
2034 </pre>
2035 </div>
2036
2037 <p>
2038 Generate <i>num-bytes</i> bytes of random data from <i>prng</i>. Updates the
2039 state of the generator.
2040 </p>
2041
2042
2043 <div class="org-src-container">
2044 <pre class="src src-lisp" id="org08902cc">(random-bits num-bits <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> prng) =&gt; integer
2045 </pre>
2046 </div>
2047
2048 <p>
2049 Generate an integer with <i>num-bits</i> bits.
2050 </p>
2051
2052
2053 <div class="org-src-container">
2054 <pre class="src src-lisp" id="orgb10722e">(strong-random limit <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> prng) =&gt; number
2055 </pre>
2056 </div>
2057
2058 <p>
2059 A drop-in replacement for <code>common-lisp:random</code>, <a href="#orgb10722e">strong-random</a>
2060 generates a number (an integer if <i>limit</i> is an integer and a float if
2061 it is a float) between 0 and <i>limit</i> - 1 in an unbiased fashion.
2062 </p>
2063
2064
2065 <div class="org-src-container">
2066 <pre class="src src-lisp" id="org45267a2">(read-os-random-seed source <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> prng) =&gt; reseed-count
2067 </pre>
2068 </div>
2069
2070 <p>
2071 Read an OS-provided random seed (from <code>/dev/urandom</code> or <code>/dev/random</code>
2072 on Unix; <code>CryptGenRandom</code> on Windows) and reseed <i>prng</i>.
2073 </p>
2074
2075 <p>
2076 <i>source</i> may be <code>:random</code>, which indicates <code>/dev/random</code> or
2077 <code>:urandom</code>, which indicates <code>/dev/urandom</code>. On Windows,
2078 <code>CryptGenRandom</code> is always used.
2079 </p>
2080
2081
2082 <div class="org-src-container">
2083 <pre class="src src-lisp" id="orgd02ec72">(read-seed path <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> prng) =&gt; t
2084 </pre>
2085 </div>
2086
2087 <p>
2088 Read enough bytes from <i>path</i> to reseed <i>prng</i>, then generate
2089 a pseudo-random seed and write it back to <i>path</i>. If <i>path</i> doesn't
2090 exist, calls <a href="#org45267a2">read-os-random-seed</a> to get a truly random seed from the
2091 OS. Note that reseeding does <b>not</b> reset the generator's state to the
2092 seed value; rather, it <b>combines</b> the generator's state with the seed
2093 to form a new state.
2094 </p>
2095
2096
2097 <div class="org-src-container">
2098 <pre class="src src-lisp" id="org72ddf09">(write-seed path <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> prng) =&gt; t
2099 </pre>
2100 </div>
2101
2102 <p>
2103 Generate enough random data to reseed <i>prng</i>, then write it to <i>path</i>.
2104 </p>
2105 </div>
2106 <div id="outline-container-orgeaea09e" class="outline-3">
2107 <h3 id="orgeaea09e">Example</h3>
2108 <div class="outline-text-3" id="text-orgeaea09e">
2109 <pre class="example" id="orgd2bf300">
2110 (crypto:random-data 16)
2111 =&gt; #(61 145 133 130 220 200 90 86 0 101 62 169 0 40 101 78)
2112
2113 (crypto:strong-random 16)
2114 =&gt; 3
2115
2116 (crypto:random-bits 16)
2117 =&gt; 41546
2118 </pre>
2119 </div>
2120 </div>
2121 <div id="outline-container-org2906e6e" class="outline-3">
2122 <h3 id="org2906e6e">Fortuna</h3>
2123 <div class="outline-text-3" id="text-org2906e6e">
2124 <p>
2125 You should only use the Fortuna PRNG if your OS does not provided
2126 a sufficiently-good PRNG. If you use a Unix or Unix-like OS (e.g.
2127 Linux), macOS or Windows, it does. Only use the Fortuna PRNG if you
2128 know for certain that you need it.
2129 </p>
2130
2131 <p>
2132 Fortuna is a cryptographically-secure random number presented by
2133 Ferguson, Schneier and Kohno in <i>Cryptography Engineering</i>. It is
2134 built around 32 entropy pools, which are used with decreasing
2135 frequency for each reseed (e.g. pool 0 is used in each reseed, pool
2136 1 in every other reseed, pool 2 in every fourth reseed and so forth).
2137 Pools are seeded with data from up to 256 sources.
2138 </p>
2139
2140 <p>
2141 Each application should have one or more entropy sources (say, one for
2142 each OS random number source, one for the low bits of the current
2143 time, one for the output of a particular command or group of commands
2144 and so forth). A source should be used to add randomness to each pool
2145 in order, so source 0 should top up pool 0, then pool 1, and so forth
2146 up to pool 31, then loop back to pool 1 again. Be very careful to
2147 spread entropy across all 32 pools.
2148 </p>
2149
2150 <p>
2151 Fortuna automatically feeds entropy from the pools back into its
2152 random state when <a href="#orgfd526f2">random-data</a> is called, using a method designed to
2153 make it resistant to various avenues of attack; even in case of
2154 generator compromise it will return to a safe state within a bounded
2155 time.
2156 </p>
2157
2158 <p>
2159 For purposes of reseeding, Fortuna will not reseed until the first
2160 pool contains 128 bits of entropy; <code>+min-pool-size+</code> sets the number
2161 of bytes this is; it defaults to a very conservative 128, meaning that
2162 by default each byte of event is assumed to contain a single bit of
2163 randomness.
2164 </p>
2165
2166 <p>
2167 It also will not reseed more than ten times per second.
2168 </p>
2169
2170
2171 <div class="org-src-container">
2172 <pre class="src src-lisp" id="org32bf024">(add-random-event source pool-id event <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> prng) =&gt; pool-length
2173 </pre>
2174 </div>
2175
2176 <p>
2177 Add entropy to <i>prng</i>.
2178 </p>
2179
2180 <p>
2181 <i>source</i> is an integer in the range 0-255 specifiying the event's
2182 application-defined source.
2183 </p>
2184
2185 <p>
2186 <i>pool-id</i> is an integer in the range 0-31 specifying the pool to top
2187 up.
2188 </p>
2189
2190 <p>
2191 <i>event</i> is up to 32 bytes of data (for longer events, hash them down
2192 or break them up into chunks).
2193 </p>
2194 </div>
2195 </div>
2196 </div>
2197 <div id="outline-container-gray-streams" class="outline-2">
2198 <h2 id="gray-streams">Gray streams</h2>
2199 <div class="outline-text-2" id="text-gray-streams">
2200 <p>
2201 Ironclad includes support for several convenient stream abstractions
2202 based on Gray streams. Gray streams support in Ironclad is included
2203 for SBCL, CMUCL, OpenMCL/CCL, Lispworks, ABCL, ECL, Clisp and Allegro.
2204 </p>
2205 </div>
2206 <div id="outline-container-org3fe7833" class="outline-3">
2207 <h3 id="org3fe7833">Octet streams</h3>
2208 <div class="outline-text-3" id="text-org3fe7833">
2209 <p>
2210 Octet streams are very similar to Common Lisp's <code>string-stream</code> except
2211 they deal in octets instead of characters.
2212 </p>
2213
2214
2215 <div class="org-src-container">
2216 <pre class="src src-lisp" id="orgc6bae48">(make-octet-input-stream buffer <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> start end) =&gt; octet-input-stream
2217 </pre>
2218 </div>
2219
2220 <p>
2221 As <code>make-string-input-stream</code>, only with octets instead of characters.
2222 </p>
2223
2224
2225 <div class="org-src-container">
2226 <pre class="src src-lisp" id="orgedb3b46">(make-octet-output-stream) =&gt; octet-output-stream
2227 </pre>
2228 </div>
2229
2230 <p>
2231 As <code>make-string-output-stream</code>, only with octets instead of characters.
2232 </p>
2233
2234
2235 <div class="org-src-container">
2236 <pre class="src src-lisp" id="org6539129">(get-output-stream-octets stream) =&gt; octet-vector
2237 </pre>
2238 </div>
2239
2240 <p>
2241 As <code>get-output-stream-string</code>, only with an octet output-steam instead
2242 of a string output-stream.
2243 </p>
2244
2245
2246 <div class="org-src-container">
2247 <pre class="src src-lisp" id="org708201e">(<span style="font-weight: bold;">with-octet-input-stream</span> ((var buffer <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> (start 0) end) <span style="font-weight: bold; text-decoration: underline;">&amp;body</span> body))
2248 </pre>
2249 </div>
2250
2251 <p>
2252 Within <i>body</i>, <i>var</i> is bound to an octet input stream. Reading from
2253 <i>var</i> gives the bytes between the indexes <i>start</i> and <i>end</i> of
2254 <i>buffer</i>. The result of the last form of <i>body</i> is returned.
2255 </p>
2256
2257
2258 <div class="org-src-container">
2259 <pre class="src src-lisp" id="orge11cc14">(<span style="font-weight: bold;">with-octet-output-stream</span> ((var) <span style="font-weight: bold; text-decoration: underline;">&amp;body</span> body)) =&gt; bytes
2260 </pre>
2261 </div>
2262
2263 <p>
2264 Within <i>body</i>, <i>var</i> is bound to an octet output stream. After all the
2265 forms in <i>body</i> have been executed, the data that has been written to
2266 <i>var</i> (and that hasn't been consumed by a call to
2267 <a href="#org6539129">get-output-stream-octets</a> within <i>body</i>) is returned.
2268 </p>
2269 </div>
2270 </div>
2271 <div id="outline-container-org075795b" class="outline-3">
2272 <h3 id="org075795b">Digest streams</h3>
2273 <div class="outline-text-3" id="text-org075795b">
2274 <p>
2275 Digest streams compute a digest of the data written to them according
2276 to a specific digest algorithm.
2277 </p>
2278
2279 <p>
2280 Example:
2281 </p>
2282 <pre class="example" id="org9ad0284">
2283 (defun frobbing-function (stream)
2284 ;; We want to compute a digest of the data being written to STREAM
2285 ;; without involving our callees in the process.
2286 (let* ((digesting-stream (crypto:make-digesting-stream :sha1))
2287 (stream (make-broadcast-stream stream digesting-stream)))
2288 ;; Feed data to STREAM.
2289 (frob-guts stream)
2290 ;; Do something with the digest computed.
2291 (... (crypto:produce-digest digesting-stream) ...)
2292 ...))
2293 </pre>
2294
2295
2296 <div class="org-src-container">
2297 <pre class="src src-lisp" id="org134ed18">(make-digesting-stream digest <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> args) =&gt; stream
2298 </pre>
2299 </div>
2300
2301 <p>
2302 Make a stream that computes a digest of the data written to it
2303 according to the algorithm <i>digest</i>. The parameters that can be used
2304 by some algorithms can be specified as <i>args</i>.
2305 <a href="#orgebfad7a">produce-digest</a> may be used to obtain a digest of all the data written
2306 to the stream.
2307 </p>
2308
2309 <p>
2310 <span class="underline">Note:</span> Calling <a href="#orgebfad7a">produce-digest</a> on a digest stream does not alter
2311 the internal state of the digest.
2312 </p>
2313
2314
2315 <div class="org-src-container">
2316 <pre class="src src-lisp" id="org5e3aedc">(<span style="font-weight: bold;">with-digesting-stream</span> (var digest-name <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> args) <span style="font-weight: bold; text-decoration: underline;">&amp;body</span> body) =&gt; digest
2317 </pre>
2318 </div>
2319
2320 <p>
2321 Within <i>body</i>, <i>var</i> is bound to a digesting stream for the
2322 <i>digest-name</i> algorithm. After all the forms in <i>body</i> have been
2323 executed, the digest of the data that has been written to <i>var</i> is
2324 returned.
2325 </p>
2326 </div>
2327 </div>
2328 <div id="outline-container-orga5b95e6" class="outline-3">
2329 <h3 id="orga5b95e6">Cipher streams</h3>
2330 <div class="outline-text-3" id="text-orga5b95e6">
2331 <p>
2332 Cipher streams encrypt or decrypt the data written to or read from
2333 them according to a specific cipher algorithm.
2334 </p>
2335
2336
2337 <div class="org-src-container">
2338 <pre class="src src-lisp" id="org1f817c7">(make-encrypting-stream stream cipher mode key <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> initialization-vector direction) =&gt; stream
2339 </pre>
2340 </div>
2341
2342 <p>
2343 Make a stream wrapped around the binary stream <i>stream</i> that encrypts
2344 data according to the algorithm <i>cipher</i> initialized with a <i>mode</i>,
2345 a <i>key</i> and an <i>initialization-vector</i>.
2346 If <i>direction</i> is <code>:input</code>, the data read from the created input
2347 stream is the encryption of the data coming from <i>stream</i>.
2348 If <i>direction</i> is <code>:output</code>, the data written to the created output
2349 stream is encrypted before being sent to <i>stream</i>.
2350 </p>
2351
2352
2353 <div class="org-src-container">
2354 <pre class="src src-lisp" id="org13e52cb">(make-decrypting-stream stream cipher mode key <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> initialization-vector direction) =&gt; stream
2355 </pre>
2356 </div>
2357
2358 <p>
2359 Make a stream wrapped around the binary stream <i>stream</i> that decrypts
2360 data according to the algorithm <i>cipher</i> initialized with a <i>mode</i>,
2361 a <i>key</i> and an <i>initialization-vector</i>.
2362 If <i>direction</i> is <code>:input</code>, the data read from the created input
2363 stream is the decryption of the data coming from <i>stream</i>.
2364 If <i>direction</i> is <code>:output</code>, the data written to the created output
2365 stream is decrypted before being sent to <i>stream</i>.
2366 </p>
2367
2368
2369 <p>
2370 <span class="underline">Note:</span> Only stream ciphers and block ciphers in CTR, CFB, CFB8 or OFB mode are
2371 supported by <a href="#org1f817c7">make-encrypting-stream</a> and <a href="#org13e52cb">make-decrypting-stream</a>.
2372 </p>
2373
2374
2375 <div class="org-src-container">
2376 <pre class="src src-lisp" id="orgb305607">(<span style="font-weight: bold;">with-encrypting-stream</span> ((var stream cipher mode key <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> initialization-vector direction) <span style="font-weight: bold; text-decoration: underline;">&amp;body</span> body))
2377 </pre>
2378 </div>
2379
2380 <p>
2381 Within <i>body</i>, <i>var</i> is bound to an encrypting stream. The result of
2382 the last form of <i>body</i> is returned.
2383 </p>
2384
2385
2386 <div class="org-src-container">
2387 <pre class="src src-lisp" id="org740784d">(<span style="font-weight: bold;">with-decrypting-stream</span> ((var stream cipher mode key <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> initialization-vector direction) <span style="font-weight: bold; text-decoration: underline;">&amp;body</span> body))
2388 </pre>
2389 </div>
2390
2391 <p>
2392 Within <i>body</i>, <i>var</i> is bound to a decrypting stream. The result of
2393 the last form of <i>body</i> is returned.
2394 </p>
2395 </div>
2396 </div>
2397 <div id="outline-container-orgf02e2a0" class="outline-3">
2398 <h3 id="orgf02e2a0">MAC streams</h3>
2399 <div class="outline-text-3" id="text-orgf02e2a0">
2400 <p>
2401 MAC streams compute a message authentication code of the data written
2402 to them according to a specific MAC algorithm.
2403 </p>
2404
2405 <div class="org-src-container">
2406 <pre class="src src-lisp" id="orgf461878">(make-authenticating-stream mac key <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> args) =&gt; stream
2407 </pre>
2408 </div>
2409
2410 <p>
2411 Make a stream that computes a MAC of the data written to it according
2412 to the algorithm <i>mac</i> initialized with a <i>key</i>. The parameters used
2413 to create the MAC can be specified as <i>args</i>.
2414 <a href="#org967004b">produce-mac</a> may be used to obtain a MAC of all the data written to the
2415 stream.
2416 </p>
2417
2418 <p>
2419 <span class="underline">Note:</span> Calling <a href="#org967004b">produce-mac</a> on a MAC stream does not alter the
2420 internal state of the MAC.
2421 </p>
2422
2423
2424 <p>
2425 Example: encrypt some data and compute a MAC of the ciphertext
2426 </p>
2427 <pre class="example" id="org5dd37b0">
2428 (let* ((data ...)
2429 (output-stream ...)
2430 (encryption-key ...)
2431 (authentication-key ...)
2432 (iv ...)
2433 (mac-stream (make-authenticating-stream :hmac
2434 authentication-key
2435 :sha3))
2436 (stream (make-broadcast-stream output-stream mac-stream))
2437 (cipher-stream (make-encrypting-stream stream
2438 :chacha
2439 :stream
2440 encryption-key
2441 :initialization-vector iv)))
2442 (write-sequence data cipher-stream)
2443 ...
2444 (let ((mac (produce-mac mac-stream)))
2445 ...))
2446 </pre>
2447
2448
2449 <div class="org-src-container">
2450 <pre class="src src-lisp" id="orge31105c">(<span style="font-weight: bold;">with-authenticating-stream</span> (var mac-name key <span style="font-weight: bold; text-decoration: underline;">&amp;rest</span> args) <span style="font-weight: bold; text-decoration: underline;">&amp;body</span> body) =&gt; mac
2451 </pre>
2452 </div>
2453
2454 <p>
2455 Within <i>body</i>, <i>var</i> is bound to an authenticating stream for the
2456 <i>mac-name</i> algorithm. After all the forms in <i>body</i> have been
2457 executed, the message authentication code of the data that has been
2458 written to <i>var</i> is returned.
2459 </p>
2460 </div>
2461 </div>
2462 </div>
2463 <div id="outline-container-utility-functions" class="outline-2">
2464 <h2 id="utility-functions">Utility functions</h2>
2465 <div class="outline-text-2" id="text-utility-functions">
2466 <div class="org-src-container">
2467 <pre class="src src-lisp" id="org6226475">(ub16ref/le vector index) =&gt; value
2468 (ub32ref/le vector index) =&gt; value
2469 (ub64ref/le vector index) =&gt; value
2470 </pre>
2471 </div>
2472
2473 <p>
2474 This family of functions accesses an unsigned 16-bit, 32-bit or 64-bit
2475 value stored in little-endian order starting at <i>index</i> in <i>vector</i>.
2476 <i>vector</i> must be a <code>(simple-array (unsigned-byte 8) (*))</code>. These
2477 functions are SETFable.
2478 </p>
2479
2480
2481 <div class="org-src-container">
2482 <pre class="src src-lisp" id="org12f19a5">(ub16ref/be vector index) =&gt; value
2483 (ub32ref/be vector index) =&gt; value
2484 (ub64ref/be vector index) =&gt; value
2485 </pre>
2486 </div>
2487
2488 <p>
2489 As the above, only the value is stored in big-endian order.
2490 </p>
2491
2492
2493 <div class="org-src-container">
2494 <pre class="src src-lisp" id="org6b0db24">(byte-array-to-hex-string vector <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end element-type) =&gt; string
2495 (hex-string-to-byte-array string <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end) =&gt; string
2496 (ascii-string-to-byte-array string <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end) =&gt; vector
2497 </pre>
2498 </div>
2499
2500 <p>
2501 <a href="#org6b0db24">byte-array-to-hex-string</a> converts the bytes of <i>vector</i> between
2502 <i>start</i> and <i>end</i> into a hexadecimal string. It is useful for
2503 converting digests to a more readable form. <i>element-type</i> indicates
2504 the element-type of the returned string.
2505 </p>
2506
2507 <p>
2508 <a href="#org6b0db24">hex-string-to-byte-array</a> parses a substring of <i>string</i> delimited
2509 <i>start</i> and <i>end</i> of hexadecimal digits into a byte array.
2510 </p>
2511
2512 <p>
2513 <a href="#org6b0db24">ascii-string-to-byte-array</a> is provided as a quick and dirty way to
2514 convert a string to a byte array suitable for feeding to <a href="#org9ba11b9">update-digest</a>
2515 or <a href="#orga0c509f">encrypt</a>. Care should be taken to ensure that the provided string is
2516 actually an ASCII string. <i>start</i> and <i>end</i> have their usual
2517 interpretations.
2518 </p>
2519
2520
2521 <div class="org-src-container">
2522 <pre class="src src-lisp" id="org0826692">(octets-to-integer octet-vec <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> start end big-endian n-bits) =&gt; number
2523 (integer-to-octets bignum <span style="font-weight: bold; text-decoration: underline;">&amp;key</span> n-bits big-endian) =&gt; vector
2524 </pre>
2525 </div>
2526
2527 <p>
2528 <a href="#org0826692">octets-to-integer</a> converts the bytes of <i>octet-vec</i> between <i>start</i>
2529 and <i>end</i> to an integer as though the bytes denoted a number in
2530 base 256. <i>big-endian</i> is a boolean indicating whether the bytes are
2531 to be read in big-endian or little-endian order. <i>n-bits</i> specifies
2532 how many bits should be considered as significant in the resulting
2533 number.
2534 </p>
2535
2536 <p>
2537 <a href="#org0826692">integer-to-octets</a> is the reverse operation.
2538 </p>
2539
2540
2541 <div class="org-src-container">
2542 <pre class="src src-lisp" id="org89429f3">(expt-mod n exponent modulus) =&gt; number
2543 (expt-mod/unsafe n exponent modulus) =&gt; number
2544 </pre>
2545 </div>
2546
2547 <p>
2548 Raises <i>n</i> to the <i>exponent</i> power modulo <i>modulus</i> in a more
2549 efficient fashion than <code>(mod (expt n exponent) modulus)</code>.
2550 <a href="#org89429f3">expt-mod</a> is using the Montgomery ladder algorithm to be more robust
2551 against timing attacks.
2552 <a href="#org89429f3">expt-mod/unsafe</a> runs faster than <a href="#org89429f3">expt-mod</a> but is not safe against
2553 timing attacks; don't use it on secret data.
2554 </p>
2555
2556
2557 <div class="org-src-container">
2558 <pre class="src src-lisp" id="orge94e41b">(prime-p n <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> prng) =&gt; boolean
2559 </pre>
2560 </div>
2561
2562 <p>
2563 <a href="#orge94e41b">prime-p</a> returns <code>t</code> if <i>n</i> has a high probability of being a prime number, and
2564 <code>nil</code> if it is a composite number. The probable primality is determined by
2565 first doing trial divisions with small primes, then running several
2566 Miller-Rabin tests with random bases, and finally doing a Lucas test. The
2567 number of Miller-Rabin tests can be configured using the
2568 <code>*number-of-miller-rabin-tests*</code> variable. It is 64 by default, which makes the
2569 probability of returning <code>t</code> for a composite number to be at most 1/2<sup>128</sup>.
2570 </p>
2571
2572
2573 <div class="org-src-container">
2574 <pre class="src src-lisp" id="org01d5086">make-random-salt <span style="font-weight: bold; text-decoration: underline;">&amp;optional</span> size =&gt; bytes
2575 </pre>
2576 </div>
2577
2578 <p>
2579 Generate a byte vector of <i>size</i> (default 16) random bytes, suitable
2580 for use as a password salt.
2581 </p>
2582
2583
2584 <div class="org-src-container">
2585 <pre class="src src-lisp" id="org9ca5d87">constant-time-equal data1 data2 =&gt; boolean
2586 </pre>
2587 </div>
2588
2589 <p>
2590 Check whether the contents of the byte arrays <i>data1</i> and <i>data2</i> are
2591 the same. This function runs in constant time (for a given array
2592 length) to prevent timing attacks. It can be used to compare passwords
2593 or MACs.
2594 </p>
2595 </div>
2596 </div>
2597 <div id="outline-container-conditions" class="outline-2">
2598 <h2 id="conditions">Conditions</h2>
2599 <div class="outline-text-2" id="text-conditions">
2600 <div class="org-src-container">
2601 <pre class="src src-lisp" id="orgdf4f1f6">ironclad-error
2602 </pre>
2603 </div>
2604
2605 <p>
2606 All errors signaled by Ironclad are of this type. This type is
2607 a direct subtype of <code>simple-error</code> without any extra slots or options.
2608 </p>
2609
2610
2611 <div class="org-src-container">
2612 <pre class="src src-lisp" id="orgac1c20a">initialization-vector-not-supplied
2613 </pre>
2614 </div>
2615
2616 <p>
2617 This error is signaled by <a href="#orga194874">make-cipher</a> when an initialization vector is
2618 not provided and the requested mode requires an initialization vector.
2619 </p>
2620
2621
2622 <div class="org-src-container">
2623 <pre class="src src-lisp" id="orgcc5eb5f">invalid-initialization-vector
2624 </pre>
2625 </div>
2626
2627 <p>
2628 This error is signaled when an invalid initialization vector is
2629 supplied to <a href="#orga194874">make-cipher</a> (e.g. when the length of the initialization
2630 vector does not match the block length of the cipher).
2631 </p>
2632
2633
2634 <div class="org-src-container">
2635 <pre class="src src-lisp" id="orgc77ebba">invalid-key-length
2636 </pre>
2637 </div>
2638
2639 <p>
2640 This error is signaled when the key provided to <a href="#orga194874">make-cipher</a> is not of
2641 an acceptable length for the requested cipher.
2642 </p>
2643
2644
2645 <div class="org-src-container">
2646 <pre class="src src-lisp" id="org8f6b6c4">unsupported-cipher
2647 </pre>
2648 </div>
2649
2650 <p>
2651 This error is signaled when the <i>cipher-name</i> provided to <a href="#orga194874">make-cipher</a>
2652 is not <a href="#orgaef3ba6">cipher-supported-p</a>.
2653 </p>
2654
2655
2656 <div class="org-src-container">
2657 <pre class="src src-lisp" id="org262ca01">unsupported-mode
2658 </pre>
2659 </div>
2660
2661 <p>
2662 This error is signaled when the <i>mode</i> provided to
2663 <a href="#orga194874">make-cipher</a> is not <i>mode-supported-p</i>.
2664 </p>
2665
2666
2667 <div class="org-src-container">
2668 <pre class="src src-lisp" id="org9b9361c">unsupported-padding
2669 </pre>
2670 </div>
2671
2672 <p>
2673 This error is signaled when the <i>padding</i> provided to <a href="#orga194874">make-cipher</a> is not
2674 supported.
2675 </p>
2676
2677
2678 <div class="org-src-container">
2679 <pre class="src src-lisp" id="org5a41f2f">unsupported-digest
2680 </pre>
2681 </div>
2682
2683 <p>
2684 This error is signaled when the <i>digest-name</i> provided to
2685 <a href="#org0aca191">make-digest</a> is not <a href="#org1786607">digest-supported-p</a>.
2686 </p>
2687
2688
2689 <div class="org-src-container">
2690 <pre class="src src-lisp" id="org7a95626">unsupported-mac
2691 </pre>
2692 </div>
2693
2694 <p>
2695 This error is signaled when the <i>mac-name</i> provided to
2696 <a href="#orgbc2a39c">make-mac</a> is not <a href="#orgfe5f676">mac-supported-p</a>.
2697 </p>
2698
2699
2700 <div class="org-src-container">
2701 <pre class="src src-lisp" id="org701dd62">insufficient-buffer-space
2702 </pre>
2703 </div>
2704
2705 <p>
2706 This error is signaled when Ironclad needs to stuff some data into
2707 a buffer (e.g. when the user provides <i>digest</i> to <a href="#orgebfad7a">produce-digest</a> and
2708 there is insufficient space).
2709 </p>
2710
2711
2712 <div class="org-src-container">
2713 <pre class="src src-lisp" id="org8bebfc7">key-not-supplied
2714 </pre>
2715 </div>
2716
2717 <p>
2718 This error is signaled when a <i>:key</i> argument is not provided
2719 to <a href="#orga194874">make-cipher</a>.
2720 </p>
2721
2722
2723 <div class="org-src-container">
2724 <pre class="src src-lisp" id="org991b5c3">unsupported-kdf
2725 </pre>
2726 </div>
2727
2728 <p>
2729 This error is signaled when an invalid KDF name is provided
2730 to <a href="#orgc3724fd">make-kdf</a>.
2731 </p>
2732
2733
2734 <div class="org-src-container">
2735 <pre class="src src-lisp" id="orgb419f89">unsupported-scrypt-cost-factors
2736 </pre>
2737 </div>
2738
2739 <p>
2740 This error is signaled when invalid Scrypt cost factors are provided
2741 to <a href="#orgc3724fd">make-kdf</a>.
2742 </p>
2743
2744
2745 <div class="org-src-container">
2746 <pre class="src src-lisp" id="org00e96f4">unsupported-argon2-cost-factors
2747 </pre>
2748 </div>
2749
2750 <p>
2751 This error is signaled when invalid Argon2 parameters are provided
2752 to <a href="#orgc3724fd">make-kdf</a>.
2753 </p>
2754
2755
2756 <div class="org-src-container">
2757 <pre class="src src-lisp" id="org242d249">invalid-padding
2758 </pre>
2759 </div>
2760
2761 <p>
2762 This error is signaled when padding in a block is determined to be
2763 invalid.
2764 </p>
2765
2766
2767 <div class="org-src-container">
2768 <pre class="src src-lisp" id="orgfbd54a5">invalid-mac-parameter
2769 </pre>
2770 </div>
2771
2772 <p>
2773 This error is signaled when an invalid parameter is provided
2774 to <a href="#orgbc2a39c">make-mac</a>.
2775 </p>
2776
2777
2778 <div class="org-src-container">
2779 <pre class="src src-lisp" id="org871c025">invalid-signature-length
2780 </pre>
2781 </div>
2782
2783 <p>
2784 This error is signaled when a signature with an invalid length is provided
2785 to <a href="#orgf029208">verify-signature</a> or <a href="#orgc5506b9">destructure-signature</a>.
2786 </p>
2787
2788
2789 <div class="org-src-container">
2790 <pre class="src src-lisp" id="orgfaddc6c">invalid-message-length
2791 </pre>
2792 </div>
2793
2794 <p>
2795 This error is signaled when a message with an invalid length is provided
2796 to <a href="#org6424db2">encrypt-message</a>, <a href="#org13a3a49">decrypt-message</a> or <a href="#orgc65f9d9">destructure-message</a>.
2797 </p>
2798
2799
2800 <div class="org-src-container">
2801 <pre class="src src-lisp" id="org2aedad4">missing-key-parameter
2802 </pre>
2803 </div>
2804
2805 <p>
2806 This error is signaled when it is determined that a parameter is
2807 missing in a call to <a href="#org6bca683">make-public-key</a> or <a href="#org59929bc">make-private-key</a>.
2808 </p>
2809
2810
2811 <div class="org-src-container">
2812 <pre class="src src-lisp" id="orga06e596">missing-message-parameter
2813 </pre>
2814 </div>
2815
2816 <p>
2817 This error is signaled when it is determined that a parameter is
2818 missing in a call to <a href="#org83c91f2">make-message</a>.
2819 </p>
2820
2821
2822 <div class="org-src-container">
2823 <pre class="src src-lisp" id="orgc5f803c">missing-signature-parameter
2824 </pre>
2825 </div>
2826
2827 <p>
2828 This error is signaled when it is determined that a parameter is
2829 missing in a call to <a href="#orgfa225d8">make-signature</a>.
2830 </p>
2831
2832
2833 <div class="org-src-container">
2834 <pre class="src src-lisp" id="org16a77de">incompatible-keys
2835 </pre>
2836 </div>
2837
2838 <p>
2839 This error is signaled when incompatible keys are provided to
2840 <a href="#org548e6ec">diffie-hellman</a>.
2841 </p>
2842
2843
2844 <div class="org-src-container">
2845 <pre class="src src-lisp" id="org1836372">invalid-curve-point
2846 </pre>
2847 </div>
2848
2849 <p>
2850 This error is signaled when trying to use an invalid curve point.
2851 </p>
2852
2853
2854 <div class="org-src-container">
2855 <pre class="src src-lisp" id="org989da1f">invalid-public-key-length
2856 </pre>
2857 </div>
2858
2859 <p>
2860 This error is signaled when a public key with an invalid length is
2861 provided to <a href="#orgf029208">verify-signature</a>.
2862 </p>
2863
2864
2865 <div class="org-src-container">
2866 <pre class="src src-lisp" id="org00b54b6">oaep-decoding-error
2867 </pre>
2868 </div>
2869
2870 <p>
2871 This error is signaled when the OAEP decoding of a message fails.
2872 </p>
2873
2874
2875 <div class="org-src-container">
2876 <pre class="src src-lisp" id="org58897fd">unsupported-authenticated-encryption-mode
2877 </pre>
2878 </div>
2879
2880 <p>
2881 This error is signaled when an invalid mode name is provided to
2882 <a href="#org44e9414">make-authenticated-encryption-mode</a>.
2883 </p>
2884
2885
2886 <div class="org-src-container">
2887 <pre class="src src-lisp" id="org94e7be8">bad-authentication-tag
2888 </pre>
2889 </div>
2890
2891 <p>
2892 This error is signaled when the verification of authenticity of a message fails.
2893 </p>
2894 </div>
2895 </div>
2896 <div id="outline-container-subsystems" class="outline-2">
2897 <h2 id="subsystems">Subsystems (experimental)</h2>
2898 <div class="outline-text-2" id="text-subsystems">
2899 <p>
2900 Instead of loading the complete Ironclad system, you can load only the
2901 subsystems of the algorithms you need.
2902 </p>
2903
2904 <p>
2905 For example if you need only AES and SHA256:
2906 </p>
2907 <pre class="example" id="org13c948d">
2908 (asdf:load-system "ironclad/cipher/aes")
2909 (asdf:load-system "ironclad/digest/sha256")
2910 </pre>
2911 </div>
2912 <div id="outline-container-orga6d26c9" class="outline-3">
2913 <h3 id="orga6d26c9">Available subsystems</h3>
2914 <div class="outline-text-3" id="text-orga6d26c9">
2915 <ul class="org-ul">
2916 <li>ironclad
2917 <ul class="org-ul">
2918 <li>ironclad/core</li>
2919 <li>ironclad/ciphers
2920 <ul class="org-ul">
2921 <li>ironclad/cipher/aes</li>
2922 <li>ironclad/cipher/arcfour</li>
2923 <li>ironclad/cipher/aria</li>
2924 <li>ironclad/cipher/blowfish</li>
2925 <li>ironclad/cipher/camellia</li>
2926 <li>ironclad/cipher/cast5</li>
2927 <li>ironclad/cipher/chacha</li>
2928 <li>ironclad/cipher/des</li>
2929 <li>ironclad/cipher/idea</li>
2930 <li>ironclad/cipher/kalyna</li>
2931 <li>ironclad/cipher/keystream</li>
2932 <li>ironclad/cipher/kuznyechik</li>
2933 <li>ironclad/cipher/misty1</li>
2934 <li>ironclad/cipher/rc2</li>
2935 <li>ironclad/cipher/rc5</li>
2936 <li>ironclad/cipher/rc6</li>
2937 <li>ironclad/cipher/salsa20</li>
2938 <li>ironclad/cipher/seed</li>
2939 <li>ironclad/cipher/serpent</li>
2940 <li>ironclad/cipher/sm4</li>
2941 <li>ironclad/cipher/sosemanuk</li>
2942 <li>ironclad/cipher/square</li>
2943 <li>ironclad/cipher/tea</li>
2944 <li>ironclad/cipher/threefish</li>
2945 <li>ironclad/cipher/twofish</li>
2946 <li>ironclad/cipher/xchacha</li>
2947 <li>ironclad/cipher/xor</li>
2948 <li>ironclad/cipher/xsalsa20</li>
2949 <li>ironclad/cipher/xtea</li>
2950 </ul></li>
2951 <li>ironclad/digests
2952 <ul class="org-ul">
2953 <li>ironclad/digest/adler32</li>
2954 <li>ironclad/digest/blake2</li>
2955 <li>ironclad/digest/blake2s</li>
2956 <li>ironclad/digest/crc24</li>
2957 <li>ironclad/digest/crc32</li>
2958 <li>ironclad/digest/groestl</li>
2959 <li>ironclad/digest/jh</li>
2960 <li>ironclad/digest/kupyna</li>
2961 <li>ironclad/digest/md2</li>
2962 <li>ironclad/digest/md4</li>
2963 <li>ironclad/digest/md5</li>
2964 <li>ironclad/digest/ripemd-128</li>
2965 <li>ironclad/digest/ripemd-160</li>
2966 <li>ironclad/digest/sha1</li>
2967 <li>ironclad/digest/sha256</li>
2968 <li>ironclad/digest/sha3</li>
2969 <li>ironclad/digest/sha512</li>
2970 <li>ironclad/digest/skein</li>
2971 <li>ironclad/digest/sm3</li>
2972 <li>ironclad/digest/streebog</li>
2973 <li>ironclad/digest/toger</li>
2974 <li>ironclad/digest/tree-hash</li>
2975 <li>ironclad/digest/whirlpool</li>
2976 </ul></li>
2977 <li>ironclad/macs
2978 <ul class="org-ul">
2979 <li>ironclad/mac/blake2-mac</li>
2980 <li>ironclad/mac/blake2s-mac</li>
2981 <li>ironclad/mac/cmac</li>
2982 <li>ironclad/mac/gmac</li>
2983 <li>ironclad/mac/hmac</li>
2984 <li>ironclad/mac/poly1305</li>
2985 <li>ironclad/mac/siphash</li>
2986 <li>ironclad/mac/skein-mac</li>
2987 </ul></li>
2988 <li>ironclad/prngs
2989 <ul class="org-ul">
2990 <li>ironclad/prng/fortuna</li>
2991 </ul></li>
2992 <li>ironclad/aeads
2993 <ul class="org-ul">
2994 <li>ironclad/aead/eax</li>
2995 <li>ironclad/aead/etm</li>
2996 <li>ironclad/aead/gcm</li>
2997 </ul></li>
2998 <li>ironclad/kdfs
2999 <ul class="org-ul">
3000 <li>ironclad/kdf/argon2</li>
3001 <li>ironclad/kdf/bcrypt</li>
3002 <li>ironclad/kdf/hmac</li>
3003 <li>ironclad/kdf/password-hash</li>
3004 <li>ironclad/kdf/pkcs5</li>
3005 <li>ironclad/kdf/scrypt</li>
3006 </ul></li>
3007 <li>ironclad/public-keys
3008 <ul class="org-ul">
3009 <li>ironclad/public-key/curve25519</li>
3010 <li>ironclad/public-key/curve448</li>
3011 <li>ironclad/public-key/dsa</li>
3012 <li>ironclad/public-key/ed25519</li>
3013 <li>ironclad/public-key/ed448</li>
3014 <li>ironclad/public-key/elgamal</li>
3015 <li>ironclad/public-key/rsa</li>
3016 <li>ironclad/public-key/secp256k1</li>
3017 <li>ironclad/public-key/secp256r1</li>
3018 <li>ironclad/public-key/secp384r1</li>
3019 <li>ironclad/public-key/secp521r1</li>
3020 </ul></li>
3021 </ul></li>
3022 </ul>
3023 </div>
3024 </div>
3025 </div>
3026 </div>
3027 </body>
3028 </html>