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:

Methods:

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.