# Monocypher Bindings

## Synopsis

`(import (crypto monocypher))`

Bindings to the Monocypher library of cryptographic operations.

## Utility Functions

### procedure: `(bytevector-wipe! `*bytevector*)

*bytevector*)

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

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

*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*)

*any*)

### procedure: `(make-key `*algorithm* *public* *secret*)

*algorithm*

*public*

*secret*)

### procedure: `(key-algorithm `*key*)

*key*)

### procedure: `(public-key `*key*)

*key*)

### procedure: `(secret-key `*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*)

*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*)

*key*)

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

### procedure: `(check-key `*who* *algorithm* *any*)

*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*))

*who*

*algorithm*

*secret-keybytes*

*secret->public*))

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

*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*)

*who*

*algorithm*

*secret-keybytes*

*secret->public*)

*password*

*salt*)

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

*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.

## Envelopes

### record: `envelope`

### procedure: `(envelope? `*any*)

*any*)

### procedure: `(make-envelope `*algorithm* *message* *signature*)

*algorithm*

*message*

*signature*)

### procedure: `(envelope-algorithm `*envelope*)

*envelope*)

### procedure: `(envelope-message `*envelope*)

*envelope*)

### procedure: `(envelope-signature `*envelope*)

*envelope*)

Encrypted and authenticated messages are represented by record instances that hold an algorithm name, a message bytevector and a signature bytevector.

### procedure: `(valid-envelope? `*algorithm* *signature-bytes* *any*)

*algorithm*

*signature-bytes*

*any*)

Checks whether the given value is an envelope with the given algorithm name and a signature bytevector of the given length.

## Message Digests

### constant: `hash-algorithm`

The name of the cryptographic message digest algorithm.

### procedure: `(hash `*message*)

*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*)

*port*)

### procedure: `(derive-random-stream-key `*password* *salt*)

*password*

*salt*)

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

*password*

*salt*

*blocks*

*iterations*)

Specialized versions of the `generate-key`

and `derive-key`

procedures for random stream keys.

### procedure: `(open-random-stream `*k* *nonce*)

*k*

*nonce*)

### procedure: `(open-random-stream `*k* *nonce* *limit*)

*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*)

*port*)

### procedure: `(derive-symmetric-sign-key `*password* *salt*)

*password*

*salt*)

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

*password*

*salt*

*blocks*

*iterations*)

Specialized versions of the `generate-key`

and `derive-key`

procedures for symmetric signature keys.

### procedure: `((symmetric-sign `*key*) *message*)

*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*)

*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*)

*port*)

### procedure: `(derive-symmetric-box-key `*password* *salt*)

*password*

*salt*)

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

*password*

*salt*

*blocks*

*iterations*)

Specialized versions of the `generate-key`

and `derive-key`

procedures for symmetric box keys.

### procedure: `((symmetric-box `*key*) *message* *nonce*)

*key*)

*message*

*nonce*)

### procedure: `((symmetric-box `*key*) *message* *additional* *nonce*)

*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.

### procedure: `((symmetric-unbox `*key*) *envelope* *nonce*)

*key*)

*envelope*

*nonce*)

### procedure: `((symmetric-unbox `*key*) *envelope* *additional* *nonce*)

*key*)

*envelope*

*additional*

*nonce*)

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*)

*port*)

### procedure: `(derive-asymmetric-sign-key `*password* *salt*)

*password*

*salt*)

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

*password*

*salt*

*blocks*

*iterations*)

Specialized versions of the `generate-key`

and `derive-key`

procedures for asymmetric signature key pairs.

### procedure: `((asymmetric-sign `*key*) *message*)

*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*)

*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*)

*port*)

### procedure: `(derive-asymmetric-box-key `*password* *salt*)

*password*

*salt*)

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

*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*)

*public*

*secret*)

### procedure: `(exchange-symmetric-box-key `*public* *secret*)

*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*)

*public*

*secret*)

*message*

*nonce*)

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

*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* *nonce*)

*public*

*secret*)

*envelope*

*nonce*)

### procedure: `((asymmetric-unbox `*public* *secret*) *envelope* *additional* *nonce*)

*public*

*secret*)

*envelope*

*additional*

*nonce*)

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.