### Example: Encrypt Data and Compute MAC (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Demonstrates a practical example of encrypting data using a cipher stream and simultaneously computing a MAC of the resulting ciphertext using a MAC stream. It utilizes broadcast streams to write to both destinations.

```lisp
(let* ((data ...)
       (output-stream ...)
       (encryption-key ...)
       (authentication-key ...)
       (iv ...)
       (mac-stream (make-authenticating-stream :hmac
                                               authentication-key
                                               :sha3))
       (stream (make-broadcast-stream output-stream mac-stream))
       (cipher-stream (make-encrypting-stream stream
                                              :chacha
                                              :stream
                                              encryption-key
                                              :initialization-vector iv)))
  (write-sequence data cipher-stream)
  ...
  (let ((mac (produce-mac mac-stream)))
    ...))
```

--------------------------------

### Example Usage of PRNG Functions (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Demonstrates the usage of various pseudo-random number generation functions in Ironclad, including generating random data, strong random numbers, and random bits. This provides practical examples for integrating these functions into applications.

```lisp
(crypto:random-data 16)
=> #(61 145 133 130 220 200 90 86 0 101 62 169 0 40 101 78)

(crypto:strong-random 16)
=> 3

(crypto:random-bits 16)
=> 41546
```

--------------------------------

### Instantiate a Cipher Object in Ironclad

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

This example shows how to create a cipher object using the `make-cipher` function from the Ironclad library. The `crypto` nickname is an alias for the `ironclad` package.

```common-lisp
(crypto:make-cipher :aes :mode :cbc :key "my-secret-key")
```

--------------------------------

### Load Ironclad System with Quicklisp

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

This snippet shows how to load the Ironclad library using the Quicklisp library manager. Quicklisp simplifies the process of installing and loading Common Lisp libraries.

```common-lisp
(ql:quickload "ironclad")
```

--------------------------------

### Multi-threaded PRNG Initialization Example (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Illustrates how to initialize separate pseudo-random number generators (PRNGs) for different threads in a multi-threaded Common Lisp application. This prevents threads from generating the same 'random' data and is essential for secure multi-threaded operations.

```lisp
(make-thread (lambda () 
               (let ((crypto:*prng* (crypto:make-prng :os))) 
                 (forms-for-thread-1))))

(make-thread (lambda () 
               (let ((crypto:*prng* (crypto:make-prng :os))) 
                 (forms-for-thread-2))))
```

--------------------------------

### Create MAC Object (HMAC-SHA256 Example)

Source: https://context7.com/sharplispers/ironclad/llms.txt

Shows how to create a Message Authentication Code (MAC) object using HMAC-SHA256 with a provided key. It includes updating the MAC with data and producing the final MAC value. Examples for CMAC, Poly1305, listing MACs, and constant-time comparison are also provided.

```lisp
;; Create an HMAC-SHA256
(let* ((key (ironclad:random-data 32))
       (mac (ironclad:make-mac :hmac key :sha256)))
  (ironclad:update-mac mac (ironclad:ascii-string-to-byte-array "Message to authenticate"))
  (ironclad:byte-array-to-hex-string (ironclad:produce-mac mac)))

;; CMAC with AES (for block ciphers)
(let* ((key (ironclad:random-data 16))
       (mac (ironclad:make-mac :cmac key :aes)))
  (ironclad:update-mac mac (ironclad:ascii-string-to-byte-array "Authenticated data"))
  (ironclad:produce-mac mac))

;; Poly1305 MAC (requires 32-byte key)
(let* ((key (ironclad:random-data 32))
       (mac (ironclad:make-mac :poly1305 key)))
  (ironclad:update-mac mac (ironclad:ascii-string-to-byte-array "Data"))
  (ironclad:produce-mac mac))
;; Returns 16-byte MAC

;; List all supported MACs
(ironclad:list-all-macs)
;; => (:BLAKE2-MAC :BLAKE2S-MAC :CMAC :GMAC :HMAC :POLY1305 :SIPHASH :SKEIN-MAC)

;; Verify a MAC using constant-time comparison
(let* ((key (ironclad:random-data 32))
       (message (ironclad:ascii-string-to-byte-array "Secret message"))
       (mac1 (let ((m (ironclad:make-mac :hmac key :sha256)))
               (ironclad:update-mac m message)
               (ironclad:produce-mac m)))
       (mac2 (let ((m (ironclad:make-mac :hmac key :sha256)))
               (ironclad:update-mac m message)
               (ironclad:produce-mac m))))
  (ironclad:constant-time-equal mac1 mac2))
;; => T
```

