Skip to content

crypto_secretstream

Jump to bottom
John Regan edited this page Dec 31, 2021 · 5 revisions

Wrapper for the crypto_secretstream functions.

Available in version 1.1 or later of the library.

Synopsis

local luasodium = require'luasodium'

local key = luasodium.crypto_secretstream_xchacha20poly1305_keygen()
local encrypt, header = luasodium.crypto_secretstream_xchacha20poly1305_init_push(key)

local messages = {
  encrypt:message('hello'),
  encrypt:final('there'),
}

local decrypt = luasodium.crypto_secretstream_xchacha20poly1305_init_pull(header, key)

local i = 1
local message, tag

repeat
  message, tag = decrypt:pull(messages[i])
  print(message)
  i = i + 1
until tag == luasodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL

Constants

  • crypto_secretstream_xchacha20poly1305_ABYTES
  • crypto_secretstream_xchacha20poly1305_HEADERBYTES
  • crypto_secretstream_xchacha20poly1305_KEYBYTES
  • crypto_secretstream_xchacha20poly1305_MESSAGEBYTES_MAX
  • crypto_secretstream_xchacha20poly1305_TAG_MESSAGE
  • crypto_secretstream_xchacha20poly1305_TAG_PUSH
  • crypto_secretstream_xchacha20poly1305_TAG_REKEY
  • crypto_secretstream_xchacha20poly1305_TAG_FINAL

Functions

crypto_secretstream_xchacha20poly1305_keygen

syntax: string key = luasodium.crypto_secretstream_xchacha20poly1305_keygen()

Generates a random key.

crypto_secretstream_xchacha20poly1305_init_push

syntax: userdata state, string header = luasodium.crypto_secretstream_xchacha20poly1305_init_push(key)

Creates and initializes a new state object for encrypting messages with a given key.

Returns the initialized state and header.

The returned state has an __index table for convenient access to functions:

  • state:message(string message [, string additional_data]) equivalent to luasodium.crypto_secretstream_xchacha20poly1305_push(string message, luasodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE [, string additional_data])
  • state:push(string message [, string additional_data]) equivalent to luasodium.crypto_secretstream_xchacha20poly1305_push(string message, luasodium.crypto_secretstream_xchacha20poly1305_TAG_PUSH [, string additional_data])
  • state:rekey(string message [, string additional_data]) equivalent to luasodium.crypto_secretstream_xchacha20poly1305_push(string message, luasodium.crypto_secretstream_xchacha20poly1305_TAG_REKEY [, string additional_data])
  • state:final(string message [, string additional_data]) equivalent to luasodium.crypto_secretstream_xchacha20poly1305_push(string message, luasodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL [, string additional_data])

The state:rekey method can be called with nil as a shortcut for luasodium.crypto_secretstream_xchacha20poly1305_rekey(state)

The returned state also has a __call method defined, so state can be used like a function:

string cipher = state(string message [, boolean final, string additional_data])

This is equivalent to calling luasodium.crypto_secretstream_xchacha20poly1305_push(message, tag, additional_data) - the value of tag is dependent on the optional final boolean. If false or nil (or anything falsey), then tag is luasodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE, if true (or anything truthy), then tag is luasodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL.

This allows for uses like:

local key = luasodium.crypto_secretstream_xchacha20poly1305_keygen()
local state, header = luasodium.crypto_secretstream_xchacha20poly1305_init_push(key)

local cipher1 = state('message1')
local cipher2 = state('message2')
local cipherfinal = state('messagefinal', true)

crypto_secretstream_xchacha20poly1305_push

syntax: string cipher = luasodium.crypto_secretstream_xchacha20poly1305_push(userdata state, string message, number tag [, string additional_data)

Encrypts a message, using an initialized state object. tag corresponds to one of these constants:

  • luasodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE - encrypt the message normally.
  • luasodium.crypto_secretstream_xchacha20poly1305_TAG_PUSH - indicate to the decoder that some chunk is complete.
  • luasodium.crypto_secretstream_xchacha20poly1305_TAG_REKEY - trigger a rekeying
  • luasodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL - indicate to the decoder that decoding is finished.

See above for details on convenient wrappers for this method.

crypto_secretstream_xchacha20poly1305_init_pull

syntax: userdata state = luasodium.crypto_secretstream_xchacha20poly1305_init_pull(string header, string key)

Creates and initializes a new state object for decrypting messages with a given header and key.

Returns nil if the header and key combination are invalid.

Returned state has an __index on the metatable for access to the pull function:

  • state:pull(string cipher [, string additional_data]) equivalent to luasodium.crypto_secretstream_xchacha20poly1305_pull(userdata state, string cipher [, string additional_data])

state also has a __call method, allowing it to be used like a function:

syntax: string message, number tag = state(string cipher [, string additional_data])

This allows for uses like:

-- assuming key and header, ciphertexts are available from elsewhere
local state = luasodium.crypto_secretstream_xchacha20poly1305_init_pull(header,key)
print(state(cipher1))
print(state(cipher2))
print(state(cipherfinal))

crypto_secretstream_xchacha20poly1305_pull

syntax: string message, number tag = luasodium.crypto_secretstream_xchacha20poly1305_pull(userdata state, string cipher [, string additional_data)

Decrypts a given ciphertext and returns the decrypted message and associated tag. tag is one of the following constants:

  • luasodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE - encrypt the message normally.
  • luasodium.crypto_secretstream_xchacha20poly1305_TAG_PUSH - indicate to the decoder that some chunk is complete.
  • luasodium.crypto_secretstream_xchacha20poly1305_TAG_REKEY - trigger a rekeying
  • luasodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL - decoding is finished.

See above for details on using state:pull(string cipher [, string additional_data) as a convenience wrapper.

crypto_secretstream_xchacha20poly1305_rekey

syntax: luasodium.crypto_secretstream_xchacha20poly1305_rekey(userdata state)

Manually trigger a rekeying on the given state object.

Also accessible as state:rekey().

Clone this wiki locally