Skip to main content
Version: 3.11.2

Module rspamd_cryptobox

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:

FunctionDescription
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(filetable)`](#f15eae)
rspamd_cryptobox_keypair.create([type='encryption'[, alg='curve25519']])Generates new keypair.
rspamd_cryptobox_signature.load(file)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)Check memory using specified cryptobox key and signature.
rspamd_cryptobox.verify_file(pk, sig, file)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)Encrypt data using specified keypair/pubkey.
[`rspamd_cryptobox.encrypt_file(kppk_string, filename)`](#f054da)
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:

MethodDescription
keypair:totable([encoding="zbase32"])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

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

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'

Returns:

  • {cryptobox_keypair}: new keypair

Back to module description.

Function rspamd_cryptobox_signature.load(file)​

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)​

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)​

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)​

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)​

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([encoding="zbase32"])​

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:

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

Returns:

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

Back to module description.

Back to top.