API

(bcrypt password rng &opt work-factor)

Provided the password and an RNG object, returns a bcrypt string.

(bcrypt-is-valid password bcrypt)

Check a bcrypt hash against the provided password, returning true if the password matches.

(block-cipher/block-size bc-obj)

Return the block size of this cipher.

(block-cipher/clear bc-obj)

Clear the internal state (such as keys) of this cipher object, but do not deallocate it. Returns `bc-obj`.

(block-cipher/decrypt bc-obj input)

Decrypt `input` data. The key must have been set beforehand. Returns decrypted data in buffer format.

(block-cipher/encrypt bc-obj input)

Encrypt `input` data. The key must have been set beforehand. Returns encrypted data in buffer format.

(block-cipher/get-keyspec mac)

Return the key spec of this cipher in format of [max-key-length min-key-length mod-key-length].

(block-cipher/name bc-obj)

Return the name of this block cipher algorithm, which may nor may not exactly match what was passed to `block-cipher/init`.

(block-cipher/new name)

Create a new cipher mode object, `name` should be for example "AES-128" or "Threefish-512". Returns `bc-obj`.

(block-cipher/set-key bc-obj key)

Set the cipher key, which is required before encrypting or decrypting. Returns `bc-obj`.

(cipher/clear cipher-obj)

Reset the state of `cipher` back to clean, as if no key and input has been supplied. Returns `cipher-obj`.

(cipher/finish cipher-obj input)

Finish processing (with an optional final `input`). May throw if message authentication checks fail, in which case all plaintext previously processed must be discarded. You may call `cipher/finish` with the entire message.

(cipher/get-default-nonce-length cipher-obj)

Returns default nonce length.

(cipher/get-keyspec cipher-obj)

Return the key spec of this `cipher` in format of `[max-key-length min-key-length mod-key-length]`.

(cipher/get-tag-length cipher-obj)

Returns the tag length (0 for unauthenticated modes).

(cipher/get-update-granularity cipher-obj)

Return the update granularity of the cipher. `cipher/update` must be called with blocks of this size, except for the final.

(cipher/is-authenticated cipher-obj)

Returns true if this is an AEAD mode.

(cipher/name cipher-obj)

Returns the name of this algorithm.

(cipher/new name type)

Creates an cipher object of the given name, e.g., "AES-256/GCM".Create an encryption cipher if `:encrypt` type is given, create decryption cipher if `:decrypt` type is supplied.

(cipher/set-associated-data cipher-obj ad)

Sets the associated data and returns `cipher-obj`. Fails if this is not an AEAD mode.

(cipher/set-key cipher-obj key)

Set the symmetric key to be used. Returns `cipher-obj`.

(cipher/start cipher-obj nonce)

Start processing a message using `nonce`. Returns `cipher-obj`.

(cipher/update cipher-obj input)

Consumes `input` text and returns output. Input text must be of `cipher/get-update-granularity` length. Alternately, always call finish with the entire message, avoiding calls to update entirely.

(cipher/valid-nonce-length cipher-obj nonce-len)

Returns true if `nonce-len` is a valid nonce len for this mode.

(constant-time-compare x y)

Check if buffer `x` equals buffer `y`. Returns a boolean.

(ffi-api-version)

Return the version of the currently supported FFI API.

(ffi-supports-api version)

Check if the FFI version specified is supported by this library. Returns a boolean.

(fpe/decrypt fpe-obj tweak)

Decrypt value under the FPE scheme using provided tweak. Returns an MPI object.

(fpe/encrypt fpe-obj tweak)

Encrypt value under the FPE scheme using provided tweak. Returns an MPI object.

(fpe/new modulus key &opt round compat-mode)

Create a new FPE instance, FE1 scheme Rounds should be 16 or higher for best security. If omitted, default value for `round` is 5, `compact-mode` is false. Returns `fpe-obj`.

(hash/clear hash-obj)

Reset the state of `hash` back to clean, as if no input has been supplied. Returns `hash-obj`.

(hash/copy hash-obj)

Return a new hash object copied from `hash`. Returns new `hash-obj`.

(hash/final hash-obj)

Finalize the hash and return the output.

(hash/name hash)

