Module OCTET

Base data type for cryptographic opearations

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 ??? 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 ???, base64, hex or even ??? 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

new ([length=64]) Create a new octet with a specified maximum size, or a default if omitted.
xor (dest, source) Bitwise XOR operation on two octets, returns a new octet.
concat (dest, source) Concatenate two octets, returns a new octet.

Class OCTET

octet:base64 () Print an octet in base64 notation.
octet:array () Converts an octet into an array of bytes, compatible with Lua's transformations on arrays.
octet:str () Print an octet as string.
octet:hex () Converts an octet into a string of hexadecimal numbers representing its contents.
octet:pad ([length=octet:max]) Pad an octet with leading zeroes up to indicated length or its maximum size.
octet:zero ([length=octet:max]) Fill an octet with zero values up to indicated size or its maximum size.
octet:eq () Compare two octets to see if contents are equal.


Global OCTET Functions

The "global OCTET functions" are all prefixed by OCTET. (please note the separator is a "." dot) and always return a new octet resulting from the operation.

This is a difference with "object methods" listed in the next section which are operating on the octet itself, doing "in place" modifications. Plan well what to use to save memory space and computations.

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

Parameters:

  • length int maximum length in bytes (default 64)

Returns:

    octet newly instantiated octet
xor (dest, source)
Bitwise XOR operation on two octets, 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. (dest, source)

Parameters:

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

Returns:

    a new octet resulting from the operation
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. (dest, source)

Parameters:

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

Returns:

    a new octet resulting from the operation

Class OCTET

Object Methods

This section lists methods that can be called as members of the OCTET: objects, using a ":" semicolon notation instead of a dot. Example synopsis:

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

In the example above we create a new "random" OCTET variable with 32 bytes of randomness, then call the ":hex()" method on it to print it out as an hexadecimal sequence.

The contents of an octet object are never changed this way: methods always return a new octet with the requested changes applied.

octet:base64 ()
Print an octet in base64 notation. ()

Returns:

    a string representing the octet's contents in base64

See also:

Usage:

    -- This method as well :string() and :hex() can be used both to set
-- from and print out in particular formats.

-- create an octet from a string:
msg = OCTET.string("my message to be encoded in base64")
-- print the message in base64 notation:
print(msg:base64())
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:str ()
Print an octet as string. ()

Returns:

    a string representing the octet's contents
octet:hex ()
Converts an octet into a string of hexadecimal numbers representing its contents.

This is the default format when print() is used on an octet. ()

Returns:

    a string of hexadecimal numbers
octet:pad ([length=octet:max])
Pad an octet with leading zeroes up to indicated length or its maximum size. (length)

Parameters:

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

Returns:

    new octet padded at length
octet:zero ([length=octet:max])
Fill an octet with zero values up to indicated size or its maximum size. (length)

Parameters:

  • length int fill with zero up to this size, use maxumum octet size if omitted (default octet:max)
octet:eq ()
Compare two octets to see if contents are equal. (first, second)

Returns:

    true if equal, false otherwise
generated by LDoc 1.4.6 Last updated 2020-04-16 01:32:19