Module rspamd_cryptobox

Rspamd cryptobox is a module that operates with digital signatures and hashes.

Example:

local hash = require "rspamd_cryptobox_hash"

local h = hash.create()
h:update('hello world')
print(h:hex())

Brief content:

Functions:

Function Description
rspamd_cryptobox_pubkey.load(file[, type[, alg]]) Loads public key from base32 encoded file.
rspamd_cryptobox_pubkey.create(data[, type[, alg]]) Loads public key from base32 encoded string.
rspamd_cryptobox_keypair.load(file|table) Loads public key from UCL file or directly from Lua.
rspamd_cryptobox_keypair.create([type='encryption'[, alg='curve25519']]) Generates new keypair.
rspamd_cryptobox_signature.load(file, [alg = 'curve25519']) Loads signature from raw file.
rspamd_cryptobox_signature.create(data) Creates signature object from raw data.
rspamd_cryptobox_hash.create([string]) Creates new hash context.
rspamd_cryptobox_hash.create_specific(type, [string]) Creates new hash context.
rspamd_cryptobox_hash.create_keyed(key, [string]) Creates new hash context with specified key.
rspamd_cryptobox_hash.create_specific_keyed(key, type, [string]) Creates new hash context with specified key.
rspamd_cryptobox.verify_memory(pk, sig, data, [alg = 'curve25519']) Check memory using specified cryptobox key and signature.
rspamd_cryptobox.verify_file(pk, sig, file, [alg = 'curve25519']) Check file using specified cryptobox key and signature.
rspamd_cryptobox.sign_memory(kp, data) Sign data using specified keypair.
rspamd_cryptobox.sign_file(kp, file) Sign file using specified keypair.
rspamd_cryptobox.encrypt_memory(kp, data[, nist=false]) Encrypt data using specified keypair/pubkey.
rspamd_cryptobox.encrypt_file(kp|pk_string, filename[, nist=false]) Encrypt data using specified keypair/pubkey.
rspamd_cryptobox.decrypt_memory(kp, data[, nist = false]) Encrypt data using specified keypair.
rspamd_cryptobox.decrypt_file(kp, filename) Encrypt data using specified keypair.
rspamd_cryptobox.encrypt_cookie(secret_key, secret_cookie) Specialised function that performs AES-CTR encryption of the provided cookie.
rspamd_cryptobox.decrypt_cookie(secret_key, encrypted_cookie) Specialised function that performs AES-CTR decryption of the provided cookie in form.
rspamd_cryptobox.pbkdf([password, [kdf_alg]]) Function that encrypts password using PBKDF function.
rspamd_cryptobox.gen_dkim_keypair([alg, [nbits]]) Generates DKIM keypair.
rspamd_cryptobox_secretbox.create(secret_string, [params]) Generates a secretbox state by expanding secret string.

Methods:

Method Description
keypair:totable([hex=false]]) Converts keypair to table (not very safe due to memory leftovers).
keypair:type() Returns type of keypair as a string.
keypair:alg() Returns algorithm of keypair as a string.
keypair:pk() Returns pubkey for a specific keypair.
rspamd_cryptobox_signature:save(file) Stores signature in raw file.
cryptobox_signature:hex() Return hex encoded signature string.
cryptobox_signature:base32([b32type='default']) Return base32 encoded signature string.
cryptobox_signature:base64() Return base64 encoded signature string.
cryptobox_signature:bin() Return raw signature string.
cryptobox_hash:update(data) Updates hash with the specified data (hash should not be finalized using hex or bin methods).
cryptobox_hash:reset() Resets hash to the initial state.
cryptobox_hash:hex() Finalizes hash and return it as hex string.
cryptobox_hash:base32([b32type]) Finalizes hash and return it as zbase32 (by default) string.
cryptobox_hash:base64() Finalizes hash and return it as base64 string.
cryptobox_hash:bin() Finalizes hash and return it as raw string.
rspamd_cryptobox_secretbox:encrypt(input, [nonce]) Encrypts data using secretbox.
rspamd_cryptobox_secretbox:decrypt(input, nonce) Decrypts data using secretbox.