Return the name of the hash function.

(hash/new name)

Creates a hash of the given name, e.g., "SHA-384". Returns `hash-obj`.

(hash/output-length hash-obj)

Return the output length of the `hash-obj`.

(hash/update hash-boj input)

Add input to the hash computation. Returns `hash-obj`.

(hex-decode str)

Performs hex decoding of string data in `str`. Returns the string.

(hex-encode bin)

Performs hex encoding of binary data in `bin`. Returns the string.

(hotp/check hotp-obj code counter &opt resync-range)

Check if provided `code` is the correct code for `counter`. If omitted, the default value for `resync-range` is 0. If `resync-range` is greater than zero, HOTP also checks up to `resync-range` following `counter` values.
Returns a tuple of (boolean number) where the boolean indicates if the code was valid, and the number indicates the next counter value that should be used. If the `code` did not verify, the next counter value is always identical to the counter that was passed in. If the `code` did verify and `resync-range` was zero, then the next counter will always be counter+1.

(hotp/generate hotp-obj counter)

Generate an HOTP code for the provided `counter`.

(hotp/new key &opt hash digits)

Instantiate a new HOTP instance with the given parameters. If omitted, the default value for `hash` is "SHA-1" and the default value for `digits` is 6. Returns `htop-obj`.

(kdf algo out-len secret salt &opt label)

Performs a key derviation function (such as “HKDF(SHA-384)”) over the provided secret, salt and label values. Returns a value of the specified length.

(mac/clear mac-obj)

Reset the state of `mac` back to clean, as if no key and input has been supplied. Returns `mac-obj`.

(mac/final mac-obj)

Finalize the MAC and return the output.

(mac/get-keyspec mac-obj)

Return the key spec of the `mac` in format of [max-key-length min-key-length mod-key-length].

(mac/new name)

Creates a MAC of the given name, e.g., "HMAC(SHA-384)".Returns `mac-obj`.

(mac/output-length mac-obj)

Return the output length of the `mac`

(mac/set-key mac-obj key)

Set the `key` for the MAC calculation. Returns `mac-obj`.

(mac/set-nonce mac-obj key)

Set the `nonce` for the MAC calculation. Returns `mac-obj`.Note that not all MAC algorithms require a nonce. If a nonce is required, the function has to be called before the data is processed.

(mac/update mac-obj input)

Add input to the MAC computation. Returns `mac-obj`.

(mpi/add mpi-obj x)

Add x to `mpi-obj` and return the new `mpi-obj`. `x` can be either `mpi-obj` or u32 number.

(mpi/clear-bit mpi-obj bit)

Clears the specified `bit` of `mpi-obj`. Returns `mpi-obj`.

(mpi/div mpi-obj-1 mpi-obj-2)

Divide `mpi-obj-1` by `mpi-obj-2`. Create new quotient `mpi-obj` and remainder `mpi-obj`. Return quotient `mpi-obj` and remainder `mpi-obj` in tuple.

(mpi/flip-sign mpi-obj)

Flip the sign of `mpi-obj`. Returns `mpi-obj`.

(mpi/from-hex-str value)

Create an MPI object with a hex string `value`. Returns `mpi-obj`.

(mpi/from-int value)

Create an MPI object with an integer `value`. Returns `mpi-obj`.

(mpi/from-mpi mpi-obj)

Create an MPI object with an MPI object `mpi`. Returns new `mpi-obj`.

(mpi/from-rng rng bits)

Create a `bits` size random MPI object with `rng`. Returns `mpi-obj`.

(mpi/from-str value)

Create an MPI object with an integer string `value`. Returns `mpi-obj`.

(mpi/gcd mpi-obj other-mpi-obj)

Create new `mpi-obj` of the greatest common divisor of `mpi-obj` and `other-mpi-obj`.

(mpi/get-bit mpi-obj bit)

Returns 0 if the specified `bit` of `mpi-obj` is not set, 1 if it is set.

(mpi/inverse-mod mpi-obj modulus)

Create the inverse of `mpi-obj` modulo `modulus`, or nil if no inverse exists.Returns new `mpi-obj`.

(mpi/is-negative mpi-obj)