--------------------------------

### Load Ironclad System with ASDF

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

This snippet demonstrates how to load the Ironclad library using the ASDF build system. It assumes Ironclad has been installed in a location discoverable by ASDF.

```common-lisp
(asdf:load-system "ironclad")
```

--------------------------------

### Digest Sequence Example

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Demonstrates high-level convenience functions for calculating digests. It shows how to compute the digest of a sequence using either a digest name or an existing digest object.

```common-lisp
(ironclad:digest-sequence :md5 *buffer*)
```

```common-lisp
(let ((digester (ironclad:make-digest :md5))) (ironclad:digest-sequence digester *buffer*))
```

--------------------------------

### Create Digest Object (SHA-256 Example)

Source: https://context7.com/sharplispers/ironclad/llms.txt

Demonstrates creating a digest object for SHA-256, updating it with data, and producing the final hash in hexadecimal format. It also shows how to list supported digests and check for support.

```lisp
;; Create a SHA-256 digest
(let ((digest (ironclad:make-digest :sha256)))
  (ironclad:update-digest digest (ironclad:ascii-string-to-byte-array "Hello, "))
  (ironclad:update-digest digest (ironclad:ascii-string-to-byte-array "World!"))
  (ironclad:byte-array-to-hex-string (ironclad:produce-digest digest)))
;; => "315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3"

;; List all supported digests
(ironclad:list-all-digests)
;; => (:ADLER32 :BLAKE2 :BLAKE2/256 :CRC32 :MD5 :RIPEMD-160 :SHA1 :SHA256 :SHA512 ...)

;; Check digest support
(ironclad:digest-supported-p :sha256)  ;; => T

;; Get digest length in bytes
(ironclad:digest-length :sha256)  ;; => 32
(ironclad:digest-length :sha512)  ;; => 64
```

--------------------------------

### Deterministic Nonce Generation for Secp256k1 (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Example of redefining the `generate-signature-nonce` method to produce deterministic nonces for Secp256k1 private keys, adhering to standards like RFC 6979.

```lisp
(defmethod generate-signature-nonce ((key secp256k1-private-key) message &optional parameters)
  (declare (ignore parameters))
  (compute-deterministic-nonce key message))
```

--------------------------------

### One-Shot Digest Functions (SHA-256 Example)

Source: https://context7.com/sharplispers/ironclad/llms.txt

Illustrates the use of convenience functions for computing digests in a single call, including digesting byte sequences, files, and streams. It also shows how to digest specific parts of a sequence and reuse digest objects.

```lisp
;; Digest a byte sequence
(ironclad:byte-array-to-hex-string
 (ironclad:digest-sequence :sha256
                           (ironclad:ascii-string-to-byte-array "Hello, World!")))
;; => "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f"

;; Digest a file
(ironclad:byte-array-to-hex-string
 (ironclad:digest-file :sha256 #P"/path/to/file"))

;; Digest from a stream
(with-open-file (stream #P"/path/to/file" :element-type '(unsigned-byte 8))
  (ironclad:byte-array-to-hex-string
   (ironclad:digest-stream :sha256 stream)))

;; Digest with start/end bounds
(let ((data (ironclad:ascii-string-to-byte-array "Hello, World!")))
  (ironclad:byte-array-to-hex-string
   (ironclad:digest-sequence :sha256 data :start 0 :end 5)))  ; Hash only "Hello"

;; Reuse digest object for efficiency
(let ((digest (ironclad:make-digest :md5))
      (buffer (make-array 32 :element-type '(unsigned-byte 8))))
  (dolist (file '("file1.txt" "file2.txt" "file3.txt"))
    (reinitialize-instance digest)  ; Reset for new hash
    (format t "~A: ~A~%" file
            (ironclad:byte-array-to-hex-string
             (ironclad:digest-file digest file)))))
```

--------------------------------

### PSS Encoding/Decoding Example (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Demonstrates the usage of the PSS (Probabilistic Signature Scheme) padding for RSA signatures during signing and verification. The `:pss t` argument enables PSS padding using SHA1.