Functions

The module rspamd_cryptobox defines the following functions.

Function rspamd_cryptobox_pubkey.load(file[, type[, alg]])

Loads public key from base32 encoded file

Parameters:

  • file {string}: filename to load
  • type {string}: optional ‘sign’ or ‘kex’ for signing and encryption
  • alg {string}: optional ‘default’ or ‘nist’ for curve25519/nistp256 keys

Returns:

  • {cryptobox_pubkey}: new public key

Back to module description.

Function rspamd_cryptobox_pubkey.create(data[, type[, alg]])

Loads public key from base32 encoded string

Parameters:

  • base32 {base32 string}: string with the key
  • type {string}: optional ‘sign’ or ‘kex’ for signing and encryption
  • alg {string}: optional ‘default’ or ‘nist’ for curve25519/nistp256 keys

Returns:

  • {cryptobox_pubkey}: new public key

Back to module description.

Function rspamd_cryptobox_keypair.load(file|table)

Loads public key from UCL file or directly from Lua

Parameters:

  • file {string}: filename to load

Returns:

  • {cryptobox_keypair}: new keypair

Back to module description.

Function rspamd_cryptobox_keypair.create([type='encryption'[, alg='curve25519']])

Generates new keypair

Parameters:

  • type {string}: type of keypair: ‘encryption’ (default) or ‘sign’
  • alg {string}: algorithm of keypair: ‘curve25519’ (default) or ‘nist’

Returns:

  • {cryptobox_keypair}: new keypair

Back to module description.

Function rspamd_cryptobox_signature.load(file, [alg = 'curve25519'])

Loads signature from raw file

Parameters:

  • file {string}: filename to load

Returns:

  • {cryptobox_signature}: new signature

Back to module description.

Function rspamd_cryptobox_signature.create(data)

Creates signature object from raw data

Parameters:

  • raw {data}: signature data

Returns:

  • {cryptobox_signature}: signature object

Back to module description.

Function rspamd_cryptobox_hash.create([string])

Creates new hash context

Parameters:

  • data {string}: optional string to hash

Returns:

  • {cryptobox_hash}: hash object

Back to module description.

Function rspamd_cryptobox_hash.create_specific(type, [string])

Creates new hash context

Parameters:

  • type {string}: type of hash (blake2, sha256, md5, sha512, mum, xxh64, xxh32, t1ha)
  • string {string}: initial data

Returns:

  • {cryptobox_hash}: hash object

Back to module description.

Function rspamd_cryptobox_hash.create_keyed(key, [string])

Creates new hash context with specified key

Parameters:

  • key {string}: key

Returns:

  • {cryptobox_hash}: hash object

Back to module description.

Function rspamd_cryptobox_hash.create_specific_keyed(key, type, [string])

Creates new hash context with specified key

Parameters:

  • key {string}: key

Returns:

  • {cryptobox_hash}: hash object

Back to module description.

Function rspamd_cryptobox.verify_memory(pk, sig, data, [alg = 'curve25519'])

Check memory using specified cryptobox key and signature

Parameters:

  • pk {pubkey}: public key to verify
  • signature {sig}: to check
  • data {string}: data to check signature against

Returns:

  • {boolean}: true - if string matches cryptobox signature

Back to module description.

Function rspamd_cryptobox.verify_file(pk, sig, file, [alg = 'curve25519'])

Check file using specified cryptobox key and signature

Parameters:

  • pk {pubkey}: public key to verify
  • signature {sig}: to check
  • file {string}: to load data from

Returns:

  • {boolean}: true - if string matches cryptobox signature

Back to module description.

Function rspamd_cryptobox.sign_memory(kp, data)

Sign data using specified keypair