Return true if `mpi-obj` is less than zero, otherwise return false.

(mpi/is-positive mpi-obj)

Return true if `mpi-obj` is greater than or equal to zero. otherwise return false.

(mpi/is-prime mpi-obj rng &opt prob)

Return true if `mpi-obj` is prime, otherwise returns false. Default value of prob is 128.

(mpi/is-zero mpi-obj)

Return true if `mpi-obj` is zero, otherwise returns false.

(mpi/lshift mpi-obj shift)

Left shift by specified `shift` bit count. Return new `mpj-obj`.

(mpi/mod-mul mpi-obj other-mpi-obj modulus)

Create new `mpi-obj` of the multiplication product of `mpi-obj` and `other-mpi-obj` modulo `modulus`. Returns new `mpi-obj`.

(mpi/sub mpi-obj-1 mpi-obj-2)

Multiply two `mpi-obj` and return the new `mpi-obj` as a result.

(mpi/new)

Create a new zero-valued MPI. Returns `mpi-obj`.

(mpi/num-bytes mpi-obj)

Return the number of significant bytes in the `mpi-obj`.

(mpi/pow-mod mpi-obj exponent modulus)

Create new `mpi-obj` to the `exponent` `mpi-obj` power modulo `modulus` `mpi-obj`.Returns new `mpi-obj`.

(mpi/rshift mpi-obj shift)

Right shift by specified `shift` bit count. Return new `mpj-obj`.

(mpi/set-bit mpi-obj bit)

Set the specified `bit` of `mpi-obj`. Returns `mpi-obj`.

(mpi/sub mpi-obj x)

Subtract x from `mpi-obj` and return the new `mpi-obj`. `x` can be either `mpi-obj` or u32 number.

(mpi/swap mpi-obj-1 mpi-obj-2)

Swap `mpi-obj-1` and `mpi-obj-2` values, Return `mpi-obj-1`.

(mpi/to-bin mpi-obj)

Convert the `mpi-obj` to a binary and return as a string.

(mpi/to-u32 mpi-obj)

Convert the `mpi-obj` to a uint32_t, if possible. Fails if `mpi-obj` is negative or too large.

(nist_key_wrap kek wrapperd &opt cipher)

This unwraps the result of nist_key_wrap. If omitted, "AES" is used for `cipher`.

(nist_key_wrap kek key &opt cipher)

This performs KW (key wrap) mode. The input must be a multiple of 8 bytes long. If omitted, "AES" is used for `cipher`.

(pbkdf algo passphrase out-len &opt iterations salt)

Derive a key from a `passphrase` for a number of `iterations`(default 100000) using the given PBKDF algorithm, e.g., "PBKDF2(SHA-512)". The `salt` can be provided or otherwise is randomly chosen. Returns `out-len` bytes of output (or potentially less depending on the algorithm and the size of the request). Returns tuple of salt, iterations, and psk

(pbkdf-timed algo passphrase out-len &opt ms-to-run salt)

Derive a key from a `passphrase` for a number of Runs for as many iterations as needed to consumed `ms-to-run` milliseconds on whatever we’re running on. Returns tuple of salt, iterations, and psk. Default value of `ms-to-run` is 300 and `salt` is 12 bytes of random values.

(pk-decrypt/decrypt op message)

Decrypt the provided data using the key.

(pk-decrypt/new privkey padding)

Create a new operation object which can be used to decrypt using the provided key and the specified padding scheme (such as "OAEP(SHA-256)" for use with RSA)

(pk-encrypt/encrypt op message &opt rng)

