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:

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 file.

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

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

Methods:

keypair:totable([hex=false]]): Converts keypair to table (not very safe due to memory leftovers).

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

keypair:alg(): Returns algorithm of keypair as a string: ‘encryption’ or ‘sign’.

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(): 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(): Finalizes hash and return it as zbase32 string.

cryptobox_hash:base64(): Finalizes hash and return it as base64 string.

cryptobox_hash:bin(): Finalizes hash and return it as raw string.

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 file

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 signature
  • data {string}: raw signature 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.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.

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

Return base32 encoded signature string

Parameters:

No parameters

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

Finalizes hash and return it as zbase32 string

Parameters:

No parameters

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.

Back to top.