Parameters:

  • kp {keypair}: keypair to sign
  • data {string}: no description

Returns:

  • {cryptobox_signature}: signature object

Back to module description.

Function rspamd_cryptobox.sign_file(kp, file)

Sign file using specified keypair

Parameters:

  • kp {keypair}: keypair to sign
  • filename {string}: no description

Returns:

  • {cryptobox_signature}: signature object

Back to module description.

Function rspamd_cryptobox.encrypt_memory(kp, data[, nist=false])

Encrypt data using specified keypair/pubkey

Parameters:

  • kp {keypair|string}: keypair or pubkey in base32 to use
  • data {string|text}: no description

Returns:

  • {rspamd_text}: encrypted text

Back to module description.

Function rspamd_cryptobox.encrypt_file(kp|pk_string, filename[, nist=false])

Encrypt data using specified keypair/pubkey

Parameters:

  • kp {keypair|string}: keypair or pubkey in base32 to use
  • filename {string}: no description

Returns:

  • {rspamd_text}: encrypted text

Back to module description.

Function rspamd_cryptobox.decrypt_memory(kp, data[, nist = false])

Encrypt data using specified keypair

Parameters:

  • kp {keypair}: keypair to use
  • data {string}: no description

Returns:

  • status,{rspamd_text} error status is boolean variable followed by either unencrypted data or an error message

Back to module description.

Function rspamd_cryptobox.decrypt_file(kp, filename)

Encrypt data using specified keypair

Parameters:

  • kp {keypair}: keypair to use
  • filename {string}: no description

Returns:

  • status,{rspamd_text} error status is boolean variable followed by either unencrypted data or an error message

Back to module description.

Function rspamd_cryptobox.encrypt_cookie(secret_key, secret_cookie)

Specialised function that performs AES-CTR encryption of the provided cookie

e := base64(nonce||aesencrypt(nonce, secret_cookie))
nonce := uint32_le(unix_timestamp)||random_64bit
aesencrypt := aes_ctr(nonce, secret_key) ^ pad(secret_cookie)
pad := secret_cookie || 0^(32-len(secret_cookie))

Parameters:

  • secret_key {string}: secret key as a hex string (must be 16 bytes in raw or 32 in hex)
  • secret_cookie {string}: secret cookie as a string for up to 31 character

Returns:

  • {string}: e function value for this sk and cookie

Back to module description.

Function rspamd_cryptobox.decrypt_cookie(secret_key, encrypted_cookie)

Specialised function that performs AES-CTR decryption of the provided cookie in form

e := base64(nonce||aesencrypt(nonce, secret_cookie))
nonce := int32_le(unix_timestamp)||random_96bit
aesencrypt := aes_ctr(nonce, secret_key) ^ pad(secret_cookie)
pad := secret_cookie || 0^(32-len(secret_cookie))

Parameters:

  • secret_key {string}: secret key as a hex string (must be 16 bytes in raw or 32 in hex)
  • encrypted_cookie {string}: encrypted cookie as a base64 encoded string

Returns:

  • {string+number}: decrypted value of the cookie and the cookie timestamp

Back to module description.

Function rspamd_cryptobox.pbkdf([password, [kdf_alg]])

Function that encrypts password using PBKDF function. This function either reads password from STDIN or accepts prepared password as an argument

Parameters:

  • password {string}: optional password string
  • kdf_alg {string}: algorithm to use (catena or pbkdf2)

Returns:

  • {string}: encrypted password or nil if error occurs

Back to module description.

Function rspamd_cryptobox.gen_dkim_keypair([alg, [nbits]])

Generates DKIM keypair. Returns 2 base64 strings as rspamd_text: privkey and pubkey

Parameters:

  • alg {string}: optional algorithm (rsa default, can be ed25519)
  • nbits {number}: optional number of bits for rsa (default 1024)

Returns:

  • {rspamd_text,rspamd_text}: private key and public key as base64 encoded strings

Back to module description.

