## tweetnacl

### Author

### Description

This egg is a CHICKEN wrapper around TweetNaCl. The C source code for TweetNaCl is included in the egg.

### Usage

(require-extension tweetnacl)

#### Asymmetric Algorithms

*[constant]*

`asymmetric-box-primitive`

A string that briefly describes the algorithm combination used to implement asymmetric cryptographic boxes.

*[constant]*

`asymmetric-box-publickeybytes`

The size of public keys for asymmetric cryptographic boxes in bytes.

*[constant]*

`asymmetric-box-secretkeybytes`

The size of private keys for asymmetric cryptographic boxes in bytes.

*[constant]*

`asymmetric-box-noncebytes`

The size of nonces for asymmetric cryptographic boxes in bytes.

*[procedure]*

`(make-asymmetric-box-keypair [entropy-port (current-entropy-port)])`

Generate a new keypair for asymmetric boxing. Reads data from `entropy-port`. Returns two blobs representing the new public and secret key.

*[procedure]*

`((asymmetric-box pk sk) m n)`

Encrypt and authenticate a message `m` from secret key `sk` to public key `pk` using nonce `n` for algorithm randomization. The plaintext `m` and the returned ciphertext are represented as strings, the nonce `n` is represented as a `u8vector`.

*[procedure]*

`((asymmetric-unbox pk sk) c n)`

Decrypt and verify a message `c` from the public key `pk` to the secret key `sk` using nonce `n` for algorithm randomization. The ciphertext `c` and the returned plaintext are represented as strings, the nonce `n` is represented as a `u8vector`. If the authenticity of the message cannot be verified the procedure returns `#f` instead of a string.

*[constant]*

`asymmetric-sign-primitive`

A string that briefly describes the algorithm combination used to implement asymmetric cryptographic signatures.

*[constant]*

`asymmetric-sign-publickeybytes`

The size of public keys for asymmetric cryptographic signatures in bytes.

*[constant]*

`asymmetric-sign-secretkeybytes`

The size of private keys for asymmetric cryptographic signatures in bytes.

*[procedure]*

`(make-asymmetric-sign-keypair [entropy-port (current-entropy-port)])`

Generate a new keypair for asymmetric signing. Reads data from `entropy-port`. Returns two blobs representing the new public and secret key.

*[procedure]*

`((asymmetric-sign sk) m)`

Sign a message `m` from secret key `sk` to the general public. The plaintext `m` and the returned signature message combination are represented as strings.

*[procedure]*

`((asymmetric-verify pk) sm)`

Decrypt and verify a message `sm` from the public key `pk` to the general public. The signature message combination `sm` and the returned plaintext are represented as strings. If the authenticity of the message cannot be verified the procedure returns `#f` instead of a string.

*[constant]*

`scalarmult-primitive`

A string that briefly describes the scalar multiplication algorithm.

*[constant]*

`scalarmult-pointbytes`

The size of field elements in bytes.

*[constant]*

`scalarmult-scalarbytes`

The size of scalar values in bytes.

*[procedure]*

`(scalarmult* n p)`

Multiplies the field element `p` by the scalar `n` and returns a new field element.

**Warning:** This is a low-level primitive that should be used with care. Key agreement schemes can be implemented using this function, but the result *does* have inherent algebraic structure and *must* be passed through a hash function before it can be used safely as a cryptographic key.

#### Symmetric Algorithms

*[constant]*

`symmetric-box-primitive`

A string that briefly describes the algorithm combination used to implement symmetric cryptographic boxes.

*[constant]*

`symmetric-box-keybytes`

The size of shared keys for symmetric cryptographic boxes in bytes.

*[constant]*

`symmetric-box-noncebytes`

The size of nonces for symmetric cryptographic boxes in bytes.

*[procedure]*

`(make-symmetric-box-key [entropy-port (current-entropy-port)])`

Generate a new key for symmetric boxing. Reads data from `entropy-port`. Returns a blob representing the new shared key.

*[procedure]*

`(derive-symmetric-box-key pk sk)`

Derive a new key for symmetric boxing from secret key `sk` to public key `pk`. The results of

(symmetric-box (derive-symmetric-box-key pk sk))