```lisp
(sign-message rsa-private-key message :pss t) => signature
(verify-signature rsa-public-key message signature :pss t) => boolean
```

--------------------------------

### Create Symmetric Cipher Object with Ironclad

Source: https://context7.com/sharplispers/ironclad/llms.txt

Demonstrates creating cipher objects for encryption and decryption using `make-cipher`. Supports various algorithms (AES, ChaCha) and modes (CBC, stream). Includes examples for generating keys/IVs, encrypting/decrypting, listing supported ciphers, and checking cipher properties like key and block lengths.

```lisp
;; Create an AES cipher in CBC mode
(let* ((key (ironclad:random-data 32))  ; 256-bit key
       (iv (ironclad:random-data 16))   ; 128-bit IV
       (cipher (ironclad:make-cipher :aes
                                     :key key
                                     :mode :cbc
                                     :initialization-vector iv))) 

  ;; Encrypt a message
  (let* ((plaintext (ironclad:ascii-string-to-byte-array "Hello, World!!!!"))  ; 16 bytes
         (ciphertext (make-array 16 :element-type '(unsigned-byte 8))))
    (ironclad:encrypt cipher plaintext ciphertext)

    ;; Decrypt the message
    (let ((decrypted (make-array 16 :element-type '(unsigned-byte 8))))
      (ironclad:decrypt cipher ciphertext decrypted)
      decrypted))
;; => #(72 101 108 108 111 44 32 87 111 114 108 100 33 33 33 33)

;; Create a ChaCha stream cipher
(let* ((key (ironclad:random-data 32))
       (nonce (ironclad:random-data 12))  ; 96-bit nonce
       (cipher (ironclad:make-cipher :chacha
                                     :key key
                                     :mode :stream
                                     :initialization-vector nonce))) 
  (ironclad:encrypt-in-place cipher (ironclad:ascii-string-to-byte-array "Secret message")))

;; List all supported ciphers
(ironclad:list-all-ciphers)
;; => (:3DES :AES :ARCFOUR :ARIA :BLOWFISH :CAMELLIA :CAST5 :CHACHA ...)

;; Check if a cipher is supported
(ironclad:cipher-supported-p :aes)  ;; => T

;; Get valid key lengths for a cipher
(ironclad:key-lengths :aes)  ;; => (16 24 32)

;; Get block length
(ironclad:block-length :aes)  ;; => 16

```

--------------------------------

### Create a Message Authentication Code (MAC)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Shows how to create a MAC object using the `make-mac` function. It requires a MAC name (keyword or symbol), a secret key, and optionally accepts algorithm-specific arguments. The example lists various supported MAC types and their common argument patterns.

```lisp
(make-mac mac-name key &rest args)
```

```lisp
(make-mac :blake2-mac key &key digest-length)
```

```lisp
(make-mac :blake2s-mac key &key digest-length)
```

```lisp
(make-mac :cmac key cipher-name)
```

```lisp
(make-mac :gmac key cipher-name initialization-vector)
```

```lisp
(make-mac :hmac key digest-name)
```

```lisp
(make-mac :poly1305 key)
```

```lisp
(make-mac :siphash key &key compression-rounds finalization-rounds digest-length)
```

```lisp
(make-mac :skein-mac key &key block-length digest-length)
```

--------------------------------

### Example: Compute Digest within a Stream (Common Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Demonstrates how to use a digesting stream in conjunction with a broadcast stream to compute a digest of data being written to another stream. This allows for digest calculation without altering the original stream's behavior.

```lisp
(defun frobbing-function (stream)
  (let* ((digesting-stream (crypto:make-digesting-stream :sha1))
         (stream (make-broadcast-stream stream digesting-stream)))
    (frob-guts stream)
    (... (crypto:produce-digest digesting-stream) ...)
    ...))
```

--------------------------------

### Calculate Digest of Sequence

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Calculates the digest of a subsequence within a given sequence. The function supports specifying the digest type, the sequence, and optional start and end bounds for the subsequence. It also allows for an output digest buffer and start position, similar to produce-digest.

```common-lisp
(digest-sequence digest-spec sequence &rest args &key start end digest digest-start) => digest
```

--------------------------------

### Get Valid Key Lengths for Cipher - Lisp

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Returns a list of all valid key lengths that can be used with a specific cipher.

