vernam package

Submodules

vernam.configuration module

This module is intended for configuration management

vernam.configuration.parseConfig(configFromFile, configFromCmd, mode='raw')

This fuction merges configuration from config file and configuration from command line. Command line options have preference over config file.

Args:
  • configFromFile: returned from readConfig functions
  • configFromCmd: args from command line
  • mode: parse mode option
Returns:
configuration : an array with the whole configuration
vernam.configuration.readConfig(config)

This function reads configuration file and combine it with parameters from console input to generate the configuration list.

Args:
  • config: configuration file to be readed
Options:
  • keyfile (-k): str, path to a file containing the random data used as key for the cipher.
workmode: You can choose one of the following methods:
  • lz4: Will compress input or decompres output with lz4, this has a great performance with all file types.
  • human: human usable mode. key will be read as 5 bits blocks, input and output will use ownBase32 encoding. This is useful when one of the sides is doing the maths by hand.
  • raw: default operation mode, will use 1KB pages for ciphering
Returns:
An array with configuration from file

vernam.keymanagement module

Keymanagement module holds all logic for key management

vernam.keymanagement.ba2humankeyba(ba)

bytearray 2 human mode key bytearray This function converts a key bytearray to a ownbase32 key

Args
  • ba: bytearray key to be converted
Returns:
ownBase32 key
vernam.keymanagement.catalog(keyPath, l2r, force=False)

This function catalogs a new keyfile by creating a description yaml file

Args:
  • keyPath: path to the file used as key
  • l2r: True if using left to right key reading
  • force: Force yaml file overwrite
Returns:
None
vernam.keymanagement.checkCatalogUUID(keyPath, binaryUUID=None, asciiUUID=None)

Function to check key UUID and UUID used in message, returns True or False

Args:
  • keyPath: path to the file used as key
  • binaryUUID: optional, message UUID in binary format
  • asciiUUID: optional, message UUID in string format
Returns:
True if match false elsewhere
vernam.keymanagement.getCatalogUUID(keyPath)

Function to get UUID from key config file, returns an UUID object.

Args:
  • keyPath: path to the file used as key
Returns:
An UUID object with key’s UUID
vernam.keymanagement.getKeyBytes(keyPath, size, l2r=None, offset=None, waste=False)

This function read bytes from key and return them. If reading in l2r mode function will return bytes reordered to r2l. If waste is true, will mark all readebytes as used into key yaml file, when using waste offset may not be set, as we will start in the last byte used.

Args:
  • keyPath: path to the file used as key
  • size: size in bytes to read
  • l2r: True if using left to right key reading
  • offset: where in key start to read
  • waste: Mark read bytes as used and update key config
Returns:
A byte array with the portion of the key
vernam.keymanagement.getKeyHashFromKey(keyPath)

This function get the hashcode for the key, it returns a hash.

Args:
  • keyPath: path to the file used as key
Returns:
Key’s hash in hexdigest format.
vernam.keymanagement.printable(keyPath)

This function returns a string with the printable version of the key

Args:
  • keyPath: path to the file used as key
Returns:
a string with ownBase32 version of the key
vernam.keymanagement.printable2file(keyPath, outputPath, force=False)

This function performs conversion from a raw binary key file to an ownbase32 and save it in a file

Args:
  • keyPath: path to the file used as key
  • outputPath: path to the generated file
  • force: Overwrite if outputPath exists
Returns:
None

vernam.message module

Message module holds all methods to work with message files

vernam.message.readHumanMessage(inputPath)

This function reads a message in the human friendly format. Function will return two elements, key offset and the encrypted message.

Args:
  • inputPath: path to the message file to read
Returns:
An array:
  • Offset in the key
  • Encrypted message
vernam.message.readMessage(keyPath, messagePath)

This function reads a message (envelope) in the defined format, and returns the data inside the file, offset in key file and the reading mode for the key. It checks that message key UUID matchs defined key UUID, also checks consistency of message via sha512

Args:
  • keyPath: path to the file used as key
  • messagePath: path to the file used to read the message
Returns:
Data inside the envelope
vernam.message.writeHumanMessage(outputPath, message, seek)

This function writes a message in the human friendly format. Format of the message is as follows:

offset#message

Args:
  • outputPath: path to the new message file
  • message: message to write in the file
  • seek: offset in key to decrypt message
