API

Number of bytes in a generic, simple hash.

Maximum number of bytes allowed when creating a keyed hash.

Minimum number of bytes allowed when creating a keyed hash.

Number of bytes required in context buffer for hashing.

(hash/final state len)

Get the final hash after digesting all of the input as a string. The resulting hash will be a string of length len.

(hash/hash size input ctx &opt key)

Hash some input bytes into an output string of length size. Optionally provide a key that can be used to generate different hashes on the same input.

Number of bytes in a key required for hashing.

(hash/keygen &opt buf)

Generate a key suitable for use in hashing. The key is a buffer of at least 32 bytes. If a buffer buf is provided, the first 32 bytes of buf will be set to a new random key. Returns a key buffer.

(hash/new-state ctx key)

Create a new hash-state. Takes a context ctx and a key and returns a new abstract type, jhydro/hash-state. Both ctx and key should be byte sequences, of at least lengths 8 and 32 respectively. Returns the new state.

(hash/update state bytes)

Add more bytes to the hash state. Returns the modified state

Maximum number of bytes allowed in kdf generated key.

Minimum number of bytes allowed in kdf generated key.

Number of bytes in context argument to jhydro/kdf functions.

(kdf/derive-from-key sublen subid ctx key)

Generate a subkey from a master key. Takes a subid, which is a positive integer that represents the key id, and ctx, which is an 8 byte string that is usually an application constant. Finally, the last parameter is the master key. Returns a string of length sublen.

Number of bytes in a kdf key.

(kdf/keygen &opt buf)

Generate a key for use in KDFs. Returns the modified buf if provided, or a new random buffer.

(kx/keygen)

Generate a keypair for use key exchanges. Contains both a public key and a secret key. Returns a struct with two entries, and :secret-key and a :public-key.

Number of bytes in the first packet sent in the KK variant key exchange.

Number of bytes in the second packet sent in the KK variant key exchange.

(kx/kk1 packet-1 static-pk pk sk)

Generate the first packet for the KK variant key exchange. Returns a jhydro/ks-state abstract which contains some useful state for the key exchange. static-pk is the peer's public key, and pk and sk are the client's public and secret keys. Modifies the buffer packet-1 by appending new data.

(kx/kk2 packet-2 packet-1 static-pk pk sk)

Generate the second packet and a session keypair in the KK variant key exchange. packet-2 is a buffer to put the new packet in. packet-1 is the packet received from the peer. static-pk is the other peer's public key, and pk and sk are the local client's public and secret keys. Returns a session keypair, which is a struct of two entries, :rx and :tx.

(kx/kk3 state packet-2 pk sk)

Generate a session key on the initiating peer in the KK variant key exchange. state is the jhydro/kx-state from step 1, packet-2 is the packet from step 2, and pk and sk are the local client's public and secret keys. Returns a session keypair, which is a struct of two entries, :rx and :tx.

Number of bytes in the first packet sent in the N variant key exchange.

(kx/n1 packet-buf psk peer-pk)

Create a session key and generate a packet on the client as the first step in the N variant key exchange. Also take a pre-shared key, and the peer's public key. Returns a session key as a struct of two entries, :tx and :rx, which are the transmit and receive keys for communicating with the peer.

(kx/n2 packet1 psk pk sk)

Create a session key as the second step in the N variant key exchange on the server. packet1 is what kx/n1 put into a buffer (packet-buf), psk is a pre-shared key, pk is the server's public key, and sk is the server's secret key. Returns a session keypair that is a mirror of what is on the client, but :tx and :rx are swapped.

Number of bytes in a pre-shared key for key exchange.

Number of bytes in a public key intended for key exchange.

Number of bytes in a secret key intended for key exchange.

Number of bytes in a session key (tx or rx key). These keys are used to encrypt and decrypt messages between two peers.

Number of bytes in the first packet sent in the XX variant key exchange.

Number of bytes in the second packet sent in the XX variant key exchange.

Number of bytes in the third packet sent in the XX variant key exchange.

