PQLR
Postquantum Crypto Library by QAPP
Common library

Data Structures

struct  pqlr_error_handler_callback
 Pqlr user's error handler callback interface. More...
 

Typedefs

typedef void(* pqlr_error_handler_fnc) (int err_no, const char *msg, void *ctx)
 Type definition for error handling function. Place to free user defined resources before termination. More...
 
typedef struct pqlr_error_handler_callback pqlr_error_handler_callback_t
 Pqlr user's error handler callback interface. More...
 
typedef struct pqlr_st * pqlr_t
 Pqlr instance handle. Pqlr represents basic library and it's algorithms configuration. There are singleton instance which could be obtained by pqlr_singleton_instance and local instances which could be obtained from concrete algorithms instances. At the initialization point all the algorithms inherit pqlr's singleton instance state. Any change in the global configuration does not affect previously created algorithms. More...
 

Enumerations

enum  algorithm_id_t {
  pqlr_algorithm_general = 0xb01a41e3820cfefd, pqlr_algorithm_newhope, pqlr_algorithm_saber = 0xc83c3990d6c012b3, pqlr_algorithm_sphincs_plus,
  pqlr_algorithm_sphinxp_gost, pqlr_algorithm_hypericum, pqlr_algorithm_falcon, pqlr_algorithm_dilithium,
  pqlr_algorithm_shipovnik, pqlr_algorithm_kryzhovnik, pqlr_algorithm_rainbow, pqlr_algorithm_polynomial_hash,
  pqlr_algorithm_xmss = 0x8f4ffb1fc25105ca, pqlr_algorithm_mceliece, pqlr_algorithm_drbg = 0xcb86e336a7c49070, pqlr_algorithm_xmssmt
}
 Pqlr instance type id. More...
 

Functions

PQLR_API void pqlr_set_error_handler (pqlr_t pqlr, pqlr_error_handler_callback_t *error_handler)
 Allows to specify custom fatal error handler for pqlr instance. Please, note that any change in the global PQLR configuration does not affect previously created algorithms. More...
 
PQLR_API void pqlr_get_error_handler (const pqlr_t pqlr, pqlr_error_handler_callback_t *error_handler)
 Obtains custom error handler specified by pqlr_set_error_handler(). More...
 
PQLR_API void pqlr_default_error_handler (int err_no, const char *msg, void *ctx)
 Default pqlr fatal error handler. Prints error string to stderr. More...
 
PQLR_API pqlr_t pqlr_singleton_instance (void)
 Pqlr singleton instance accessor Please, note that any change in the global PQLR configuration does not affect previously created algorithms. More...
 
PQLR_API algorithm_id_t pqlr_get_algorithm_id (pqlr_t)
 Detects algorithm type id. More...
 
PQLR_API void pqlr_get_entropy (const pqlr_t pqlr, void *data, size_t size)
 Gets entropy via default entropy source. More...
 
PQLR_API const char * pqlr_get_version (void)
 Returns null terminated string containing library version. Usage example: More...
 

Detailed Description

Shared common functions and definitions for different PQLR algorithms

Typedef Documentation

◆ pqlr_error_handler_callback_t

Pqlr user's error handler callback interface.

In case of fatal error in any pqlr algorithm abort() will be called. If set this callback would be called just before the abort.

See also
pqlr_error_handler_fnc

◆ pqlr_error_handler_fnc

typedef void(* pqlr_error_handler_fnc) (int err_no, const char *msg, void *ctx)

Type definition for error handling function. Place to free user defined resources before termination.

Warning
In case of it throws exception or performs longjmp behaviour is undefined
Parameters
err_noError code.
msgText message.
ctxPointer to user defined data. Could be used as link to resources which are should be made free.

◆ pqlr_t

typedef struct pqlr_st* pqlr_t

Pqlr instance handle. Pqlr represents basic library and it's algorithms configuration. There are singleton instance which could be obtained by pqlr_singleton_instance and local instances which could be obtained from concrete algorithms instances. At the initialization point all the algorithms inherit pqlr's singleton instance state. Any change in the global configuration does not affect previously created algorithms.

Note
All operations on singleton instance are thread-safe.
All operations on local instance are reentrant.
See also
pqlr_singleton_instance

Enumeration Type Documentation

◆ algorithm_id_t

Pqlr instance type id.

Enumerator
pqlr_algorithm_general 

Singleton instance id.

pqlr_algorithm_newhope 

Linked to newhope instance id.

pqlr_algorithm_saber 

Linked to saber instance id.

pqlr_algorithm_sphincs_plus 

Linked to sphincs_plus instance id.

pqlr_algorithm_sphinxp_gost 

Linked to sphinxp_gost instance id.

