PQLR
Postquantum Crypto Library by QWall
Common library

Data Structures

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

Typedefs

typedef void(* pqlr_entropy_source_fnc) (void *buf, size_t len, void *ctx)
 Type definition for entropy source function. More...
 
typedef struct pqlr_entropy_source_callback pqlr_entropy_source_callback_t
 Pqlr user's entropy source callback interface. More...
 
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. More...
 

Enumerations

enum  algorithm_id_t {
  pqlr_algorithm_general = 0xb01a41e3820cfefd, pqlr_algorithm_newhope, pqlr_algorithm_sphincs_plus, pqlr_algorithm_polynomial_hash,
  pqlr_algorithm_xmss = 0x8f4ffb1fc25105ca, pqlr_algorithm_mceliece
}
 Pqlr instance type id. More...
 

Functions

PQLR_API void pqlr_set_entropy_source (pqlr_t pqlr, pqlr_entropy_source_callback_t *entropy_source)
 Allows to specify custom entropy source for pqlr instance. This can be useful for systems with non-standard random generation methods e.g. HW random generators or custom PRNG. Custom function fills buffer located at buf with len bytes of entropy. More...
 
PQLR_API void pqlr_get_entropy_source (const pqlr_t pqlr, pqlr_entropy_source_callback_t *entropy_source)
 Returns entropy source function specified by pqlr_set_entropy_source. More...
 
PQLR_API void pqlr_get_entropy (const pqlr_t pqlr, void *data, size_t size)
 Gets entropy via entropy source configured for pqlr instance. More...
 
PQLR_API void pqlr_get_entropy_from_urandom (void *buf, size_t len, void *ctx)
 Get entropy using /dev/urandom source. More...
 
PQLR_API void pqlr_get_entropy_from_libc (void *buf, size_t len, void *ctx)
 Get entropy using libc. More...
 
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. 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 ()
 Pqlr singleton instance accessor. More...
 
PQLR_API algorithm_id_t pqlr_get_algorithm_id (pqlr_t)
 Detects algorithm type id. More...
 
PQLR_API const char * pqlr_get_version ()
 Returns null terminated string containing library version. Usage example: More...
 

Detailed Description

Shared common functions and definitions for different PQLR algorithms

Typedef Documentation

◆ pqlr_entropy_source_callback_t

Pqlr user's entropy source callback interface.

See also
pqlr_entropy_source_fnc

◆ pqlr_entropy_source_fnc

typedef void(* pqlr_entropy_source_fnc) (void *buf, size_t len, void *ctx)

Type definition for entropy source function.

Parameters
[out]bufPointer to buffer which receives entropy
lenBuffer length
ctxUser defined context, e.g. seed for entropy source, or urandom file descriptor, could be NULL (if user setup so)
See also
pqlr_entropy_source_callback

◆ 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.

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_sphincs_plus 

Linked to sphincs_plus 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.

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 entropy source configured for pqlr instance.

Usage example:

Parameters
pqlrInitialized pqlr instance
[out]datapointer to buffer where entropy will be written
sizerequested entropy size
See also
pqlr_entropy_source_callback_t
pqlr_set_entropy_source

◆ pqlr_get_entropy_from_libc()

PQLR_API void pqlr_get_entropy_from_libc ( void *  buf,
size_t  len,
void *  ctx 
)

Get entropy using libc.

This function should NEVER be used directly.

Parameters
[out]bufPreallocated empty buffer, used to return entropy.
lenRequested entropy length in bytes. Must be less or equal length of buffer pointed by buf.
ctxUnused, seed always generated from scratch

◆ pqlr_get_entropy_from_urandom()

PQLR_API void pqlr_get_entropy_from_urandom ( void *  buf,
size_t  len,
void *  ctx 
)

Get entropy using /dev/urandom source.

Available on UNIX-like systems.

This function should NEVER be used directly. The correct usage example is:

// obtain target pqlr instance
// if you want to configure specific algorithm - cast it to pqlr
NULL };
pqlr_set_entropy_source(pqlr, &callback);
Parameters
[out]bufPreallocated empty buffer, used to return entropy.
lenRequested entropy length in bytes. Must be less or equal length of buffer pointed by buf.
ctxUnused

◆ pqlr_get_entropy_source()

PQLR_API void pqlr_get_entropy_source ( const pqlr_t  pqlr,
pqlr_entropy_source_callback_t entropy_source 
)

Returns entropy source function specified by pqlr_set_entropy_source.

Usage example:

int main()
{
// obtain target pqlr instance
// if you want to check specific algorithm - cast it to pqlr
pqlr_entropy_source_callback_t entropy_source = {
0,
};
pqlr_get_entropy_source(pqlr, &entropy_source);
// ...
return 0;
}
Parameters
pqlrInitialized pqlr instance
entropy_sourcePointer where current entropy source callback set by pqlr_set_entropy_source will be stored.
See also
pqlr_entropy_source_callback_t
pqlr_set_entropy_source

◆ 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 ( )

Returns null terminated string containing library version. Usage example:

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

◆ pqlr_set_entropy_source()

PQLR_API void pqlr_set_entropy_source ( pqlr_t  pqlr,
pqlr_entropy_source_callback_t entropy_source 
)

Allows to specify custom entropy source for pqlr instance. This can be useful for systems with non-standard random generation methods e.g. HW random generators or custom PRNG. Custom function fills buffer located at buf with len bytes of entropy.

Usage example:

void custom_entropy_source(void* buf, size_t len, void* ctx)
{
if (NULL == ctx) {
abort();
}
int urandom_fd = *((int*)ctx);
read(urandom_fd, buf, len);
}
int main()
{
// obtain target pqlr instance
// if you want to configure specific algorithm - cast it to pqlr
int urandom_fd = open("/dev/urandom", O_RDONLY);
pqlr_entropy_source_callback_t callback = { custom_entropy_source,
&urandom_fd };
pqlr_set_entropy_source(pqlr, &callback);
// ...
close(urandom_fd);
return 0;
}

You can use default /dev/urandom with pqlr_get_entropy_from_urandom() function if your OS supports it.

Parameters
pqlrInitialized pqlr instance
entropy_sourcePointer to entropy source callback. Callback data will be copied. Callback instance could be destroyed after call.
See also
pqlr_entropy_source_callback_t
pqlr_get_entropy_source
pqlr_get_entropy

◆ 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.

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()
{
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 ( )

Pqlr singleton instance accessor.

Returns
singleton instance of pqlr
See also
pqlr_t