((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/tweetnacl" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.")) (section 2 "tweetnacl" (toc) (section 3 "Author" (p (int-link "/users/thomas chust" "Thomas Chust"))) (section 3 "Description" (p "This egg is a CHICKEN wrapper around " (link "http://tweetnacl.cr.yp.to/" "TweetNaCl") ". The C source code for TweetNaCl is included in the egg.")) (section 3 "Usage" (pre " (require-extension tweetnacl)") (section 4 "Asymmetric Algorithms" (def (sig (constant "asymmetric-box-primitive" (id asymmetric-box-primitive))) (p "A string that briefly describes the algorithm combination used to implement asymmetric cryptographic boxes.")) (def (sig (constant "asymmetric-box-publickeybytes" (id asymmetric-box-publickeybytes))) (p "The size of public keys for asymmetric cryptographic boxes in bytes.")) (def (sig (constant "asymmetric-box-secretkeybytes" (id asymmetric-box-secretkeybytes))) (p "The size of private keys for asymmetric cryptographic boxes in bytes.")) (def (sig (constant "asymmetric-box-noncebytes" (id asymmetric-box-noncebytes))) (p "The size of nonces for asymmetric cryptographic boxes in bytes.")) (def (sig (procedure "(make-asymmetric-box-keypair [entropy-port (current-entropy-port)])" (id make-asymmetric-box-keypair))) (p "Generate a new keypair for asymmetric boxing. Reads data from " (tt "entropy-port") ". Returns two blobs representing the new public and secret key.")) (def (sig (procedure "((asymmetric-box pk sk) m n)" (id asymmetric-box))) (p "Encrypt and authenticate a message " (tt "m") " from secret key " (tt "sk") " to public key " (tt "pk") " using nonce " (tt "n") " for algorithm randomization. The plaintext " (tt "m") " and the returned ciphertext are represented as strings, the nonce " (tt "n") " is represented as a " (tt "u8vector") ".")) (def (sig (procedure "((asymmetric-unbox pk sk) c n)" (id asymmetric-unbox))) (p "Decrypt and verify a message " (tt "c") " from the public key " (tt "pk") " to the secret key " (tt "sk") " using nonce " (tt "n") " for algorithm randomization. The ciphertext " (tt "c") " and the returned plaintext are represented as strings, the nonce " (tt "n") " is represented as a " (tt "u8vector") ". If the authenticity of the message cannot be verified the procedure returns " (tt "#f") " instead of a string.")) (def (sig (constant "asymmetric-sign-primitive" (id asymmetric-sign-primitive))) (p "A string that briefly describes the algorithm combination used to implement asymmetric cryptographic signatures.")) (def (sig (constant "asymmetric-sign-publickeybytes" (id asymmetric-sign-publickeybytes))) (p "The size of public keys for asymmetric cryptographic signatures in bytes.")) (def (sig (constant "asymmetric-sign-secretkeybytes" (id asymmetric-sign-secretkeybytes))) (p "The size of private keys for asymmetric cryptographic signatures in bytes.")) (def (sig (procedure "(make-asymmetric-sign-keypair [entropy-port (current-entropy-port)])" (id make-asymmetric-sign-keypair))) (p "Generate a new keypair for asymmetric signing. Reads data from " (tt "entropy-port") ". Returns two blobs representing the new public and secret key.")) (def (sig (procedure "((asymmetric-sign sk) m)" (id asymmetric-sign))) (p "Sign a message " (tt "m") " from secret key " (tt "sk") " to the general public. The plaintext " (tt "m") " and the returned signature message combination are represented as strings.")) (def (sig (procedure "((asymmetric-verify pk) sm)" (id asymmetric-verify))) (p "Decrypt and verify a message " (tt "sm") " from the public key " (tt "pk") " to the general public. The signature message combination " (tt "sm") " and the returned plaintext are represented as strings. If the authenticity of the message cannot be verified the procedure returns " (tt "#f") " instead of a string.")) (def (sig (constant "scalarmult-primitive" (id scalarmult-primitive))) (p "A string that briefly describes the scalar multiplication algorithm.")) (def (sig (constant "scalarmult-pointbytes" (id scalarmult-pointbytes))) (p "The size of field elements in bytes.")) (def (sig (constant "scalarmult-scalarbytes" (id scalarmult-scalarbytes))) (p "The size of scalar values in bytes.")) (def (sig (procedure "(scalarmult* n p)" (id scalarmult*))) (p "Multiplies the field element " (tt "p") " by the scalar " (tt "n") " and returns a new field element.") (p (b "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 " (i "does") " have inherent algebraic structure and " (i "must") " be passed through a hash function before it can be used safely as a cryptographic key."))) (section 4 "Symmetric Algorithms" (def (sig (constant "symmetric-box-primitive" (id symmetric-box-primitive))) (p "A string that briefly describes the algorithm combination used to implement symmetric cryptographic boxes.")) (def (sig (constant "symmetric-box-keybytes" (id symmetric-box-keybytes))) (p "The size of shared keys for symmetric cryptographic boxes in bytes.")) (def (sig (constant "symmetric-box-noncebytes" (id symmetric-box-noncebytes))) (p "The size of nonces for symmetric cryptographic boxes in bytes.")) (def (sig (procedure "(make-symmetric-box-key [entropy-port (current-entropy-port)])" (id make-symmetric-box-key))) (p "Generate a new key for symmetric boxing. Reads data from " (tt "entropy-port") ". Returns a blob representing the new shared key.")) (def (sig (procedure "(derive-symmetric-box-key pk sk)" (id derive-symmetric-box-key))) (p "Derive a new key for symmetric boxing from secret key " (tt "sk") " to public key " (tt "pk") ". The results of") (pre "(symmetric-box (derive-symmetric-box-key pk sk))") (p "and") (pre "(asymmetric-box pk sk)") (p "are equivalent. The same holds for the corresponding unbox calls.")) (def (sig (procedure "((symmetric-box k) m n)" (id symmetric-box))) (p "Encrypt and authenticate a message " (tt "m") " using the shared key " (tt "k") " and nonce " (tt "n") " for algorithm randomization. The plaintext " (tt "m") " and the returned ciphertext are represented as strings, the nonce " (tt "n") " is represented as a " (tt "u8vector") ".")) (def (sig (procedure "((symmetric-unbox k) c n)" (id symmetric-unbox))) (p "Decrypt and verify a message " (tt "c") " using the shared key " (tt "k") " and nonce " (tt "n") " for algorithm randomization. The ciphertext " (tt "c") " and the returned plaintext are represented as strings, the nonce " (tt "n") " is represented as a " (tt "u8vector") ". If the authenticity of the message cannot be verified the procedure returns " (tt "#f") " instead of a string.")) (def (sig (constant "symmetric-sign-primitive" (id symmetric-sign-primitive))) (p "A string that briefly describes the algorithm combination used to implement symmetric cryptographic one-time signatures.")) (def (sig (constant "symmetric-sign-keybytes" (id symmetric-sign-keybytes))) (p "The size of shared keys for symmetric cryptographic one-time signatures in bytes.")) (def (sig (procedure "(make-symmetric-sign-key [entropy-port (current-entropy-port)])" (id make-symmetric-sign-key))) (p "Generate a new key for symmetric signing. Reads data from " (tt "entropy-port") ". Returns a blob representing the new shared key.")) (def (sig (procedure "((symmetric-sign k) m #!key tag-only?)" (id symmetric-sign))) (p "Sign a message " (tt "m") " using the shared key " (tt "k") ". The plaintext " (tt "m") " and the returned signature message combination are represented as strings. If " (tt "tag-only?") " is given and not " (tt "#f") ", the procedure returns only the message authentication tag as a string rather than a combination of authentication tag and message.")) (def (sig (procedure "((symmetric-verify k) sm #!optional m)" (id symmetric-verify))) (p "Decrypt and verify a message " (tt "sm") " using the shared key " (tt "k") ". The signature message combination " (tt "sm") " and the returned plaintext are represented as strings. If the authenticity of the message cannot be verified the procedure returns " (tt "#f") " instead of a string. If " (tt "m") " is given and not " (tt "#f") " it must be a string containing the plaintext of the message and " (tt "sm") " is expected to only contain the message authentication tag in that case."))) (section 4 "Pseudo-Random Streams" (def (sig (constant "random-stream-primitive" (id random-stream-primitive))) (p "A string that briefly describes the algorithm combination used to implement pseudo-random streams.")) (def (sig (constant "random-stream-keybytes" (id random-stream-keybytes))) (p "The size of shared keys for pseudo-random streams in bytes.")) (def (sig (constant "random-stream-noncebytes" (id random-stream-noncebytes))) (p "The size of nonces for pseudo-random streams in bytes.")) (def (sig (procedure "(make-random-stream-key [entropy-port (current-entropy-port)])" (id make-random-stream-key))) (p "Generate a new key for pseudo-random streams. Reads data from " (tt "entropy-port") ". Returns a blob representing the new shared key.")) (def (sig (procedure "(derive-random-stream-key pk sk)" (id derive-random-stream-key))) (p "Derive a new key for pseudo-random streams from secret key " (tt "sk") " to public key " (tt "pk") ".")) (def (sig (procedure "(open-random-stream k n #!optional [limit (expt 2 30)])" (id open-random-stream))) (p "Open a stream of pseudo-random bytes using the shared key " (tt "k") " and nonce " (tt "n") " for algorithm randomization. The stream ends after " (tt "limit") " bytes, unless " (tt "limit") " is " (tt "#f") " or infinity.")) (def (sig (procedure "(stream-xor! buffer #!optional [stream (current-input-port)])" (id stream-xor!))) (p "Destructively xors the contents of the string " (tt "buffer") " with bytes read from " (tt "stream") ". Returns " (tt "buffer") ".")) (def (sig (procedure "(stream-xor buffer #!optional [stream (current-input-port)])" (id stream-xor))) (p "Xors the contents of the string " (tt "buffer") " with bytes read from " (tt "stream") ". Returns a new string holding the result."))) (section 4 "Miscellaneous" (def (sig (constant "hash-primitive" (id hash-primitive))) (p "A string that briefly describes the message digest algorithm.")) (def (sig (constant "hash-bytes" (id hash-bytes))) (p "The size of message digests in bytes.")) (def (sig (procedure "(hash m)" (id hash))) (p "Hashes the string " (tt "m") " into a message digest. Returns the binary digest as a string.")) (def (sig (parameter "current-entropy-port" (id current-entropy-port))) (p "An input port connected to an entropy source for key generation.") (p "When compiled on a unix system, this parameter is by default bound to the result of " (tt "(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 " (link "https://msdn.microsoft.com/en-us/library/aa387694.aspx" "RtlGenRandom") ". On other systems the default value of the parameter will be " (tt "#f") " and you will have to set it explicitly before key generation functions can be used.") (p "To speed up key generation it can be useful to set " (tt "current-entropy-port") " to a pseudo-random stream only seeded initially from the system entropy source:") (pre " (current-entropy-port (open-random-stream (make-random-stream-key) (make-u8vector random-stream-noncebytes 0)))"))))))