crypto

n cryptographically random bytes as hex text (2n characters): random_bytes(32) makes an AES-256 key, random_bytes(16) a salt or token.

A random URL-safe token (base64 without padding) of bytes random bytes (default 32), for session ids, reset links and API keys.

Encrypt text with AES-GCM. It is authenticated: any tampering is detected when decrypting.

Arguments

• key hex text of 32, 48 or 64 characters. Make one with crypto.random_bytes(32).
• text the text to encrypt.
• aad optional extra text, like a record id. It is not encrypted, but it must match when decrypting.

Returns

• base64 text holding the nonce, the ciphertext and the tag.
• A fresh random 12-byte nonce is used every time.

Pure Python, so it runs at about 0.5 MB/s.

Example

let key = crypto.random_bytes(32)
let secret = crypto.aes_gcm_encrypt(key, "meet at noon")
say(crypto.aes_gcm_decrypt(key, secret))

Decrypt what aes_gcm_encrypt() made (base64 text). A wrong key, wrong aad or changed data gives a catchable error instead of garbage.

Encrypt text with AES-CBC and PKCS#7 padding. Use it to talk to older systems. Prefer aes_gcm_encrypt(), which also detects tampering.

Arguments

• key hex text of 32, 48 or 64 characters.
• text the text to encrypt.
• iv optional hex text of 32 characters (default: random).

Returns base64 text holding the iv and then the ciphertext.

Decrypt what aes_cbc_encrypt() made (base64 text of iv + ciphertext). Bad padding (wrong key or changed data) gives a catchable error.

Turn a password into a key with PBKDF2-HMAC (default sha256, length 32 bytes), as hex text. salt is text or hex from random_bytes(16); use 600000+ iterations for password storage.

Turn a password into a key with scrypt (memory-hard, so GPUs can't guess fast), as hex text. Defaults: n = 16384, r = 8, p = 1, length = 32 bytes.

A keyed signature (HMAC) of text, as hex. Compare it with hash.compare(), so timing can't leak the answer.

Options

• hash the hash to use (default: sha256). One of:
  • sha256, sha1, sha384, sha512 or md5

The 6-digit one-time code an authenticator app shows right now. secret is the base32 text behind the QR code. time is an optional timestamp to use instead of now.

Options

• digits how long the code is (default: 6).
• period seconds each code lasts (default: 30).
• hash the hash to use (default: "sha1").

True if code is the current one-time code for the secret. The code just before or after also counts, because clocks drift. It is compared in constant time.

Options

• digits, period, hash as for totp().
• window how many steps either side to accept (default: 1).

The counter-based one-time code (HOTP, RFC 4226) for a base32 secret.

A new random base32 secret (default 20 bytes = 32 characters) to put in an authenticator app.

Make a signed JSON Web Token from a payload map with a shared secret: alg is HS256 (default), HS384 or HS512. Add "exp" (a timestamp) to the payload yourself to make it expire. RS* signing needs a private key and isn't included; verifying RS* tokens is (jwt_verify).

Check a JWT's signature and times, and give back its payload.

The key

• For HS256, HS384 or HS512: the shared secret.
• For RS256, RS384 or RS512: a PEM public key or certificate (checked with pure-Python RSA).

Options

• leeway seconds of clock difference to allow (default: 60).
• now a timestamp to use as the current time.
• algs a list like ["HS256"] to allow only some algorithms.

Errors

Each one is catchable, and err.reason says which:

• "signature" the signature is bad.
• "alg" the token says "alg": "none" (or an algorithm you did not allow).
• "expired" the token has expired (its exp time).
• "not_yet" the token is not valid yet (its nbf time).

Read a JWT WITHOUT checking its signature. Good for a look inside. Never trust the payload without jwt_verify().

Returns a map with

• "header" the token's header map.
• "payload" the token's payload map.
• "alg" the algorithm the header names.
• "expired" true if its exp time has passed.
• "verified" always false.

Hash a password for storing with scrypt and a random salt. The answer looks like $scrypt$n=16384,r=8,p=1$<salt>$<hash> and password_verify() checks it. Never store passwords any other way.

True if password matches a hash from password_hash() (constant-time compare).

True if signature is a valid RSA PKCS#1 v1.5 signature of text. Pure Python (pow()), no OpenSSL.

Arguments

• signature base64 or hex text.
• public_key a PEM public key. One of:
  • a PUBLIC KEY block (-----BEGIN PUBLIC KEY-----)
  • an RSA PUBLIC KEY block
  • a CERTIFICATE
• hash the hash used (default: sha256). One of:
  • sha256, sha1, sha384 or sha512

Read a PEM public key, or the key inside a certificate.

Returns a map with

• "kind" "rsa", "ec" or "ed25519".
• "bits" the key size.
• "n" (hex) and "e": for RSA keys.
• "curve" for EC keys.

Read an X.509 certificate. Give it PEM text, or DER as base64 or hex text. now is an optional timestamp to judge validity against.

Returns a map with

• "subject", "issuer" maps with CN, O, C... and "text".
• "common_name" the subject's CN.
• "dns_names" the host names the certificate covers.
• "sans" all alternative names (dns, ip, email, uri).
• "not_before", "not_after" when it starts and stops being valid.
• "valid_now", "expired", "days_left" its validity now (or at now).
• "is_ca", "self_signed" what kind of certificate it is.
• "key_usage", "ext_key_usage" what the key may be used for.
• "signature_algorithm" how it was signed.
• "public_key" a map with kind and bits.
• "serial" the serial number.
• "fingerprint_sha256", "fingerprint_sha1", "fingerprint_md5" colon hex.
• "extensions" the names of its extensions, sorted.
• "pem" the certificate as PEM text.

Every certificate in PEM text (a chain file), each parsed like x509_parse().

Re-encode hex text (a key or hash) as base64.

Re-encode base64 text as hex.