xrn_common.md 28 KB
Common library
Introduction
The common library is used to define common functions for the cryptography library. The library defines return values, printing messages, checksum functions and types for file and byte streams.
Definitions
Library header.
#ifndef XORON_COMMON_H
#define XORON_COMMON_H
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <string.h>
#include <time.h>
#include "xrn_settings.h"
The XRN_MAX_STR_SIZE is used to define the maximum string length for string manipulation int the library.
#define XRN_MAX_STR_SIZE 2048
The XRN_SUBJECT_CERTIFICATE_LENGTH is used to define the maximum string length for the subject in certificates.
#define XRN_SUBJECT_CERTIFICATE_LENGTH 512
The XRN_BUFF_SIZE is used to define the maximum string length for a generic buffer.
#define XRN_BUFF_SIZE 256
The XRN_CHKSUM_BUFF is used to define the buffer size in xnums for the check sums dump.
#define XRN_CHKSUM_BUFF 32
The XRN_MIN_ALLOWED_STATE_SIZE define is used to define the minimum size of a state size in all the algorithms.
#define XRN_MIN_ALLOWED_STATE_SIZE 4
The XRN_MAGIC_NUMBER_BLOCK define is used to define the magic number for a block file.
#define XRN_MAGIC_NUMBER_BLOCK 0x22fe2022
The XRN_MAGIC_NUMBER_ENCODED_BLOCK define is used to define the magic number for an encoded block file.
#define XRN_MAGIC_NUMBER_ENCODED_BLOCK 0x23fe2022
The XRN_MAX_MERGE_PARALLELISM define is the maximum number of blocks that can be merged in parallel.
#define XRN_MAX_MERGE_PARALLELISM 64
Extra include
#include "xrn_common_backend.h"
Output streams definition for errors, warnings, notification and debug messages.
#define XSTD_ERROR_OUTPUT stderr
#define XSTD_WARNING_OUTPUT stdout
#define XSTD_NOTIFICATION_OUTPUT stdout
#define XSTD_DEBUG_OUTPUT stdout
Predefined printing messages.
#define XERR_IO_MSG "input output fault"
#define XERR_NULL_MSG "null pointer detected"
#define XERR_ENDS_MSG "detected equal ends"
#define XERR_CRC_MSG "crc unmatched"
#define XWAR_TRY_MSG "maximum number of tries reached"
#define XERR_VERSION_MSG "not supported version"
#define XERR_END_DEC_MSG "unexpected end"
#define XERR_NBITS_MSG "non coherent number of bits"
#define XERR_PADDING_MSG "inconsinstent padding"
#define XERR_TYPE_MSG "wrong data type"
#define XWAR_SIG_MSG "unmatched signature"
#define XERR_STARTS_MSG "different start points"
#define XWAR_FORMAT_MSG "unexpected format"
#define XERR_CRYPTO_MSG "failed crypto primitive"
#define XERR_BUFF_MSG "not sufficient buffer size"
#define XERR_SUBJECT_MSG "subject out of boundery"
#define XWAR_TIMING_MSG "data structure expired"
#define XERR_TIMING_MSG "data structure expired"
#define XERR_GENERAL_MSG "generic error"
#define XERR_STR_MSG "wrong formatted string"
#define XERR_SETTINGS_MSG "wrong settings"
#define XERR_JOIN_MSG "headers do not match"
#define XWAR_PROOF_MSG "proof not valid"
#define XERR_MAGIC_MSG "wrong magic number"
#define XERR_NLINEAR_START_MSG "either entry point or dead code used as start point"
#define XERR_NLINEAR_MSG "non linear exception"
#define XINFO_PERMUTED_MATRIX_MSG "xoron matrix has been permuted"
#define XERR_NOT_MATRIX_MSG "not valid xoron matrix"
#define XERR_SPARSE_MKEY_MSG "sparse monomial key"
#define XERR_NOT_GENESIS_MSG "invalid xoron genesis base"
#define XERR_RING_SIG_SIZE_MSG "not supported ring signature size"
#define XERR_ENC_STRUCTURES_MSG "invalid encoding data structure"
#define XERR_PASS_LEN_MSG "out of range password"
#define XERR_INC_PERM_MSG "inconsistent permutation layer"
#define XWAR_VERSION_MSG "version partially supported"
#define XERR_PROB_ENC_C0_MSG "too many consecutive zeroes"
#define XERR_PROB_ENC_C1_MSG "too many consecutive ones"
#define XERR_PROB_ENC_0_MSG "too many zeroes"
#define XERR_PROB_ENC_1_MSG "too many ones"
#define XWAR_PROB_ENC_C0_MSG "suspecious number of consecutive zeroes"
#define XWAR_PROB_ENC_C1_MSG "suspecious number of consecutive ones"
#define XWAR_PROB_ENC_0_MSG "suspecious number of zeroes"
#define XWAR_PROB_ENC_1_MSG "suspecious number of ones"
#define XWAR_STEG_CAPACITY_MSG "low capacity in envelop"
#define XNOT_EQUAL_MSG "non equal data structure"
#define XSUCCESS_MSG "correct function execution"
#define XEQUAL_MSG "equal data structure"
#define XCOMPLETE_MSG "complete data structure"
#define XNCOMPLETE_MSG "non complete data structure"
Predefined return values.
#define XINFO_PERMUTED_MATRIX ( 0x00000002 )
#define XNOT_EQUAL ( 0x00000001 )
#define XSUCCESS ( 0x00000000 )
#define XEQUAL ( 0x00000000 )
#define XCOMPLETE ( 0x00000000 )
#define XNCOMPLETE ( 0x00000001 )
#define XERR_OPCODE 0x40000000
#define XERR_GENERAL ( 0 | XERR_OPCODE )
#define XERR_IO ( 1 | XERR_OPCODE )
#define XERR_NULL ( 2 | XERR_OPCODE )
#define XERR_CRC ( 3 | XERR_OPCODE )
#define XERR_VERSION ( 4 | XERR_OPCODE )
#define XERR_END_DEC ( 5 | XERR_OPCODE )
#define XERR_NBITS ( 6 | XERR_OPCODE )
#define XERR_PADDING ( 7 | XERR_OPCODE )
#define XERR_TYPE ( 8 | XERR_OPCODE )
#define XERR_NOT_GENESIS ( 9 | XERR_OPCODE )
#define XERR_NOT_MATRIX ( 10 | XERR_OPCODE )
#define XERR_STARTS ( 11 | XERR_OPCODE )
#define XERR_CRYPTO ( 12 | XERR_OPCODE )
#define XERR_BUFF ( 13 | XERR_OPCODE )
#define XERR_BLOCK_I ( 14 | XERR_OPCODE )
#define XERR_SUBJECT ( 15 | XERR_OPCODE )
#define XERR_SETTINGS ( 16 | XERR_OPCODE )
#define XERR_JOIN ( 17 | XERR_OPCODE )
#define XERR_STR ( 18 | XERR_OPCODE )
#define XERR_MAGIC ( 19 | XERR_OPCODE )
#define XERR_NLINEAR_START ( 20 | XERR_OPCODE )
#define XERR_NLINEAR ( 21 | XERR_OPCODE )
#define XERR_SPARSE_MKEY ( 22 | XERR_OPCODE )
#define XERR_RING_SIG_SIZE ( 23 | XERR_OPCODE )
#define XERR_ENC_STRUCTURES ( 24 | XERR_OPCODE )
#define XERR_PROB_ENC_C0 ( 25 | XERR_OPCODE )
#define XERR_PROB_ENC_C1 ( 26 | XERR_OPCODE )
#define XERR_PROB_ENC_0 ( 27 | XERR_OPCODE )
#define XERR_PROB_ENC_1 ( 28 | XERR_OPCODE )
#define XERR_TIMING ( 29 | XERR_OPCODE )
#define XERR_ENDS ( 30 | XERR_OPCODE )
#define XERR_INC_PERM ( 31 | XERR_OPCODE )
#define XWAR_OPCODE 0x80000000
#define XWAR_TIMING ( 0x00001000 | XWAR_OPCODE )
#define XWAR_FORMAT ( 0x00002000 | XWAR_OPCODE )
#define XWAR_SIG ( 0x00004000 | XWAR_OPCODE )
#define XWAR_VERSION ( 0x00008000 | XWAR_OPCODE )
#define XWAR_TRY ( 0x00010000 | XWAR_OPCODE )
#define XWAR_PROB_ENC_C0 ( 0x00020000 | XWAR_OPCODE )
#define XWAR_PROB_ENC_C1 ( 0x00040000 | XWAR_OPCODE )
#define XWAR_PROB_ENC_0 ( 0x00080000 | XWAR_OPCODE )
#define XWAR_PROB_ENC_1 ( 0x00100000 | XWAR_OPCODE )
#define XWAR_PROOF ( 0x00200000 | XWAR_OPCODE )
#define XWAR_STEG_CAPACITY ( 0x00400000 | XWAR_OPCODE )
Type definitions
xrn_log_t
The file pointers defining where to log.
typedef struct xrn_log_t {
FILE * err_fp ;
FILE * war_fp ;
FILE * not_fp ;
FILE * deb_fp ;
uint8_t err_en ;
uint8_t war_en ;
uint8_t not_en ;
uint8_t deb_en ;
uint32_t deb_seed ;
uint32_t war_shown ;
} xrn_log_t ;
extern xrn_log_t xlog;
The err_fp field defines the file pointer for the error stream.
The war_fp field defines the file pointer for the warning stream.
The not_fp field defines the file pointer for the notification stream.
The deb_fp field defines the file pointer for the debugging stream.
The err_en field defines weather the error stream is enabled.
The war_en field defines weather the warning stream is enabled.
The not_en field defines weather the notification stream is enabled.
The deb_en field defines weather the debugging stream is enabled.
The deb_seed field defines the seed for the current run of the program.
The war_shown field defines the if a warning was already displayed.
xrn_crypto_lib_header_t
Definition of headers for crypto_lib files and bit streams are given below.
typedef struct xrn_crypto_lib_header_t {
uint8_t encoding_guard[256] ;
uint32_t magic_number ;
uint32_t version ;
uint32_t reserved_0 ;
uint32_t reserved_1 ;
uint8_t type ;
uint8_t state_size ;
uint8_t crc8 ;
} xrn_crypto_lib_header_t ;
The encoding_guard field defines the random sequence to protect the encoding layer.
The magic_number field defines the unique number for a file of the Xoron library.
The version field defines the version for the header, algorithms, input/output, and minor changes.
The permutation_id field defines the compiled version for the permutation layer.
The reserved_0 field is not defined in the library.
The reserved_1 field is not defined in the library.
The type field defines the content file enumerate as defined in xrn_lib_xtype_t.
The state_size field defines the number of variables in a cipher block.
The crc8 field defines the checksum for the header.
Enumerations definition
xrn_lib_xtype_t
Definitions used to identify the file types of the file are given below.
typedef enum {
c_genesis = 0,
c_base = 1,
c_vector = 2,
c_matrix = 3,
c_matrix_compressed = 4,
c_start = 5,
c_monomial_key = 6,
c_binomial_key = 7,
c_point = 8,
c_hash = 9,
c_signature_sym = 10,
c_signature_asy = 11,
c_ring_signature = 12,
c_certificate_sym = 13,
c_certificate_asy = 14,
c_monomial_commitment = 15,
c_binomial_commitment = 16,
c_monomial_response = 17,
c_monomial_proof = 18,
c_polyvalent_proof = 19,
c_polyvalent_key = 20,
c_monovalent_key = 21,
c_challenge = 22,
c_solution = 23,
c_sym_encryption = 24,
c_asy_encryption = 25
} xrn_lib_xtype_t ;
Checksum Functions
xrn_make_checksums_wrapper
Description:
The xrn_make_checksums_wrapper is used to dump checksums.
Function declaration:
int xrn_make_checksums_wrapper (
FILE *fpi,
FILE *fpo
);
Arguments description:
input: fpi $\rightarrow$ The input file pointer. \ output: fpo $\rightarrow$ The output file pointer.
xrn_dump_checksums_bytes_wrapper
Description:
The xrn_dump_checksums_bytes_wrapper is used to dump checksums from a stream of bytes.
Function declaration:
int xrn_dump_checksums_bytes_wrapper (
uint8_t * i_bytes,
uint64_t i_length,
uint8_t * o_bytes,
uint64_t o_length,
uint64_t * o_written_bytes
);
Arguments description:
input: i_bytes $\rightarrow$ The input stream of bytes. \ input: i_length $\rightarrow$ The length of the stream of input bytes.\ output: o_bytes $\rightarrow$ The output stream of bytes.\ input: o_length $\rightarrow$ The output stream of bytes.\ output: o_written_bytes $\rightarrow$ The number of written bytes.
xrn_estimate_checksum_bytes_length
Description:
The xrn_estimate_checksum_bytes_length is used to estimate the output length size.
Function declaration:
int xrn_estimate_checksum_bytes_length (
uint64_t i_length,
uint64_t * o_length
);
Arguments description:
input: i_length $\rightarrow$ The length of the stream of input bytes. \ output: o_length $\rightarrow$ The length of the stream of output bytes.
xrn_check_checksums_wrapper
Description:
The xrn_check_checksums_wrapper is used to compare a file with a checksum dump.
Function declaration:
int xrn_check_checksums_wrapper(
FILE *fpi,
FILE *fpc
);
Arguments description:
input: fpi $\rightarrow$ The input file pointer. \ input: fpc $\rightarrow$ The checksum file pointer.
xrn_check_checksums_bytes_wrapper
Description:
The xrn_check_checksums_bytes_wrapper is used to compare a stream of bytes with a checksum dump.
Function declaration:
int xrn_check_checksums_bytes_wrapper (
uint8_t * i_bytes,
uint64_t i_length,
uint8_t * ck_bytes,
uint64_t ck_length
);
Arguments description:
input: i_bytes $\rightarrow$ The input stream of bytes. \ input: i_length $\rightarrow$ The length of the stream of input bytes. \ input: ck_bytes $\rightarrow$ The stream of checksums bytes. \ input: ck_length $\rightarrow$ The length of the stream of checksums bytes.
Logging Functions
xrn_set_default_log
Description:
The xrn_set_default_log is used to set all the default log stream.
Function declaration:
void xrn_set_default_log (
);
xrn_change_error_log
Description:
The xrn_change_error_log is used to set the error log stream.
Function declaration:
int xrn_change_error_log ( FILE *fp , uint8_t err_en );
Arguments description:
input: fp $\rightarrow$ The error file pointer. \ input: err_en $\rightarrow$ The error file enable
xrn_change_warning_log
Description:
The xrn_change_warning_log is used to set the warning log stream.
Function declaration:
int xrn_change_warning_log (
FILE *fp,
uint8_t war_en
);
Arguments description:
input: fp $\rightarrow$ The warning file pointer. \ input: war_en $\rightarrow$ The warning file enable.
xrn_change_notification_log
Description:
The xrn_change_notification_log is used to set the notification log stream.
Function declaration:
int xrn_change_notification_log (
FILE *fp,
uint8_t not_en
);
Arguments description:
input: fp $\rightarrow$ The notification file pointer. \ input: not_en $\rightarrow$ The notification file enable.
xrn_change_debug_log
Description:
The xrn_change_debug_log is used to set the debug log stream.
Function declaration:
int xrn_change_debug_log (
FILE *fp,
uint8_t deb_en,
uint32_t deb_seed
);
Arguments description:
input: fp $\rightarrow$ The debug file pointer. \ input: deb_en $\rightarrow$ The debug file enable. \ input: deb_seed $\rightarrow$ The debug seed to identify each run.
Type Functions
xrn_convert_libtype_to_string
Description:
The xrn_convert_libtype_to_string is used to convert a xrn_lib_xtype_t value into a string.
Function declaration:
int xrn_convert_libtype_to_string (
xrn_lib_xtype_t type,
char * buff,
int len
);
Arguments description:
input: type $\rightarrow$ The type describes what file or byte-stream need to be converted into a string. \ output: buff $\rightarrow$ The string to store the name. \ input: len $\rightarrow$ The length of the output string, which is used to check if the buffer length is sufficiently large.
xrn_convert_string_to_libtype
Description:
The xrn_convert_string_to_libtype is used to convert a string into a xrn_lib_xtype_t.
Function declaration:
int xrn_convert_string_to_libtype (
char * buff,
xrn_lib_xtype_t * type
);
Arguments description:
input: buff $\rightarrow$ The string to store the name. \ output: type $\rightarrow$ The type describes what file or byte-stream need to be converted into a string.
Version Comparison Function
xrn_compare_version
Description:
The xrn_compare_version is used to evaluate if the provided version is compatible with the current build of the library.
Function declaration:
int xrn_compare_version (
uint32_t version,
uint32_t git_ref
);
Arguments description:
input: version $\rightarrow$ The version to evaluate. \ input: git_ref $\rightarrow$ The git version.
xrn_store_warnings_in_return_value
Description:
The xrn_store_warnings_in_return_value is used to asses if the return value is a warning or an error. In the case of a warning the function collect the warning values.
Function declaration:
int xrn_store_warnings_in_return_value (
int current_return,
int previous_version
);
Arguments description:
input: version $\rightarrow$ The version to evaluate.
Block Functions
xrn_check_complete_blocks
Description:
The xrn_check_complete_blocks is used to asses if the block file is complete.
Function declaration:
int xrn_check_complete_blocks (
FILE * fpi
);
Arguments description:
input: fpi $\rightarrow$ The file pointer.
xrn_join_blocks
Description:
The xrn_join_blocks is used to merge two blocks of file into one.
Function declaration:
int xrn_join_blocks (
FILE * in_files[XRN_MAX_MERGE_PARALLELISM],
uint8_t number_of_inputs,
FILE * out_file
);
Arguments description:
input: in_files $\rightarrow$ The array of file pointers that collects all the blocks to be mereged. \ input: number_of_inputs $\rightarrow$ The number of input file pointers. \ output: out_file $\rightarrow$ The output file pointer for the merged block files.
xrn_make_block
Description:
The xrn_make_block is used to create a block file.
Function declaration:
int xrn_make_block (
FILE * fpi,
FILE * fpo,
uint32_t tag,
uint64_t offset,
uint64_t length
);
Arguments description:
input: fpi $\rightarrow$ The input file pointer. \ output: fpo $\rightarrow$ The output file pointer. \ input: tag $\rightarrow$ The tag to be written in the header. \ input: offset $\rightarrow$ The offset to be written in the header. \ input: length $\rightarrow$ The length of the block to be written in the header.
xrn_strip_header_from_block
Description:
The xrn_strip_header_from_block is used to remove the header for a block file.
Function declaration:
int xrn_strip_header_from_block (
FILE * fpi,
FILE * fpo
);
Arguments description:
input: fpi $\rightarrow$ The input file pointer. \ output: fpo $\rightarrow$ The output file pointer.
xrn_estimate_block_bytes_length
Description:
The xrn_estimate_block_bytes_length is used to get the size of the output buffer for a block.
Function declaration:
int xrn_estimate_block_bytes_length (
uint64_t i_length,
uint64_t * o_length
);
Arguments description:
input: i_length $\rightarrow$ The size of the input bytes. \ output: o_length $\rightarrow$ The size of the output bytes.
xrn_estimate_block_bytes_length_merge
Description:
The xrn_estimate_block_bytes_length_merge is used to get the size of the output merged buffer for a block.
Function declaration:
int xrn_estimate_block_bytes_length_merge (
uint64_t lengths[XRN_MAX_MERGE_PARALLELISM],
uint8_t num_inputs,
uint64_t * o_length
);
Arguments description:
input: lengths $\rightarrow$ The lengths in bytes of the streams that are going to be merged. \ input: num_inputs $\rightarrow$ The number of input streams. \ output: o_length $\rightarrow$ The size of the output bytes.
xrn_estimate_block_bytes_length_strip
Description:
The xrn_estimate_block_bytes_length_strip is used to get the size of the output stripped buffer for a block.
Function declaration:
int xrn_estimate_block_bytes_length_strip (
uint64_t i_length,
uint64_t * o_length
);
Arguments description:
input: i_length $\rightarrow$ The size of the input bytes. \ output: o_length $\rightarrow$ The size of the output bytes.
xrn_check_complete_blocks_bytes
Description:
The xrn_check_complete_blocks_bytes is used to asses if the block stored in the bytes is complete.
Function declaration:
int xrn_check_complete_blocks_bytes(
uint8_t * i_bytes,
uint64_t i_length
);
Arguments description:
input: i_bytes $\rightarrow$ The input bytes. \ input: i_length $\rightarrow$ The size of the output bytes.
xrn_join_blocks_bytes
Description:
The xrn_join_blocks_bytes is used to merge two stream of blocks stored in bytes into one.
Function declaration:
int xrn_join_blocks_bytes (
uint8_t * i_bytes[XRN_MAX_MERGE_PARALLELISM],
uint64_t i_length[XRN_MAX_MERGE_PARALLELISM],
uint8_t number_of_inputs,
uint8_t * o_bytes,
uint64_t o_length
);
Arguments description:
input: i_bytes $\rightarrow$ The stream of bytes that can not be overwritten by the secondary stream of bytes. \ input: i_length $\rightarrow$ The length for the primary stream of bytes. \ input: number_of_inputs $\rightarrow$ the number of provided inputs. \ output: o_bytes $\rightarrow$ The streams of the output bytes. \ input: o_length $\rightarrow$ The length of the output stream of bytes.
xrn_make_block_bytes
Description:
The xrn_make_block_bytes is used to create a block stream of bytes.
Function declaration:
int xrn_make_block_bytes (
uint8_t * i_bytes,
uint64_t i_length,
uint8_t * o_bytes,
uint64_t o_length,
uint32_t tag,
uint64_t offset,
uint64_t length
);
Arguments description:
input: i_bytes $\rightarrow$ The input stream of bytes. \ input: i_length $\rightarrow$ The size of the input stream of bytes. \ output: o_bytes $\rightarrow$ The output stream of bytes. \ input: o_length $\rightarrow$ The size of the output stream of bytes. \ input: tag $\rightarrow$ The tag that should be written in the file header. \ input: offset $\rightarrow$ The offset from where to start the block. \ input: length $\rightarrow$ The size of the block.
xrn_strip_header_from_block_bytes
Description:
The xrn_strip_header_from_block_bytes is used to remove the header for a block stream of bytes.
Function declaration:
int xrn_strip_header_from_block_bytes (
uint8_t * i_bytes,
uint64_t i_length,
uint8_t * o_bytes,
uint64_t o_length
);
Arguments description:
input: i_bytes $\rightarrow$ The input stream of bytes. \ input: i_length $\rightarrow$ The size of the input stream of bytes. \ output: o_bytes $\rightarrow$ The output stream of bytes. \ input: o_length $\rightarrow$ The size of the output stream of bytes.
Type Checks
xrn_check_valid_type
Description:
The xrn_check_valid_type is used to evaluate if the type is a Xoron type.
Function declaration:
int xrn_check_valid_type (
xrn_lib_xtype_t type
);
Arguments description:
input: type $\rightarrow$ The type of file.
xrn_print_all_warnings
Description:
The xrn_print_all_warnings is used to print all the warnings of a return value.
Function declaration:
void xrn_print_all_warnings (
uint32_t current_return
);
Arguments description:
input: current_return $\rightarrow$ The return value of a library function.
End of the library
#endif