(kx/xx1 packet-1 psk)

First step in XX variant key exchange. Takes in a packet buffer and pre-shared key, and generates the first packet. Also returns a jhydro/kx-state for use in future steps.

(kx/xx2 packet-2 packet-1 psk pk sk)

Second step in XX variant key exchange. Takes a buffer for writing packet number 2 too, packet 1, a pre-shared key, and the local public key and secret key. Writes the second packet to packet-2, and returns a jhydro/kx-state.

(kx/xx3 state packet-3 packet-2 psk pk sk &opt peer-pk)

Third step in XX variant key exchange. Takes the state returned from kx/xx1, a buffer packet-3 to write the final packet into, the packet packet-2 send from the other peer, a pre-shared key psk, and the public and secret keys of the local machine. Optionally takes a buffer to write the remote peer's public key into, so you can reject connections if they do not match the expected public key. Returns a session keypair, which is a struct with two entries, :rx and :tx.

(kx/xx4 state packet-3 psk &opt peer-pk)

Fourth and final step in the XX key exchange variant. Takes the state returned from kx/xx2, the packet received from kx/xx3, and a pre-shared key psk. Optionally takes a buffer peer-pk, which will have the remote peer's public key written appended to it. Returns a session keypair, which contains :tx and :rx entires.

(pwhash/create passwd masterkey &opt opslimit memlimit threads)

Hash a password and get a blob that can be safely stored in a database. The returned result is a 128 byte string. Can take optional parameters to tune the difficulty of the hash.

(pwhash/derive-static-key keylen stored passwd ctx master-key &opt opslimit memlimit threads)

Derive a static key for used in cryptographic applications from a hashed password and other entropy (kept in stored). Returns a string with keylen bytes.

(pwhash/deterministic hlen passwd ctx master-key &opt opslimit memlimit threads)

Hash a password to produce a high entropy key. The returned hashed password is a string of length hlen.

(pwhash/keygen &opt buf)

Generate a master key for use in hashing passwords. The master key is used to encrypt all hashed passwords for an extra level of security. Returns a buffer with the new key.

(pwhash/reencrypt stored masterkey new-masterkey)

Re-encrypt a hashed password under a new master key without needing the original password, only the previously hashed password and master key. Returns the new hashed password as a string.

(pwhash/upgrade stored masterkey &opt opslimit memlimit threads)

Change the encryption parameters of a key to make decrypting faster or slower. This can be used to scale difficulty of password hashing in the event of hardware advancements. Returns the new password hash as a string.

(pwhash/verify stored passwd master-key &opt opslimit memlimit threads)

Check if a password matches a stored password hash. Hashing options must be the same as the ones used to created the stored hash.

(random/buf buf &opt size)

Fill a buffer with random bytes. If size is not provided, will clear and fill the given buffer. If size is provided, will append size random bytes to the buffer. Alternatively, you can provide just the size argument, and a new randomized buffer will be returned.

(random/buf-deterministic buf len seed)

Generate len random bytes and push them into a buffer buf. seed is a byte sequence of at least 32 bytes that initializes the state of the RNG. Returns the modified buffer.

(random/ratchet)

Increment the internal state of the RNG.

(random/reseed)

Provide a new random seed for the internal RNG.

Number of bytes in a seed for the RNG.

(random/u32)

Generate a psuedo random 32 bit unsigned integer

(random/uniform top)

Generate a random 32 bit unsigned integer less than top.

Number of bytes in a context for secretbox functions.

(secretbox/decrypt cipher-text msg-id ctx key &opt buf)

Decrypt a cipher text that was produced with secretbox/encrypt. msg-id, ctx, and key must be the same as those used to encrypt the message. An optional buffer can be used to contain the plain text, otherwise a new buffer is created. Returns a buffer containing the plain text.

(secretbox/encrypt msg msg-id ctx key &opt buf)