```lisp
(key-lengths cipher) => list
```

--------------------------------

### Get Block Length of Cipher - Lisp

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Returns the number of octets that a cipher processes at a time. For stream ciphers, this will always return 1.

```lisp
(block-length cipher) => number
```

--------------------------------

### Get Octets from Output Stream (Common Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Retrieves the octets (bytes) that have been written to an octet output stream. This function is the octet-based equivalent of get-output-stream-string.

```lisp
(get-output-stream-octets stream)
```

--------------------------------

### Manage Keystream Position - Lisp

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Allows getting or setting the current position within the keystream of a cipher. Returns the position or a boolean indicating success/failure of setting.

```lisp
(keystream-position cipher &optional position) => number or boolean
```

--------------------------------

### List Supported MAC Algorithms

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Returns a list of all MAC algorithm names that can be used with the 'make-mac' function.

```lisp
(list-all-macs)
```

--------------------------------

### Load Ironclad Subsystems for AES and SHA256

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Demonstrates how to load specific Ironclad subsystems for AES encryption and SHA256 hashing. This is useful for reducing the overall memory footprint and load time of the Ironclad library by only including necessary components.

```lisp
(asdf:load-system "ironclad/cipher/aes")
(asdf:load-system "ironclad/digest/sha256")
```

--------------------------------

### Run Ironclad Test Suite with ASDF

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

This snippet illustrates how to run the test suite for the Ironclad library using ASDF. Running tests is crucial for verifying the correctness of the cryptographic implementations.

```common-lisp
(asdf:test-system "ironclad")
```

--------------------------------

### Decrypt Message with Cipher - Lisp

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Decrypts a message segment using a provided cipher. The algorithm is determined by the cipher's class. Supports specifying start and end points for the message.

```lisp
(decrypt-message cipher message &key start end &allow-other-keys) => decrypted-message
```

--------------------------------

### Encrypt Message with Cipher - Lisp

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Encrypts a message segment using a provided cipher. The algorithm is determined by the cipher's class. Supports specifying start and end points for the message.

```lisp
(encrypt-message cipher message &key start end &allow-other-keys) => encrypted-message
```

--------------------------------

### Encrypt Message with Key (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Encrypts a message using a provided public key. The function supports specifying start and end points within the message data. The output is the encrypted message.

```lisp
(encrypt-message key message &key start end &allow-other-keys) => encrypted-message
```

--------------------------------

### List Available Key Derivation Functions (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Returns a list of all available key derivation function (KDF) kinds that can be used with the make-kdf function. This helps users discover and select appropriate KDFs for their key derivation needs.

```lisp
(list-all-kdfs) => list
```

--------------------------------

### Reinitialize MAC Instance

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Reinitializes an existing MAC instance with new initialization arguments. The ':key' argument can be provided to set a new secret key for the MAC computation.

```lisp
(reinitialize-instance mac &rest initargs &key key &allow-other-keys)
```

--------------------------------

### Get Digest Length

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Returns the length (in bytes) of a digest computed by the specified digest. The input can be either a digest name (symbol or keyword) or a digest instance. This is useful for pre-allocating buffers for digest outputs.

```lisp
(digest-length digest)
```

--------------------------------

### Initialize MAC with Key and Algorithm

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Creates a Message Authentication Code (MAC) object. The key length for SipHash must be 16 bytes. For Skein, block length can be 32, 64, or 128, and digest length is flexible. Default values are provided for block and digest lengths.

```lisp
(ironclad:make-mac :hmac key :sha256)
```

--------------------------------

### List Supported KDFs

Source: https://context7.com/sharplispers/ironclad/llms.txt

Retrieves a list of all supported Key Derivation Functions (KDFs) available in the Ironclad library, including PBKDF2, Scrypt, Argon2 variants, Bcrypt, and HMAC-KDF.

```lisp
(ironclad:list-all-kdfs)
```

--------------------------------

### Verify Digital Signature (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Verifies if a given signature is valid for a message using a specific key. Returns true if the signature is valid, false otherwise. Supports specifying start and end points for the message.

```lisp
(verify-signature key message signature &key start end &allow-other-keys) => boolean
```

--------------------------------

### Create Key Derivation Function Instance (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Instantiates a key derivation function (KDF) object based on the specified kind and optional parameters. This function supports various KDFs including Argon2, Bcrypt, PBKDF1, PBKDF2, Scrypt, and HMAC, with different parameters influencing their behavior and security.

