crypto library

The library provides common cryptographic functions

Hashing

crypto.sha256(data: str) -> str
crypto.sha384(data: str) -> str
crypto.sha512(data: str) -> str
crypto.md5(data: str) -> str

crypto.hash(hash: str, data: str) -> str
crypto.hmac(hash: str, key: str, data: str) -> str

Supported names are SHA256, SHA384, SHA512 and MD5

MD5 is needed for compatibility with old formats. SHA256 is better for new data

Large files can be passed in parts

local hash = crypto.hash_new("SHA256")

hash:update(part1)
hash:update(part2)

local result = hash:final()

The context can be cleared with reset after final

Signatures

crypto.ed25519_keypair() -> private_key, public_key
crypto.ed25519_public(private_key: str) -> str
crypto.ed25519_sign(private_key: str, message: str) -> str
crypto.ed25519_verify(public_key: str, message: str, signature: str)
    -> true
    -> false, error

Ed25519 keys are 32 bytes long. A signature is 64 bytes long

crypto.ecdsa_keypair(curve: str) -> private_key, public_key
crypto.ecdsa_public(curve: str, private_key: str) -> str
crypto.ecdsa_sign(curve: str, private_key: str, message: str, hash: str) -> str
crypto.ecdsa_verify(curve: str, public_key: str, message: str,
                    signature: str, hash: str)
    -> true
    -> false, error

Available curves are P-256, P-384 and P-521

An ECDSA public key is stored as an uncompressed SEC1 point. A signature is stored in DER format

crypto.rsa_pkcs1_verify(hash: str, modulus: str, exponent: str,
                        message: str, signature: str)
    -> true
    -> false, error

crypto.rsa_pss_verify(hash: str, modulus: str, exponent: str,
                      message: str, signature: str, salt_length: int)
    -> true
    -> false, error

RSA modulus and exponent are passed in big endian. A salt_length value of -1 uses the hash size

Key exchange

crypto.x25519_keypair() -> private_key, public_key
crypto.x25519_public(private_key: str) -> str
crypto.x25519(private_key: str, peer_public_key: str) -> str
crypto.x25519_shared(private_key: str, peer_public_key: str) -> str

crypto.p256_keypair() -> private_key, public_key
crypto.p256_public(private_key: str) -> str
crypto.p256_shared(private_key: str, peer_public_key: str) -> str

x25519 and x25519_shared perform the same operation

The shared secret should not be used as a ready key. Pass it through HKDF first

Encryption

crypto.aes_gcm_encrypt(key: str, nonce: str, aad: str, plaintext: str) -> str
crypto.aes_gcm_decrypt(key: str, nonce: str, aad: str, ciphertext: str)
    -> plaintext
    -> nil, error

crypto.chacha20_poly1305_encrypt(key: str, nonce: str, aad: str,
                                 plaintext: str) -> str
crypto.chacha20_poly1305_decrypt(key: str, nonce: str, aad: str,
                                 ciphertext: str)
    -> plaintext
    -> nil, error

AES GCM accepts 16 and 32 byte keys

ChaCha20 Poly1305 uses a 32 byte key and a 12 byte nonce

A 16 byte tag is appended to encrypted data

Never reuse a nonce with the same key

Other functions

crypto.random_bytes(length: int) -> str
crypto.constant_time_equal(left: str, right: str) -> bool

crypto.hkdf_extract(hash: str, salt: str, ikm: str) -> str
crypto.hkdf_expand(hash: str, prk: str, info: str, length: int) -> str

crypto.pbkdf2(hash: str, password: str, salt: str,
              iterations: int, length: int) -> str
crypto.scrypt(password: str, salt: str, n: int, r: int, p: int,
              length: int, [optional]max_memory: int=0) -> str

crypto.features() -> table

Use scrypt or PBKDF2 with a random salt for passwords. A regular SHA256 hash is not suitable for passwords

features returns the OpenSSL version and a list of available features

An invalid signature returns false, "invalid_signature"

An invalid encryption tag returns nil, "authentication_failed"

Invalid arguments raise a regular Lua error

3.9 KiB Raw Blame History