Encrypt the provided data using the key`. New rng is used by default, if `rng` is not provided.

(pk-encrypt/new pubkey padding)

Create a new operation object which can be used to encrypt using the provided key and the specified padding scheme (such as "OAEP(SHA-256)" for use with RSA)

pk-kem-decrypt/decrypt-shared-key op salt desired-key-len encapsulated-key)
Decrypt an encapsulated key and return the shared secret.

(pk-kem-decrypt/new privkey kdf)

Create a KEM operation, decrypt version.

(pk-kem-decrypt/shared-key-length op desired-shared-key-length)

Return the output shared key length, assuming desired-shared-key-length is provided.

(pk-kem-encrypt/create-shared-key op salt desired-key-len &opt rng)

Create a new encapsulated key. If `rng` is not provided, new rng is used by default. Return the tuple of (shared-key, encapsulated-key)

(pk-kem-encrypt/encapsulated-key-length op)

Return the length of the encapsulated key.

(pk-kem-encrypt/new pubkey kdf)

Create a KEM operation, encrypt version.

(pk-kem-encrypt/shared-key-length op desired-shared-key-length)

Return the output shared key length, assuming desired-shared-key-length is provided.

(pk-key_agreement/agree op other-key salt &opt key-len)

Returns a key derived by the KDF. If `key-len` is omitted, default agreement size will be used.

(pk-key-agreement/new privkey kdf)

Set up to perform key derivation using the given private key and specified KDF.

(pk-key_agreement/public-value op)

Returns the public value to be passed to the other party

(pk-sign/finish op &opt rng)

Return a signature over all of the messages provided. Afterwards, the sign operator is reset and may be used to sign a new message.New rng is used by default, if `rng` is not provided.

(pk-sign/new privkey hash-and-padding)

Create a signature operator for the provided key. The padding string specifies what hash function and padding should be used, for example "PKCS1v15(SHA-256)" for PKCS #1 v1.5 padding (used with RSA) or "SHA-384". Generally speaking only RSA has special padding modes; for other algorithms like ECDSA one just names the hash.

(pk-sign/update op message)

Add the message to be signed. Return the self object.

(pk-verify/finish op signature)

Verify if the signature provided matches with the message provided. Return boolean.

(pk-verify/new pubkey hash-and-padding)

Create a verifyature operator for the provided key. The padding string specifies what hash function and padding should be used, for example "PKCS1v15(SHA-256)" for PKCS #1 v1.5 padding (used with RSA) or "SHA-384". Generally speaking only RSA has special padding modes; for other algorithms like ECDSA one just names the hash.

(pk-verify/update op message)

Add the message to be verifyed. Return the self object.

(privkey/algo-name privkey)

Returns the algorithm name.

(privkey/check-key privkey rng &opt weak)

Test the key for consistency. If weak is provided then less expensive tests are performed.

(privkey/export &opt pem)

Exports the private key in PKCS8 format. If `pem` is provided, the result is a PEM encoded string. Otherwise it is a binary DER value. The key will not be encrypted.

(privkey/get-field filed-name)

Return an integer field related to the private key. The valid field names vary depending on the algorithm. For example first RSA secret prime can be extracted with `(privkey/get-field key "p")`. This function can also be used to extract the public parameters.

(privkey/get-pubkey privkey)

Return a `pubkey` object.

(privkey/load blob &opt password)

Return a private key (DER or PEM formats accepted). No `password` indicate no encryption expected.

(privkey/load-dh p g x)

Return a private DH key.

(privkey/load-dsa p q g x)

Return a private DSA key.

(privkey/load-ecdh curve x)

Return a private ECDH key.

(privkey/load-ecdsa curve x)

Return a private ECDSA key.

(privkey/load-elgamal p g x)

Return a private ElGamal key.

(privkey/load-kyber key)

Return a private Kyber key.

(privkey/load-rsa p q e)

Return a private RSA key.

(privkey/load-sm2 curve x)

Return a private SM2 key.

(privkey/new algo param &opt rng)

Creates a new private key. The parameter type/value depends on the algorithm. For "rsa" it is the size of the key in bits. For "ecdsa" and "ecdh" it is a group name (for instance "secp256r1"). For "ecdh" there is also a special case for group "curve25519" (which is actually a completely distinct key type with a non-standard encoding). Use `rng` if provided.

(privkey/to-pem privkey)

Return the DER encoded private key (unencrypted).

(privkey/to-pem privkey)

Return the PEM encoded private key (unencrypted).

(pubkey/algo-name pubkey)

Returns the algorithm name.

(pubkey/check-key pubkey rng &opt weak)

Test the key for consistency. If weak is provided then less expensive tests are performed.

(pubkey/estimated_strength pubkey)

Returns the estimated strength of this key against known attacks (NFS, Pollard’s rho, etc)

(pubkey/export pubkey &opt pem)

Exports the public key using the usual X.509 SPKI representation. If `pem` is provided, the result is a PEM encoded string. Otherwise it is a binary DER value.

(pubkey/fingerprint pubkey &opt hash)

Returns a hash of the public key. "SHA-256" is used as a default hash, if `hash` is not provided.

(pubkey/get-field pubkey filed-name)

Return an integer field related to the public key. The valid field names vary depending on the algorithm. For example RSA public modulus can be extracted with (pubkey/get-field "n").

(pubkey/get-public-point pubkey)

Return a public point of the key.

(pubkey/load value)

Load a public key. The value should be a PEM or DER blob.

(pubkey/load-dh p g y)

Return a public DH key.

(pubkey/load-dsa p q g y)

Return a public DSA key.

(pubkey/load-ecdh curve x y)

Return a public ECDH key.

(pubkey/load-ecdsa curve x y)

Return a public ECDSA key.

(pubkey/load-elgamal p g y)

Return a public ElGamal key.

(pubkey/load-kyber key)

Return a public Kyber key.

(pubkey/load-rsa n e)

Load an RSA public key giving the modulus and public exponent as integers.

(pubkey/load-sm2 curve x y)

Return a public SM2 key.

(pubkey/to-pem pubkey)

Return the DER encoded public key (unencrypted).

(pubkey/to-pem pubkey)

Return the PEM encoded public key (unencrypted).

(rng/add-entropy rng-obj seed)

Adds the provided `seed` array or tuple to the `rng`. Returns `rng-obj`.

(rng/get rng-obj len)

Returns random bytes of length `len` from a random number generator `rng-obj`.

(rng/new &opt type)

Initialize a random number generator from the given `type`:
"system": System-RNG (defaulting to "system" type rng)
"user": AutoSeeded-RNG
"user-threadsafe": serialized AutoSeeded-RNG
"null": Null-RNG (always fails)
"hwrnd" or "rdrand": Processor-RNG (if available)
Returns `rng-obj`

(rng/reseed rng-obj bits)

Reseeds the random number generator `rng` with bits number of `bits` from the System-RNG. Returns `rng-obj`.

(rng/reseed-from-rng rng-obj src bits)

Reseeds the random number generator `rng` with bits number of `bits` taken from given the source rng `src`. Returns `rng-obj`.

(scrypt out-len password salt &opt N r p)

Runs Scrypt key derivation function over the specified password and salt using Scrypt parameters N, r, p. If omitted, the default values of N=1024, r=8, p=8 are used.

(srp6-client-agree username password group-id hash salt B &opt rng)

The client receives these parameters from the server, except for the `username` and `password` which are provided by the user. The parameter B is the output of step1.
The client agreement step outputs a shared symmetric key along with the parameter A which is returned to the server (and allows it the compute the shared key).

(srp6-generate-verifier identifier password salt group-id hash)

Generates a new verifier using the specified `password` and `salt`. This is stored by the server. The salt must also be stored. Later, the given username(`identifier`) and `password` are used to by the client during the key agreement step.

(srp6-server-session/new group-id)

Create srp6 server session object along with `group-id`.

(srp6-server-session/step1 srp6-obj verifier hash rng)

Takes a verifier (generated by srp6-generate-verifier) along with the group-id, and output a value B which is provided to the client.

(srp6-server-session/step2 srp6-obj A)

Takes the parameter A generated by srp6-client-agree, and return the shared secret key.
In the event of an impersonation attack (or wrong username/password, etc) no error occurs, but the key returned will be different on the two sides. The two sides must verify each other, for example by using the shared secret to key an HMAC and then exchanging authenticated messages.

(totp/check totp code &opt timestamp acceptable-drift)

Return true if the provided OTP `code` is correct for the provided `timestamp`. If required, use clock `acceptable-drift` to deal with the client and server having slightly different clocks. If omitted, current timestamp is used for `timestamp` and the default value for `acceptable-drift` is 0.

(totp/generate totp &opt timestamp)

Generate an TOTP code for the provided `timestamp`. If omitted, current timestamp is used.

(totp/new key &opt hash digits timestep)

Instantiate a new TOTP instance with the given parameters. If omitted, the default value for `hash` is "SHA-1", the default value for `digits` is 6 and the default value for `timestep` is 30.

(version-datestamp)

Returns the date this version was released as an integer YYYYMMDD,or 0 if an unreleased version.

(version-major)

Returns the major version of the library.

(version-minor)

Returns the minor version of the library.

(version-patch)

Returns the patch version of the library.

(version-string)

Returns a string describing the version.

(x509-cert/allowed-usage cert-obj cert-usage)

Test if the certificate is allowed for a particular usage.

(x509-cert/authority-key-id cert-obj)

Return the authority key ID set in the certificate, which may be empty.

(x509-cert/dup cert-obj)

Create a new object that refers to the same certificate.

(x509-cert/fingerprint cert-obj &opt hash-algo)

Return a fingerprint for the certificate, which is basically just a hash of the binary contents. Normally "SHA-1" or "SHA-256" is used, but any hash function is allowed. If omitted, "SHA-256" is used.

(x509-cert/hostname-match cert-obj hostname)

Return true if the Common Name (CN) field of the certificate matches a given `hostname`.

(x509-cert/issuer-dn cert-obj key index)

Get a value from the issuer DN field. `key` specifies a value to get, for instance "Name" or "Country".

(x509-cert/load cert)

Load a X.509 certificate from DER or PEM representation.

(x509-cert/load-file file-name)

Load an X.509 certificate from a file.

(x509-cert/not-after cert-obj)

Return the time the certificate expires, as seconds since epoch.

(x509-cert/not-before cert-obj)

Return the time the certificate becomes valid, as seconds since epoch.

(x509-cert/serial-number cert-obj)

Return the serial number of the certificate.

(x509-cert/subject-dn cert-obj key index)

Get a value from the subject DN field. `key` specifies a value to get, for instance "Name" or "Country".

(x509-cert/subject-key-id cert-obj)

Return the subject key ID set in the certificate, which may be empty.

(x509-cert/subject-public-key cert-obj)

Get the public key included in this certificate as an object of `pubkey`.

(x509-cert/subject-public-key-bits cert-obj)

Get the serialized representation of the public key included in this certificate.

(x509-cert/to-string cert-obj)

Return a free-form string representation of this certificate

(x509-cert/validation-status error-code)

Return an informative string explaining the verification return code.

(x509-cert/verify cert-obj &keys {:intermediates intermediates :trusted trusted :truste trusted-path :required-strength required-strength :hostname hostname :reference-time reference-time :crl crls})

Verify a certificate. Returns 0 if validation was successful, returns a positive error code if the validation was unsuccesful.* `:intermediates` - A tuple of untrusted subauthorities.
* `:trusted` - A tuple of trusted root CAs.
* `:trusted-path` - A path refers to a directory where one or more trusted CA certificates are stored.
* `:required-strength` - Indicates the minimum key and hash strength that is allowed. For instance setting to 80 allows 1024-bit RSA and SHA-1. Setting to 110 requires 2048-bit RSA and SHA-256 or higher. Set to zero to accept a default. Default value is 0, if omitted.
* `:hostname` - Check against the certificates CN field.
* `:reference-time` - Time value which the certificate chain is validated against. Use zero(default) to use the current system clock.
* `crls` - A tuple of CRLs issued by either trusted or untrusted authorities.

(x509-crl/load crl cert)

Check whether a given `crl` contains a given `cert`. Return true when the certificate is revoked.

(x509-crl/load crl)

Load a CRL from the DER or PEM representation.

(x509-crl/load file-name)

Load a CRL from a file.

(zfec-decode k n indexes inputs)

Decode some FEC shares. `k` is the number of shares required to recover the original. `n` is the total number of shares. The `indexes` is the list specifies which shares are presented in `inputs`. `inputs` is the list of the input shares (e.g. from a previous call to zfec_encode) which all must be the same length. Return a list of strings containing the original shares decoded from the provided shares (in `inputs`).

(zfec-encode k n input)

Perform forward error correction encoding. `k` is the number of shares required to recover the original. `n` is the total number of shares. The `input` length must be a multiple of K bytes. Return n list of strings, each one containing a single share.