Botan Bindings

Synopsis

(import (crypto botan))

Bindings to the Botan cryptography library. If this documentation contains insufficient detail, consider consulting the Botan FFI documentation directly.

Utility Functions

procedure: (botan-api-version)

Report the supported API version of the Botan library as an integer in the form YYYYMMDD.

procedure: (botan-version-info)

Report the version of the Botan library as a record containing the semantic version number and a descriptive string.

procedure: (bytevector-wipe! bytevector)

Wipes the memory of the given bytevector destroying any meaningful information inside it.

procedure: (bytevector=?/O1 bytevector-a bytevector-b)

Compares the contents of two bytevectors. The comparison takes the same amount of time no matter whether the contents differ or not.

Error Handling

condition: &botan

procedure: (botan-error? any)

A condition used to represent errors reported by the Botan library. The type is derived from &condition.

procedure: (make-botan-error errno)

Create a Botan error from an integer error code. The returned composite condition also contains a &message.

procedure: (botan-errno error)

Extract the integer error code from a &botan condition.

condition: &key-i/o

procedure: (key-i/o-error? any)

procedure: (make-key-i/o-error port)

A condition used to represent key encoding errors. The type is derived from &i/o-port and holds an offending port object.

Encoding

syntax: (hex-option symbol)

syntax: (hex-options symbol ...)

Flags for hexadecimal encoding of binary data: lower-case uses lower-case letters for hexadecimal digits greater than nine.

procedure: (hex-encode bytevector)

procedure: (hex-encode bytevector options)

Encode binary data into a hexadecimal string.

procedure: (hex-decode string)

Decode a hexadecimal string into binary data. Whitespace in the input is ignored.

Random Number Generators

record: rng

procedure: (rng? any)

procedure: (make-rng type)

Random number generators are represented by opaque record instances. You can create a new generator specifying the type as a symbol:

• system for an operating system service,
• user or user-threadsafe for a pseudo random number generator in user space seeded automatically from an operating system service,
• hwrnd or rdrand for a hardware generator if your processor supports it,
• null for a dummy generator that always fails.

parameter: current-rng

Default random number generator. Initialized to a user or user-threadsafe generator when the module is loaded, depending on the value of (threaded?).

procedure: (rng-get rng length)

Retrieve a random bytevector of the given length from the given generator.

procedure: (rng-reseed! rng bits)

procedure: (rng-reseed! rng source-rng bits)

Reseed a generator with random bits from the system entropy source or the given generator.

Keys

record: key

procedure: (key? any)

Cryptographic keys are represented as opaque record instances.

procedure: (key-algorithm key)

Return a string identifying the cryptographic algorithm for which the key can be used.

procedure: (key-estimated-strength key)

Return an integer estimate of the strength of a cryptographic key.

procedure: (key-fingerprint hash key)

Compute a binary fingerprint of the public key material using the hash function identified by a string algorithm name. If the key has no public component, the procedure returns #f.

procedure: (key-wipe! key)

Make sure that no secret key material remains in memory. The given key is unusable after this operation.

record: public-key

procedure: (public-key? any)

Asymmetric public keys are represented as opaque record instances derived from the key base type.

procedure: (make-public-key key)

Convert a secret key into a public key or pass a public key through unmodified.

record: secret-key

procedure: (secret-key? any)

Asymmetric secret keys are represented as opaque record instances derived from the key base type.

procedure: (generate-asymmetric-key algorithm parameters rng)

procedure: (generate-asymmetric-key algorithm parameters)

procedure: (generate-asymmetric-key algorithm)

Generate a new asymmetric secret key for the algorithm specified by a string name. Optionally, algorithm parameters may be specified as another string argument. If no random number generator is specified, (current-rng) is used.

record: symmetric-key

procedure: (symmetric-key? any)

Symmetric secret keys are represented as opaque record instances derived from the key base type.

procedure: (generate-symmetric-key algorithm length rng)

procedure: (generate-symmetric-key algorithm length)

procedure: (generate-symmetric-key algorithm)

Generate a new symmetric secret key for the algorithm specified by a string name. Optionally, the length of the key in bytes may be specified. If no random number generator is specified, (current-rng) is used.

thread parameter: current-key-derivation

A list containing a string algorithm name and the default parameters for key derivation functions. The initial value of the parameter is "PBKDF2(SHA-256)" 10000 0 0.

procedure: (derive-symmetric-key algorithm length password salt kdf param0 param1 param2)

procedure: (derive-symmetric-key algorithm length password salt kdf param0 param1)

procedure: (derive-symmetric-key algorithm length password salt kdf param0)

procedure: (derive-symmetric-key algorithm password salt kdf param0)

procedure: (derive-symmetric-key algorithm length password salt)

procedure: (derive-symmetric-key algorithm password salt)

Derive a new symmetric secret key for the algorithm specified by a string name from the given password and salt. Optionally, the length of the key in bytes may be specified. If no key derivation algorithm is specified, the parameters from (current-key-derivation) are used.

