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_kyber = 0xdbd34adf68c5f0eb , 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_proxy_set_context (pqlr_t pqlr, const void *proxy_context)
	set context for proxy backend More...
void	pqlr_proxy_context_free (pqlr_t pqlr)
	free proxy backend context More...
PQLR_API int	pqlr_proxy_connect_to_server (const char *host, int port)
	Connect to server on port. More...
PQLR_API int	pqlr_proxy_send_and_rcv (pqlr_t pqlr, int sockfd, const msgpack_sbuffer *msg, msgpack_unpacker *unp, msgpack_unpacked *und)
	Sends a packed message and blocks till gets a packed message in response, then unpacks it. 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

typedef struct pqlr_error_handler_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_no	Error code.
msg	Text message.
ctx	Pointer 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

enum 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_kyber	Linked to kyber 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_no	Error code.
msg	Text message.
ctx	Unused, 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_t pqlr = pqlr_singleton_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

	pqlr	Initialized pqlr instance
[out]	data	pointer to buffer where entropy will be written
	size	requested 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
    pqlr_error_handler_callback_t callback = {
        0,
    };
 
    // obtain pqlr_t instance, e.g. just singletone instance
    pqlr_t pqlr = pqlr_singleton_instance();
    // if you want to check specific algorithm configuration - cast it to pqlr
 
    pqlr_get_error_handler(pqlr, &callback);
 

Parameters

	pqlr	Pqlr instance.
[out]	error_handler	Pointer 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_proxy_connect_to_server()

PQLR_API int pqlr_proxy_connect_to_server	(	const char *	host,
		int	port
	)

Connect to server on port.

Parameters

host	host address
port	host port

Returns

-1 if error, socket file descriptor otherwise

pqlr_proxy_context_free()

void pqlr_proxy_context_free

(

pqlr_t

pqlr

)

free proxy backend context

Parameters

pqlr	instance of pqlr

pqlr_proxy_send_and_rcv()

PQLR_API int pqlr_proxy_send_and_rcv	(	pqlr_t	pqlr,
		int	sockfd,
		const msgpack_sbuffer *	msg,
		msgpack_unpacker *	unp,
		msgpack_unpacked *	und
	)

Sends a packed message and blocks till gets a packed message in response, then unpacks it.

Parameters

sockfd	socket file descriptor with connected host
msg	message to send to a server
unp	unpacker, keeps data buffer for reading
und	unpacked message to return

Returns

-1 if error, 0 otherwise

pqlr_proxy_set_context()

PQLR_API void pqlr_proxy_set_context	(	pqlr_t	pqlr,
		const void *	proxy_context
	)

set context for proxy backend

Parameters

pqlr	instance of pqlr
proxy_context	context to pass to proxy backend

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
    pqlr_t pqlr = pqlr_singleton_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:
    pqlr_set_error_handler(pqlr, NULL);

Parameters

pqlr	Pqlr instance.
error_handler	Pointer 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