Monocypher Bindings

Synopsis

(import (crypto monocypher))

Bindings to the Monocypher library of cryptographic operations.

Utility Functions

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 that must be 0, 16, 32, or 64 bytes long. The comparison takes the same amount of time no matter whether the contents differ or not.

Keys

record: key

procedure: (key? any)

procedure: (make-key algorithm public secret)

procedure: (key-algorithm key)

procedure: (public-key key)

procedure: (secret-key key)

Keys are represented by record instances that hold an algorithm name, a public key bytevector and a secret key bytevector. Depending on the algorithm and intended use of the key, either the public or secret component may be #f.

procedure: (make-public-key key)

Creates a new key key that has the same algorithm and public key bytevector as the given one, but does not contain a secret component.

procedure: (key-wipe! key)

If the given key has a secret component, wipes the secret data from memory.

procedure: (check-key who algorithm any)

Ensures that the given value is a key with the given algorithm name and returns the key. If the value does not pass the check, an error condition is raised that contains a &who condition indicating the given location.

procedure: ((generate-key who algorithm secret-keybytes secret->public))

procedure: ((generate-key who algorithm secret-keybytes secret->public) port)

Generates a new key or keypair using entropy from the given port or from (current-entropy-port).

procedure: ((derive-key who algorithm secret-keybytes secret->public) password salt)

procedure: ((derive-key who algorithm secret-keybytes secret->public) password salt blocks iterations)

Generates a new key or keypair from a password using the Argon2i key derivation algorithm. The password may be either a string or a bytevector. The number of blocks defaults to 262144, i.e. 256 MiB. The number of iterations defaults to 8.

Message Digests

constant: hash-algorithm

The name of the cryptographic message digest algorithm.

procedure: (hash message)

Computes a cryptographic message digest of the given bytevector.

Pseudo-Random Streams

constant: random-stream-algorithm

The name of the pseudo-random number generator algorithm.

constant: random-stream-keybytes

constant: random-stream-noncebytes

Byte lengths of algorithm parameters.

procedure: (generate-random-stream-key)

procedure: (generate-random-stream-key port)

procedure: (derive-random-stream-key password salt)

procedure: (derive-random-stream-key password salt blocks iterations)

Specialized versions of the generate-key and derive-key procedures for random stream keys.

procedure: (open-random-stream k nonce)

procedure: (open-random-stream k nonce limit)

Open a binary input port backed by a pseudo-random number generator. The default limit, after which the port will signal end of file, is 1 GiB of random data, but #f or +inf.0 may be passed to deactivate the limit.

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

constant: symmetric-box-algorithm

The name of the symmetric box algorithm combination.

constant: symmetric-box-keybytes

constant: symmetric-box-noncebytes

Byte lengths of algorithm parameters.

procedure: (generate-symmetric-box-key)

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

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

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

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

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 binary input port, or #f; if not specified as a bytevector, a nonce of the right length is read from the input port, which defaults to (current-entropy-port).

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

constant: asymmetric-sign-algorithm

The name of the cryptographic signature algorithm combination.

constant: asymmetric-sign-publickeybytes

constant: asymmetric-sign-secretkeybytes

The key lengths of the cryptographic signature algorithm.

procedure: (generate-asymmetric-sign-key)

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

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

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

Specialized versions of the generate-key and derive-key procedures for asymmetric signature key pairs.

procedure: ((asymmetric-sign key) 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) 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

constant: asymmetric-box-algorithm

The name of the asymmetric box algorithm combination.

constant: asymmetric-box-publickeybytes

constant: asymmetric-box-secretkeybytes

constant: asymmetric-box-noncebytes

Byte lengths of algorithm parameters.

procedure: (generate-asymmetric-box-key)

procedure: (generate-asymmetric-box-key port)

procedure: (derive-asymmetric-box-key password salt)

procedure: (derive-asymmetric-box-key password salt blocks iterations)

Specialized versions of the generate-key and derive-key procedures for key agreement key pairs.

procedure: (exchange-random-stream-key public secret)

procedure: (exchange-symmetric-box-key public secret)

Derive a random stream key or symmetric box key through an asymmetric key agreement given the other party's public and our own secret key.

procedure: ((asymmetric-box public secret) message nonce)

procedure: ((asymmetric-box public secret) message additional nonce)

Derive a symmetric box key through an asymmetric key agreement given the other party's public and our own secret key, 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 public secret) envelope)

procedure: ((asymmetric-unbox public secret) envelope additional)

Derive a symmetric box key through an asymmetric key agreement given the other party's public and our own secret key, 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.