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

Octets can export their contents to portable formats as sequences of base64 or base58 or hex strings just using their appropriate methods. They can also be exported to Lua's array format.

Info:

  • Copyright: Dyne.org foundation 2017-2018
  • License: GPLv3
  • Author: Denis "Jaromil" Roio

Global Octet Functions

new ([length=4096]) 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:base58 () Print an octet in base58 notation.
octet:array () Converts an octet into an array of bytes, compatible with Lua's transformations on arrays.
octet:string () 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

So called "global functions" are all prefixed by octet., operate on one or more octet objects 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=4096])
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 4096)

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:

 octet:method(args)
 

Octet contents are never changed: the 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:base58 ()

Print an octet in base58 notation.

This encoding uses the same alphabet as Bitcoin addresses. Why base58 instead of standard base64 encoding?

  • Don't want 0OIl characters that look the same in some fonts and could be used to create visually identical looking data.
  • A string with non-alphanumeric characters is not as easily accepted as input.
  • E-mail usually won't line-break if there's no punctuation to break at.
  • Double-clicking selects the whole string as one word if it's all alphanumeric. ()

Returns:

    a string representing the octet's contents in base58
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:string ()
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.3 Last updated 2018-10-01 18:53:47
]==]