Zenroom

• Index

Contents

• Global OCTET Functions
• Class OCTET

Modules

• OCTET
• HASH
• ECP
• BIG
• FLOAT
• TIME
• AES
• ECDH
• ED
• P256
• QP
• String
• Table
• INSPECT
• lua.zencode
• BBS

Module OCTET

Array of raw bytes: base data type in Zenroom

Octets are first-class citizens in Zenroom.

They consist of arrays of bytes (8bit) compatible with all cryptographic functions and methods. They are implemented to avoid any buffer overflow and their maximum size is known at the time of instantiation. It is possible to create OCTET instances using the new() method:

message = OCTET.new(64) -- creates a 64 bytes long octet

The code above fills all 64 bytes with zeroes; to initialise with random data is possible to use the OCTET.random function:

random = OCTET.random(32) -- creates a 32 bytes random octet

Octets can export their contents to a simple string or more portable encodings as sequences of url64, base64, hex or even bin as sequences of binary 0 and 1. They can also be exported to Lua's array format with one element per byte.

Usage:

-- import a string as octet using the shortcut function str()
hello = str("Hello, World!")
-- print in various encoding formats
print(hello:string()) -- print octet as string
print(hello:hex())    -- print octet as hexadecimal sequence
print(hello:base64()) -- print octet as base64
print(hello:url64())  -- print octet as base64 url (preferred)
print(hello:bin())    -- print octet as a sequence of 0 and 1

Info:

• Copyright: Dyne.org foundation 2017-2019
• License: AGPLv3
• Author: Denis "Jaromil" Roio

Global OCTET Functions

Class OCTET

Global OCTET Functions

new ([length=64])

Create a new octet with a specified maximum size, or a default if omitted. All operations exceeding the octet's size will truncate excessing data. Octets cannot be resized.

Parameters:

• length integer maximum length in bytes (default 64)

Returns:

octet newly instantiated octet

empty ()

Create a new octet of size 0.

Returns:

octet newly instantiated octet

random (len)

Generate an octet of specified length containing random bytes.

Parameters:

• len a specified length

Returns:

random octet of specified length

is_base64 (s)

Check if a Lua string is a valid base64-encoded string. If the string is valid base64, it pushes true, otherwise it pushes false onto the Lua stack.

Parameters:

• s a Lua string

Returns:

a boolean value

is_url64 (s)

Check if a Lua string is a valid url64-encoded string. If the string is valid url64, it pushes true, otherwise it pushes false onto the Lua stack.

Parameters:

• s a Lua string

Returns:

a boolean value

is_base58 (s)

Check if a Lua string is a valid base58-encoded string. If the string is valid base58, it pushes true, otherwise it pushes false onto the Lua stack.

Parameters:

• s a Lua string

Returns:

a boolean value

is_hex (s)

Check if a Lua string is a valid hexadecimal-encoded string. If the string is valid hex, it pushes true, otherwise it pushes false onto the Lua stack.

Parameters:

• s a Lua string

Returns:

a boolean value

is_bin (s)

Check if a Lua string is a valid bin-encoded string. If the string is valid bin, it pushes true, otherwise it pushes false onto the Lua stack.

Parameters:

• s a Lua string

Returns:

a boolean value

from_number (num)

Convert a Lua integer into a 16-byte octet object, padding the upper 8 bytes with zeros and handling endianness.

Parameters:

• num Lua integer

Returns:

16-byte octet object

from_base64 (str)

Decode a base64-encoded string into an octet object, after checking if the input string is valid base64.

Parameters:

• str base64-encoded string

Returns:

decoded octet object

from_url64 (str)

Decode a url64-encoded string into an octet object, after checking if the input string is valid url64.

Parameters:

• str url64-encoded string

Returns:

decoded octet object

from_base58 (str)

Decode a base58-encoded string into an octet object, after checking if the input string is valid base58.

Parameters:

• str base58-encoded string

Returns:

decoded octet object

from_string (str)

Convert a string into an octet object, after checking if the input is a valid string.

Parameters:

• str string

Returns:

convert octet object

from_hex (str)

Decode an hexadecimal-encoded string into an octet object, after checking if the input string is valid hexadecimal.

Parameters:

• str hexadecimal-encoded string

Returns:

decoded octet object

from_bin (bin)

Convert a binary string (composed of '0' and '1' characters) into an octet object.

Parameters:

• bin binary string