and

(asymmetric-box pk sk)

are equivalent. The same holds for the corresponding unbox calls.

*[procedure]*

`((symmetric-box k) m n)`

Encrypt and authenticate a message `m` using the shared key `k` and nonce `n` for algorithm randomization. The plaintext `m` and the returned ciphertext are represented as strings, the nonce `n` is represented as a `u8vector`.

*[procedure]*

`((symmetric-unbox k) c n)`

Decrypt and verify a message `c` using the shared key `k` and nonce `n` for algorithm randomization. The ciphertext `c` and the returned plaintext are represented as strings, the nonce `n` is represented as a `u8vector`. If the authenticity of the message cannot be verified the procedure returns `#f` instead of a string.

*[constant]*

`symmetric-sign-primitive`

A string that briefly describes the algorithm combination used to implement symmetric cryptographic one-time signatures.

*[constant]*

`symmetric-sign-keybytes`

The size of shared keys for symmetric cryptographic one-time signatures in bytes.

*[procedure]*

`(make-symmetric-sign-key [entropy-port (current-entropy-port)])`

Generate a new key for symmetric signing. Reads data from `entropy-port`. Returns a blob representing the new shared key.

*[procedure]*

`((symmetric-sign k) m #!key tag-only?)`

Sign a message `m` using the shared key `k`. The plaintext `m` and the returned signature message combination are represented as strings. If `tag-only?` is given and not `#f`, the procedure returns only the message authentication tag as a string rather than a combination of authentication tag and message.

*[procedure]*

`((symmetric-verify k) sm #!optional m)`

Decrypt and verify a message `sm` using the shared key `k`. The signature message combination `sm` and the returned plaintext are represented as strings. If the authenticity of the message cannot be verified the procedure returns `#f` instead of a string. If `m` is given and not `#f` it must be a string containing the plaintext of the message and `sm` is expected to only contain the message authentication tag in that case.

#### Pseudo-Random Streams

*[constant]*

`random-stream-primitive`

A string that briefly describes the algorithm combination used to implement pseudo-random streams.

*[constant]*

`random-stream-keybytes`

The size of shared keys for pseudo-random streams in bytes.

*[constant]*

`random-stream-noncebytes`

The size of nonces for pseudo-random streams in bytes.

*[procedure]*

`(make-random-stream-key [entropy-port (current-entropy-port)])`

Generate a new key for pseudo-random streams. Reads data from `entropy-port`. Returns a blob representing the new shared key.

*[procedure]*

`(derive-random-stream-key pk sk)`

Derive a new key for pseudo-random streams from secret key `sk` to public key `pk`.

*[procedure]*

`(open-random-stream k n #!optional [limit (expt 2 30)])`

Open a stream of pseudo-random bytes using the shared key `k` and nonce `n` for algorithm randomization. The stream ends after `limit` bytes, unless `limit` is `#f` or infinity.

*[procedure]*

`(stream-xor! buffer #!optional [stream (current-input-port)])`

Destructively xors the contents of the string `buffer` with bytes read from `stream`. Returns `buffer`.

*[procedure]*

`(stream-xor buffer #!optional [stream (current-input-port)])`

Xors the contents of the string `buffer` with bytes read from `stream`. Returns a new string holding the result.

#### Miscellaneous

*[constant]*

`hash-primitive`

A string that briefly describes the message digest algorithm.

*[constant]*

`hash-bytes`

The size of message digests in bytes.

*[procedure]*

`(hash m)`

Hashes the string `m` into a message digest. Returns the binary digest as a string.

*[parameter]*

`current-entropy-port`

An input port connected to an entropy source for key generation.

When compiled on a unix system, this parameter is by default bound to the result of `(open-input-file "/dev/random")`. When compiled on a windows system, the default value of the parameter is a custom input port that returns bytes produced by RtlGenRandom. On other systems the default value of the parameter will be `#f` and you will have to set it explicitly before key generation functions can be used.

To speed up key generation it can be useful to set `current-entropy-port` to a pseudo-random stream only seeded initially from the system entropy source:

(current-entropy-port (open-random-stream (make-random-stream-key) (make-u8vector random-stream-noncebytes 0)))