Returns:
None
vernam.message.writeMessage(keyPath, messagePath, ciphered, offsetInKey, l2r=True)
This function Writes a message in the defined format. Format of the message is as follows:
  • Header 20 bytes, as defined, two options, one for R2L and another for L2R it’s on the todo.
  • Message size in 8 bytes (64 bits) integer
  • Key UUID used in message 16 bytes
  • Message it’s self, it’s size is defined in the second field
  • Hash of the message, 32 bytes a sha512
Args:
  • keyPath: path to the file used as key
  • messagePath: path to the file used to store the message
  • ciphered: ciphered data to write in the file (envelope)
  • offsetInKey: need to jump to this byte in key to decrypt
  • l2r: Indicates if the key will need to be readed R2L or L2R (True)
Returns:
None

vernam.ownbase32 module

ownbase module handles all ownbase encoding, decoding and utilities related to ownbase alphabet

vernam.ownbase32.ba2ob32string(ba)

bytearray to ob32 string. this function converts a bytearray to an ob32 string

Args:
  • ba : bytearray to convert
Returns:
An ownBase32 compilant array
vernam.ownbase32.char2pos(c)

This function returns char position in oB32 alphabet

Args:
  • c: a character
Returns:
Char position in ownBase32 alphabet
vernam.ownbase32.getFromByte(twobytes)

This function convert a (un)signed 16 bits integer to three ob32 characters. It will be used to convert key to ob32, in order to waste as little key as possible all reads will be in done in 16 bits and 15 bits will be used (3 groups of 5)

Args:
  • data: binary raw data
Returns:
This fuction will return an array of three ob32 characters.
vernam.ownbase32.ownBase32()

This function just return the ownBase32 alphabet

vernam.ownbase32.string2ob32ba(s)

This function returns a byte array of positions in ob32 for the given strings must be ownbase32 only

Args:
  • s : string to convert
Returns:
a byte array with string’s positions
vernam.ownbase32.string2ownBase32(characters)

This function transforms a string to ownBase32. Just give a string as parameter and it will retun a string converted by best effor to ownBase32

Args:
  • characters: String to convert
Returns:
A converted strings

vernam.util module

Util module handles all unspecific utilities

vernam.util.hashSum(data)

This function helps to create hash resumes for many parts of the code. It uses sha512 as hashing algorithm

Args:
  • data : data to be hashsed
Returns:
Hash in hexdigest format

vernam.vernam module

This is the core module form verna encryption. It manages all Vernam encryption/decription stuff

vernam.vernam.decrypt(inputPath, keyPath, outputPath, force=False, mode='raw')

This function performs vernam decryption using an input file and a key, result is stored in output file.

Args:
  • inputPath : path to the file used as input
  • keyPath : path to the file used as key
  • outputPath : path to the file used as output
  • mode : working mode, Modes are:
    • raw: traditional way
    • lz4: all input data will be decompressed via lz4
    • human: all data will be converted to ownBase32 beforehand
Returns:
None
vernam.vernam.encrypt(inputPath, keyPath, outputPath, force=False, mode='raw')

This function performs vernam encryption using an input file and a key, result is stored in output file.

Args:
  • inputPath : path to the file used as input
  • keyPath : path to the file used as key
  • outputPath : path to the file used as output
  • mode : working mode, Modes are:
    • raw: traditional way
    • lz4: all input data will be compressed via lz4
    • human: all data will be converted to ownBase32 beforehand
Returns:
None
vernam.vernam.vernam(one, two)

This function performs vernam (de)ciphering with two bytearrays, order doesn’t matter as it is a pure xor fuction. function will return xored bytearray

Args:
  • one, two : Two arraybytes to perform vernam cipher.
Returns:
A bytearray with Vernam results

Module contents

Here is a Vernam cipher implementation in python. My goal with this project is achive my degree in CS ;) but also create a optimized way to use Vernam cipher in the real world(TM).

This implementation rely on a huge file filled with real random data shared with another person. For example Alice and Bob (original me).

Alice will be our creator, the person who created the huge file and Bob will be the consumer. It’s important to identify this two roles, because the use of the key file (that huge random generated file) will be different for each user.

Creator will use the file from the beggining to the end, meanwhile consumer will do it in reverse, from the end to the beggining. This is the way create a bidirectional commmuncation with only a file. As key data availability (last consumer minus last creator position used) drops under a certain thresold, software will alert you to meet your fella and interchange a new key file, and to prevent you to reuse key file. As soon the key is reused, software will alert you, so if this happend it’s on your own. If this happend it’s pretty difficult to break the whole message but, an interceptor can start to work.