Returns:

convert octet object

from_segwit (s)

In the bitcoin world, addresses are the hash of the public key (binary data). However, the user usually knows them in some encoded form (which also include some error check mechanism, to improve security against typos). Bech32 is the format used with segwit transactions.

Parameters:

• s Address encoded as Bech32(m)

Returns:

Address as binary data

Or

Segwit version (version 0 is Bech32, version >0 is Bechm)

to_segwit (o, witver, s)

For an introduction see from_segwit. HRP (human readble part) are the first characters of the address, they can be bc (bitcoin network) or tb (testnet network).

Parameters:

• o Address in binary format (octet with the result of the hash160)
• witver Segwit version
• s HRP

Returns:

Bech32(m) encoded string

from_base45 (str)

Decode a base45-encoded string into an octet object, after checking if the input string is valid base45.

Parameters:

• str base45-encoded string

Returns:

decoded octet object

from_mnemonic (str)

Decode a mnemonic-encoded string into an octet object, after checking if the input string is valid mnemonic.

Parameters:

• str mnemonic-encoded string

Returns:

decoded octet object

zero ([length=octet:max])

Create an octet filled with zero values up to indicated size or its maximum size.

Parameters:

• length integer fill with zero up to this size, use maximum octet size if omitted (default octet:max)

Returns:

octet filled with zeros

Class OCTET

 random = OCTET.random(32) -- global OCTET constructor using the dot
 print( random:hex() ) -- method call on the created object using the colon
 

octet:base64 ()

Encode an octet in base64 notation.

Returns:

a string representing the octet's contents in base64

octet:url64 ()

Encode an octet in url64 notation.

Returns:

a string representing the octet's contents in url64

octet:url64 ()

Encode an octet in base58 notation.

Returns:

a string representing the octet's contents in base58

octet:base45 ()

Encode an octet in base45 notation.

Returns:

a string representing the octet's contents in base45

octet:mnemonic ()

Encode an octet in mnemonic notation.

Returns:

a string representing the octet's contents in mnemonic

octet:array ()

Converts an octet into an array of bytes, compatible with Lua's transformations on arrays.

Returns:

an array as Lua's internal representation

octet:octet ()

Return self (octet), implemented for compatibility with all zenroom types so that anything can be casted to octet.

Returns:

the self octet

octet:string ()

Print an octet as string.

Returns:

a string representing the octet's contents

octet:hex ()

Encode an octet into a string of hexadecimal numbers representing its contents.

Returns:

a string of hexadecimal numbers

octet:bin ()

Encode an octet to a string of zeroes and ones (0/1) as binary sequence.

Returns:

a string of bits

octet:fill (oct)

Fill an octet object with the contents of another octet object.

Parameters:

• oct the source octet providing the data

Returns:

the target octet is fully filled, and its len is set to its max capacity.

octet:concat (dest, source)

Concatenate two octets, returns a new octet. This is also executed when using the '..' operator btween two octets. It results in a newly allocated octet, does not change the contents of other octets.

Parameters:

• dest leftmost octet will be overwritten by result
• source rightmost octet used in XOR operation

Returns:

a new octet resulting from the operation

octet:pad ([length=octet:max])

Pad an octet with leading zeroes up to indicated length or its maximum size.

Parameters:

• length integer pad to this size, will use maximum octet size if omitted (default octet:max)

Returns:

new octet padded at length

octet:trim ()

Trim all leading and following zero bytes in an octet and return a new one of equal length or smaller.

Returns:

trimmed octet

Usage:

--create an octet of bin
oct = OCTET.from_bin("00000000111111000")
--print 11111100
print(oct:trim():bin())

octet:chop (len)

Split an octet into two parts based on a specified length and return both parts. The first part will have a length in bytes equal to the input parameter. The second part will contain the remaining bytes.

Parameters:

• len an optional length parameter (defaulting to 0)

Returns:

Returns the two resulting octets

Usage:

--create an octet of bin
oct = OCTET.from_bin("001000001111110001")
--consider the length parameter equal to 1
part1, part2 = oct:chop(1)
--part1 = 00100000, part2 = 11111100

octet:reverse ()

Build the byte in reverse order with respect to the one which is given.

Returns:

reverse order octet

octet:sub (start, end)

Extracts a piece of the octet from the start position to the end position inclusive, expressed in numbers.

Parameters:

• start integer position, begins from 1 not 0 like in lua
• end integer position, may be same as start for a single byte

Returns:

new octet sub-section from start to end inclusive

octet:eq ()

Compare two octets to see if contents are equal.

Returns:

true if equal, false otherwise

octet:__len ()

Retrieve and return the length of an octet.

Returns:

length of the octet

octet:max ()

Retrieve and return the maximum capacity of an octet.

Returns:

maximum capacity of an octet

octet:rmchar (char)

Given a string and a characater, this function removes from the string all the occurences of the character in the string

Parameters:

• char the character to remove

Returns:

the initial string without the input character

Usage:

-- oct is the octet with the string to modify
-- to_remove is the character to remove from oct
oct = OCTET.from_string("Hello, world!")
to_remove = OCTET.from_string("l")
print(oct:rmchar(to_remove))
--print: Heo, word!

octet:compact_ascii ()

Process an octet structure and create a new octet by filtering out certain ASCII characters and handling escape sequences. If an escape character \ is encountered, it sets an escape flag. If the next character is one of 'a', 'b', 't', 'n', 'v', 'f', or 'r', both the escape character \ and the escaped character are skipped. All other valid characters are copied to the new octet.

Returns:

New octet which contains the filtered and processed data

Usage:

--create a string octet
oct=OCTET.from_string("st\ring fo\r ex\ample")
print(oct:compact_ascii())
--print: stingfoexmple

octet:bytefreq ()

Calculate the frequency of each byte value in an octet and returns the results as a Lua table. It is useful for analyzing the distribution of byte values in a byte array, which can be used for entropy calculations or other statistical analyses.

Returns:

Lua table containing bytes distribution

Usage:

--create an octet of bin
oct=OCTET.from_bin("101010001010100010101000101010000001011000011111")
--save the frequency of the bytes in a table (tab)
tab=oct:bytefreq()
--print the table
for byte, freq in pairs(tab) do
   	print(string.format("Byte %d: Frequency %d", byte, freq))
end
--print .. Byte 23: Frequency 1 ..
	.. Byte 32: Frequency 1 ..
	.. Byte 169: Frequency 4 ..
--all the others frequency values are 0

octet:entropy ()

Calculate the entropy of an octet structure.
Entropy is a measure of randomness or uncertainty in the data, often used in information theory.

Allocate a frequency table to store the count of each byte value.
Allocate a probability table to store the probability of each byte value.
Increment the count for each byte value in the frequency table.
Calculate the probability of each byte value.
Compute the entropy.
Compute the maximum possible entropy for the given number of unique bytes.

Returns:

1. the entropy ratio (relative to the maximum entropy)
2. the maximum possible entropy
3. he computed entropy in bits

Usage:

--create an octet of bin
oct=OCTET.from_bin("101010001010100010101000101010000001011000011111")
--save the three outpus
ratio, max_entropy, bits = oct:entropy()
print(ratio)
print(max_entropy)
print(bits)
--the three outputs are: 0.7896901, 1.584962, 1.251629

octet:popcount_hamming (oct)

Calculate the Hamming distance between two octet structures.
The Hamming distance is the number of positions at which the corresponding bits differ between the two octets. This function calculates the Hamming distance between two octets by treating them as arrays of 64-bit integers. It only works with octets whose lengths are multiples of 8 bytes. It does not handle smaller octets or padding. Ideal for applications involving large octets where performance is critical.

Parameters:

• oct an octet to compare with another one

Returns:

the Hamming distance between the two octets

Usage:

--create two octets of bin (number of bits multiple of 64)
oct=OCTET.from_bin("1010001010100010101000101010001010100010101000101010001010100010")
oct2=OCTET.from_bin("1001000010010000100100001001000010010000100100001001000010010000")
--print the Hamming distance between the two octets
print(oct:popcount_hamming(oct2))
--print: 24

octet:hamming (oct)

Calculate the Hamming distance between two octets by comparing them byte by byte and counting the number of differing bits.
It is useful for comparing binary data and measuring their similarity. This function requires the two octets to have the same length. If they differ, it throws an error. Suitable for small to medium-sized octets where simplicity is more important than performance.

Parameters:

• oct an octet to compare with another one

Returns:

the Hamming distance between the two octets

Usage:

--create two octets of bin of the same length
oct=OCTET.from_bin("101000101010001010100010101000101010001010100010")
oct2=OCTET.from_bin("100100001001000010010000100100001001000010010000")
--print the Hamming distance between the two octets
print(oct:hamming(oct2))
--print: 18

