diff options
| -rw-r--r-- | NEWS | 6 | ||||
| -rw-r--r-- | README.org | 4 | ||||
| -rw-r--r-- | doc/ironclad.html | 757 | ||||
| -rw-r--r-- | ironclad.asd | 4 |
4 files changed, 367 insertions, 404 deletions
@@ -1,11 +1,15 @@ -*- mode: outline -*- -* Changes since version 0.60 +* Version 0.61, released 2024-08-20 ** new features Added the Argon2id key derivation function (without parallelism). +** bug fixes + +Fix build with recent SBCL on x86-32. + * Version 0.60, released 2024-02-29 ** new features @@ -80,8 +80,8 @@ thread. There is an example showing how it can be done in the section about :CUSTOM_ID: installation :END: -The current version of Ironclad is 0.60. It can be downloaded -at [[https://github.com/sharplispers/ironclad/archive/v0.60.tar.gz]]. +The current version of Ironclad is 0.61. It can be downloaded +at [[https://github.com/sharplispers/ironclad/archive/v0.61.tar.gz]]. If you are feeling adventurous, you can download a bleeding-edge version at [[https://github.com/sharplispers/ironclad]]. diff --git a/doc/ironclad.html b/doc/ironclad.html index 39cad20..89acb1c 100644 --- a/doc/ironclad.html +++ b/doc/ironclad.html @@ -1,7 +1,7 @@ <!DOCTYPE html> <html lang="en"> <head> -<!-- 2024-02-29 jeu. 13:30 --> +<!-- 2024-08-20 mar. 10:03 --> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Ironclad</title> @@ -26,7 +26,7 @@ pre.example { margin-right: 10%; margin-top: 1.5em; margin-bottom: 1.5em; border <div id="content" class="content"> <h1 class="title">Ironclad</h1> -<div id="org6980beb" class="figure"> +<div id="orge8f24ca" class="figure"> <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> </p> </div> @@ -72,7 +72,6 @@ a level of confidence in the correctness of the implementations. </ul> </div> </div> - <div id="outline-container-warning" class="outline-2"> <h2 id="warning">Warnings</h2> <div class="outline-text-2" id="text-warning"> @@ -116,17 +115,16 @@ are created using the <b>bordeaux-threads</b> library (or by a library using you are using the threading functions of your Common Lisp implementation directly, you have to bind the <code>*prng*</code> special variable to a new PRNG in each thread. There is an example showing how it can be done in the section about -<a href="#orgbfe1c12">make-prng</a>. +<a href="#org4ee888f">make-prng</a>. </p> </div> </div> - <div id="outline-container-installation" class="outline-2"> <h2 id="installation">Installation</h2> <div class="outline-text-2" id="text-installation"> <p> -The current version of Ironclad is 0.60. It can be downloaded -at <a href="https://github.com/sharplispers/ironclad/archive/v0.60.tar.gz">https://github.com/sharplispers/ironclad/archive/v0.60.tar.gz</a>. +The current version of Ironclad is 0.61. It can be downloaded +at <a href="https://github.com/sharplispers/ironclad/archive/v0.61.tar.gz">https://github.com/sharplispers/ironclad/archive/v0.61.tar.gz</a>. If you are feeling adventurous, you can download a bleeding-edge version at <a href="https://github.com/sharplispers/ironclad">https://github.com/sharplispers/ironclad</a>. </p> @@ -182,7 +180,6 @@ use the generic Lisp code, it can be achieved by commenting out the </p> </div> </div> - <div id="outline-container-license" class="outline-2"> <h2 id="license">License</h2> <div class="outline-text-2" id="text-license"> @@ -192,12 +189,11 @@ anything you want to with the code except claim that you wrote it. </p> </div> </div> - <div id="outline-container-ciphers" class="outline-2"> <h2 id="ciphers">Ciphers</h2> <div class="outline-text-2" id="text-ciphers"> <div class="org-src-container"> -<pre class="src src-lisp" id="org305b09d">(make-cipher name <span style="font-weight: bold; text-decoration: underline;">&key</span> key mode initialization-vector padding tweak) => cipher +<pre class="src src-lisp" id="orga194874">(make-cipher name <span style="font-weight: bold; text-decoration: underline;">&key</span> key mode initialization-vector padding tweak) => cipher </pre> </div> @@ -206,7 +202,7 @@ Return a cipher object suitable for use for both encryption and decryption. </p> <p> -<i>name</i> denotes the encryption algorithm to use. <a href="#org7d0194b">list-all-ciphers</a> will tell you +<i>name</i> denotes the encryption algorithm to use. <a href="#orgd644b3b">list-all-ciphers</a> will tell you the names of all supported ciphers. They are: </p> <ul class="org-ul"> @@ -267,7 +263,7 @@ such as AES and DES can operate in several different modes: <li>ecb</li> <li>cbc</li> <li>ofb</li> -<li>cfb (note that Ironclad's CFB mode is <i>n</i>-bit CFB, where <i>n</i> is the <a href="#org228bea0">block-length</a> of the cipher)</li> +<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> <li>cfb8 (this seems to be the mode other crypto packages call CFB)</li> <li>ctr</li> </ul> @@ -281,7 +277,7 @@ such as AES and DES can operate in several different modes: <p> <i>initialization-vector</i> (IV) should be supplied only if <i>mode</i> requires one. <i>initialization-vector</i> should be a <code>(simple-array (unsigned-byte 8) (*))</code>. -The supplied IV should be the same length as the <a href="#org228bea0">block-length</a> of <i>name</i>. +The supplied IV should be the same length as the <a href="#org32e5f3d">block-length</a> of <i>name</i>. The Chacha and Salsa20 stream ciphers also use an initialization vector (nonce). It should be 8 or 12 bytes long for Chacha, 8 bytes long for Salsa20, and 24 bytes long for XChacha and XSalsa20. @@ -293,8 +289,8 @@ for Salsa20, and 24 bytes long for XChacha and XSalsa20. </p> <p> -If <i>padding</i> is supplied, the specified padding method will be used by <a href="#org911f61d">encrypt</a> -and <a href="#org530d42d">decrypt</a> to handle short blocks when the <code>:handle-final-block</code> argument is +If <i>padding</i> is supplied, the specified padding method will be used by <a href="#orga0c509f">encrypt</a> +and <a href="#org8d3dffc">decrypt</a> to handle short blocks when the <code>:handle-final-block</code> argument is supplied. <i>padding</i> will only be used if the mode is ECB or CBC. The possible values for <i>padding</i> are <code>:pkcs7</code>, <code>:ansi-x923</code> and <code>:iso-7816-4</code>. </p> @@ -306,7 +302,7 @@ with the <i>tweak</i> key parameter. <div class="org-src-container"> -<pre class="src src-lisp" id="org911f61d">(encrypt cipher plaintext ciphertext <span style="font-weight: bold; text-decoration: underline;">&key</span> plaintext-start plaintext-end ciphertext-start handle-final-block) => n-bytes-consumed, n-bytes-produced +<pre class="src src-lisp" id="orga0c509f">(encrypt cipher plaintext ciphertext <span style="font-weight: bold; text-decoration: underline;">&key</span> plaintext-start plaintext-end ciphertext-start handle-final-block) => n-bytes-consumed, n-bytes-produced </pre> </div> @@ -318,7 +314,7 @@ data is placed in <i>ciphertext</i> starting at <i>ciphertext-start</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="org530d42d">(decrypt cipher ciphertext plaintext <span style="font-weight: bold; text-decoration: underline;">&key</span> ciphertext-start ciphertext-end plaintext-start handle-final-block) => n-bytes-consumed, n-bytes-produced +<pre class="src src-lisp" id="org8d3dffc">(decrypt cipher ciphertext plaintext <span style="font-weight: bold; text-decoration: underline;">&key</span> ciphertext-start ciphertext-end plaintext-start handle-final-block) => n-bytes-consumed, n-bytes-produced </pre> </div> @@ -330,11 +326,11 @@ data is placed in <i>plaintext</i> starting at <i>plaintext-start</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="org86ad0d6">(encrypt-in-place cipher text <span style="font-weight: bold; text-decoration: underline;">&key</span> start end) => n-bytes-consumed, n-bytes-produced +<pre class="src src-lisp" id="org1eeb930">(encrypt-in-place cipher text <span style="font-weight: bold; text-decoration: underline;">&key</span> start end) => n-bytes-consumed, n-bytes-produced </pre> </div> <div class="org-src-container"> -<pre class="src src-lisp" id="org35f96bd">(decrypt-in-place cipher text <span style="font-weight: bold; text-decoration: underline;">&key</span> start end) => n-bytes-consumed, n-bytes-produced +<pre class="src src-lisp" id="orgb24e31a">(decrypt-in-place cipher text <span style="font-weight: bold; text-decoration: underline;">&key</span> start end) => n-bytes-consumed, n-bytes-produced </pre> </div> @@ -342,23 +338,23 @@ data is placed in <i>plaintext</i> starting at <i>plaintext-start</i>. Encrypts or decrypts data in <i>text</i> between <i>start</i> and <i>end</i> "in-place" according to <i>cipher</i>. These functions are shorthand for: </p> -<pre class="example" id="org3b8d230"> +<pre class="example" id="org63313bc"> (encrypt cipher text text :plaintext-start start :plaintext-end end :ciphertext-start start) (decrypt cipher text text :ciphertext-start start :ciphertext-end end :plaintext-start start) </pre> <p> -<span class="underline">Note:</span> <a href="#org86ad0d6">encrypt-in-place</a> and <a href="#org35f96bd">decrypt-in-place</a> do not support -a <i>handle-final-block</i> parameter as <a href="#org911f61d">encrypt</a> and <a href="#org530d42d">decrypt</a> do. If you +<span class="underline">Note:</span> <a href="#org1eeb930">encrypt-in-place</a> and <a href="#orgb24e31a">decrypt-in-place</a> do not support +a <i>handle-final-block</i> parameter as <a href="#orga0c509f">encrypt</a> and <a href="#org8d3dffc">decrypt</a> do. If you need the functionality that <i>handle-final-block</i> provides, then you -need to use <a href="#org911f61d">encrypt</a> and <a href="#org530d42d">decrypt</a>. +need to use <a href="#orga0c509f">encrypt</a> and <a href="#org8d3dffc">decrypt</a>. </p> <p> <span class="underline">Note:</span> <i>n-bytes-consumed</i> and <i>n-bytes-produced</i> may not always be equal to the length of the data specified in the call to -<a href="#org86ad0d6">encrypt-in-place</a> or <a href="#org35f96bd">decrypt-in-place</a>. This subtlely is also present in -<a href="#org911f61d">encrypt</a> or <a href="#org530d42d">decrypt</a>. +<a href="#org1eeb930">encrypt-in-place</a> or <a href="#orgb24e31a">decrypt-in-place</a>. This subtlely is also present in +<a href="#orga0c509f">encrypt</a> or <a href="#org8d3dffc">decrypt</a>. </p> @@ -383,33 +379,32 @@ Return the <i>message</i> between <i>start</i> and <i>end</i> decrypted by the < class of <i>cipher</i> determines the algorithm used to decrypt the message. </p> </div> - -<div id="outline-container-org1125b49" class="outline-3"> -<h3 id="org1125b49">Inquiry functions</h3> -<div class="outline-text-3" id="text-org1125b49"> +<div id="outline-container-orgb6b9101" class="outline-3"> +<h3 id="orgb6b9101">Inquiry functions</h3> +<div class="outline-text-3" id="text-orgb6b9101"> <div class="org-src-container"> -<pre class="src src-lisp" id="org7d0194b">(list-all-ciphers) => list +<pre class="src src-lisp" id="orgd644b3b">(list-all-ciphers) => list </pre> </div> <p> -Returns a list of cipher-names that may be validly passed to <a href="#org305b09d">make-cipher</a>. +Returns a list of cipher-names that may be validly passed to <a href="#orga194874">make-cipher</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orge2e33ff">(cipher-supported-p name) => boolean +<pre class="src src-lisp" id="orgaef3ba6">(cipher-supported-p name) => boolean </pre> </div> <p> -Returns <code>t</code> if <i>name</i> would be in the list returned by <a href="#org7d0194b">list-all-ciphers</a>, +Returns <code>t</code> if <i>name</i> would be in the list returned by <a href="#orgd644b3b">list-all-ciphers</a>, <code>nil</code> otherwise. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org2b78eea">(key-lengths cipher) => list +<pre class="src src-lisp" id="org016f0ae">(key-lengths cipher) => list </pre> </div> @@ -419,7 +414,7 @@ Return a list of valid key lengths for <i>cipher</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="org228bea0">(block-length cipher) => number +<pre class="src src-lisp" id="org32e5f3d">(block-length cipher) => number </pre> </div> @@ -429,10 +424,9 @@ function always returns 1 for stream ciphers. </p> </div> </div> - -<div id="outline-container-orgb6628a5" class="outline-3"> -<h3 id="orgb6628a5">Key stream position</h3> -<div class="outline-text-3" id="text-orgb6628a5"> +<div id="outline-container-orgf14df47" class="outline-3"> +<h3 id="orgf14df47">Key stream position</h3> +<div class="outline-text-3" id="text-orgf14df47"> <p> Block ciphers in CTR mode and some stream ciphers have the ability to change the current position within the key stream in constant time instead of having to @@ -440,21 +434,21 @@ consume all the bytes until the desired position is reached. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org7025082">(keystream-position cipher <span style="font-weight: bold; text-decoration: underline;">&optional</span> position) => number or boolean +<pre class="src src-lisp" id="org93fb9e3">(keystream-position cipher <span style="font-weight: bold; text-decoration: underline;">&optional</span> position) => number or boolean </pre> </div> <p> Return or change the current <i>position</i> within the key stream of a <i>cipher</i>. -When <i>position</i> is not supplied, <a href="#org7025082">keystream-position</a> returns the current position +When <i>position</i> is not supplied, <a href="#org93fb9e3">keystream-position</a> returns the current position in the key stream, or <i>nil</i> if it can't be determined. When <i>position</i> is supplied, the key stream position of the <i>cipher</i> is set to that <i>position</i> if -possible. <a href="#org7025082">keystream-position</a> returns <i>t</i> if the repositioning is performed +possible. <a href="#org93fb9e3">keystream-position</a> returns <i>t</i> if the repositioning is performed successfully, or <i>nil</i> otherwise. </p> <p> -<a href="#org7025082">keystream-position</a> can be used with the following ciphers: +<a href="#org93fb9e3">keystream-position</a> can be used with the following ciphers: </p> <ul class="org-ul"> <li>all the block ciphers (aes, twofish, etc.) in CTR mode</li> @@ -474,7 +468,6 @@ successfully, or <i>nil</i> otherwise. </div> </div> </div> - <div id="outline-container-digests" class="outline-2"> <h2 id="digests">Digests</h2> <div class="outline-text-2" id="text-digests"> @@ -504,14 +497,14 @@ See your local Unicode guru for more details. <div class="org-src-container"> -<pre class="src src-lisp" id="org6b2b195">(make-digest digest-name <span style="font-weight: bold; text-decoration: underline;">&rest</span> keys <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => digester +<pre class="src src-lisp" id="org0aca191">(make-digest digest-name <span style="font-weight: bold; text-decoration: underline;">&rest</span> keys <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => digester </pre> </div> <p> Returns a digest object. <i>digest-name</i> is a keyword naming the algorithm you wish <i>digester</i> to use. The supported digest names can be found -by calling <a href="#org897980f">list-all-digests</a>. They are: +by calling <a href="#org2ccff16">list-all-digests</a>. They are: </p> <ul class="org-ul"> <li>adler32</li> @@ -578,7 +571,7 @@ by calling <a href="#org897980f">list-all-digests</a>. They are: </ul> <p> -Like for <a href="#org305b09d">make-cipher</a>, <i>digest-name</i> should be a symbol in the +Like for <a href="#orga194874">make-cipher</a>, <i>digest-name</i> should be a symbol in the <code>keyword</code> or <code>ironclad</code> packages. </p> @@ -588,13 +581,13 @@ any size. The size of the digest in bytes can be specified with the <i>output-length</i> key parameter: </p> -<pre class="example" id="orgd807cd0"> +<pre class="example" id="org4d40d35"> (make-digest :shake256 :output-length 123) </pre> <div class="org-src-container"> -<pre class="src src-lisp" id="org356a991">(update-digest digester thing <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => (values) +<pre class="src src-lisp" id="org9ba11b9">(update-digest digester thing <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => (values) </pre> </div> @@ -614,7 +607,7 @@ listing them would get very tedious for no benefit. An example should suffice. </p> -<pre class="example" id="org599e26c"> +<pre class="example" id="org4595f34"> (let ((digester (ironclad:make-digest :sha1)) (array (make-array 16 :element-type '(unsigned-byte 8) :initial-element 0))) ;; Update with 16 zeroes. @@ -634,14 +627,14 @@ suffice. Update the internal state of <i>digester</i> with the contents of <i>stream</i>, which must respond to <code>read-byte</code> or <code>read-sequence</code> with a <code>(simple-array (unsigned-byte 8) (*))</code> and return <i>digester</i>. It -differs from <a href="#orgbf974ca">digest-stream</a>, below, in that you may need to digest data +differs from <a href="#org4fb38fd">digest-stream</a>, below, in that you may need to digest data before or after the contents of <i>stream</i> (this happens, for instance, when signing the contents of some file). </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org49c655e">(produce-digest digester <span style="font-weight: bold; text-decoration: underline;">&key</span> digest digest-start) => digest +<pre class="src src-lisp" id="orgebfad7a">(produce-digest digester <span style="font-weight: bold; text-decoration: underline;">&key</span> digest digest-start) => digest </pre> </div> @@ -652,24 +645,23 @@ Return the digest of the data processed by <i>digester</i> so far. <p> If <i>digest</i> is provided, the computed digest will be placed into <i>digest</i> starting at <i>digest-start</i>. <i>digest</i> must be a -<code>(simple-array (unsigned-byte 8) (*))</code>. An <a href="#org3306fab">insufficient-buffer-space</a> +<code>(simple-array (unsigned-byte 8) (*))</code>. An <a href="#org701dd62">insufficient-buffer-space</a> error will be signaled if there is insufficient space in <i>digest</i>. </p> </div> - -<div id="outline-container-org9532fc4" class="outline-3"> -<h3 id="org9532fc4">High-level convenience functions</h3> -<div class="outline-text-3" id="text-org9532fc4"> +<div id="outline-container-org15f4a95" class="outline-3"> +<h3 id="org15f4a95">High-level convenience functions</h3> +<div class="outline-text-3" id="text-org15f4a95"> <p> Several high-level convenience functions that encapsulate common -sequences of <a href="#org6b2b195">make-digest</a>, <a href="#org356a991">update-digest</a> and <a href="#org49c655e">produce-digest</a> are +sequences of <a href="#org0aca191">make-digest</a>, <a href="#org9ba11b9">update-digest</a> and <a href="#orgebfad7a">produce-digest</a> are provided by Ironclad as well. They come in two flavors: the first -takes a digest name as would be provided to <a href="#org6b2b195">make-digest</a>. The second +takes a digest name as would be provided to <a href="#org0aca191">make-digest</a>. The second way to call these functions is to provide an actual digest object as the first argument. So one can say: </p> -<pre class="example" id="orgf2e4eb9"> +<pre class="example" id="org92e50e2"> (ironclad:digest-sequence :md5 *buffer*) </pre> @@ -677,18 +669,18 @@ the first argument. So one can say: or, equivalently: </p> -<pre class="example" id="orgb45f611"> +<pre class="example" id="org1cea259"> (let ((digester (ironclad:make-digest :md5))) (ironclad:digest-sequence digester *buffer*)) </pre> <p> -The second form comes in handy if you plan on <a href="#org79174fc">reusing the digest object</a>. +The second form comes in handy if you plan on <a href="#org9d66bdc">reusing the digest object</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgd5c1c87">(digest-sequence digest-spec sequence <span style="font-weight: bold; text-decoration: underline;">&rest</span> args <span style="font-weight: bold; text-decoration: underline;">&key</span> start end digest digest-start) => digest +<pre class="src src-lisp" id="orgbd0777b">(digest-sequence digest-spec sequence <span style="font-weight: bold; text-decoration: underline;">&rest</span> args <span style="font-weight: bold; text-decoration: underline;">&key</span> start end digest digest-start) => digest </pre> </div> @@ -696,12 +688,12 @@ The second form comes in handy if you plan on <a href="#org79174fc">reusing the Returns the digest of the subsequence of <i>sequence</i> bounded by <i>start</i> and <i>end</i>, according to <i>digest-name</i>. <i>sequence</i> must be a <code>(vector (unsigned-byte 8))</code>. <i>digest</i> and <i>digest-start</i> -are as in <a href="#org49c655e">produce-digest</a>. +are as in <a href="#orgebfad7a">produce-digest</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgbf974ca">(digest-stream digest-spec stream <span style="font-weight: bold; text-decoration: underline;">&rest</span> args <span style="font-weight: bold; text-decoration: underline;">&key</span> buffer start end digest digest-start) => digest +<pre class="src src-lisp" id="org4fb38fd">(digest-stream digest-spec stream <span style="font-weight: bold; text-decoration: underline;">&rest</span> args <span style="font-weight: bold; text-decoration: underline;">&key</span> buffer start end digest digest-start) => digest </pre> </div> @@ -710,7 +702,7 @@ Returns the digest of the contents of the stream specified by <i>stream</i>. <code>read-byte</code> must be a legal operation on <i>stream</i> and return an <code>(unsigned-byte 8)</code>. In a similar fashion, <code>read-sequence</code> on <i>stream</i> must support reading into a <code>(simple-array (unsigned-byte 8) (*))</code>. -<i>digest</i> and <i>digest-start</i> are as in <a href="#org49c655e">produce-digest</a>. +<i>digest</i> and <i>digest-start</i> are as in <a href="#orgebfad7a">produce-digest</a>. </p> <p> @@ -721,13 +713,13 @@ the data from the stream. <div class="org-src-container"> -<pre class="src src-lisp" id="orgfa721d4">(digest-file digest-spec pathname <span style="font-weight: bold; text-decoration: underline;">&rest</span> args <span style="font-weight: bold; text-decoration: underline;">&key</span> buffer start end digest digest-start) => digest +<pre class="src src-lisp" id="org7c78769">(digest-file digest-spec pathname <span style="font-weight: bold; text-decoration: underline;">&rest</span> args <span style="font-weight: bold; text-decoration: underline;">&key</span> buffer start end digest digest-start) => digest </pre> </div> <p> Returns the digest of the contents of the file named by <i>pathname</i>. -<i>digest</i> and <i>digest-start</i> are as in <a href="#org49c655e">produce-digest</a>. +<i>digest</i> and <i>digest-start</i> are as in <a href="#orgebfad7a">produce-digest</a>. </p> <p> @@ -737,33 +729,32 @@ the data from the stream. </p> </div> </div> - -<div id="outline-container-org8f955e1" class="outline-3"> -<h3 id="org8f955e1">Inquiry functions</h3> -<div class="outline-text-3" id="text-org8f955e1"> +<div id="outline-container-orgff3b3d6" class="outline-3"> +<h3 id="orgff3b3d6">Inquiry functions</h3> +<div class="outline-text-3" id="text-orgff3b3d6"> <div class="org-src-container"> -<pre class="src src-lisp" id="org897980f">(list-all-digests) => list +<pre class="src src-lisp" id="org2ccff16">(list-all-digests) => list </pre> </div> <p> -Returns a list whose elements may be validly passed to <a href="#org6b2b195">make-digest</a>. +Returns a list whose elements may be validly passed to <a href="#org0aca191">make-digest</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org8315ac3">(digest-supported-p name) => boolean +<pre class="src src-lisp" id="org1786607">(digest-supported-p name) => boolean </pre> </div> <p> -Returns <code>t</code> if <i>name</i> would be in the list returned by <a href="#org897980f">list-all-digests</a>, +Returns <code>t</code> if <i>name</i> would be in the list returned by <a href="#org2ccff16">list-all-digests</a>, <code>nil</code> otherwise. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orge810cd0">(digest-length digest) => number +<pre class="src src-lisp" id="orgdb90ebb">(digest-length digest) => number </pre> </div> @@ -773,10 +764,9 @@ a digest-name or a digest instance. </p> </div> </div> - -<div id="outline-container-org79174fc" class="outline-3"> -<h3 id="org79174fc">Miscellaneous</h3> -<div class="outline-text-3" id="text-org79174fc"> +<div id="outline-container-org9d66bdc" class="outline-3"> +<h3 id="org9d66bdc">Miscellaneous</h3> +<div class="outline-text-3" id="text-org9d66bdc"> <p> Ironclad digests are CLOS objects; the interesting thing about this for most purposes is that functions like <code>reinitialize-instance</code> are @@ -784,7 +774,7 @@ supported. This means one can write a fairly efficient clone of the <code>md5sum</code> program like so: </p> -<pre class="example" id="org6f312df"> +<pre class="example" id="orgc953f23"> (defun digest-sum-files (digest-name &rest files) (unless files (error "no files given to digest")) @@ -800,16 +790,15 @@ supported. This means one can write a fairly efficient clone of the </pre> </div> </div> - -<div id="outline-container-org4b94ab9" class="outline-3"> -<h3 id="org4b94ab9">Tree hashes</h3> -<div class="outline-text-3" id="text-org4b94ab9"> +<div id="outline-container-org631e0c2" class="outline-3"> +<h3 id="org631e0c2">Tree hashes</h3> +<div class="outline-text-3" id="text-org631e0c2"> <p> 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>. You create tree hashes as if you were creating a digest: </p> -<pre class="example" id="org2d7744c"> +<pre class="example" id="org1c3219b"> (ironclad:make-digest :tree-hash) </pre> @@ -820,7 +809,7 @@ digest algorithm is so common, a convenience function that makes your intent obvious has also been provided: </p> -<pre class="example" id="orgb67e2fe"> +<pre class="example" id="orgb990c13"> (ironclad:make-tiger-tree-hash) </pre> @@ -829,7 +818,7 @@ You may indicate that you wish to use a different algorithm than Tiger: </p> -<pre class="example" id="org137aafb"> +<pre class="example" id="org10cf356"> (ironclad:make-digest '(:treehash :digest :sha256)) </pre> @@ -837,7 +826,7 @@ Tiger: Or you might wish to use a different segment size: </p> -<pre class="example" id="orgf2232e9"> +<pre class="example" id="org42828ef"> (ironclad:make-digest '(:tree-hash :block-length 16384)) </pre> @@ -848,7 +837,6 @@ computed while computing the final tree hash. </div> </div> </div> - <div id="outline-container-message-authentication-codes" class="outline-2"> <h2 id="message-authentication-codes">Message authentication codes</h2> <div class="outline-text-2" id="text-message-authentication-codes"> @@ -874,14 +862,14 @@ Ironclad provides different kinds of MACs: <div class="org-src-container"> -<pre class="src src-lisp" id="orga84ba09">(make-mac mac-name key <span style="font-weight: bold; text-decoration: underline;">&rest</span> args) => mac +<pre class="src src-lisp" id="orgbc2a39c">(make-mac mac-name key <span style="font-weight: bold; text-decoration: underline;">&rest</span> args) => mac </pre> </div> <p> Return a MAC object initialized with a secret <i>key</i>. <i>mac-name</i> is a keyword naming the algorithm you wish <i>mac</i> to use. The supported -MACs can be found by calling <a href="#org9bb62e5">list-all-macs</a>. They are: +MACs can be found by calling <a href="#org73970a8">list-all-macs</a>. They are: </p> <ul class="org-ul"> <li>blake2-mac</li> @@ -895,7 +883,7 @@ MACs can be found by calling <a href="#org9bb62e5">list-all-macs</a>. They are: </ul> <p> -Like for <a href="#org6b2b195">make-digest</a>, <i>mac-name</i> should be a symbol in the <code>keyword</code> +Like for <a href="#org0aca191">make-digest</a>, <i>mac-name</i> should be a symbol in the <code>keyword</code> or <code>ironclad</code> packages. </p> @@ -903,7 +891,7 @@ or <code>ironclad</code> packages. Some MACs take extra arguments that can be specified in <i>args</i>. </p> -<pre class="example" id="org21661a7"> +<pre class="example" id="orgc279203"> (make-mac :blake2-mac key &key digest-length) (make-mac :blake2s-mac key &key digest-length) (make-mac :cmac key cipher-name) @@ -915,34 +903,34 @@ Some MACs take extra arguments that can be specified in <i>args</i>. </pre> <p> -When making a Blake2 MAC, the length of the <i>key</i> passed to <a href="#orga84ba09">make-mac</a> +When making a Blake2 MAC, the length of the <i>key</i> passed to <a href="#orgbc2a39c">make-mac</a> must be 64 bytes. </p> <p> -When making a Blake2s MAC, the length of the <i>key</i> passed to <a href="#orga84ba09">make-mac</a> +When making a Blake2s MAC, the length of the <i>key</i> passed to <a href="#orgbc2a39c">make-mac</a> must be 32 bytes. </p> <p> -When making a CMAC, <i>cipher-name</i> must have a <a href="#org228bea0">block-length</a> of either 8, 16, 32, +When making a CMAC, <i>cipher-name</i> must have a <a href="#org32e5f3d">block-length</a> of either 8, 16, 32, 64 or 128; this restriction is satisfied by many ciphers in Ironclad with the notable exception of stream ciphers. <i>key</i> must be an acceptable key for <i>cipher-name</i>. </p> <p> -When making a GMAC, <i>cipher-name</i> must have a <a href="#org228bea0">block-length</a> of 16. <i>key</i> must be +When making a GMAC, <i>cipher-name</i> must have a <a href="#org32e5f3d">block-length</a> of 16. <i>key</i> must be an acceptable key for <i>cipher-name</i>. </p> <p> -When making a Poly1305 MAC, the length of the <i>key</i> passed to <a href="#orga84ba09">make-mac</a> must be +When making a Poly1305 MAC, the length of the <i>key</i> passed to <a href="#orgbc2a39c">make-mac</a> must be 32 bytes. </p> <p> -When making a SipHash MAC, the length of the <i>key</i> passed to <a href="#orga84ba09">make-mac</a> must be 16 +When making a SipHash MAC, the length of the <i>key</i> passed to <a href="#orgbc2a39c">make-mac</a> must be 16 bytes. <i>digest-length</i> is 8 by default, but it can also be set to 16. By default, <i>compression-rounds</i> is 2 and <i>finalization-rounds</i> is 4. </p> @@ -966,12 +954,12 @@ MAC objects support <code>reinitialize-instance</code>: </div> <p> -The <i>:key</i> argument is the secret key, as provided to <a href="#orga84ba09">make-mac</a>. +The <i>:key</i> argument is the secret key, as provided to <a href="#orgbc2a39c">make-mac</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgb66a902">(update-mac mac thing <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => (values) +<pre class="src src-lisp" id="org91341ca">(update-mac mac thing <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => (values) </pre> </div> @@ -991,7 +979,7 @@ listing them would get very tedious for no benefit. An example should suffice. </p> -<pre class="example" id="org06f9eba"> +<pre class="example" id="org23a2d97"> (let* ((key (random-data 32)) (mac (ironclad:make-mac :hmac key :sha256)) (array (make-array 16 :element-type '(unsigned-byte 8) :initial-element 0))) @@ -1004,7 +992,7 @@ suffice. <div class="org-src-container"> -<pre class="src src-lisp" id="org9989d0c">(produce-mac mac <span style="font-weight: bold; text-decoration: underline;">&key</span> digest digest-start) => digest +<pre class="src src-lisp" id="org967004b">(produce-mac mac <span style="font-weight: bold; text-decoration: underline;">&key</span> digest digest-start) => digest </pre> </div> @@ -1017,57 +1005,55 @@ compute a "rolling MAC" of a document. <p> If <i>digest</i> is provided, the computed digest will be placed into <i>digest</i> starting at <i>digest-start</i>. <i>digest</i> must be a -<code>(simple-array (unsigned-byte 8) (*))</code>. An <a href="#org3306fab">insufficient-buffer-space</a> +<code>(simple-array (unsigned-byte 8) (*))</code>. An <a href="#org701dd62">insufficient-buffer-space</a> error will be signaled if there is insufficient space in <i>digest</i>. </p> <p> -The length of the digest returned by <a href="#org9989d0c">produce-mac</a> is determined by the -kind of MAC and the extra arguments passed to <a href="#orga84ba09">make-mac</a>: +The length of the digest returned by <a href="#org967004b">produce-mac</a> is determined by the +kind of MAC and the extra arguments passed to <a href="#orgbc2a39c">make-mac</a>: </p> <ul class="org-ul"> <li>blake2-mac: from 1 to 64 bytes (64 by default)</li> <li>blake2s-mac: from 1 to 32 bytes (32 by default)</li> -<li>cmac: <a href="#org228bea0">block-length</a> of the <i>cipher-name</i> passed to <a href="#orga84ba09">make-mac</a></li> +<li>cmac: <a href="#org32e5f3d">block-length</a> of the <i>cipher-name</i> passed to <a href="#orgbc2a39c">make-mac</a></li> <li>gmac: 16 bytes</li> -<li>hmac: <a href="#orge810cd0">digest-length</a> of the <i>digest-name</i> passed to <a href="#orga84ba09">make-mac</a></li> +<li>hmac: <a href="#orgdb90ebb">digest-length</a> of the <i>digest-name</i> passed to <a href="#orgbc2a39c">make-mac</a></li> <li>poly1305: 16 bytes</li> -<li>siphash: <i>digest-length</i> passed to <a href="#orga84ba09">make-mac</a> (8 by default)</li> -<li>skein-mac: <i>digest-length</i> passed to <a href="#orga84ba09">make-mac</a> (64 by default)</li> +<li>siphash: <i>digest-length</i> passed to <a href="#orgbc2a39c">make-mac</a> (8 by default)</li> +<li>skein-mac: <i>digest-length</i> passed to <a href="#orgbc2a39c">make-mac</a> (64 by default)</li> </ul> </div> - -<div id="outline-container-org15d5964" class="outline-3"> -<h3 id="org15d5964">Inquiry functions</h3> -<div class="outline-text-3" id="text-org15d5964"> +<div id="outline-container-org898454b" class="outline-3"> +<h3 id="org898454b">Inquiry functions</h3> +<div class="outline-text-3" id="text-org898454b"> <div class="org-src-container"> -<pre class="src src-lisp" id="org9bb62e5">(list-all-macs) => list +<pre class="src src-lisp" id="org73970a8">(list-all-macs) => list </pre> </div> <p> -Returns a list whose elements may be validly passed to <a href="#orga84ba09">make-mac</a>. +Returns a list whose elements may be validly passed to <a href="#orgbc2a39c">make-mac</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgb9b4f69">(mac-supported-p name) => boolean +<pre class="src src-lisp" id="orgfe5f676">(mac-supported-p name) => boolean </pre> </div> <p> -Returns <code>t</code> if <i>name</i> would be in the list returned by <a href="#org9bb62e5">list-all-macs</a>, +Returns <code>t</code> if <i>name</i> would be in the list returned by <a href="#org73970a8">list-all-macs</a>, <code>nil</code> otherwise. </p> </div> </div> </div> - <div id="outline-container-authenticated-encryption" class="outline-2"> <h2 id="authenticated-encryption">Authenticated encryption</h2> <div class="outline-text-2" id="text-authenticated-encryption"> <div class="org-src-container"> -<pre class="src src-lisp" id="org6cb8142">(make-authenticated-encryption-mode name <span style="font-weight: bold; text-decoration: underline;">&rest</span> args) => mode +<pre class="src src-lisp" id="org44e9414">(make-authenticated-encryption-mode name <span style="font-weight: bold; text-decoration: underline;">&rest</span> args) => mode </pre> </div> @@ -1077,7 +1063,7 @@ and decryption. </p> <p> -<i>name</i> denotes the mode to use. <a href="#org10931e4">list-all-authenticated-encryption-modes</a> will +<i>name</i> denotes the mode to use. <a href="#orga5e1f4c">list-all-authenticated-encryption-modes</a> will tell you the names of all the supported modes. They are: </p> <ul class="org-ul"> @@ -1094,7 +1080,7 @@ tell you the names of all the supported modes. They are: <i>args</i> depends on the chosen authenticated encryption mode. </p> -<pre class="example" id="org7787415"> +<pre class="example" id="orgbacd74f"> (make-authenticated-encryption-mode :eax &key tag cipher-name key initialization-vector) (make-authenticated-encryption-mode :etm &key tag cipher mac) (make-authenticated-encryption-mode :gcm &key tag cipher-name key initialization-vector) @@ -1104,8 +1090,8 @@ tell you the names of all the supported modes. They are: If <i>tag</i> is specified, it will be used at the end of decryption (when the <i>handle-final-block</i> flag is <code>t</code>) to check the authenticity of the data. A <code>bad-authentication-tag</code> error will be signaled if the data is not authentic. -If you don't specify it, you will have to call <a href="#orgd14307b">produce-tag</a> after decryption and -check that the tags match (e.g. using <a href="#org5829b54">constant-time-equal</a>). +If you don't specify it, you will have to call <a href="#org2949cbe">produce-tag</a> after decryption and +check that the tags match (e.g. using <a href="#org9ca5d87">constant-time-equal</a>). </p> <p> @@ -1113,18 +1099,18 @@ When using EAX, <i>key</i> must be a suitable key for the chosen <i>cipher-name< </p> <p> -When using ETM, <i>cipher</i> must be a cipher object created by <a href="#org305b09d">make-cipher</a>. -<i>mac</i> must be a mac object created by <a href="#orga84ba09">make-mac</a>. +When using ETM, <i>cipher</i> must be a cipher object created by <a href="#orga194874">make-cipher</a>. +<i>mac</i> must be a mac object created by <a href="#orgbc2a39c">make-mac</a>. </p> <p> -When using GCM, <i>cipher-name</i> must have a <a href="#org228bea0">block-length</a> of 16 bytes. <i>key</i> must be a suitable key +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 for the chosen cipher. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org99a5c5d">(process-associated-data mode data <span style="font-weight: bold; text-decoration: underline;">&key</span> start end) => (values) +<pre class="src src-lisp" id="org0172765">(process-associated-data mode data <span style="font-weight: bold; text-decoration: underline;">&key</span> start end) => (values) </pre> </div> @@ -1135,11 +1121,11 @@ and <i>end</i> so that they are taken into consideration in the authentication t <p> -An authenticated encryption object can be used with the <a href="#org911f61d">encrypt</a>, <a href="#org530d42d">decrypt</a>, -<a href="#orgdc7621c">encrypt-message</a> and <a href="#orgae61015">decrypt-message</a> functions. +An authenticated encryption object can be used with the <a href="#orga0c509f">encrypt</a>, <a href="#org8d3dffc">decrypt</a>, +<a href="#org6424db2">encrypt-message</a> and <a href="#org13a3a49">decrypt-message</a> functions. </p> -<pre class="example" id="org1e63499"> +<pre class="example" id="org15664f4"> (encrypt mode plaintext ciphertext &key plaintext-start plaintext-end ciphertext-start handle-final-block) (decrypt mode ciphertext plaintext &key ciphertext-start ciphertext-end plaintext-start handle-final-block) (encrypt-message mode message &key start end associated-data associated-data-start associated-data-end) @@ -1148,7 +1134,7 @@ An authenticated encryption object can be used with the <a href="#org911f61d">en <div class="org-src-container"> -<pre class="src src-lisp" id="orgd14307b">(produce-tag mode <span style="font-weight: bold; text-decoration: underline;">&key</span> tag tag-start) => tag +<pre class="src src-lisp" id="org2949cbe">(produce-tag mode <span style="font-weight: bold; text-decoration: underline;">&key</span> tag tag-start) => tag </pre> </div> @@ -1156,38 +1142,36 @@ An authenticated encryption object can be used with the <a href="#org911f61d">en Return the authentication tag of the data processed by <i>mode</i> so far. If <i>tag</i> is provided, the computed tag will be placed into <i>tag</i> starting at <i>tag-start</i>. <i>tag</i> must be a <code>(simple-array (unsigned-byte 8) (*))</code>. An -<a href="#org3306fab">insufficient-buffer-space</a> error will be signaled if there is insufficient space +<a href="#org701dd62">insufficient-buffer-space</a> error will be signaled if there is insufficient space in <i>tag</i>. </p> </div> - -<div id="outline-container-orga5b5b5e" class="outline-3"> -<h3 id="orga5b5b5e">Inquiry functions</h3> -<div class="outline-text-3" id="text-orga5b5b5e"> +<div id="outline-container-org9d6ac20" class="outline-3"> +<h3 id="org9d6ac20">Inquiry functions</h3> +<div class="outline-text-3" id="text-org9d6ac20"> <div class="org-src-container"> -<pre class="src src-lisp" id="org10931e4">(list-all-authenticated-encryption-modes) => list +<pre class="src src-lisp" id="orga5e1f4c">(list-all-authenticated-encryption-modes) => list </pre> </div> <p> Returns a list whose elements may be validly passed to -<a href="#org6cb8142">make-authenticated-encryption-mode</a>. +<a href="#org44e9414">make-authenticated-encryption-mode</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org03df408">(authenticated-encryption-mode-supported-p name) => boolean +<pre class="src src-lisp" id="org60f6656">(authenticated-encryption-mode-supported-p name) => boolean </pre> </div> <p> Returns <code>t</code> if <i>name</i> would be in the list returned by -<a href="#org10931e4">list-all-authenticated-encryption-modes</a> <code>nil</code> otherwise. +<a href="#orga5e1f4c">list-all-authenticated-encryption-modes</a> <code>nil</code> otherwise. </p> </div> </div> </div> - <div id="outline-container-key-derivation-functions" class="outline-2"> <h2 id="key-derivation-functions">Key derivation functions</h2> <div class="outline-text-2" id="text-key-derivation-functions"> @@ -1195,7 +1179,7 @@ Returns <code>t</code> if <i>name</i> would be in the list returned by Ironclad comes with a few key derivation functions: </p> <ul class="org-ul"> -<li>Argon2 (only Argon2d and Argon2i without parallelism are implemented)</li> +<li>Argon2 (only variants without parallelism are implemented)</li> <li>Bcrypt</li> <li>Bcrypt-pbkdf</li> <li>PBKDF1</li> @@ -1206,12 +1190,12 @@ Ironclad comes with a few key derivation functions: <div class="org-src-container"> -<pre class="src src-lisp" id="orgbeaefe6">(derive-key kdf passphrase salt iteration-count key-length) => digest +<pre class="src src-lisp" id="org9813827">(derive-key kdf passphrase salt iteration-count key-length) => digest </pre> </div> <p> -Given a key derivation function object (produced by <a href="#orgb345fc9">make-kdf</a>), +Given a key derivation function object (produced by <a href="#orgc3724fd">make-kdf</a>), a password and salt (both must be of type <code>(simple-array (unsigned-byte 8) (*))</code>), and number of iterations, returns the password digest as a byte array of length <i>key-length</i>. @@ -1229,7 +1213,7 @@ For bcrypt-pbkdf, the <i>key-length</i> must be between 1 and 1024. <div class="org-src-container"> -<pre class="src src-lisp" id="orgb345fc9">(make-kdf kind <span style="font-weight: bold; text-decoration: underline;">&key</span> digest n r p block-count additional-key additional-data) => kdf +<pre class="src src-lisp" id="orgc3724fd">(make-kdf kind <span style="font-weight: bold; text-decoration: underline;">&key</span> digest n r p block-count additional-key additional-data) => kdf </pre> </div> @@ -1243,6 +1227,7 @@ Returns a key derivation function instance. <ul class="org-ul"> <li>argon2d</li> <li>argon2i</li> +<li>argon2id</li> <li>bcrypt</li> <li>bcrypt-pbkdf</li> <li>pbkdf1</li> @@ -1270,7 +1255,7 @@ memory cost parameters that must be defined such that <p> The default Scrypt parameters are <i>N</i> = 4096, <i>r</i> = 8, and <i>p</i> = 2. Please note that depending on the values of <i>N</i> and <i>r</i>, -<a href="#orgbeaefe6">derive-key</a> may not be able to allocate sufficient space for its +<a href="#org9813827">derive-key</a> may not be able to allocate sufficient space for its temporary arrays. </p> @@ -1282,18 +1267,17 @@ to precise the <code>info</code> vector from the <a href="https://tools.ietf.org <div class="org-src-container"> -<pre class="src src-lisp" id="orgdf994b9">(list-all-kdfs) => list +<pre class="src src-lisp" id="org3509dc1">(list-all-kdfs) => list </pre> </div> <p> -Returns a list of KDF kinds that may be validly passed to <a href="#orgb345fc9">make-kdf</a>. +Returns a list of KDF kinds that may be validly passed to <a href="#orgc3724fd">make-kdf</a>. </p> </div> - -<div id="outline-container-org7d71e97" class="outline-3"> -<h3 id="org7d71e97">PBKDF convenience functions</h3> -<div class="outline-text-3" id="text-org7d71e97"> +<div id="outline-container-org9f9093d" class="outline-3"> +<h3 id="org9f9093d">PBKDF convenience functions</h3> +<div class="outline-text-3" id="text-org9f9093d"> <p> Ironclad comes with convenience functions for using PBKDF1 and PBKDF2 to store passwords. @@ -1301,7 +1285,7 @@ to store passwords. <div class="org-src-container"> -<pre class="src src-lisp" id="orgd74e355">(pbkdf2-hash-password password <span style="font-weight: bold; text-decoration: underline;">&key</span> salt digest iterations) => password +<pre class="src src-lisp" id="org7012f46">(pbkdf2-hash-password password <span style="font-weight: bold; text-decoration: underline;">&key</span> salt digest iterations) => password </pre> </div> @@ -1313,7 +1297,7 @@ byte vectors. <div class="org-src-container"> -<pre class="src src-lisp" id="org07400ac">(pbkdf2-hash-password-to-combined-string password <span style="font-weight: bold; text-decoration: underline;">&key</span> salt digest iterations) => password +<pre class="src src-lisp" id="org57ce335">(pbkdf2-hash-password-to-combined-string password <span style="font-weight: bold; text-decoration: underline;">&key</span> salt digest iterations) => password </pre> </div> @@ -1325,19 +1309,18 @@ encodes the given salt and PBKDF2 algorithm parameters. <div class="org-src-container"> -<pre class="src src-lisp" id="org7b00ae1">(pbkdf2-check-password password combined-salt-and-digest) => boolean +<pre class="src src-lisp" id="orgf7339d5">(pbkdf2-check-password password combined-salt-and-digest) => boolean </pre> </div> <p> Given a <i>password</i> byte vector and a combined salt and digest string -produced by <a href="#org07400ac">pbkdf2-hash-password-to-combined-string</a>, checks whether +produced by <a href="#org57ce335">pbkdf2-hash-password-to-combined-string</a>, checks whether the password is valid. </p> </div> </div> </div> - <div id="outline-container-public-key-cryptography" class="outline-2"> <h2 id="public-key-cryptography">Public key cryptography</h2> <div class="outline-text-2" id="text-public-key-cryptography"> @@ -1381,12 +1364,11 @@ Diffie-Hellman key exchange: <li>Secp521r1 (a.k.a. NIST P-521)</li> </ul> </div> - -<div id="outline-container-org5c57224" class="outline-3"> -<h3 id="org5c57224">Key pair generation</h3> -<div class="outline-text-3" id="text-org5c57224"> +<div id="outline-container-orgf7c1959" class="outline-3"> +<h3 id="orgf7c1959">Key pair generation</h3> +<div class="outline-text-3" id="text-orgf7c1959"> <div class="org-src-container"> -<pre class="src src-lisp" id="org27d207e">(generate-key-pair kind <span style="font-weight: bold; text-decoration: underline;">&key</span> num-bits <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => private-key, public-key +<pre class="src src-lisp" id="org3dec0c7">(generate-key-pair kind <span style="font-weight: bold; text-decoration: underline;">&key</span> num-bits <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => private-key, public-key </pre> </div> @@ -1404,27 +1386,26 @@ generated. For example, if Alice wants to generate a key pair for a Diffie-Hellman exchange with Bob's Elgamal key pair: </p> -<pre class="example" id="org9580db2"> +<pre class="example" id="org68b3971"> (generate-key-pair :elgamal :compatible-with-key bob-public-key) </pre> <div class="org-src-container"> -<pre class="src src-lisp" id="orgf6e574c">(list-all-key-pair-kinds) => list +<pre class="src src-lisp" id="org7158eaf">(list-all-key-pair-kinds) => list </pre> </div> <p> Returns a list of key pair kinds that may be validly passed to -<a href="#org27d207e">generate-key-pair</a>. +<a href="#org3dec0c7">generate-key-pair</a>. </p> </div> - -<div id="outline-container-org6aa62e3" class="outline-4"> -<h4 id="org6aa62e3">Key construction</h4> -<div class="outline-text-4" id="text-org6aa62e3"> +<div id="outline-container-org0191a1b" class="outline-4"> +<h4 id="org0191a1b">Key construction</h4> +<div class="outline-text-4" id="text-org0191a1b"> <div class="org-src-container"> -<pre class="src src-lisp" id="org3c01c3b">(make-public-key kind <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => public-key +<pre class="src src-lisp" id="org6bca683">(make-public-key kind <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => public-key </pre> </div> @@ -1434,7 +1415,7 @@ arguments vary according to <i>kind</i>. The interesting bits are in the methods that specialize on <i>kind</i>, below. </p> -<pre class="example" id="orgd1fedb4"> +<pre class="example" id="org3e6e3b5"> (make-public-key :curve25519 &key y) => public-key (make-public-key :curve448 &key y) => public-key (make-public-key :dsa &key p q g y) => public-key @@ -1450,7 +1431,7 @@ methods that specialize on <i>kind</i>, below. <div class="org-src-container"> -<pre class="src src-lisp" id="orga28ccaf">(make-private-key kind <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => private-key +<pre class="src src-lisp" id="org59929bc">(make-private-key kind <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => private-key </pre> </div> @@ -1460,7 +1441,7 @@ according to <i>kind</i>. The interesting bits are in the methods that specialize on <i>kind</i>, below. </p> -<pre class="example" id="org8e7a077"> +<pre class="example" id="org96ff947"> (make-private-key :curve25519 &key x y) => private-key (make-private-key :curve448 &key x y) => private-key (make-private-key :dsa &key p q g y x) => private-key @@ -1508,44 +1489,42 @@ For RSA keys, the type of the parameters is <code>integer</code>: </ul> </div> </div> - -<div id="outline-container-orgdb9c7eb" class="outline-4"> -<h4 id="orgdb9c7eb">Key destructuring</h4> -<div class="outline-text-4" id="text-orgdb9c7eb"> +<div id="outline-container-org3ab9605" class="outline-4"> +<h4 id="org3ab9605">Key destructuring</h4> +<div class="outline-text-4" id="text-org3ab9605"> <p> -The <a href="#orgf19c814">destructure-public-key</a> and <a href="#orgdbaf636">destructure-private-key</a> functions can +The <a href="#org35e890d">destructure-public-key</a> and <a href="#orgf52139e">destructure-private-key</a> functions can be useful if you need to store keys somewhere for future use. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgf19c814">(destructure-public-key public-key) => plist +<pre class="src src-lisp" id="org35e890d">(destructure-public-key public-key) => plist </pre> </div> <p> Return the elements of a public key in a plist. The indicators of the -plist match the <i>&key</i> arguments of the <a href="#org3c01c3b">make-public-key</a> method. +plist match the <i>&key</i> arguments of the <a href="#org6bca683">make-public-key</a> method. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgdbaf636">(destructure-private-key private-key) => plist +<pre class="src src-lisp" id="orgf52139e">(destructure-private-key private-key) => plist </pre> </div> <p> Return the elements of a private key in a plist. The indicators of the -plist match the <i>&key</i> arguments of the <a href="#orga28ccaf">make-private-key</a> method. +plist match the <i>&key</i> arguments of the <a href="#org59929bc">make-private-key</a> method. </p> </div> </div> </div> - -<div id="outline-container-org140ddac" class="outline-3"> -<h3 id="org140ddac">Digital signatures</h3> -<div class="outline-text-3" id="text-org140ddac"> +<div id="outline-container-orgc179c55" class="outline-3"> +<h3 id="orgc179c55">Digital signatures</h3> +<div class="outline-text-3" id="text-orgc179c55"> <div class="org-src-container"> -<pre class="src src-lisp" id="org283003e">(sign-message key message <span style="font-weight: bold; text-decoration: underline;">&key</span> start end <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => signature +<pre class="src src-lisp" id="org6d2558f">(sign-message key message <span style="font-weight: bold; text-decoration: underline;">&key</span> start end <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => signature </pre> </div> @@ -1556,14 +1535,14 @@ Return a signature of <i>message</i> between <i>start</i> and <i>end</i> signed </p> <p> -<span class="underline">Note:</span> The <a href="#org283003e">sign-message</a> does not perform the hashing of the data. You +<span class="underline">Note:</span> The <a href="#org6d2558f">sign-message</a> does not perform the hashing of the data. You should hash your data using your favorite hash function, and then use -this hash as the <i>message</i> passed to <a href="#org283003e">sign-message</a>. +this hash as the <i>message</i> passed to <a href="#org6d2558f">sign-message</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgb30dba8">(verify-signature key message signature <span style="font-weight: bold; text-decoration: underline;">&key</span> start end <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => boolean +<pre class="src src-lisp" id="orgf029208">(verify-signature key message signature <span style="font-weight: bold; text-decoration: underline;">&key</span> start end <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => boolean </pre> </div> @@ -1573,10 +1552,9 @@ Verify whether <i>signature</i> is a valid signature of <i>message</i> between and <code>nil</code> otherwise. </p> </div> - -<div id="outline-container-org50a14a9" class="outline-4"> -<h4 id="org50a14a9">Padding</h4> -<div class="outline-text-4" id="text-org50a14a9"> +<div id="outline-container-org5339bb4" class="outline-4"> +<h4 id="org5339bb4">Padding</h4> +<div class="outline-text-4" id="text-org5339bb4"> <p> To be secure, RSA signature requires the message to be padded. The <i>pss</i> key parameter is provided to pad (or unpad) the message @@ -1585,7 +1563,7 @@ The value of the <i>pss</i> key parameter can be either a digest name or <code>t</code> (which will use the sha1 digest). </p> -<pre class="example" id="orge629c27"> +<pre class="example" id="org34ea6e9"> (sign-message rsa-private-key message :pss t) => signature (verify-signature rsa-public-key message signature :pss t) => boolean </pre> @@ -1596,20 +1574,19 @@ necessary. </p> </div> </div> - -<div id="outline-container-org1d6e634" class="outline-4"> -<h4 id="org1d6e634">Signature nonce</h4> -<div class="outline-text-4" id="text-org1d6e634"> +<div id="outline-container-org35d622b" class="outline-4"> +<h4 id="org35d622b">Signature nonce</h4> +<div class="outline-text-4" id="text-org35d622b"> <p> DSA, Elgamal and ECDSA (Secp256k1, Secp256r1, Secp384r1 and Secp521r1) signatures require the generation of a nonce. You must never sign two different messages with the same key and the same nonce, or anyone having these two signatures will be able compute your private key. Ironclad uses the -<a href="#org207e590">generate-signature-nonce</a> method which by default generates random nonces. +<a href="#org432e2f4">generate-signature-nonce</a> method which by default generates random nonces. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org207e590">(generate-signature-nonce (key message <span style="font-weight: bold; text-decoration: underline;">&optional</span> parameters)) => nonce +<pre class="src src-lisp" id="org432e2f4">(generate-signature-nonce (key message <span style="font-weight: bold; text-decoration: underline;">&optional</span> parameters)) => nonce </pre> </div> @@ -1621,35 +1598,34 @@ For DSA, <i>parameters</i> is <i>q</i>. For Elgamal, <i>parameters</i> is <i>p</ <p> If instead of random nonces, you want to have deterministic nonces (e.g. like -in RFC 6979), you will have to redefine <a href="#org207e590">generate-signature-nonce</a>. For example, +in RFC 6979), you will have to redefine <a href="#org432e2f4">generate-signature-nonce</a>. For example, to have deterministic nonces for Secp256k1 ECDSA signatures, you could do something like: </p> -<pre class="example" id="org1e9bd3b"> +<pre class="example" id="org3692b97"> (defmethod generate-signature-nonce ((key secp256k1-private-key) message &optional parameters) (declare (ignore parameters)) (compute-deterministic-nonce key message)) </pre> </div> </div> - -<div id="outline-container-orgd1680ea" class="outline-4"> -<h4 id="orgd1680ea">Format of signatures</h4> -<div class="outline-text-4" id="text-orgd1680ea"> +<div id="outline-container-orgf19958c" class="outline-4"> +<h4 id="orgf19958c">Format of signatures</h4> +<div class="outline-text-4" id="text-orgf19958c"> <p> -<a href="#org283003e">sign-message</a> returns signatures as octet vectors. When the signature +<a href="#org6d2558f">sign-message</a> returns signatures as octet vectors. When the signature contains several values (e.g. the R and S values of DSA signatures), the octet vector is the concatenation of these values (e.g. the first half of the vector is the R value, the second half is the S value). -You can use the <a href="#org7b9e693">make-signature</a> and <a href="#orgbc60ed4">destructure-signature</a> functions if +You can use the <a href="#orgfa225d8">make-signature</a> and <a href="#orgc5506b9">destructure-signature</a> functions if you need access to the elements of a signature (e.g. to use a different kind of serialization). </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org7b9e693">(make-signature kind <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => signature +<pre class="src src-lisp" id="orgfa225d8">(make-signature kind <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => signature </pre> </div> @@ -1659,7 +1635,7 @@ vary according to <i>kind</i>. The interesting bits are in the methods that specialize on <i>kind</i>, below. </p> -<pre class="example" id="orgc601eab"> +<pre class="example" id="org090baba"> (make-signature :dsa &key r s n-bits) => signature (make-signature :ed25519 &key r s) => signature (make-signature :ed448 &key r s) => signature @@ -1689,23 +1665,22 @@ For RSA signatures, the type of the parameters <i>s</i> and <i>n-bits</i> is <div class="org-src-container"> -<pre class="src src-lisp" id="orgbc60ed4">(destructure-signature kind signature) => plist +<pre class="src src-lisp" id="orgc5506b9">(destructure-signature kind signature) => plist </pre> </div> <p> Return the elements of a signature in a plist. The indicators of the -plist match the <i>&key</i> arguments of the <a href="#org7b9e693">make-signature</a> method. +plist match the <i>&key</i> arguments of the <a href="#orgfa225d8">make-signature</a> method. </p> </div> </div> </div> - -<div id="outline-container-org3abbf25" class="outline-3"> -<h3 id="org3abbf25">Encryption and decryption</h3> -<div class="outline-text-3" id="text-org3abbf25"> +<div id="outline-container-org2a13b46" class="outline-3"> +<h3 id="org2a13b46">Encryption and decryption</h3> +<div class="outline-text-3" id="text-org2a13b46"> <div class="org-src-container"> -<pre class="src src-lisp" id="orgdc7621c">(encrypt-message key message <span style="font-weight: bold; text-decoration: underline;">&key</span> start end <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => encrypted-message +<pre class="src src-lisp" id="org6424db2">(encrypt-message key message <span style="font-weight: bold; text-decoration: underline;">&key</span> start end <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => encrypted-message </pre> </div> @@ -1716,7 +1691,7 @@ the class of <i>key</i> determines the algorithm used to encrypt the message. <div class="org-src-container"> -<pre class="src src-lisp" id="orgae61015">(decrypt-message key message <span style="font-weight: bold; text-decoration: underline;">&key</span> start end n-bits <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => decrypted-message +<pre class="src src-lisp" id="org13a3a49">(decrypt-message key message <span style="font-weight: bold; text-decoration: underline;">&key</span> start end n-bits <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => decrypted-message </pre> </div> @@ -1728,10 +1703,9 @@ message (e.g. a small byte vector starting with zeros encrypted without padding, which is probably a bad idea, c.f. Padding section). </p> </div> - -<div id="outline-container-orgade7ef1" class="outline-4"> -<h4 id="orgade7ef1">Padding</h4> -<div class="outline-text-4" id="text-orgade7ef1"> +<div id="outline-container-org113df61" class="outline-4"> +<h4 id="org113df61">Padding</h4> +<div class="outline-text-4" id="text-org113df61"> <p> To be secure, RSA encryption requires the message to be padded. The <i>oaep</i> key parameter is provided to pad (or unpad) the message during @@ -1740,7 +1714,7 @@ The value of the <i>oaep</i> key parameter can be either a digest name or <code>t</code> (which will use the sha1 digest). </p> -<pre class="example" id="org7293352"> +<pre class="example" id="org2c2f3ec"> (encrypt-message rsa-public-key message :oaep t) => encrypted-message (decrypt-message rsa-private-key message :oaep t) => decrypted-message </pre> @@ -1751,24 +1725,23 @@ necessary. </p> </div> </div> - -<div id="outline-container-org9acd73d" class="outline-4"> -<h4 id="org9acd73d">Format of messages</h4> -<div class="outline-text-4" id="text-org9acd73d"> +<div id="outline-container-orgea18398" class="outline-4"> +<h4 id="orgea18398">Format of messages</h4> +<div class="outline-text-4" id="text-orgea18398"> <p> -<a href="#orgdc7621c">encrypt-message</a> returns encrypted messages as octet vectors. When the +<a href="#org6424db2">encrypt-message</a> returns encrypted messages as octet vectors. When the message contains several values (e.g. the C1 and C2 values of Elgamal messages), the octet vector is the concatenation of these values (e.g. the first half of the vector is the big-endian representation of the C1 value, the second half is the C2 value). You can use the -<a href="#org90529bc">make-message</a> and <a href="#org715c55b">destructure-message</a> functions if you need access to +<a href="#org83c91f2">make-message</a> and <a href="#orgc65f9d9">destructure-message</a> functions if you need access to the elements of a message (e.g. to use a different kind of serialization). </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org90529bc">(make-message kind <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => message +<pre class="src src-lisp" id="org83c91f2">(make-message kind <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => message </pre> </div> @@ -1778,7 +1751,7 @@ vary according to <i>kind</i>. The interesting bits are in the methods that specialize on <i>kind</i>, below. </p> -<pre class="example" id="orgb26e7ea"> +<pre class="example" id="org7b37e36"> (make-message :elgamal &key c1 c2 n-bits) => message (make-message :rsa &key m n-bits) => message </pre> @@ -1795,23 +1768,22 @@ For RSA signatures, the type of the parameters <i>m</i> and <i>n-bits</i> is <div class="org-src-container"> -<pre class="src src-lisp" id="org715c55b">(destructure-message kind message) => plist +<pre class="src src-lisp" id="orgc65f9d9">(destructure-message kind message) => plist </pre> </div> <p> Return the elements of a message in a plist. The indicators of the -plist match the <i>&key</i> arguments of the <a href="#org90529bc">make-message</a> method. +plist match the <i>&key</i> arguments of the <a href="#org83c91f2">make-message</a> method. </p> </div> </div> </div> - -<div id="outline-container-orgc3ebbf6" class="outline-3"> -<h3 id="orgc3ebbf6">Diffie-Hellman key exchange</h3> -<div class="outline-text-3" id="text-orgc3ebbf6"> +<div id="outline-container-org0cacffc" class="outline-3"> +<h3 id="org0cacffc">Diffie-Hellman key exchange</h3> +<div class="outline-text-3" id="text-org0cacffc"> <div class="org-src-container"> -<pre class="src src-lisp" id="org063463a">(diffie-hellman private-key public-key) => bytes +<pre class="src src-lisp" id="org548e6ec">(diffie-hellman private-key public-key) => bytes </pre> </div> @@ -1822,12 +1794,11 @@ compatible, i.e. have the same group parameters). </p> </div> </div> - -<div id="outline-container-orgeb05200" class="outline-3"> -<h3 id="orgeb05200">Elliptic curve operations</h3> -<div class="outline-text-3" id="text-orgeb05200"> +<div id="outline-container-orge1daa32" class="outline-3"> +<h3 id="orge1daa32">Elliptic curve operations</h3> +<div class="outline-text-3" id="text-orge1daa32"> <div class="org-src-container"> -<pre class="src src-lisp" id="orgd26c3be">(ec-make-point kind <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => point +<pre class="src src-lisp" id="orgd4c1351">(ec-make-point kind <span style="font-weight: bold; text-decoration: underline;">&key</span> <span style="font-weight: bold; text-decoration: underline;">&allow-other-keys</span>) => point </pre> </div> @@ -1836,7 +1807,7 @@ Return a point of <i>kind</i>, initialized according to the specified coordinate The interesting bits are in the methods that specialize on <i>kind</i>, below. </p> -<pre class="example" id="orgd1e034b"> +<pre class="example" id="org52b7109"> (ec-make-point :curve25519 &key x) (ec-make-point :curve448 &key x) (ec-make-point :ed25519 &key x y) @@ -1853,18 +1824,18 @@ The <i>x</i> and <i>y</i> parameters must be integers. <div class="org-src-container"> -<pre class="src src-lisp" id="org16900cd">(ec-destructure-point p) => plist +<pre class="src src-lisp" id="org8a1d525">(ec-destructure-point p) => plist </pre> </div> <p> Return a plist containing the coordinates of the point <i>P</i>. The indicators of -the plist match the <i>&key</i> arguments of the <a href="#orgd26c3be">ec-make-point</a> method. +the plist match the <i>&key</i> arguments of the <a href="#orgd4c1351">ec-make-point</a> method. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org9c19d48">(ec-point-on-curve p) => boolean +<pre class="src src-lisp" id="orgfe46874">(ec-point-on-curve p) => boolean </pre> </div> @@ -1874,7 +1845,7 @@ Return <code>t</code> if the point <i>P</i> is on the curve. <div class="org-src-container"> -<pre class="src src-lisp" id="org0b551f6">(ec-point-equal p q) => boolean +<pre class="src src-lisp" id="org8492328">(ec-point-equal p q) => boolean </pre> </div> @@ -1884,7 +1855,7 @@ Return <code>t</code> if <i>P</i> and <i>Q</i> represent the same point. <div class="org-src-container"> -<pre class="src src-lisp" id="orgc003b0c">(ec-double p) => point +<pre class="src src-lisp" id="orgf27adea">(ec-double p) => point </pre> </div> @@ -1894,7 +1865,7 @@ Return the point 2 * <i>P</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="orgcdd6677">(ec-add p q) => point +<pre class="src src-lisp" id="org57afb21">(ec-add p q) => point </pre> </div> @@ -1904,7 +1875,7 @@ Return the point <i>P</i> + <i>Q</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="orgf2c5f06">(ec-scalar-mult p e) => point +<pre class="src src-lisp" id="orgd5e5266">(ec-scalar-mult p e) => point </pre> </div> @@ -1914,7 +1885,7 @@ Return the point <i>e</i> * <i>P</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="org9a24908">(ec-scalar-inv kind n) => integer +<pre class="src src-lisp" id="orgb624683">(ec-scalar-inv kind n) => integer </pre> </div> @@ -1924,7 +1895,7 @@ Return the modular inverse of <i>n</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="org2a0ef66">(ec-encode-scalar kind n) => vector +<pre class="src src-lisp" id="org9986a7c">(ec-encode-scalar kind n) => vector </pre> </div> @@ -1934,7 +1905,7 @@ Return an octet vector representing the integer <i>n</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="org5036efe">(ec-decode-scalar kind octets) => integer +<pre class="src src-lisp" id="org03dc66c">(ec-decode-scalar kind octets) => integer </pre> </div> @@ -1944,7 +1915,7 @@ Return the integer represented by the <i>octets</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="orgef3f5d7">(ec-encode-point p) => vector +<pre class="src src-lisp" id="org57b8ed7">(ec-encode-point p) => vector </pre> </div> @@ -1954,7 +1925,7 @@ Return an octet vector representing the point <i>P</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="org308ad21">(ec-decode-point kind octets) => point +<pre class="src src-lisp" id="orga0fac6b">(ec-decode-point kind octets) => point </pre> </div> @@ -1964,7 +1935,6 @@ Return the point represented by the <i>octets</i>. </div> </div> </div> - <div id="outline-container-pseudo-random-number-generation" class="outline-2"> <h2 id="pseudo-random-number-generation">Pseudo-random number generation</h2> <div class="outline-text-2" id="text-pseudo-random-number-generation"> @@ -1987,7 +1957,7 @@ use <code>os-prng</code>, which is the default. <div class="org-src-container"> -<pre class="src src-lisp" id="orgbfe1c12">(make-prng name <span style="font-weight: bold; text-decoration: underline;">&key</span> seed) => prng +<pre class="src src-lisp" id="org4ee888f">(make-prng name <span style="font-weight: bold; text-decoration: underline;">&key</span> seed) => prng </pre> </div> @@ -1996,7 +1966,7 @@ Create a pseudo-random number generator. </p> <p> -<i>name</i> denotes the style of PRNG to use. <a href="#org3e45a62">list-all-prngs</a> will tell you +<i>name</i> denotes the style of PRNG to use. <a href="#org9a97a96">list-all-prngs</a> will tell you the names of all supported PRNGs. Currently supported PRNGs are: </p> <ul class="org-ul"> @@ -2024,7 +1994,7 @@ be used to seed the PRNG. </p> <p> -In single-threaded applications, you should very rarely need to call <a href="#orgbfe1c12">make-prng</a>; +In single-threaded applications, you should very rarely need to call <a href="#org4ee888f">make-prng</a>; the default OS-provided PRNG should be appropriate in nearly all cases. </p> @@ -2038,7 +2008,7 @@ Lisp implementation directly, you have to bind the <code>*prng*</code> special v a new PRNG in each thread. For example: </p> -<pre class="example" id="org82d8af9"> +<pre class="example" id="org1e42bc7"> (make-thread (lambda () (let ((crypto:*prng* (crypto:make-prng :os))) (forms-for-thread-1)))) @@ -2050,7 +2020,7 @@ a new PRNG in each thread. For example: <div class="org-src-container"> -<pre class="src src-lisp" id="org3e45a62">(list-all-prngs) => list +<pre class="src src-lisp" id="org9a97a96">(list-all-prngs) => list </pre> </div> @@ -2060,7 +2030,7 @@ List all known PRNG types. <div class="org-src-container"> -<pre class="src src-lisp" id="orgaf9aa78">(random-data num-bytes <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => bytes +<pre class="src src-lisp" id="orgfd526f2">(random-data num-bytes <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => bytes </pre> </div> @@ -2071,7 +2041,7 @@ state of the generator. <div class="org-src-container"> -<pre class="src src-lisp" id="orgef393f8">(random-bits num-bits <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => integer +<pre class="src src-lisp" id="org08902cc">(random-bits num-bits <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => integer </pre> </div> @@ -2081,19 +2051,19 @@ Generate an integer with <i>num-bits</i> bits. <div class="org-src-container"> -<pre class="src src-lisp" id="org933ecb7">(strong-random limit <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => number +<pre class="src src-lisp" id="orgb10722e">(strong-random limit <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => number </pre> </div> <p> -A drop-in replacement for <code>common-lisp:random</code>, <a href="#org933ecb7">strong-random</a> +A drop-in replacement for <code>common-lisp:random</code>, <a href="#orgb10722e">strong-random</a> generates a number (an integer if <i>limit</i> is an integer and a float if it is a float) between 0 and <i>limit</i> - 1 in an unbiased fashion. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org75b5142">(read-os-random-seed source <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => reseed-count +<pre class="src src-lisp" id="org45267a2">(read-os-random-seed source <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => reseed-count </pre> </div> @@ -2110,14 +2080,14 @@ on Unix; <code>CryptGenRandom</code> on Windows) and reseed <i>prng</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="org61caf1b">(read-seed path <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => t +<pre class="src src-lisp" id="orgd02ec72">(read-seed path <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => t </pre> </div> <p> Read enough bytes from <i>path</i> to reseed <i>prng</i>, then generate a pseudo-random seed and write it back to <i>path</i>. If <i>path</i> doesn't -exist, calls <a href="#org75b5142">read-os-random-seed</a> to get a truly random seed from the +exist, calls <a href="#org45267a2">read-os-random-seed</a> to get a truly random seed from the OS. Note that reseeding does <b>not</b> reset the generator's state to the seed value; rather, it <b>combines</b> the generator's state with the seed to form a new state. @@ -2125,7 +2095,7 @@ to form a new state. <div class="org-src-container"> -<pre class="src src-lisp" id="orge597d3b">(write-seed path <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => t +<pre class="src src-lisp" id="org72ddf09">(write-seed path <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => t </pre> </div> @@ -2133,11 +2103,10 @@ to form a new state. Generate enough random data to reseed <i>prng</i>, then write it to <i>path</i>. </p> </div> - -<div id="outline-container-orgb96db70" class="outline-3"> -<h3 id="orgb96db70">Example</h3> -<div class="outline-text-3" id="text-orgb96db70"> -<pre class="example" id="org77390cf"> +<div id="outline-container-orgeaea09e" class="outline-3"> +<h3 id="orgeaea09e">Example</h3> +<div class="outline-text-3" id="text-orgeaea09e"> +<pre class="example" id="orgd2bf300"> (crypto:random-data 16) => #(61 145 133 130 220 200 90 86 0 101 62 169 0 40 101 78) @@ -2149,10 +2118,9 @@ Generate enough random data to reseed <i>prng</i>, then write it to <i>path</i>. </pre> </div> </div> - -<div id="outline-container-org64766cb" class="outline-3"> -<h3 id="org64766cb">Fortuna</h3> -<div class="outline-text-3" id="text-org64766cb"> +<div id="outline-container-org2906e6e" class="outline-3"> +<h3 id="org2906e6e">Fortuna</h3> +<div class="outline-text-3" id="text-org2906e6e"> <p> You should only use the Fortuna PRNG if your OS does not provided a sufficiently-good PRNG. If you use a Unix or Unix-like OS (e.g. @@ -2181,7 +2149,7 @@ spread entropy across all 32 pools. <p> Fortuna automatically feeds entropy from the pools back into its -random state when <a href="#orgaf9aa78">random-data</a> is called, using a method designed to +random state when <a href="#orgfd526f2">random-data</a> is called, using a method designed to make it resistant to various avenues of attack; even in case of generator compromise it will return to a safe state within a bounded time. @@ -2201,7 +2169,7 @@ It also will not reseed more than ten times per second. <div class="org-src-container"> -<pre class="src src-lisp" id="org64bdc22">(add-random-event source pool-id event <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => pool-length +<pre class="src src-lisp" id="org32bf024">(add-random-event source pool-id event <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => pool-length </pre> </div> @@ -2226,7 +2194,6 @@ or break them up into chunks). </div> </div> </div> - <div id="outline-container-gray-streams" class="outline-2"> <h2 id="gray-streams">Gray streams</h2> <div class="outline-text-2" id="text-gray-streams"> @@ -2236,10 +2203,9 @@ based on Gray streams. Gray streams support in Ironclad is included for SBCL, CMUCL, OpenMCL/CCL, Lispworks, ABCL, ECL, Clisp and Allegro. </p> </div> - -<div id="outline-container-org587a479" class="outline-3"> -<h3 id="org587a479">Octet streams</h3> -<div class="outline-text-3" id="text-org587a479"> +<div id="outline-container-org3fe7833" class="outline-3"> +<h3 id="org3fe7833">Octet streams</h3> +<div class="outline-text-3" id="text-org3fe7833"> <p> Octet streams are very similar to Common Lisp's <code>string-stream</code> except they deal in octets instead of characters. @@ -2247,7 +2213,7 @@ they deal in octets instead of characters. <div class="org-src-container"> -<pre class="src src-lisp" id="org064b0c9">(make-octet-input-stream buffer <span style="font-weight: bold; text-decoration: underline;">&optional</span> start end) => octet-input-stream +<pre class="src src-lisp" id="orgc6bae48">(make-octet-input-stream buffer <span style="font-weight: bold; text-decoration: underline;">&optional</span> start end) => octet-input-stream </pre> </div> @@ -2257,7 +2223,7 @@ As <code>make-string-input-stream</code>, only with octets instead of characters <div class="org-src-container"> -<pre class="src src-lisp" id="org3b51900">(make-octet-output-stream) => octet-output-stream +<pre class="src src-lisp" id="orgedb3b46">(make-octet-output-stream) => octet-output-stream </pre> </div> @@ -2267,7 +2233,7 @@ As <code>make-string-output-stream</code>, only with octets instead of character <div class="org-src-container"> -<pre class="src src-lisp" id="org88399b6">(get-output-stream-octets stream) => octet-vector +<pre class="src src-lisp" id="org6539129">(get-output-stream-octets stream) => octet-vector </pre> </div> @@ -2278,7 +2244,7 @@ of a string output-stream. <div class="org-src-container"> -<pre class="src src-lisp" id="orge500e84">(<span style="font-weight: bold;">with-octet-input-stream</span> ((var buffer <span style="font-weight: bold; text-decoration: underline;">&optional</span> (start 0) end) <span style="font-weight: bold; text-decoration: underline;">&body</span> body)) +<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;">&optional</span> (start 0) end) <span style="font-weight: bold; text-decoration: underline;">&body</span> body)) </pre> </div> @@ -2290,7 +2256,7 @@ Within <i>body</i>, <i>var</i> is bound to an octet input stream. Reading from <div class="org-src-container"> -<pre class="src src-lisp" id="orgce6cba7">(<span style="font-weight: bold;">with-octet-output-stream</span> ((var) <span style="font-weight: bold; text-decoration: underline;">&body</span> body)) => bytes +<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;">&body</span> body)) => bytes </pre> </div> @@ -2298,14 +2264,13 @@ Within <i>body</i>, <i>var</i> is bound to an octet input stream. Reading from Within <i>body</i>, <i>var</i> is bound to an octet output stream. After all the forms in <i>body</i> have been executed, the data that has been written to <i>var</i> (and that hasn't been consumed by a call to -<a href="#org88399b6">get-output-stream-octets</a> within <i>body</i>) is returned. +<a href="#org6539129">get-output-stream-octets</a> within <i>body</i>) is returned. </p> </div> </div> - -<div id="outline-container-orgfd86d0f" class="outline-3"> -<h3 id="orgfd86d0f">Digest streams</h3> -<div class="outline-text-3" id="text-orgfd86d0f"> +<div id="outline-container-org075795b" class="outline-3"> +<h3 id="org075795b">Digest streams</h3> +<div class="outline-text-3" id="text-org075795b"> <p> Digest streams compute a digest of the data written to them according to a specific digest algorithm. @@ -2314,7 +2279,7 @@ to a specific digest algorithm. <p> Example: </p> -<pre class="example" id="org1e99a87"> +<pre class="example" id="org9ad0284"> (defun frobbing-function (stream) ;; We want to compute a digest of the data being written to STREAM ;; without involving our callees in the process. @@ -2329,7 +2294,7 @@ Example: <div class="org-src-container"> -<pre class="src src-lisp" id="orgdc549ae">(make-digesting-stream digest <span style="font-weight: bold; text-decoration: underline;">&rest</span> args) => stream +<pre class="src src-lisp" id="org134ed18">(make-digesting-stream digest <span style="font-weight: bold; text-decoration: underline;">&rest</span> args) => stream </pre> </div> @@ -2337,18 +2302,18 @@ Example: Make a stream that computes a digest of the data written to it according to the algorithm <i>digest</i>. The parameters that can be used by some algorithms can be specified as <i>args</i>. -<a href="#org49c655e">produce-digest</a> may be used to obtain a digest of all the data written +<a href="#orgebfad7a">produce-digest</a> may be used to obtain a digest of all the data written to the stream. </p> <p> -<span class="underline">Note:</span> Calling <a href="#org49c655e">produce-digest</a> on a digest stream does not alter +<span class="underline">Note:</span> Calling <a href="#orgebfad7a">produce-digest</a> on a digest stream does not alter the internal state of the digest. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org83cf76f">(<span style="font-weight: bold;">with-digesting-stream</span> (var digest-name <span style="font-weight: bold; text-decoration: underline;">&rest</span> args) <span style="font-weight: bold; text-decoration: underline;">&body</span> body) => digest +<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;">&rest</span> args) <span style="font-weight: bold; text-decoration: underline;">&body</span> body) => digest </pre> </div> @@ -2360,10 +2325,9 @@ returned. </p> </div> </div> - -<div id="outline-container-orgb756c05" class="outline-3"> -<h3 id="orgb756c05">Cipher streams</h3> -<div class="outline-text-3" id="text-orgb756c05"> +<div id="outline-container-orga5b95e6" class="outline-3"> +<h3 id="orga5b95e6">Cipher streams</h3> +<div class="outline-text-3" id="text-orga5b95e6"> <p> Cipher streams encrypt or decrypt the data written to or read from them according to a specific cipher algorithm. @@ -2371,7 +2335,7 @@ them according to a specific cipher algorithm. <div class="org-src-container"> -<pre class="src src-lisp" id="org9e8f346">(make-encrypting-stream stream cipher mode key <span style="font-weight: bold; text-decoration: underline;">&key</span> initialization-vector direction) => stream +<pre class="src src-lisp" id="org1f817c7">(make-encrypting-stream stream cipher mode key <span style="font-weight: bold; text-decoration: underline;">&key</span> initialization-vector direction) => stream </pre> </div> @@ -2387,7 +2351,7 @@ stream is encrypted before being sent to <i>stream</i>. <div class="org-src-container"> -<pre class="src src-lisp" id="org38c03d0">(make-decrypting-stream stream cipher mode key <span style="font-weight: bold; text-decoration: underline;">&key</span> initialization-vector direction) => stream +<pre class="src src-lisp" id="org13e52cb">(make-decrypting-stream stream cipher mode key <span style="font-weight: bold; text-decoration: underline;">&key</span> initialization-vector direction) => stream </pre> </div> @@ -2404,12 +2368,12 @@ stream is decrypted before being sent to <i>stream</i>. <p> <span class="underline">Note:</span> Only stream ciphers and block ciphers in CTR, CFB, CFB8 or OFB mode are -supported by <a href="#org9e8f346">make-encrypting-stream</a> and <a href="#org38c03d0">make-decrypting-stream</a>. +supported by <a href="#org1f817c7">make-encrypting-stream</a> and <a href="#org13e52cb">make-decrypting-stream</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgf1f4d22">(<span style="font-weight: bold;">with-encrypting-stream</span> ((var stream cipher mode key <span style="font-weight: bold; text-decoration: underline;">&key</span> initialization-vector direction) <span style="font-weight: bold; text-decoration: underline;">&body</span> body)) +<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;">&key</span> initialization-vector direction) <span style="font-weight: bold; text-decoration: underline;">&body</span> body)) </pre> </div> @@ -2420,7 +2384,7 @@ the last form of <i>body</i> is returned. <div class="org-src-container"> -<pre class="src src-lisp" id="orgb0ba9ad">(<span style="font-weight: bold;">with-decrypting-stream</span> ((var stream cipher mode key <span style="font-weight: bold; text-decoration: underline;">&key</span> initialization-vector direction) <span style="font-weight: bold; text-decoration: underline;">&body</span> body)) +<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;">&key</span> initialization-vector direction) <span style="font-weight: bold; text-decoration: underline;">&body</span> body)) </pre> </div> @@ -2430,17 +2394,16 @@ the last form of <i>body</i> is returned. </p> </div> </div> - -<div id="outline-container-orgdc150b3" class="outline-3"> -<h3 id="orgdc150b3">MAC streams</h3> -<div class="outline-text-3" id="text-orgdc150b3"> +<div id="outline-container-orgf02e2a0" class="outline-3"> +<h3 id="orgf02e2a0">MAC streams</h3> +<div class="outline-text-3" id="text-orgf02e2a0"> <p> MAC streams compute a message authentication code of the data written to them according to a specific MAC algorithm. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgbb928e2">(make-authenticating-stream mac key <span style="font-weight: bold; text-decoration: underline;">&rest</span> args) => stream +<pre class="src src-lisp" id="orgf461878">(make-authenticating-stream mac key <span style="font-weight: bold; text-decoration: underline;">&rest</span> args) => stream </pre> </div> @@ -2448,12 +2411,12 @@ to them according to a specific MAC algorithm. Make a stream that computes a MAC of the data written to it according to the algorithm <i>mac</i> initialized with a <i>key</i>. The parameters used to create the MAC can be specified as <i>args</i>. -<a href="#org9989d0c">produce-mac</a> may be used to obtain a MAC of all the data written to the +<a href="#org967004b">produce-mac</a> may be used to obtain a MAC of all the data written to the stream. </p> <p> -<span class="underline">Note:</span> Calling <a href="#org9989d0c">produce-mac</a> on a MAC stream does not alter the +<span class="underline">Note:</span> Calling <a href="#org967004b">produce-mac</a> on a MAC stream does not alter the internal state of the MAC. </p> @@ -2461,7 +2424,7 @@ internal state of the MAC. <p> Example: encrypt some data and compute a MAC of the ciphertext </p> -<pre class="example" id="org0ad0448"> +<pre class="example" id="org5dd37b0"> (let* ((data ...) (output-stream ...) (encryption-key ...) @@ -2484,7 +2447,7 @@ Example: encrypt some data and compute a MAC of the ciphertext <div class="org-src-container"> -<pre class="src src-lisp" id="org0459f60">(<span style="font-weight: bold;">with-authenticating-stream</span> (var mac-name key <span style="font-weight: bold; text-decoration: underline;">&rest</span> args) <span style="font-weight: bold; text-decoration: underline;">&body</span> body) => mac +<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;">&rest</span> args) <span style="font-weight: bold; text-decoration: underline;">&body</span> body) => mac </pre> </div> @@ -2497,12 +2460,11 @@ written to <i>var</i> is returned. </div> </div> </div> - <div id="outline-container-utility-functions" class="outline-2"> <h2 id="utility-functions">Utility functions</h2> <div class="outline-text-2" id="text-utility-functions"> <div class="org-src-container"> -<pre class="src src-lisp" id="orgff5a37f">(ub16ref/le vector index) => value +<pre class="src src-lisp" id="org6226475">(ub16ref/le vector index) => value (ub32ref/le vector index) => value (ub64ref/le vector index) => value </pre> @@ -2517,7 +2479,7 @@ functions are SETFable. <div class="org-src-container"> -<pre class="src src-lisp" id="org13b1ae5">(ub16ref/be vector index) => value +<pre class="src src-lisp" id="org12f19a5">(ub16ref/be vector index) => value (ub32ref/be vector index) => value (ub64ref/be vector index) => value </pre> @@ -2529,41 +2491,41 @@ As the above, only the value is stored in big-endian order. <div class="org-src-container"> -<pre class="src src-lisp" id="org7a78384">(byte-array-to-hex-string vector <span style="font-weight: bold; text-decoration: underline;">&key</span> start end element-type) => string +<pre class="src src-lisp" id="org6b0db24">(byte-array-to-hex-string vector <span style="font-weight: bold; text-decoration: underline;">&key</span> start end element-type) => string (hex-string-to-byte-array string <span style="font-weight: bold; text-decoration: underline;">&key</span> start end) => string (ascii-string-to-byte-array string <span style="font-weight: bold; text-decoration: underline;">&key</span> start end) => vector </pre> </div> <p> -<a href="#org7a78384">byte-array-to-hex-string</a> converts the bytes of <i>vector</i> between +<a href="#org6b0db24">byte-array-to-hex-string</a> converts the bytes of <i>vector</i> between <i>start</i> and <i>end</i> into a hexadecimal string. It is useful for converting digests to a more readable form. <i>element-type</i> indicates the element-type of the returned string. </p> <p> -<a href="#org7a78384">hex-string-to-byte-array</a> parses a substring of <i>string</i> delimited +<a href="#org6b0db24">hex-string-to-byte-array</a> parses a substring of <i>string</i> delimited <i>start</i> and <i>end</i> of hexadecimal digits into a byte array. </p> <p> -<a href="#org7a78384">ascii-string-to-byte-array</a> is provided as a quick and dirty way to -convert a string to a byte array suitable for feeding to <a href="#org356a991">update-digest</a> -or <a href="#org911f61d">encrypt</a>. Care should be taken to ensure that the provided string is +<a href="#org6b0db24">ascii-string-to-byte-array</a> is provided as a quick and dirty way to +convert a string to a byte array suitable for feeding to <a href="#org9ba11b9">update-digest</a> +or <a href="#orga0c509f">encrypt</a>. Care should be taken to ensure that the provided string is actually an ASCII string. <i>start</i> and <i>end</i> have their usual interpretations. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgf5c6d27">(octets-to-integer octet-vec <span style="font-weight: bold; text-decoration: underline;">&key</span> start end big-endian n-bits) => number +<pre class="src src-lisp" id="org0826692">(octets-to-integer octet-vec <span style="font-weight: bold; text-decoration: underline;">&key</span> start end big-endian n-bits) => number (integer-to-octets bignum <span style="font-weight: bold; text-decoration: underline;">&key</span> n-bits big-endian) => vector </pre> </div> <p> -<a href="#orgf5c6d27">octets-to-integer</a> converts the bytes of <i>octet-vec</i> between <i>start</i> +<a href="#org0826692">octets-to-integer</a> converts the bytes of <i>octet-vec</i> between <i>start</i> and <i>end</i> to an integer as though the bytes denoted a number in base 256. <i>big-endian</i> is a boolean indicating whether the bytes are to be read in big-endian or little-endian order. <i>n-bits</i> specifies @@ -2572,12 +2534,12 @@ number. </p> <p> -<a href="#orgf5c6d27">integer-to-octets</a> is the reverse operation. +<a href="#org0826692">integer-to-octets</a> is the reverse operation. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org1d446fd">(expt-mod n exponent modulus) => number +<pre class="src src-lisp" id="org89429f3">(expt-mod n exponent modulus) => number (expt-mod/unsafe n exponent modulus) => number </pre> </div> @@ -2585,20 +2547,20 @@ number. <p> Raises <i>n</i> to the <i>exponent</i> power modulo <i>modulus</i> in a more efficient fashion than <code>(mod (expt n exponent) modulus)</code>. -<a href="#org1d446fd">expt-mod</a> is using the Montgomery ladder algorithm to be more robust +<a href="#org89429f3">expt-mod</a> is using the Montgomery ladder algorithm to be more robust against timing attacks. -<a href="#org1d446fd">expt-mod/unsafe</a> runs faster than <a href="#org1d446fd">expt-mod</a> but is not safe against +<a href="#org89429f3">expt-mod/unsafe</a> runs faster than <a href="#org89429f3">expt-mod</a> but is not safe against timing attacks; don't use it on secret data. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgacafbaa">(prime-p n <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => boolean +<pre class="src src-lisp" id="orge94e41b">(prime-p n <span style="font-weight: bold; text-decoration: underline;">&optional</span> prng) => boolean </pre> </div> <p> -<a href="#orgacafbaa">prime-p</a> returns <code>t</code> if <i>n</i> has a high probability of being a prime number, and +<a href="#orge94e41b">prime-p</a> returns <code>t</code> if <i>n</i> has a high probability of being a prime number, and <code>nil</code> if it is a composite number. The probable primality is determined by first doing trial divisions with small primes, then running several Miller-Rabin tests with random bases, and finally doing a Lucas test. The @@ -2609,7 +2571,7 @@ probability of returning <code>t</code> for a composite number to be at most 1/2 <div class="org-src-container"> -<pre class="src src-lisp" id="org878233d">make-random-salt <span style="font-weight: bold; text-decoration: underline;">&optional</span> size => bytes +<pre class="src src-lisp" id="org01d5086">make-random-salt <span style="font-weight: bold; text-decoration: underline;">&optional</span> size => bytes </pre> </div> @@ -2620,7 +2582,7 @@ for use as a password salt. <div class="org-src-container"> -<pre class="src src-lisp" id="org5829b54">constant-time-equal data1 data2 => boolean +<pre class="src src-lisp" id="org9ca5d87">constant-time-equal data1 data2 => boolean </pre> </div> @@ -2632,12 +2594,11 @@ or MACs. </p> </div> </div> - <div id="outline-container-conditions" class="outline-2"> <h2 id="conditions">Conditions</h2> <div class="outline-text-2" id="text-conditions"> <div class="org-src-container"> -<pre class="src src-lisp" id="org5ae338f">ironclad-error +<pre class="src src-lisp" id="orgdf4f1f6">ironclad-error </pre> </div> @@ -2648,152 +2609,152 @@ a direct subtype of <code>simple-error</code> without any extra slots or options <div class="org-src-container"> -<pre class="src src-lisp" id="orga9239b7">initialization-vector-not-supplied +<pre class="src src-lisp" id="orgac1c20a">initialization-vector-not-supplied </pre> </div> <p> -This error is signaled by <a href="#org305b09d">make-cipher</a> when an initialization vector is +This error is signaled by <a href="#orga194874">make-cipher</a> when an initialization vector is not provided and the requested mode requires an initialization vector. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org2bc7c3b">invalid-initialization-vector +<pre class="src src-lisp" id="orgcc5eb5f">invalid-initialization-vector </pre> </div> <p> This error is signaled when an invalid initialization vector is -supplied to <a href="#org305b09d">make-cipher</a> (e.g. when the length of the initialization +supplied to <a href="#orga194874">make-cipher</a> (e.g. when the length of the initialization vector does not match the block length of the cipher). </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org304dc15">invalid-key-length +<pre class="src src-lisp" id="orgc77ebba">invalid-key-length </pre> </div> <p> -This error is signaled when the key provided to <a href="#org305b09d">make-cipher</a> is not of +This error is signaled when the key provided to <a href="#orga194874">make-cipher</a> is not of an acceptable length for the requested cipher. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org96a8cde">unsupported-cipher +<pre class="src src-lisp" id="org8f6b6c4">unsupported-cipher </pre> </div> <p> -This error is signaled when the <i>cipher-name</i> provided to <a href="#org305b09d">make-cipher</a> -is not <a href="#orge2e33ff">cipher-supported-p</a>. +This error is signaled when the <i>cipher-name</i> provided to <a href="#orga194874">make-cipher</a> +is not <a href="#orgaef3ba6">cipher-supported-p</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org1388624">unsupported-mode +<pre class="src src-lisp" id="org262ca01">unsupported-mode </pre> </div> <p> This error is signaled when the <i>mode</i> provided to -<a href="#org305b09d">make-cipher</a> is not <i>mode-supported-p</i>. +<a href="#orga194874">make-cipher</a> is not <i>mode-supported-p</i>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgfe8006f">unsupported-padding +<pre class="src src-lisp" id="org9b9361c">unsupported-padding </pre> </div> <p> -This error is signaled when the <i>padding</i> provided to <a href="#org305b09d">make-cipher</a> is not +This error is signaled when the <i>padding</i> provided to <a href="#orga194874">make-cipher</a> is not supported. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgbdc5bf7">unsupported-digest +<pre class="src src-lisp" id="org5a41f2f">unsupported-digest </pre> </div> <p> This error is signaled when the <i>digest-name</i> provided to -<a href="#org6b2b195">make-digest</a> is not <a href="#org8315ac3">digest-supported-p</a>. +<a href="#org0aca191">make-digest</a> is not <a href="#org1786607">digest-supported-p</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org2688cb0">unsupported-mac +<pre class="src src-lisp" id="org7a95626">unsupported-mac </pre> </div> <p> This error is signaled when the <i>mac-name</i> provided to -<a href="#orga84ba09">make-mac</a> is not <a href="#orgb9b4f69">mac-supported-p</a>. +<a href="#orgbc2a39c">make-mac</a> is not <a href="#orgfe5f676">mac-supported-p</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org3306fab">insufficient-buffer-space +<pre class="src src-lisp" id="org701dd62">insufficient-buffer-space </pre> </div> <p> This error is signaled when Ironclad needs to stuff some data into -a buffer (e.g. when the user provides <i>digest</i> to <a href="#org49c655e">produce-digest</a> and +a buffer (e.g. when the user provides <i>digest</i> to <a href="#orgebfad7a">produce-digest</a> and there is insufficient space). </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org5d7aa03">key-not-supplied +<pre class="src src-lisp" id="org8bebfc7">key-not-supplied </pre> </div> <p> This error is signaled when a <i>:key</i> argument is not provided -to <a href="#org305b09d">make-cipher</a>. +to <a href="#orga194874">make-cipher</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org1d53f91">unsupported-kdf +<pre class="src src-lisp" id="org991b5c3">unsupported-kdf </pre> </div> <p> This error is signaled when an invalid KDF name is provided -to <a href="#orgb345fc9">make-kdf</a>. +to <a href="#orgc3724fd">make-kdf</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgd95b64b">unsupported-scrypt-cost-factors +<pre class="src src-lisp" id="orgb419f89">unsupported-scrypt-cost-factors </pre> </div> <p> This error is signaled when invalid Scrypt cost factors are provided -to <a href="#orgb345fc9">make-kdf</a>. +to <a href="#orgc3724fd">make-kdf</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org8af4fa7">unsupported-argon2-cost-factors +<pre class="src src-lisp" id="org00e96f4">unsupported-argon2-cost-factors </pre> </div> <p> This error is signaled when invalid Argon2 parameters are provided -to <a href="#orgb345fc9">make-kdf</a>. +to <a href="#orgc3724fd">make-kdf</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orgd8000d6">invalid-padding +<pre class="src src-lisp" id="org242d249">invalid-padding </pre> </div> @@ -2804,84 +2765,84 @@ invalid. <div class="org-src-container"> -<pre class="src src-lisp" id="org9f32b16">invalid-mac-parameter +<pre class="src src-lisp" id="orgfbd54a5">invalid-mac-parameter </pre> </div> <p> This error is signaled when an invalid parameter is provided -to <a href="#orga84ba09">make-mac</a>. +to <a href="#orgbc2a39c">make-mac</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org9631945">invalid-signature-length +<pre class="src src-lisp" id="org871c025">invalid-signature-length </pre> </div> <p> This error is signaled when a signature with an invalid length is provided -to <a href="#orgb30dba8">verify-signature</a> or <a href="#orgbc60ed4">destructure-signature</a>. +to <a href="#orgf029208">verify-signature</a> or <a href="#orgc5506b9">destructure-signature</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org2bf0a9e">invalid-message-length +<pre class="src src-lisp" id="orgfaddc6c">invalid-message-length </pre> </div> <p> This error is signaled when a message with an invalid length is provided -to <a href="#orgdc7621c">encrypt-message</a>, <a href="#orgae61015">decrypt-message</a> or <a href="#org715c55b">destructure-message</a>. +to <a href="#org6424db2">encrypt-message</a>, <a href="#org13a3a49">decrypt-message</a> or <a href="#orgc65f9d9">destructure-message</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org780df66">missing-key-parameter +<pre class="src src-lisp" id="org2aedad4">missing-key-parameter </pre> </div> <p> This error is signaled when it is determined that a parameter is -missing in a call to <a href="#org3c01c3b">make-public-key</a> or <a href="#orga28ccaf">make-private-key</a>. +missing in a call to <a href="#org6bca683">make-public-key</a> or <a href="#org59929bc">make-private-key</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org93b43e1">missing-message-parameter +<pre class="src src-lisp" id="orga06e596">missing-message-parameter </pre> </div> <p> This error is signaled when it is determined that a parameter is -missing in a call to <a href="#org90529bc">make-message</a>. +missing in a call to <a href="#org83c91f2">make-message</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org9309feb">missing-signature-parameter +<pre class="src src-lisp" id="orgc5f803c">missing-signature-parameter </pre> </div> <p> This error is signaled when it is determined that a parameter is -missing in a call to <a href="#org7b9e693">make-signature</a>. +missing in a call to <a href="#orgfa225d8">make-signature</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orga549324">incompatible-keys +<pre class="src src-lisp" id="org16a77de">incompatible-keys </pre> </div> <p> This error is signaled when incompatible keys are provided to -<a href="#org063463a">diffie-hellman</a>. +<a href="#org548e6ec">diffie-hellman</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="orga5e84da">invalid-curve-point +<pre class="src src-lisp" id="org1836372">invalid-curve-point </pre> </div> @@ -2891,18 +2852,18 @@ This error is signaled when trying to use an invalid curve point. <div class="org-src-container"> -<pre class="src src-lisp" id="org492db1e">invalid-public-key-length +<pre class="src src-lisp" id="org989da1f">invalid-public-key-length </pre> </div> <p> This error is signaled when a public key with an invalid length is -provided to <a href="#orgb30dba8">verify-signature</a>. +provided to <a href="#orgf029208">verify-signature</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org0472882">oaep-decoding-error +<pre class="src src-lisp" id="org00b54b6">oaep-decoding-error </pre> </div> @@ -2912,18 +2873,18 @@ This error is signaled when the OAEP decoding of a message fails. <div class="org-src-container"> -<pre class="src src-lisp" id="org7b1a8ca">unsupported-authenticated-encryption-mode +<pre class="src src-lisp" id="org58897fd">unsupported-authenticated-encryption-mode </pre> </div> <p> This error is signaled when an invalid mode name is provided to -<a href="#org6cb8142">make-authenticated-encryption-mode</a>. +<a href="#org44e9414">make-authenticated-encryption-mode</a>. </p> <div class="org-src-container"> -<pre class="src src-lisp" id="org3691bc8">bad-authentication-tag +<pre class="src src-lisp" id="org94e7be8">bad-authentication-tag </pre> </div> @@ -2932,7 +2893,6 @@ This error is signaled when the verification of authenticity of a message fails. </p> </div> </div> - <div id="outline-container-subsystems" class="outline-2"> <h2 id="subsystems">Subsystems (experimental)</h2> <div class="outline-text-2" id="text-subsystems"> @@ -2944,15 +2904,14 @@ subsystems of the algorithms you need. <p> For example if you need only AES and SHA256: </p> -<pre class="example" id="org64dcc0e"> +<pre class="example" id="org13c948d"> (asdf:load-system "ironclad/cipher/aes") (asdf:load-system "ironclad/digest/sha256") </pre> </div> - -<div id="outline-container-orgd3761e2" class="outline-3"> -<h3 id="orgd3761e2">Available subsystems</h3> -<div class="outline-text-3" id="text-orgd3761e2"> +<div id="outline-container-orga6d26c9" class="outline-3"> +<h3 id="orga6d26c9">Available subsystems</h3> +<div class="outline-text-3" id="text-orga6d26c9"> <ul class="org-ul"> <li>ironclad <ul class="org-ul"> diff --git a/ironclad.asd b/ironclad.asd index c73014e..3aeabe9 100644 --- a/ironclad.asd +++ b/ironclad.asd @@ -10,7 +10,7 @@ (defclass ironclad-system (system) () (:default-initargs - :version "0.60" + :version "0.61" :author "Nathan Froyd <froydnj@gmail.com>" :maintainer "Guillaume LE VAILLANT <glv@posteo.net>" :description "A cryptographic toolkit written in pure Common Lisp" @@ -248,7 +248,7 @@ (defsystem "ironclad/tests" :depends-on ("ironclad" "rt") - :version "0.60" + :version "0.61" :in-order-to ((test-op (load-op "ironclad/tests"))) :perform (test-op (o s) (or (funcall (intern "DO-TESTS" (find-package "RTEST"))) |