Ironclad Cryptography Library

Ironclad uses a special variable *prng* to determine the default generator.

PRNG Types

• OS: The default. Uses /dev/urandom (Unix) or CryptGenRandom (Windows). Recommended for most users.
• Fortuna: A cryptographically-secure generator. Use only if your OS does not provide a good PRNG.
• Fortuna-generator: High-quality, deterministic-seeming numbers for simulations.

Multi-threading Note

In multi-threaded applications using bordeaux-threads or lparallel, the PRNG is handled automatically. If using implementation-specific threading, you must bind a unique PRNG to *prng* in each thread to avoid generating identical random data.

;; Manual thread setup for custom threading
(make-thread (lambda ()
               (let ((crypto:*prng* (crypto:make-prng :os)))
                 (forms-for-thread-1))))

;; Generating random data
(random-data 16)           ; 16 bytes
(random-bits 16)           ; integer with 16 bits
(strong-random 16)        ; unbiased number between 0 and 15

Ironclad provides several stream wrappers to perform cryptographic operations on data as it flows through a stream.

Octet Streams

Use make-octet-input-stream and make-octet-output-stream to handle raw byte data similarly to standard Lisp string streams.

Digest Streams

Use make-digesting-stream to compute a hash (e.g., :sha1) of data written to the stream. Use produce-digest to retrieve the result.

Cipher Streams

Use make-encrypting-stream or make-decrypting-stream to wrap an existing stream.

• Supported modes: Stream ciphers or block ciphers in CTR, CFB, CFB8, or OFB mode.
• Direction: :input (data read from the stream is encrypted) or :output (data written to the stream is encrypted).

MAC Streams

Use make-authenticating-stream to compute a Message Authentication Code (MAC) as data is written. Use produce-mac to retrieve the result.

;; Example: Encrypt data and compute an HMAC of the ciphertext
(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))) 
    ...)) 

Ironclad provides high-level functions specifically for storing passwords using PBKDF2.

Hash Password

(pbkdf2-hash-password password &key salt digest iterations) => password

Returns the derived hash and the original salt as byte vectors.

(pbkdf2-hash-password-to-combined-string password &key salt digest iterations) => password

Returns the derived hash as a single string encoding the salt and parameters.

Verify Password

(pbkdf2-check-password password combined-salt-and-digest) => boolean

Checks a password byte vector against a combined string produced by pbkdf2-hash-password-to-combined-string.

;; Example workflow
(let ((pass (make-array 8 :element-type '(unsigned-byte 8) :initial-element 0))) 
      (combined (ironclad:pbkdf2-hash-password-to-combined-string pass :salt my-salt :digest :sha256 :iterations 1000)))
  (ironclad:pbkdf2-check-password pass combined)) ; => T or NIL

Ironclad provides several KDFs for deriving keys from passwords or other secrets.

Supported KDFs

• argon2d, argon2i, argon2id (Note: only variants without parallelism are implemented)
• bcrypt, bcrypt-pbkdf
• pbkdf1, pbkdf2
• scrypt-kdf
• hmac-kdf

Signature

(derive-key kdf passphrase salt iteration-count key-length) => digest

Specific Requirements

• bcrypt: salt must be 16 bytes, iteration-count must be a power of 2 between $2^4$ and $2^{31}$, and key-length must be 24.
• bcrypt-pbkdf: key-length must be between 1 and 1024.
• Scrypt: Ignores iteration-count. Uses N, r, and p parameters (set via make-kdf). $N$ must be a power of 2. $r imes p ext{ must be } \le 2^{30}$.

;; Using the general derive-key API
(let ((kdf (ironclad:make-kdf :pbkdf2 :digest :sha256))
      (pass (make-array 8 :element-type '(unsigned-byte 8) :initial-element 0))
      (salt (make-array 16 :element-type '(unsigned-byte 8) :initial-element 0)))
  (ironclad:derive-key kdf pass salt 1000 32))

Use make-cipher to create an object for encryption and decryption.

Signature

(make-cipher name &key key mode initialization-vector padding tweak) => cipher

Parameters

• name: The algorithm (e.g., :aes, ironclad:arcfour). Use (list-all-ciphers) to see all supported names.
• mode: The mode of operation (e.g., :ecb, :cbc, :ctr, :stream).
• key: A (simple-array (unsigned-byte 8) (*)).
• initialization-vector: A (simple-array (unsigned-byte 8) (*)) of the cipher's block length. For Chacha/Salsa20, use 8 or 12 bytes; for XChacha/XSalsa20, use 24 bytes.
• padding: Supported for ECB/CBC modes: :pkcs7, :ansi-x923, :iso-7816-4.
• tweak: Supported by certain ciphers like threefish.

Encryption and Decryption

Standard API

(encrypt cipher plaintext ciphertext &key plaintext-start plaintext-end ciphertext-start handle-final-block)
(decrypt cipher ciphertext plaintext &key ciphertext-start ciphertext-end plaintext-start handle-final-block)

Note: handle-final-block is required if using padding.

In-place API

(encrypt-in-place cipher text &key start end)
(decrypt-in-place cipher text &key start end)

Note: In-place functions do not support handle-final-block.

Message API

(encrypt-message cipher message &key start end &allow-other-keys)
(decrypt-message cipher message &key start end &allow-other-keys)

(let ((key (make-array 32 :element-type '(unsigned-byte 8) :initial-element 0))
      (iv  (make-array 16 :element-type '(unsigned-byte 8) :initial-element 0))
      (p   (make-array 16 :element-type '(unsigned-byte 8) :initial-element 1))
      (c   (make-array 16 :element-type '(unsigned-byte 8))))
  (let ((cipher (make-cipher :aes :key key :mode :cbc :initialization-vector iv :padding :pkcs7)))
    (encrypt cipher p c :handle-final-block t)
    (decrypt cipher c p :handle-final-block t)))