octet:charcount (char)

Count the occurrences of a specific character in an octet and return the count as an integer to Lua.
It is useful for simple character-based analysis of binary data.

Parameters:

• char the charcater to count

Returns:

the number of occurrences of a specific character

Usage:

--create a string octet
oct=OCTET.from_string("Hello world!")
--print the number of occurrences of "l"
print(oct:charcount("l"))
--print: 3

octet:crc ()

Compute the CRC-8 checksum of an octet and return the result as a new octet of length 1.
It is useful for error detection in data transmission or storage. CRC-8 is a cyclic redundancy check algorithm that produces an 8-bit checksum.

Returns:

the new octet containing the CRC-8 checksum

Usage:

--create an octet of bin
oct=OCTET.from_bin("01110100000111010100101000100111010")
print(oct:crc():bin())
--print: 10011110

octet:elide_at_start (prefix)

Create a new octet with the prefix removed. If the prefix doesn't match, it returns nil.

Parameters:

• prefix to remove

Returns:

initial octet without the prefix or nil

octet:fillrepeat (size)

Creates a new octet of given size repeating the octet as input.

Parameters:

• size

Returns:

octet of given size

Usage:

--create an octet of hex
oct=OCTET.from_hex("0xa1")
print(oct:fillrepeat(5):hex())
print: a1a1a1a1a1

octet:__lt (oct)

Compare two octet structures and determine if the first octet is lexicographically less than the second octet.

Parameters:

• oct an octet to compare

Returns:

a boolean value

Usage:

--create two octets of bin to compare
oct=OCTET.from_bin("01001010")
oct2=OCTET.from_bin("10111011")
--compare them
if (oct:__lt(oct2)) then
   	print("oct less than oct2")
else
   	print("oct2 less than oct")
end
--print: oct less than oct2

octet:__shl (positions)

Shift octet to the left by n bits. Leftmost bits disappear. This is also executed when using the 'o << n' with o an octet and n an integer.

Parameters:

• positions number of positions to bit shift to the left

Returns:

the shifted octet

Usage:

--create an octet of bin
oct=OCTET.from_bin("01001010")
--shift of three positions
print(oct:__shl(3):bin())
print: 01010000

octet:__shr (positions)

Shift octet to the right by n bits. Rightmost bits disappear. This is also executed when using the 'o >> n' with o an octet and n an integer.

Parameters:

• positions number of positions to bit shift to the right

Returns:

the shiftet octet

Usage:

--create an octet of bin
oct=OCTET.from_bin("01001010")
--shift of three positions
print(oct:__shr(3):bin())
print: 00001001

octet:shl_circular (positions)

Shift octet to the left by n bits.
Leftmost bits do not disappear but appear on the right.

Parameters:

• positions number of positions to bit shift to the left

Returns:

the circular shiftet octet

Usage:

--create an octet of bin
oct=OCTET.from_bin("01001010")
--circular shift of three positions
print(oct:shl_circular(3):bin())
--print: 01010010

octet:rhl_circular (positions)

Shift octet to the right by n bits.
Rightmost bits do not disappear but appear on the left.

Parameters:

• positions number of positions to bit shift to the right

Returns:

the circular shiftet octet

Usage:

--create an octet of bin
oct=OCTET.from_bin("01001010")
--circular shift of three positions
print(oct:shr_circular(3):bin())
--print: 01001001

octet:and_grow (oct)

Bitwise AND operation on two octets padded to reach the same length, returns a new octet. Results in a newly allocated octet, does not change the contents of any other octet involved. If the two octets have different lengths, the shorter one is padded with zeros to match the length of the longer one before performing the operation.

Parameters:

• oct an octet for the bitwise AND operation

Returns:

the result of the bitwise AND operation between the two octets

Usage:

--create two octets of bin
oct=OCTET.from_bin("0100101001001011")
oct2=OCTET.from_bin("10111011")
print(oct:and_grow(oct2):bin())
--print: 0000000000001011

octet:__band (oct)

Bitwise AND operation on two octets truncating at the shortest one length, returns a new octet. This is also executed when using the '&' operator between two octets. Results in a newly allocated octet, does not change the contents of any other octet involved.

Parameters:

• oct an octet for the bitwise AND operation

Returns:

the result of the bitwise AND operation between the two octets