procedure: (derive-symmetric-key/msec algorithm length password salt kdf msec)

procedure: (derive-symmetric-key/msec algorithm password salt kdf msec)

procedure: (derive-symmetric-key/msec algorithm password salt msec)

Derive a new symmetric secret key for the algorithm specified by a string name from the given password and salt. Optionally, the length of the key in bytes may be specified. The procedure determines algorithm parameters to make the key derivation take roughly the given number of milliseconds, which are stored in current-key-derivation upon return. If no key derivation algorithm is specified, the one from (current-key-derivation) is used, but the other parameters are ignored.

Symmetric Signatures

constant: symmetric-sign-algorithm

The name of the cryptographic message authentication code.

constant: symmetric-sign-keybytes

The key length of the cryptographic message authentication code.

procedure: (generate-symmetric-sign-key)

procedure: (generate-symmetric-sign-key port)

procedure: (derive-symmetric-sign-key password salt)

procedure: (derive-symmetric-sign-key password salt blocks iterations)

Specialized versions of the generate-key and derive-key procedures for symmetric signature keys.

procedure: ((symmetric-sign key) message)

Compute a cryptographic message authentication code of the given message bytevector using the given key and return an envelope containing the plain message and the signature.

procedure: ((symmetric-verify key) envelope)

Verify the cryptographic message authentication code of the given envelope using the given key and return the valid message bytevector or #f in case of failure.

Symmetric Boxes

procedure: ((symmetric-box key) message nonce)

procedure: ((symmetric-box key) message additional nonce)

Encrypt and authenticate the given message bytevector using the given key and return an envelope containing the ciphertext and message authentication code. Optionally also authenticate the given additional data bytevector.

The nonce can be a bytevector, a random number generator, or #f; if not specified as a bytevector, a nonce of the right length is obtained from the generator, which defaults to (current-rng).

procedure: ((symmetric-unbox key) envelope)

procedure: ((symmetric-unbox key) envelope additional)

Decrypt and authenticate the given envelope using the given key and return the valid plaintext bytevector or #f in case of failure. Optionally also authenticate the given additional data bytevector.

Asymmetric Signatures

procedure: ((asymmetric-sign key hash/padding) message)

Compute a cryptographic message digest and signature of the given message bytevector using the given key and return an envelope containing the plain message and the signature.

procedure: ((asymmetric-verify key hash/padding) envelope)

Verify the cryptographic message digest and signature of the given envelope using the given key and return the valid message bytevector or #f in case of failure.

Asymmetric Boxes

procedure: (export-public-key key)

Given an asymmetric secret key, export the corresponding public key as a bytevector that can be consumed by exchange-symmetric-key.

procedure: (export-symmetric-key padding public-key symmetric-key rng)

procedure: (export-symmetric-key padding public-key symmetric-key)

Given an asymmetric public key, wrap the given symmetric key in an encrypted envelope that can be consumed by exchanged-symmetric-key.

procedure: (exchange-symmetric-key algorithm other key)

Given some exported key exchange information and a secret key, reconstruct a shared symmetric key:

• If other is a bytevector produced by export-public-key, the algorithm should be a string in the form "CIPHER/KDF" specifying the desired ciphersuite of the resulting key and the key derivation function used to process the output of the key agreement function.
• If other is an envelope produced by export-symmetric-key, the algorithm should be a string in the form "CIPHER/PADDING" specifying the desired ciphersuite of the resulting key and the padding algorithm used to wrap the key.

procedure: ((asymmetric-box algorithm other key) message nonce)

procedure: ((asymmetric-box algorithm other key) message additional nonce)

Derive a symmetric box key through a asymmetric key agreement or key wrapping, then encrypt and authenticate the given message bytevector using the derived key and return an envelope containing the ciphertext and message authentication code. Optionally also authenticate the given additional data bytevector.

procedure: ((asymmetric-unbox algorithm other key) envelope)

procedure: ((asymmetric-unbox algorithm other key) envelope additional)

Derive a symmetric box key through a asymmetric key agreement or key wrapping, then decrypt and authenticate the given envelope using the derived key and return the valid plaintext bytevector or #f in case of failure. Optionally also authenticate the given additional data bytevector.

I/O Operations

thread parameter: current-key-wrap

A list containing a string password and an encryption algorithm name, or #f to disable automatic key wrapping and unwrapping (the default).

procedure: (read-key port)

procedure: (read-key)

Read a textual representation of a cryptographic key from the given input port or from (current-input-port).

If (current-key-wrap) is not #f, encrypted keys are automatically unwrapped when read. Otherwise an error is raised when an encrypted key is encountered in the input.

procedure: (write-key key port)

procedure: (write-key key)

Write a textual representation of a cryptographic key to the given input port or to (current-output-port).

If (current-key-wrap) is not #f, secret keys are automatically wrapped and written out in encrypted form.