Function rspamd_cryptobox_secretbox.create(secret_string, [params])

Generates a secretbox state by expanding secret string

Parameters:

  • secret_string {string/text}: secret string (should have high enough entropy)
  • params {table}: optional parameters - NYI

Returns:

  • {rspamd_cryptobox_secretbox}: opaque object with the key expanded

Back to module description.

Methods

The module rspamd_cryptobox defines the following methods.

Method keypair:totable([hex=false]])

Converts keypair to table (not very safe due to memory leftovers)

Parameters:

No parameters

Returns:

No return

Back to module description.

Method keypair:type()

Returns type of keypair as a string: ‘encryption’ or ‘sign’

Parameters:

No parameters

Returns:

  • {string}: type of keypair as a string

Back to module description.

Method keypair:alg()

Returns algorithm of keypair as a string: ‘encryption’ or ‘sign’

Parameters:

No parameters

Returns:

  • {string}: type of keypair as a string

Back to module description.

Method keypair:pk()

Returns pubkey for a specific keypair

Parameters:

No parameters

Returns:

  • {rspamd_pubkey}: pubkey for a keypair

Back to module description.

Method rspamd_cryptobox_signature:save(file)

Stores signature in raw file

Parameters:

  • file {string}: filename to use

Returns:

  • {boolean}: true if signature has been saved

Back to module description.

Method cryptobox_signature:hex()

Return hex encoded signature string

Parameters:

No parameters

Returns:

  • {string}: raw value of signature

Back to module description.

Method cryptobox_signature:base32([b32type='default'])

Return base32 encoded signature string

Parameters:

  • b32type {string}: base32 type (default, bleach, rfc)

Returns:

  • {string}: raw value of signature

Back to module description.

Method cryptobox_signature:base64()

Return base64 encoded signature string

Parameters:

No parameters

Returns:

  • {string}: raw value of signature

Back to module description.

Method cryptobox_signature:bin()

Return raw signature string

Parameters:

No parameters

Returns:

  • {string}: raw value of signature

Back to module description.

Method cryptobox_hash:update(data)

Updates hash with the specified data (hash should not be finalized using hex or bin methods)

Parameters:

  • data {string}: data to hash

Returns:

No return

Back to module description.

Method cryptobox_hash:reset()

Resets hash to the initial state

Parameters:

No parameters

Returns:

No return

Back to module description.

Method cryptobox_hash:hex()

Finalizes hash and return it as hex string

Parameters:

No parameters

Returns:

  • {string}: hex value of hash

Back to module description.

Method cryptobox_hash:base32([b32type])

Finalizes hash and return it as zbase32 (by default) string

Parameters:

  • b32type {string}: base32 type (default, bleach, rfc)

Returns:

  • {string}: base32 value of hash

Back to module description.

Method cryptobox_hash:base64()

Finalizes hash and return it as base64 string

Parameters:

No parameters

Returns:

  • {string}: base64 value of hash

Back to module description.

Method cryptobox_hash:bin()

Finalizes hash and return it as raw string

Parameters:

No parameters

Returns:

  • {string}: raw value of hash

Back to module description.

Method rspamd_cryptobox_secretbox:encrypt(input, [nonce])

Encrypts data using secretbox. MAC is prepended to the message

Parameters:

  • input {string/text}: input to encrypt
  • nonce {string/text}: optional nonce (must be 1 - 192 bits length)
  • params {table}: optional parameters - NYI

Returns:

  • {rspamd_text}: ,{rspamd_text} output with mac + nonce or just output if nonce is there

Back to module description.

Method rspamd_cryptobox_secretbox:decrypt(input, nonce)

Decrypts data using secretbox

Parameters:

  • nonce {string/text}: nonce used to encrypt
  • input {string/text}: input to decrypt
  • params {table}: optional parameters - NYI

Returns:

  • {boolean}: ,{rspamd_text} decryption result + decrypted text

Back to module description.

Back to top.