xrn-tools

Xoronos software library

This repository contains an implementation of Xoron cryptography. The software is currently not supported on Windows platforms.

Overview

The scripts can be used to generate the following outputs:

1. The static libraries for both 128 and 256 bits implementations (xrnlib-128.a, xrnlib-256.a).

2. The dynamic libraries for both 128 and 256 bits implementations (xrnlib-128.so, xrnlib-256.so).

3. The interactive command line interface, which internally loads the two dynamic libraries (xrnlib-cli).

4. The interactive command line interface to convert Xoron files to standard files and vice-versa (xrnconv-cli)

5. Python libraries (_xrnlib128.so, xrnlib128.py, _xrnlib256.so, xrnlib256.py).

6. Both C and Python code examples (examples-128, examples-256).

7. Tests for each implemented function (tests-128, tests-256).

User guide

Clone the repository

The project can cloned using the following command:

git clone https://github.com/yourusername/xrn_lib.git

Before running a script

All the front facing scripts can be found in the scripts directory. All the scripts should be run from the scripts directory.

cd ./xrn_lib/scripts

All the scripts are written assuming "sudo" as the command for privilege escalation, and "apt" as package manager. To change this behavior you can edit the initialize_host.sh, install_dependencies.sh, install.sh and uninstall.sh scripts, changing the privilege_escalation, install_cmd, update_cmd, and user_developer variables accordingly.

We recommend to run the following commands in order as shown below:

cd ./xrn_lib/scripts
./install_dependencies.sh
./initialize_host.sh
python compile_code.py
./install.sh
source $HOME/.local/xoronos/source.sh

Install dependencies

To install the required dependencies, you can run the install_dependencies.sh script as below.

./install_dependencies.sh

Initialize the host

To initialize the host operating system you can run the following command.

./initialize_host.sh

The script is used to extract all the archives present in the repository, to create directories ($HOME/.local/xoronos, $HOME/.local/cache/xoronos), and copy files in the host operating system.

This step is required to generate working scripts and code examples while running the following commands, after the program has been installed

xrnlib-cli --example command
xrnlib-cli --script command

Furthermore, this step is required to compile documentation. We recommend each user to run the initialize_host.sh script, all the files can be removed later by running the uninstall.sh script.

Compile code

To compile all the static and dynamic libraries for both C and Python, and all the outputs to install you can run:

python compile_code.py

The script will first compile a program to generate or restore secrets to be compiled in the program. The tool is used to generate:

1. The permutation key.

2. The initial encoding parameters.

If you type "generate" and "random" for both the options when prompted, which is recommended for new users, you will see on the screen the two keys that can be used to recompile in a deterministic way the Xoronos utilities.

The generated or restored secrets will be used to compile all the other outputs.

Programs that have different permutation keys will be by default incompatible with each other. This behavior can be circumvented by disabling the permutation layer at run time, for example if the xrnlib-cli program is installed you can specify the --permutation-conf -no-permutation-key option to disable the permutation layer. Programs that have different encoding parameters will be by incompatible if the --decoding-conf -compiled-param or --encoding-conf -compiled-param options are specified.

To replicate the compilation you can chose "restore" instead of "generate" while prompted, you will than requested to write up the secret keys as they appeared on the screen.

Installation

To install all the compiled outputs you can run the following command:

./install.sh

To remove all the files generated by the initialize_host.sh and install.st scripts on your system, you can run the uninstalling script as below.

./uninstall.sh

After the installation, all the Xoronos files can be found in the /etc/bash_completiiton.d/ /usr/lib/xoronos /usr/local/bin directories. If you have pandoc installed you can find the Xoronos template in /usr/share/pandoc/data/templates directory.

How to set environmental variables

To get tab auto complete for the xrnlib-cli command, to update the PYTHONPATH, LD_LIBRARY_PATH, TEXMFHOME variables you can run the following command.

source $HOME/.local/xoronos/source.sh

You can run the command also from the script directory as:

source ./source.sh

This step is important to make available shared libraries in C, and the import xrnlib256 or the import xrnlib128 instructions in python, and to compile the documentation.

To clean the environment from Xoronos paths you can run the following command:

source $HOME/.local/xoronos/unsource.sh

You can run the command also from the script directory as:

source ./unsource.sh

Running C code examples

To compile examples you can run the following command:

python compile_code.py examples-256

The compile_code.py removes all the outputs generated by previous compilations.

To get the list of examples you can run the following command.

python run.py

To run the first example you can run the following command.

python run.py 0

We provide only the 256 bits architecture for code examples. The code implementation for the 128 bits is identical to the provided 256 bits implementation. The directory for all the code examples can be found in xrn_lib/code/app/examples/c/src/.

Running Python code examples

To compile examples you can run the following command:

python compile_code.py swigpy-256

The compile_code.py removes all the outputs generated by previous compilations.

To get the list of examples you can run the following command.

python run.py

To run the first example you can run the following command.

python run.py 0

We provide only the 256 bits architecture for code examples. The code implementation for the 128 bits is identical to the provided 256 bits implementation. The directory for all the code examples can be found in xrn_lib/code/app/examples/py/.

Running tests

To compile tests using a 256 bits architecture you can run the following command:

python compile_code.py tests-256

To compile tests using a 128 bits architecture you can run the following command:

python compile_code.py tests-128

To run all the tests you can run:

python run.py

Compile documentation

To run the documentation you should first:

1. Install the required dependencies by editing and running the install_dependencies.sh script, changing the user_developer variable to "developer".

2. Initialize the host operating system by running the initialize_host.sh script.

3. Source the source.sh script to update the TEXMFHOME global variable.

A summary for all the scripts can be found below.

cd scripts
./install_dependencies.sh
./initialize_host.sh
sources ./sources.sh

To compile the documentation you can run the following command.

python compile_documentation.py

The result of the compilation can be found in the xrn_lib/build/doc directory.

cd ../build/doc

Usage

The best way to learn about the library is to use the xrnlib-cli tool.

To get the list of possible commands you can run one of the following instructions.

xrnlib-cli --help
xrnlib-cli --example
xrnlib-cli --script

The output of the previous three commands is a list of commands that can be run with comments.

The help command is used to get all the options and commands related to one instruction. One example can be found below.

xrnlib-cli --help encrypt-symmetric

The example command is used to get a working example related to one instruction.

xrnlib-cli --example encrypt-symmetric

The example command can be randomized as below.

xrnlib-cli --example -rnd encrypt-symmetric

The script command is used to generate a working script with the specified instruction included.

xrnlib-cli --scripts encrypt-symmetric

The scripts command can be randomized as below.

xrnlib-cli --scripts -rnd encrypt-symmetric

License

The code provided in this repository is licensed under the GPL3.

Contributing

We do not accept direct external code contributions to the project. We are open for constructive feedback and bug reports. The best way to report a bug is to contact us directly.

Contact

For any question or feedback, you can contact us at support@xoronos.com