This egg provides a binding to the Botan cryptographic library for CHICKEN. It uses the C interface layer provided with Botan and declared in the botan/ffi.h header.
Most functions in the C interface to Botan can return error status codes, which are converted to composite conditions of type (exn botan) in CHICKEN. These conditions have a status property can be set to one of the following symbols:
invalid-verifier
invalid-input
bad-mac
insufficient-buffer-space
exception-thrown
out-of-memory
bad-flag
null-pointer
bad-parameter
key-not-set
invalid-key-length
not-implemented
invalid-object
unknown-error
The C interface to Botan does not provide access to any detailed error message. If you encounter a mystifying exception, consider setting the environment variable BOTAN_FFI_PRINT_EXCEPTIONS=1 to trigger console logging for C++ exceptions caught by the C interface.
Library Management
procedure: (botan-api-version) → integer?
procedure: (botan-api-version [version integer?]) → void?
Retrieve the API version supported by the Botan runtime library, or ensure that a specific version of the functionality is available. The version is an integer representing a date in the form YYYYMMDD. At the time of writing, the egg requires at least version 20191214 to function correctly.
procedure: (botan-version-string) → string?
Retrieve a human-readable version information string for the Botan runtime library.
procedure: (botan-version) → list?
Retrieve the release version of the Botan runtime library. The returned list contains at least three elements: Major version, minor version, and patchlevel. A fourth element representing a date in the form YYYYMMDD may be returned for release version.
General Utilities
predicate: data?
Check whether a given object is a binary data container. The boolean #f, or any object satisfying string?, blob?, or u8vector? qualifies.
procedure: (data-eqv? [a data?] [b data?]) → boolean?
Compare the contents of two binary data containers. If both inputs are of the same length, the comparison always takes the same time, regardless of their contents.
procedure: (data-scrub! [data data?]) → void?
Securely destroy the contents of a binary data container.
procedure: (hex-encode [data data?] #!key [downcase boolean?]) → string?
Convert the contents of a binary data container into a string of hexadecimal digits. If downcase is given a true value, the resulting string contains only lower case letters, otherwise it uses only upper case letters.
procedure: (hex-decode [hex string?]) → u8vector?
Decode a string of hexadecimal digits into a byte vector. Spaces are ignored in the input.
procedure: (base64-encode [data data?]) → string?
Convert the contents of a binary data container into a string in Base64 format.
procedure: (base64-decode [base64 string?]) → u8vector?
Decode a string in Base64 format into a byte vector. Spaces are ignored in the input.
Random Number Generators
predicate: rng?
Check whether an object is a random number generator.
procedure: (make-rng [type (or symbol? string?)]) → rng?
procedure: (rng-get [rng rng?] [v (or integer? u8vector?)] #!key [from integer?] [to integer?]) → u8vector?
procedure: (rng-reseed! [rng rng?] #!key [bits integer?] [source rng?]) → void?
procedure: (rng-add-entropy! [rng rng?] [v data?] #!key [from integer?] [to integer?]) → void?
Hash Functions
predicate: hash?
Check whether an object is a hash function.
procedure: (make-hash [name (or symbol? string?)]) → hash?
procedure: (hash-name [hash hash?]) → (or symbol? string?)
procedure: (hash-copy [hash hash?]) → hash?
procedure: (hash-clear! [hash hash?]) → void?
procedure: (hash-update! [hash hash?] [data data?] #!key [from integer?] [to integer?]) → void?
procedure: (hash-length [hash hash?]) → integer?
procedure: (hash-final [hash hash?]) → u8vector?
Message Authentication Codes
predicate: mac?
Check whether an object is a message authentication code.
procedure: (make-mac [name (or (list symbol? symbol?) symbol? string?)]) → mac?
procedure: (mac-name [mac mac?]) → (or (list symbol? symbol?) string?)
procedure: (mac-clear! [mac mac?]) → void?
procedure: (mac-keyspec [mac mac?]) → (values integer? integer? integer?)
procedure: (mac-set-key! [mac mac?] [key u8vector?]) → void?
procedure: (mac-update! [mac mac?] [data data?] #!key [from integer?] [to integer?]) → void?
procedure: (mac-length [mac mac?]) → integer?
procedure: (mac-final [mac mac?]) → u8vector?
Symmetric Ciphers
predicate: cipher?
Check whether an object is a symmetric cipher operation.
procedure: (make-cipher [name (or symbol? string?)] [direction (or 'encrypt 'decrypt)]) → cipher?
procedure: (cipher-name [cipher cipher?]) → (or symbol? string?)
procedure: (cipher-clear! [cipher cipher?]) → void?
procedure: (cipher-keyspec [cipher cipher?]) → (values integer? integer? integer?)
procedure: (cipher-set-key! [cipher cipher?] [key u8vector?]) → void?
procedure: (cipher-output-length [cipher cipher?] [input-length integer?]) → integer?
procedure: (cipher-tag-length [cipher cipher?]) → integer?
procedure: (cipher-valid-nonce-length? [cipher cipher?] [nonce-length integer?]) → boolean?
procedure: (cipher-default-nonce-length [cipher cipher?]) → integer?
procedure: (cipher-transform [cipher cipher?] [data data?] #!key [from integer?] [to integer?] [aad data?] [nonce u8vector?]) → data?
Key Derivation Functions
parameter: pbkdf-iterations
Default number of iterations for PBKDF algorithms. Updated when specifying a timeout instead.
procedure: (pbkdf [algo (or (list symbol? symbol?) symbol? string?)] [v (or integer? u8vector?)] [password string?] #!key [from integer?] [to integer?] [salt data?] [iterations integer?] [milliseconds integer?]) → u8vector?
procedure: (kdf [algo (or (list symbol? symbol?) symbol? string?)] [v (or integer? u8vector?)] [secret data?] #!key [from integer?] [to integer?] [salt data?] [label string?]) → u8vector?
Password Hashing
procedure: (bcrypt-generate [password string?] [rng rng?] #!key [work-factor integer?]) → string?
procedure: (bcrypt-valid? [password string?] [hash string?]) → boolean?
Asymmetric Algorithms
predicate: privkey?
Check whether an object is an asymmetric private key.
procedure: (generate-privkey [algo (or symbol? string?)] [rng rng?] #!optional [params string?]) → privkey?
procedure: (make-privkey/rsa #!key [p integer?] [q integer?] [e integer?]) → privkey?
procedure: (make-privkey/dsa #!key [p integer?] [q integer?] [g integer?] [x integer?]) → privkey?
procedure: (make-privkey/elgamal #!key [p integer?] [g integer?] [x integer?]) → privkey?
procedure: (make-privkey/dh #!key [p integer?] [g integer?] [x integer?]) → privkey?
procedure: (make-privkey/ed25519 [v u8vector?]) → privkey?
procedure: (make-privkey/x25519 [v u8vector?]) → privkey?
procedure: (make-privkey/ecdsa #!key [scalar integer?] [curve (or symbol? string?)]) → privkey?
procedure: (make-privkey/ecdh #!key [scalar integer?] [curve (or symbol? string?)]) → privkey?
procedure: (make-privkey/sm2 #!key [scalar integer?] [curve (or symbol? string?)]) → privkey?
procedure: (load-privkey [path string?] #!key [password string?]) → privkey?
procedure: (data->privkey [data data?] #!key [from integer?] [to integer?] [password string?]) → privkey?
procedure: (privkey->string [sk privkey?] #!key [rng rng?] [password string?] [cipher (or symbol? string?)] [hash (or symbol? string?)] [iterations integer?] [milliseconds integer?]) → string?
procedure: (privkey->blob [sk privkey?] #!key [rng rng?] [password string?] [cipher (or symbol? string?)] [hash (or symbol? string?)] [iterations integer?] [milliseconds integer?]) → blob?
procedure: (privkey->ed25519 [sk privkey?]) → u8vector?
procedure: (privkey->x25519 [sk privkey?]) → u8vector?
procedure: (privkey-check [sk privkey?] [rng rng?] #!key [strong boolean?]) → boolean?
procedure: (privkey-algorithm [sk privkey?]) → (or symbol? string?)
procedure: (privkey-field [sk privkey?] [field symbol?]) → integer?
predicate: pubkey?
Check whether an object is an asymmetric public key.
procedure: (privkey->pubkey [sk privkey?]) → pubkey?
procedure: (make-pubkey/rsa #!key [n integer?] [e integer?]) → pubkey?
procedure: (make-pubkey/dsa #!key [p integer?] [q integer?] [g integer?] [y integer?]) → pubkey?
procedure: (make-pubkey/elgamal #!key [p integer?] [g integer?] [y integer?]) → pubkey?
procedure: (make-pubkey/dh #!key [p integer?] [g integer?] [y integer?]) → pubkey?
procedure: (make-pubkey/ed25519 [v u8vector?]) → pubkey?
procedure: (make-pubkey/x25519 [v u8vector?]) → pubkey?
procedure: (make-pubkey/ecdsa #!key [x integer?] [y integer?] [curve (or symbol? string?)]) → pubkey?
procedure: (make-pubkey/ecdh #!key [x integer?] [y integer?] [curve (or symbol? string?)]) → pubkey?
procedure: (make-pubkey/sm2 #!key [x integer?] [y integer?] [curve (or symbol? string?)]) → pubkey?
procedure: (load-pubkey [path string?]) → pubkey?
procedure: (data->pubkey [data data?] #!key [from integer?] [to integer?]) → pubkey?
procedure: (pubkey->string [pk pubkey?]) → string?
procedure: (pubkey->blob [pk pubkey?]) → blob?
procedure: (pubkey->ed25519 [pk pubkey?]) → u8vector?
procedure: (pubkey->x25519 [pk pubkey?]) → u8vector?
procedure: (pubkey-algorithm [pk pubkey?]) → (or symbol? string?)
procedure: (pubkey-field [pk pubkey?] [field symbol?]) → integer?
procedure: (pubkey-estimated-strength [pk pubkey?]) → integer?
procedure: (pubkey-fingerprint [pk pubkey?] #!key [hash (or symbol? string?)]) → u8vector?
predicate: pk-encrypt?
Check whether an object is an asymmetric encryption operation.
procedure: (make-pk-encrypt [pk pubkey?] [padding (or (list symbol? symbol?) symbol? string?)]) → pk-encrypt?
procedure: (pk-encrypt-output-length [op pk-encrypt?] [input-length integer?]) → integer?
procedure: (pk-encrypt [op pk-encrypt?] [rng rng?] [data data?] #!key [from integer?] [to integer?]) → data?
predicate: pk-decrypt?
Check whether an object is an asymmetric decryption operation.
procedure: (make-pk-decrypt [sk privkey?] [padding (or (list symbol? symbol?) symbol? string?)]) → pk-decrypt?
procedure: (pk-decrypt-output-length [op pk-decrypt?] [input-length integer?]) → integer?
procedure: (pk-decrypt [op pk-decrypt?] [data data?] #!key [from integer?] [to integer?]) → data?
predicate: pk-sign?
Check whether an object is an asymmetric signing operation.
procedure: (make-pk-sign [sk privkey?] [padding (or (list symbol? symbol?) symbol? string?)]) → pk-sign?
procedure: (pk-sign-update! [op pk-sign?] [data data?] #!key [from integer?] [to integer?]) → void?
procedure: (pk-sign-length [op pk-sign?]) → integer?
procedure: (pk-sign-final [op pk-sign?] [rng rng?]) → u8vector?
predicate: pk-verify?
Check whether an object is an asymmetric signature verification operation.
procedure: (make-pk-verify [pk pubkey?] [padding (or (list symbol? symbol?) symbol? string?)]) → pk-verify?
procedure: (pk-verify-update! [op pk-verify?] [data data?] #!key [from integer?] [to integer?]) → void?
procedure: (pk-verify-final [op pk-verify?] [data data?] #!key [from integer?] [to integer?]) → boolean?
predicate: pk-key-agreement?
Check whether an object is an asymmetric key agreement operation.
procedure: (make-pk-key-agreement [sk privkey?] [kdf (or (list symbol? symbol?) symbol? string?)]) → pk-key-agreement?
procedure: (pk-key-agreement-length [op pk-key-agreement?]) → integer?
procedure: (pk-key-agreement-export-public [sk privkey?]) → u8vector?
procedure: (pk-key-agreement [op pk-key-agreement?] [pk u8vector?] #!key [salt data?]) → u8vector?
X.509 Certificates
predicate: x509-cert?
Check whether an object is an X.509 certificate.
procedure: (load-x509-cert [path string?]) → x509-cert?
procedure: (load-x509-cert-chain [path string?]) → (list x509-cert? ...)
procedure: (data->x509-cert [data data?] #!key [from integer?] [to integer?]) → x509-cert?
procedure: (x509-cert->string [cert x509-cert?]) → string?
procedure: (x509-cert->pubkey [cert x509-cert?]) → pubkey?
procedure: (x509-cert-not-before [cert x509-cert?]) → integer?
procedure: (x509-cert-not-after [cert x509-cert?]) → integer?
procedure: (x509-cert-serial-number [cert x509-cert?]) → u8vector?
procedure: (x509-cert-fingerprint [cert x509-cert?] #!key [hash (or symbol? string?)]) → string?
procedure: (x509-cert-issuer-key-id [cert x509-cert?]) → u8vector?
procedure: (x509-cert-issuer-dn [cert x509-cert?] [field symbol?] #!optional [index integer?]) → (or string? #f)
procedure: (x509-cert-subject-key-id [cert x509-cert?]) → u8vector?
procedure: (x509-cert-subject-dn [cert x509-cert?] [field symbol?] #!optional [index integer?]) → (or string? #f)
predicate: x509-crl?
Check whether an object is an X.509 certificate revocation list.
procedure: (load-x509-crl [path string?]) → x509-crl?
procedure: (data->x509-crl [data data?] #!key [from integer?] [to integer?]) → x509-crl?
procedure: (x509-usage-allowed? [cert x509-cert?] [usage (or 'digital-signature 'non-repudiation 'key-encipherment 'data-encipherment 'key-agreement 'key-cert-sign 'crl-sign 'encipher-only 'decipher-only)] ...) → boolean?
procedure: (x509-hostname-match? [cert x509-cert?] [hostname string?]) → boolean?
procedure: (x509-revoked? [cert x509-cert?] [crl x509-crl?]) → boolean?
procedure: (x509-verify [cert x509-cert?] #!key [crl (or x509-xrl? (list x509-crl? ...))] [intermediate (or x509-cert? (list x509-cert ...))] [trusted (or x509-cert (list x509-cert? ...))] [trusted-path string?] [strength integer?] [hostname string?] [time integer?]) → (values boolean? string?)
One-Time Passwords
predicate: hotp?
Check whether an object is a hashed one time password context.
procedure: (make-hotp [key u8vector?] #!key [hash (or symbol? string?)] [digits integer?]) → hotp?
procedure: (hotp-generate [otp hotp?] [counter integer?]) → integer?
procedure: (hotp-valid? [otp hotp?] [code integer?] [counter integer?] #!key [resync-range integer?]) → (or integer? #f)
predicate: totp?
Check whether an object is a time-based one time password context.
procedure: (make-totp [key u8vector?] #!key [hash (or symbol? string?)] [digits integer?] [time-step integer?]) → totp?
procedure: (totp-generate [otp totp?] #!key [time integer?]) → integer?
procedure: (totp-valid? [otp totp?] [code integer?] #!key [time integer?] [acceptable-drift integer?]) → boolean?
Format Preserving Encryption
predicate: fpe?
Check whether an object is a format preserving encryption context.