```lisp
(make-kdf kind &key digest n r p block-count additional-key additional-data) => kdf
```

--------------------------------

### Update MAC State

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Updates the internal state of a MAC object with the provided data. The data can be of various types, and specific methods exist for byte arrays, allowing updates with subsequences using start and end arguments.

```lisp
(update-mac mac thing &key &allow-other-keys)
```

```lisp
(let* ((key (random-data 32))
       (mac (ironclad:make-mac :hmac key :sha256))
       (array (make-array 16 :element-type '(unsigned-byte 8) :initial-element 0)))
  ;; Update with 16 zeroes.
  (ironclad:update-mac mac array)
  ;; Update with 8 ones.
  (fill array 1 :start 2 :end 10)
  (ironclad:update-mac mac array :start 2 :end 10))
```

--------------------------------

### Produce Final Digest Value

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Returns the computed digest of all data processed by the digester so far. Optionally, the digest can be written directly into a provided byte array at a specified starting position, with error handling for insufficient buffer space.

```lisp
(produce-digest digester &key digest digest-start) => digest
```

--------------------------------

### Initialization Vector Not Supplied Error (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Signaled when `make-cipher` is called without a required initialization vector.

```lisp
initialization-vector-not-supplied
```

--------------------------------

### Signature Nonce Generation

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Details on how to generate nonces for DSA, Elgamal, and ECDSA signatures. Explains the use of random nonces by default and how to implement deterministic nonces.

```APIDOC
## Signature Nonce Generation

### Description
DSA, Elgamal and ECDSA signatures require the generation of a nonce. It is crucial to never sign two different messages with the same key and the same nonce, as this could compromise the private key. Ironclad's `generate-signature-nonce` method generates random nonces by default. For deterministic nonces, as specified in RFC 6979, this method needs to be redefined.

### Method
`(generate-signature-nonce (key message &optional parameters))`

### Parameters
- `key`: The private key used for signing.
- `message`: The message to be signed.
- `parameters`: Optional. For DSA, this is `q`. For Elgamal, this is `p`. For ECDSA, this is `nil`.

### Example (Deterministic Nonce for Secp256k1 ECDSA)
```lisp
(defmethod generate-signature-nonce ((key secp256k1-private-key) message &optional parameters)
  (declare (ignore parameters))
  (compute-deterministic-nonce key message))
```
```

--------------------------------

### Decrypt Message (Ironclad)

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Decrypts a portion of an encrypted message using a provided key. The decryption algorithm is determined by the class of the key. Allows specifying start and end points, and optionally the expected number of bits in the decrypted message.

```common-lisp
(decrypt-message key message &key start end n-bits &allow-other-keys) => decrypted-message
```

--------------------------------

### Decrypt Data in Lisp

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Decrypts data using a provided cipher object. It takes the cipher, ciphertext, and plaintext buffers, along with optional start and end points for both ciphertext and plaintext. It also supports handling the final block with padding.

```lisp
(decrypt cipher ciphertext plaintext &key ciphertext-start ciphertext-end plaintext-start handle-final-block) => n-bytes-consumed, n-bytes-produced
```

--------------------------------

### Signature Formatting

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Explains how signatures are formatted as octet vectors and provides functions for creating and deconstructing signatures.

```APIDOC
## Signature Formatting

### Description
Signatures are returned as octet vectors. For signatures with multiple components (e.g., R and S values for DSA), the vector is a concatenation of these components. The `make-signature` and `destructure-signature` functions allow for creating and accessing these components.

### `make-signature` Function

#### Method
`(make-signature kind &key &allow-other-keys)`

#### Description
Creates an octet vector representing a signature. The available `&key` arguments depend on the `kind` of signature.

#### Signature Kinds and Parameters
- `:dsa` &key `r` `s` `n-bits`
- `:ed25519` &key `r` `s`
- `:ed448` &key `r` `s`
- `:elgamal` &key `r` `s` `n-bits`
- `:rsa` &key `s` `n-bits`
- `:secp256k1` &key `r` `s`
- `:secp256r1` &key `r` `s`
- `:secp384r1` &key `r` `s`
- `:secp521r1` &key `r` `s`

#### Parameter Types
- For Ed25519, Ed448, Secp256k1, Secp256r1, Secp384r1, and Secp521r1: `r` and `s` are of type `(simple-array (unsigned-byte 8) (*))`.
- For DSA and Elgamal: `r`, `s`, and `n-bits` are of type `integer`.
- For RSA: `s` and `n-bits` are of type `integer`.

### `destructure-signature` Function

#### Method
`(destructure-signature kind signature)`

#### Description
Deconstructs a signature octet vector into a property list (plist). The keys in the plist correspond to the `&key` arguments used in `make-signature` for the given `kind`.
```