Encrypt a message with a secretbox key and return the cipher text in a buffer. Also requires a message id, which is an integer, and a ctx, which is a non-secret byte-sequence. Lastly, requires a secret symmetric key for encryption. An optional buffer will prevent Janet from creating a new buffer, and instead append to and return the provided buffer.

Number of bytes in the header of an encrypted message.

Number of bytes in a secretbox key.

(secretbox/keygen)

Generate a key suitable for secretbox. The returned key is a 32 byte buffer.

Number of bytes in a secretbox probe.

(secretbox/probe-create cipher-text ctx key)

Create a probe for some cipher text created by secretbox/encrypt. The resulting probe is a constant length string that can be used to verify if cipher text is valid before decrypting the entire text. Returns a string.

(secretbox/probe-verify probe cipher-text ctx key)

Use a probe produced by secretbox/probe-create to check if some cipher text is genuine. If the cipher text is not forged or tampered with, returns true, otherwise false. Genuine cipher text can then be decrypted. Returns a boolean.

Number of bytes in a signature.

Number of bytes needed for a signature context.

(sign/create msg ctx sk)

Create a new sigature from a message, ctx, and secret key. The message can be any byte sequence, the context ctx should be a byte sequence of at least 8 bytes, and the secret key sk should be secret key as generated from sign/keygen or sign/keygen-deterministic. Returns a signature, which is a 64 byte string.

(sign/final-create state sk)

Create a signature from the sign-state. Takes a jhydro/sign-state state and a secret key sk. Returns the signature and also modifies the state.

(sign/final-verify state csig pk)

Verify a signature with a public key. Given a sign-state state, signature csig, and public key pk, return true if csig is valid, otherwise false.

(sign/keygen)

Create a random key pair for public key signing. Returns a struct containing a :public-key and a :secret-key as strings.

(sign/keygen-deterministic seed)

Create a key pair from a seed. Seed should be a byte sequence of at least 32 bytes; random/buf should work well. Returns a struct of two key value pairs, a :secret-key and a :public-key. Each key is a string.

(sign/new-state ctx)

Create a new state machine for generating a signature. A state machine allows processing a message in chunks to generate a signature. A string ctx of at least 8 bytes is also required, and can be a hard coded string. Returns a new jhydro/sign-state.

Number of bytes in a public key for making signatures.

Number of bytes in a secret key for making signatures.

Number of bytes in a seed for generating a key.

(sign/update state msg)

Process a message chunk for generating a signature. Returns the modified signature state.

(sign/verify csig msg ctx pk)

Check a signature to determine if a message is authentic. csig is the signature as generated by sign/create or sign/final-create, msg is the message that we are checking, ctx is the context string, and pk is the public key. Returns a boolean, true if the signature is valid, false otherwise.

(util/++ buffer)

Increment a buffer, treating it as a little endian large integer. If the increment results in an overflow, sets the buffer to all zero bytes. Returns the modified buffer.

(util/= lhs rhs)

Compare the contents of two equal length buffers without early returns, which helps prevent side channel attacks. This is the function that should be used for comparing two buffers with cryptographic content. If the two buffers are of different lengths, returns early. Returns a boolen.

(util/bin2hex bin &opt hex)

Convert binary data into hexidecimal. The hex representation of bin, the input buffer, is converted to a ascii hexidecimal and put in the buffer hex, or a new buffer if hex is not supplied. Returns hex or a new buffer.

(util/compare lhs rhs)

Compare two buffers without early returns to help prevent side channel attacks. Returns an integer -1, 0, or 1.

(util/hex2bin hex &opt bin ignore)

Convert a hexidecimal string to binary data. Can provide an optional bin to write into instead of creating a new buffer, and also a string of characters to ignore while reading hex. Returns the buffer bin or a new buffer.

(util/memzero buffer)

Clear memory in a buffer to 0, not changing the size of the buffer. Returns the modified buffer.

(util/pad buffer blocksize)

Pad a buffer according to the ISO/IEC 7816-4 algorithm. Returns the modified buffer.

(util/unpad buffer blocksize)

Unpad a buffer padded via util/pad. Returns the modifed buffer.