cryptoModule

Lua interface to the Linux Crypto API.

Crypto objects are created in a process runtime alone: in a softirq or hardirq runtime a constructor raises “‘crypto.shash’: process-context class in interrupt-context runtime”, naming its class. Errors are raised as errno names: “ENOENT” for an unknown algorithm, “EINVAL” for a wrong IV, key or state length or a block cipher input that is not a multiple of blocksize(), “ENOMEM” when the kernel cannot allocate the transform, “ENOKEY” for a signature verifier used before its key is set, and “not enough memory” when the binding cannot allocate its own state, its output or the copy of its input. An AEAD message that does not authenticate is no error: decrypt answers nil and “EBADMSG” for it, and a signature that does not verify is none either: verify answers false and the errno’s name.

Functions

aead (algname)	Creates an AEAD cipher transform.
comp (algname)	Creates a compression transform.
rng ([algname="stdrng"])	Creates a random number generator and seeds it as `reset` does without a seed.
shash (algname)	Creates a synchronous hash transform.
sig (algname)	Creates a signature verifier.
skcipher (algname)	Creates a symmetric-key cipher transform.

Functions in detail

aead (algname)

Creates an AEAD cipher transform. Only a synchronous implementation is chosen: an asynchronous one, such as a hardware engine’s or a cryptd(...) instance, is passed over.

Parameters

algname string algorithm name (e.g., “gcm(aes)”, “ccm(aes)”)

Returns

crypto_aead

Raises

“ENOENT” for an unknown algorithm or one no synchronous implementation serves (“EEXIST” on 6.12 and later for a template whose instance is asynchronous, such as cryptd(...)), “ENOMEM” or “not enough memory” on allocation failure

Usage

local aead = require("crypto").aead
local cipher = aead("gcm(aes)")

comp (algname)

Creates a compression transform. Absent on 6.15 and later, whose kernel has no synchronous compression API.

Parameters

algname string algorithm name (e.g., “lz4”, “deflate”)

Returns

crypto_comp

Raises

“ENOENT” for an unknown algorithm, “ENOMEM” or “not enough memory” on allocation failure

Usage

local comp = require("crypto").comp
local c = comp("lz4")

rng ([algname="stdrng"])

Creates a random number generator and seeds it as reset does without a seed.

Parameters

algname string algorithm name (default "stdrng")

Returns

crypto_rng

Raises

“ENOENT” for an unknown algorithm, “ENOMEM” or “not enough memory” on allocation failure, or the errno of the seeding it runs at creation

Usage

local rng = require("crypto").rng
local r = rng()

shash (algname)

Creates a synchronous hash transform.

Parameters

algname string algorithm name (e.g., “sha256”, “hmac(sha256)”)

Returns

crypto_shash

Raises

“ENOENT” for an unknown algorithm, “ENOMEM” or “not enough memory” on allocation failure

Usage

local shash = require("crypto").shash
local h = shash("sha256")

sig (algname)

Creates a signature verifier. The name is the kernel’s, which differs by release for a DER or a PKCS#1 v1.5 signature: ECDSA over an X9.62 DER signature is x962(ecdsa-nist-p256) on 6.13 and later and ecdsa-nist-p256 on 6.12 and earlier, the curve one of p192, p256, p384, and p521 from 6.10; RSA PKCS#1 v1.5 is pkcs1(rsa,sha256) on 6.13 and later and pkcs1pad(rsa,sha256) on 6.12 and earlier. On 6.13 and later p1363(ecdsa-nist-p256) takes r and s concatenated big-endian, each of the key’s size, and the bare ecdsa-nist-p256 is the kernel’s raw form, which takes r and s in the kernel’s own digits and answers false and “EINVAL” to a DER or a P1363 signature. A script that runs on both sides tries the newer name first and takes “ENOENT” as the cue for the older one. The module links crypto_alloc_sig, which CONFIG_CRYPTO_SIG2 builds on every kernel that has a signature algorithm.

Parameters

algname string algorithm name (e.g., “x962(ecdsa-nist-p256)”, “pkcs1(rsa,sha256)”)

Returns

crypto_sig

Raises

“ENOENT” for an unknown algorithm, or one the kernel serves only for encryption, such as rsa on 6.13 and later, “ENOMEM” or “not enough memory” on allocation failure

Usage

local sig = require("crypto").sig
local function verifier(name, older)
  local ok, v = pcall(sig, name)
  if ok then
    return v
  end
  assert(v == "ENOENT", v)
  return sig(older)
end
local v = verifier("x962(ecdsa-nist-p256)", "ecdsa-nist-p256")
v:setpubkey(point)
local ok, err = v:verify(signature, digest)

skcipher (algname)

Creates a symmetric-key cipher transform. Only a synchronous implementation is chosen: an asynchronous one, such as a hardware engine’s or a cryptd(...) instance, is passed over.

Parameters

algname string algorithm name (e.g., “cbc(aes)”, “ctr(aes)”)

Returns

crypto_skcipher

Raises

Usage

local skcipher = require("crypto").skcipher
local cipher = skcipher("cbc(aes)")