pqlr_algorithm_hypericum 

Linked to hypericum instance id.

pqlr_algorithm_falcon 

Linked to falcon instance id.

pqlr_algorithm_dilithium 

Linked to dilithium instance id.

pqlr_algorithm_shipovnik 

Linked to shipovnik instance id.

pqlr_algorithm_kryzhovnik 

Linked to kryzhovnik instance id.

pqlr_algorithm_rainbow 

Linked to rainbow instance id.

pqlr_algorithm_polynomial_hash 

Linked to polynomial_hash instance id.

pqlr_algorithm_xmss 

Linked to xmss instance id.

pqlr_algorithm_mceliece 

Linked to mceliece instance id.

pqlr_algorithm_drbg 

Linked to drbg instance id.

pqlr_algorithm_xmssmt 

Linked to xmssmt instance id.

Function Documentation

◆ pqlr_default_error_handler()

PQLR_API void pqlr_default_error_handler ( int  err_no,
const char *  msg,
void *  ctx 
)

Default pqlr fatal error handler. Prints error string to stderr.

Parameters
err_noError code.
msgText message.
ctxUnused, could be NULL

◆ pqlr_get_algorithm_id()

PQLR_API algorithm_id_t pqlr_get_algorithm_id ( pqlr_t  )

Detects algorithm type id.

Returns
pqlr algorithm id
See also
pqlr_t
algorithm_id_t

◆ pqlr_get_entropy()

PQLR_API void pqlr_get_entropy ( const pqlr_t  pqlr,
void *  data,
size_t  size 
)

Gets entropy via default entropy source.

Usage example:

int main(void)
{
// obtain target pqlr instance
pqlr_sei_t sei;
// if you want to obtain source of entropy input from pqlr instance - call
// pqlr_get_sei
sei = pqlr_get_sei(pqlr);
// ...
// Do not forget to free allocated resources
pqlr_sei_free(sei);
return 0;
}
Parameters
pqlrInitialized pqlr instance
[out]datapointer to buffer where entropy will be written
sizerequested entropy size

◆ pqlr_get_error_handler()

PQLR_API void pqlr_get_error_handler ( const pqlr_t  pqlr,
pqlr_error_handler_callback_t error_handler 
)

Obtains custom error handler specified by pqlr_set_error_handler().

Usage:

// prepare callback storage
0,
};
// obtain pqlr_t instance, e.g. just singletone instance
// if you want to check specific algorithm configuration - cast it to pqlr
pqlr_get_error_handler(pqlr, &callback);
Parameters
pqlrPqlr instance.
[out]error_handlerPointer to error handling callback.
See also
pqlr_error_handler_callback_t
pqlr_set_error_handler
pqlr_t

◆ pqlr_get_version()

PQLR_API const char* pqlr_get_version ( void  )

Returns null terminated string containing library version. Usage example:

const char* version = pqlr_get_version();
Returns
Null terminated string containing library version.

◆ pqlr_set_error_handler()

PQLR_API void pqlr_set_error_handler ( pqlr_t  pqlr,
pqlr_error_handler_callback_t error_handler 
)

Allows to specify custom fatal error handler for pqlr instance. Please, note that any change in the global PQLR configuration does not affect previously created algorithms.

Usage example:

typedef struct my_app_state
{
void* resource1;
FILE* resource2;
} my_app_state_t;
void custom_error_handler(int err_code, const char* error, void* ctx)
{
// free resources
my_app_state_t* state = (my_app_state_t*)ctx;
free(state->resource1);
fflush(state->resource2);
fclose(state->resource2);
// e.t.c
// perform logging, e.g. call default callback
pqlr_default_error_handler(err_code, error, ctx);
}
int main(void)
{
my_app_state_t state = {
0,
};
state.resource1 = malloc(42);
state.resource2 = fopen("test", "rw");
pqlr_error_handler_callback_t callback = { custom_error_handler, &state };
// obtain pqlr_t instance, e.g. just singletone instance
// if you want to configure specific algorithm - cast it to pqlr
pqlr_set_error_handler(pqlr, &callback);
// initiate error, e.g. try to set invalid error handler:
Parameters
pqlrPqlr instance.
error_handlerPointer to error handler callback struct. If NULL, program will exit immediately on fatal error.
See also
pqlr_error_handler_callback_t
pqlr_get_error_handler
pqlr_t

◆ pqlr_singleton_instance()

PQLR_API pqlr_t pqlr_singleton_instance ( void  )

Pqlr singleton instance accessor Please, note that any change in the global PQLR configuration does not affect previously created algorithms.

Returns
singleton instance of pqlr or NULL if out of memory
See also
pqlr_t