--------------------------------

### Encrypt Data in Lisp

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Encrypts data using a provided cipher object. It takes the cipher, plaintext, and ciphertext buffers, along with optional start and end points for both plaintext and ciphertext. It also supports handling the final block with padding.

```lisp
(encrypt cipher plaintext ciphertext &key plaintext-start plaintext-end ciphertext-start handle-final-block) => n-bytes-consumed, n-bytes-produced
```

--------------------------------

### Create a Tree Hash Digest

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Demonstrates how to create a tree hash object using Ironclad. By default, it uses the Tiger algorithm and a segment size of 1024 bytes. It shows the basic instantiation and a convenience function for Tiger tree hashes.

```lisp
(ironclad:make-digest :tree-hash)
```

```lisp
(ironclad:make-tiger-tree-hash)
```

--------------------------------

### RSA Padding with OAEP

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Details on how to apply the OAEP padding scheme for RSA encryption and decryption, including using the `oaep` key parameter and the `oaep-encode`/`oaep-decode` functions.

```APIDOC
## RSA Padding with OAEP

### Description
For secure RSA encryption, padding is required. The OAEP (Optimal Asymmetric Encryption Padding) scheme is supported via the `oaep` key parameter during encryption and decryption. This parameter can accept a digest name or `t` to use SHA1. Alternatively, `oaep-encode` and `oaep-decode` functions can be used manually.

### Using `oaep` Key Parameter

#### Example (Encryption)
```lisp
(encrypt-message rsa-public-key message :oaep t)
```

#### Example (Decryption)
```lisp
(decrypt-message rsa-private-key message :oaep t)
```

### Manual OAEP Encoding/Decoding

#### Functions
- `oaep-encode`: Encodes a message using OAEP padding.
- `oaep-decode`: Decodes a message that was padded with OAEP.
```

--------------------------------

### List All Digests

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Returns a list of all supported digest algorithm names.

```APIDOC
## LIST-ALL-DIGESTS

### Description
Returns a list whose elements may be validly passed to [make-digest](#org0aca191).

### Function Signature
(list-all-digests) => list

### Returns
- **list** (list) - A list of supported digest algorithm names.
```

--------------------------------

### Update Digest State with Data (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Updates the internal state of a digest object with new data. The `thing` can be an octet vector or a stream. When using an octet vector, `start` and `end` arguments can specify a subsequence. This function returns the digester object.

```lisp
(update-digest digester thing &key &allow-other-keys)
```

```lisp
(let ((digester (ironclad:make-digest :sha1))
      (array (make-array 16 :element-type '(unsigned-byte 8) :initial-element 0)))
  ;; Update with 16 zeroes.
  (ironclad:update-digest digester array)
  ;; Update with 8 ones.
  (fill array 1 :start 2 :end 10)
  (ironclad:update-digest digester array :start 2 :end 10))
```

```lisp
(update-digest digester (stream stream) &key buffer start end &allow-other-keys)
```

--------------------------------

### High-Level Hashing Functions

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Convenience functions for hashing sequences, streams, and files.