Usage:

--create two octets of bin
oct=OCTET.from_bin("0100101001001011")
oct2=OCTET.from_bin("10111011")
print(oct:__band(oct2):bin())
--print: 00001010

octet:or_grow (oct)

Bitwise OR operation on two octets padded to reach the same length, returns a new octet. Results in a newly allocated octet, does not change the contents of any other octet involved. If the two octets have different lengths, the shorter one is padded with zeros to match the length of the longer one before performing the operation.

Parameters:

• oct an octet for the bitwise OR operation

Returns:

the result of the bitwise OR operation between the two octets

Usage:

--create two octets of bin
oct=OCTET.from_bin("0100101001001011")
oct2=OCTET.from_bin("10111011")
print(oct:or_grow(oct2):bin())
--print: 0100101011111011

octet:__bor (oct)

Bitwise OR operation on two octets truncating at the shortest one length, returns a new octet. This is also executed when using the '|' operator between two octets. Results in a newly allocated octet, does not change the contents of any other octet involved.

Parameters:

• oct an octet for the bitwise OR operation

Returns:

the result of the bitwise OR operation between the two octets

Usage:

--create two octets of bin
oct=OCTET.from_bin("0100101001001011")
oct2=OCTET.from_bin("10111011")
print(oct:__bor(oct2):bin())
--print: 11111011

octet:xor_grow (dest, source)

Bitwise XOR operation on two octets padded to reach the same length, returns a new octet. Results in a newly allocated octet, does not change the contents of any other octet involved.

Parameters:

• dest leftmost octet used in XOR operation
• source rightmost octet used in XOR operation

Returns:

a new octet resulting from the operation

Usage:

--create two octets of bin
oct=OCTET.from_bin("0100101001001011")
oct2=OCTET.from_bin("10111011")
print(oct:xor_grow(oct2):bin())
--print: 0100101001001011

octet:__bxor (dest, source)

Bitwise XOR operation on two octets truncating at the shortest one length, returns a new octet. This is also executed when using the '~' operator between two octets. Results in a newly allocated octet, does not change the contents of any other octet involved.

Parameters:

• dest leftmost octet used in XOR operation
• source rightmost octet used in XOR operation

Returns:

a new octet resulting from the operation

Usage:

--create two octets of bin
oct=OCTET.from_bin("0100101001001011")
oct2=OCTET.from_bin("10111011")
print(oct:__bxor(oct2):bin())
--print: 11110001

octet:__bnot ()

Bitwise NOT operation on an octet returns a new octet. This is also executed when using the '~' operator. Results in a newly allocated octet.

Returns:

the new octet containing the result of the bitwise NOT operation

Usage:

--create an octet of bin
oct=OCTET.from_bin("0100101001001011")
print(oct:__bnot():bin())
--print: 1011010110110100

octet:find (haystack, needle, pos)

Finds a needle sequence of bytes in a haystack octet and returns the position where it has been found (counting from 0) or nil when not found.

Parameters:

• haystack the octet in which to find the needle
• needle the octet needle to search for
• pos integer (optional) the position to start searching in haystack

Returns:

a number indicating the position found in haystack or nil

Usage:

--create an octet in hex
oct=OCTET.from_hex("0xa1b2c3d4")
--create the needle
needle=OCTET.from_hex("0xc3")
print(oct:find(needle))
--print: 2.0

octet:copy (haystack, start, length)

Copies out a needle octet from an haystack octet starting at position and long as indicated.

Parameters:

• haystack octet from which we copy bytes out into needle
• start integer position, begins from 0
• length integer of byte sequence to copy

Returns:

new octet copied out

Usage:

--create an octet in hex
oct=OCTET.from_hex("0xa1b2c3d4")
--define the start position equal to 1
--define the length of byte sequence to copy equal to 2
print(oct:copy(1,2):hex())
--print: b2c3

octet:paste (haystack, needle, starting)

Paste a needle octet into an haystack octet starting at position and overwriting all its byte values in place.

--create an octet of hex
oct=OCTET.from_hex("0xa1b2c3d4")
--create the needle
needle=OCTET.from_hex("0xc3")
--paste the needle in the position 1
print(oct:paste(needle,1):hex())
--print: a1c3c3d4

Parameters:

• haystack octet destination in which to copy needle
• needle octet source of needle bytes
• starting integer position to paste the needle

Returns:

the modified octet