```APIDOC
## digest-sequence

### Description
Computes the digest of a byte sequence.

### Method
POST

### Endpoint
/digest-sequence

### Parameters
#### Query Parameters
- **digest-spec** (string | object) - Required - The digest algorithm name or a digest object.
- **sequence** (bytes) - Required - The byte sequence to hash.
- **start** (integer) - Optional - The starting index of the subsequence.
- **end** (integer) - Optional - The ending index of the subsequence.
- **digest** (bytes) - Optional - A buffer to store the result.
- **digest-start** (integer) - Optional - The starting index in the `digest` buffer.

### Request Example
```json
{
  "digest-spec": ":md5",
  "sequence": "<byte-array>",
  "start": 0,
  "end": 16
}
```

### Response
#### Success Response (200)
- **digest** (bytes) - The computed digest.

#### Response Example
```json
{
  "digest": "<computed-digest-bytes>"
}
```

## digest-stream

### Description
Computes the digest of a stream's contents.

### Method
POST

### Endpoint
/digest-stream

### Parameters
#### Query Parameters
- **digest-spec** (string | object) - Required - The digest algorithm name or a digest object.
- **stream** (stream) - Required - The input stream.
- **buffer** (bytes) - Optional - A buffer for reading from the stream.
- **start** (integer) - Optional - The starting index for the buffer.
- **end** (integer) - Optional - The ending index for the buffer.
- **digest** (bytes) - Optional - A buffer to store the result.
- **digest-start** (integer) - Optional - The starting index in the `digest` buffer.

### Request Example
```json
{
  "digest-spec": ":sha256",
  "stream": "<input-stream>",
  "buffer": "<byte-array>",
  "start": 0,
  "end": 4096
}
```

### Response
#### Success Response (200)
- **digest** (bytes) - The computed digest.

#### Response Example
```json
{
  "digest": "<computed-digest-bytes>"
}
```

## digest-file

### Description
Computes the digest of a file's contents.

### Method
POST

### Endpoint
/digest-file

### Parameters
#### Query Parameters
- **digest-spec** (string | object) - Required - The digest algorithm name or a digest object.
- **pathname** (string) - Required - The path to the file.
- **buffer** (bytes) - Optional - A buffer for reading from the file.
- **start** (integer) - Optional - The starting index for the buffer.
- **end** (integer) - Optional - The ending index for the buffer.
- **digest** (bytes) - Optional - A buffer to store the result.
- **digest-start** (integer) - Optional - The starting index in the `digest` buffer.

### Request Example
```json
{
  "digest-spec": ":tiger",
  "pathname": "/path/to/your/file.txt",
  "buffer": "<byte-array>"
}
```

### Response
#### Success Response (200)
- **digest** (bytes) - The computed digest.

#### Response Example
```json
{
  "digest": "<computed-digest-bytes>"
}
```
```

--------------------------------

### Decrypt In-Place (Common Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Decrypts data directly within the provided text buffer. This is a shorthand for the `decrypt` function where ciphertext and plaintext buffers are the same. Supports specifying start and end points for the operation. Returns the number of bytes consumed and produced.

```common-lisp
(decrypt-in-place cipher text &key start end) => n-bytes-consumed, n-bytes-produced
```

--------------------------------

### Encrypt In-Place (Common Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Encrypts data directly within the provided text buffer. This is a shorthand for the `encrypt` function where plaintext and ciphertext buffers are the same. Supports specifying start and end points for the operation. Returns the number of bytes consumed and produced.

```common-lisp
(encrypt-in-place cipher text &key start end) => n-bytes-consumed, n-bytes-produced
```

--------------------------------

### PBKDF Convenience Functions

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Provides simplified functions for hashing and checking passwords using PBKDF2.

```APIDOC
### PBKDF convenience functions

### pbkdf2-hash-password

#### Description
Convenience function for hashing passwords using the PBKDF2 algorithm. Returns the derived hash of the password, and the original salt, as byte vectors.

### Method
(pbkdf2-hash-password password &key salt digest iterations)

#### Parameters
##### Path Parameters
- **password** (byte array) - Required - The password to hash.
- **salt** (byte array) - Optional - The salt to use. If not provided, a random salt is generated.
- **digest** (symbol) - Optional - The digest algorithm to use. Defaults to SHA256.
- **iterations** (integer) - Optional - The number of iterations. Defaults to 10000.

#### Response
#### Success Response (password)
- password (byte array) - The derived hash of the password.
- salt (byte array) - The salt used for hashing.

### pbkdf2-hash-password-to-combined-string

#### Description
Convenience function for hashing passwords using the PBKDF2 algorithm. Returns the derived hash of the password as a single string that encodes the given salt and PBKDF2 algorithm parameters.

### Method
(pbkdf2-hash-password-to-combined-string password &key salt digest iterations)

#### Parameters
##### Path Parameters
- **password** (byte array) - Required - The password to hash.
- **salt** (byte array) - Optional - The salt to use. If not provided, a random salt is generated.
- **digest** (symbol) - Optional - The digest algorithm to use. Defaults to SHA256.
- **iterations** (integer) - Optional - The number of iterations. Defaults to 10000.

#### Response
#### Success Response (password)
- password (string) - The combined salt and digest string.

### pbkdf2-check-password

#### Description
Given a _password_ byte vector and a combined salt and digest string produced by [pbkdf2-hash-password-to-combined-string](#org57ce335), checks whether the password is valid.

### Method
(pbkdf2-check-password password combined-salt-and-digest)

#### Parameters
##### Path Parameters
- **password** (byte array) - Required - The password to check.
- **combined-salt-and-digest** (string) - Required - The combined salt and digest string.

#### Response
#### Success Response (boolean)
- boolean (boolean) - `t` if the password is valid, `nil` otherwise.
```

--------------------------------

### Create Octet Input Stream (Common Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Creates an octet input stream from a buffer. Similar to Common Lisp's string-input-stream but operates on octets (bytes) instead of characters. Optional start and end parameters define the buffer range.

```lisp
(make-octet-input-stream buffer &optional start end)
```

--------------------------------

### Digest a Sequence (Vector)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

A high-level convenience function that computes the digest of a byte sequence (vector). It encapsulates the process of creating a digest object, updating it with the sequence data, and producing the final digest. It supports specifying start and end points within the sequence.

```lisp
(digest-sequence digest-spec sequence &rest args &key start end digest digest-start) => digest
```

```lisp
(ironclad:digest-sequence :md5 *buffer*)
```

```lisp
(let ((digester (ironclad:make-digest :md5)))
  (ironclad:digest-sequence digester *buffer*))
```

--------------------------------

### Create Key Derivation Function (KDF) Instance

Source: https://github.com/sharplispers/ironclad/blob/master/doc/ironclad.html

Creates an instance of a Key Derivation Function (KDF). Accepts a kind (e.g., argon2d, bcrypt, pbkdf2) and optional parameters like digest, memory blocks, or cost factors depending on the KDF type.

```lisp
(make-kdf kind &key digest n r p block-count additional-key additional-data)
```

--------------------------------

### Unsupported MAC Error (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Signaled when `make-mac` is called with a MAC name that is not supported by the library.

```lisp
unsupported-mac
```

--------------------------------

### Read Seed from File (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Reads seed data from a specified file to reseed a pseudo-random number generator (PRNG). If the file does not exist, it attempts to get a seed from the OS. It also writes a new seed back to the file, ensuring future unpredictability.

```lisp
(read-seed path &optional prng) => t
```

--------------------------------

### Create Tree Hash with Custom Algorithm or Segment Size

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Illustrates creating a tree hash with specific configurations. You can specify a different internal digest algorithm (e.g., SHA256) or a custom segment size (block length).

```lisp
(ironclad:make-digest '(:treehash :digest :sha256))
```

```lisp
(ironclad:make-digest '(:tree-hash :block-length 16384))
```

--------------------------------

### Make Private Key (Lisp)

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Constructs a private key object based on its kind and associated parameters. The specific keyword arguments vary by key type, including secret components like 'x' or 'd' and group parameters for DSA/Elgamal/RSA.

```lisp
(make-private-key :curve25519 &key x y) => private-key
```

```lisp
(make-private-key :curve448 &key x y) => private-key
```

```lisp
(make-private-key :dsa &key p q g y x) => private-key
```

```lisp
(make-private-key :ed25519 &key x y) => private-key
```

```lisp
(make-private-key :ed448 &key x y) => private-key
```

```lisp
(make-private-key :elgamal &key p g y x) => private-key
```

```lisp
(make-private-key :rsa &key d n p q) => private-key
```

```lisp
(make-private-key :secp256k1 &key x y) => private-key
```

```lisp
(make-private-key :secp256r1 &key x y) => private-key
```

```lisp
(make-private-key :secp384r1 &key x y) => private-key
```

```lisp
(make-private-key :secp521r1 &key x y) => private-key
```

--------------------------------

### Produce MAC Digest

Source: https://github.com/sharplispers/ironclad/blob/master/README.org

Computes and returns the MAC digest of the data processed so far without modifying the MAC's internal state. An optional digest buffer and start position can be provided to store the result. The digest length varies based on the MAC algorithm.

```lisp
(produce-mac mac &key digest digest-start)
```