PQLR common algorithm interface

Macros
#define	PQLR_ALG_OPTION_ENABLE_HW_ACC   0x00000001u
#define	PQLR_ALG_OPTION_ENABLE_PROXY   0x00000002u

Typedefs
typedef struct pqlr_alg_st *	pqlr_alg
	PQLR algorithm instance handle. More...

Functions
PQLR_API pqlr_alg	pqlr_alg_new (const char *alg_str)
	Creates pqlr_alg instance. More...
PQLR_API void	pqlr_alg_free (pqlr_alg alg)
	Frees pqlr_alg instance and all corresponding resources. More...
PQLR_API const char *	pqlr_alg_get_str (const pqlr_alg alg)
	Gets a string with the name of PQLR algorithm. More...
PQLR_API int	pqlr_alg_num_paramsets (const pqlr_alg alg)
	Gets available parameter sets for this algorithm. If the return value is n then all parameter sets from range [0; n) can be used. More...
PQLR_API int	pqlr_alg_get_paramset (const pqlr_alg alg)
	Gets parameter set configured for given algorithm instance. More...
PQLR_API int	pqlr_alg_set_paramset (pqlr_alg alg, int paramset)
	Enables selected parameter set. More...
PQLR_API const char *	pqlr_alg_get_paramset_str_from_id (const pqlr_alg alg, int paramset)
	Gets parameter set string for given algorithm and id. More...
PQLR_API int	pqlr_alg_get_paramset_id_from_str (const pqlr_alg alg, const char *paramset_str)
	Gets parameter set id for given algorithm and paramset string. More...
PQLR_API size_t	pqlr_alg_get_paramset_strs (const pqlr_alg alg, const char **paramsets, size_t count)
	Fills the provided buffer with names of available parameter sets for given algorithm. More...
PQLR_API int	pqlr_alg_set_options (pqlr_alg alg, uint32_t options)
	Enables selected option. More...
PQLR_API void	pqlr_alg_set_defaults (pqlr_alg alg)
	Configures the PQLR algorithm with default parameter and options set. More...

Detailed Description

In order to use any PQLR common algorithm interface functions, add following include:

#include <pqlr/common/alg.h>

Example code is listed below:

#include <stdlib.h>
#include <pqlr/common/alg.h>
 
 
void use_set_paramset()
{
    pqlr_alg alg = pqlr_alg_new("hypericum");
    const char* param_str = "hypericum_fast_sign";
    int param_id = pqlr_alg_get_paramset_id_from_str(alg, param_str);
    pqlr_alg_set_paramset(alg, param_id);
 
    pqlr_alg_free(alg);
}
 
void use_get_paramset_str_from_id()
{
    pqlr_alg alg = pqlr_alg_new("hypericum");
    int param_id = pqlr_alg_get_paramset(alg);
    const char* param_str = pqlr_alg_get_paramset_str_from_id(alg, param_id);
 
    pqlr_alg_free(alg);
}
 
 
void use_get_paramset_strs(void)
{
    pqlr_alg alg = pqlr_alg_new("hypericum");
    size_t npsets = pqlr_alg_num_paramsets(alg);
    const char** psets = malloc(sizeof(const char*) * npsets);
    pqlr_alg_get_paramset_strs(alg, psets, npsets);
 
    free(psets);
    pqlr_alg_free(alg);
}
 
 
int main(void)
{
    use_set_paramset();
    use_get_paramset_str_from_id();
    use_get_paramset_strs();
}

Macro Definition Documentation

PQLR_ALG_OPTION_ENABLE_HW_ACC

#define PQLR_ALG_OPTION_ENABLE_HW_ACC   0x00000001u

PQLR_ALG_OPTION_ENABLE_PROXY

#define PQLR_ALG_OPTION_ENABLE_PROXY   0x00000002u

Typedef Documentation

pqlr_alg

typedef struct pqlr_alg_st* pqlr_alg

PQLR algorithm instance handle.

See also

pqlr_alg_new

pqlr_alg_free

pqlr_alg_get_str

pqlr_alg_num_paramsets

pqlr_alg_set_defaults

Function Documentation

pqlr_alg_free()

PQLR_API void pqlr_alg_free

(

pqlr_alg

alg

)

Frees pqlr_alg instance and all corresponding resources.

Parameters

[in]

alg

PQLR algorithm instance

See also

pqlr_alg

pqlr_alg_new

pqlr_alg_get_paramset()

PQLR_API int pqlr_alg_get_paramset

(

const pqlr_alg

alg

)

Gets parameter set configured for given algorithm instance.

Parameters

[in]

alg

PQLR algorithm instance

See also

pqlr_alg

pqlr_alg_num_paramsets

pqlr_alg_set_paramset

Returns

non-negative value on success or PQLR_ALG_ERROR on failure

pqlr_alg_get_paramset_id_from_str()

PQLR_API int pqlr_alg_get_paramset_id_from_str	(	const pqlr_alg	alg,
		const char *	paramset_str
	)

Gets parameter set id for given algorithm and paramset string.

Parameters

[in]	alg	PQLR algorithm instance
[in]	paramset_str	Algorithm paramset string

See also

pqlr_alg

pqlr_alg_get_paramset_strs

pqlr_alg_get_paramset_str_from_id

Returns

non-negative value on success or PQLR_ALG_ERROR on failure

pqlr_alg_get_paramset_str_from_id()

PQLR_API const char* pqlr_alg_get_paramset_str_from_id	(	const pqlr_alg	alg,
		int	paramset
	)

Gets parameter set string for given algorithm and id.

Usage:

    pqlr_alg alg = pqlr_alg_new("hypericum");
    int param_id = pqlr_alg_get_paramset(alg);
    const char* param_str = pqlr_alg_get_paramset_str_from_id(alg, param_id);

Note

Result string must not be freed by user.

Parameters

[in]	alg	PQLR algorithm instance
[in]	paramset	Algorithm paramset id

See also

pqlr_alg

pqlr_alg_get_paramset_strs

pqlr_alg_get_paramset_id_from_str

Returns

string on success or NULL on failure

pqlr_alg_get_paramset_strs()

PQLR_API size_t pqlr_alg_get_paramset_strs	(	const pqlr_alg	alg,
		const char **	paramsets,
		size_t	count
	)

Fills the provided buffer with names of available parameter sets for given algorithm.

Usage:

    pqlr_alg alg = pqlr_alg_new("hypericum");
    size_t npsets = pqlr_alg_num_paramsets(alg);
    const char** psets = malloc(sizeof(const char*) * npsets);
    pqlr_alg_get_paramset_strs(alg, psets, npsets);

Note

If the number of parameter sets is more than the array size, then it'll be truncated. Individual strings in the output array must not be freed.

Parameters

[in]	alg	PQLR algorithm instance
[out]	paramsets	Array of parameter set names
[in]	count	Array size

Returns

number of parameter sets in the output array.

See also

pqlr_alg

pqlr_alg_new

pqlr_alg_num_paramsets

pqlr_alg_set_paramset

pqlr_alg_get_paramset_id_from_str

pqlr_alg_get_str()

PQLR_API const char* pqlr_alg_get_str

(

const pqlr_alg

alg

)

Gets a string with the name of PQLR algorithm.

Note

String memory does not need to be freed by user.

Parameters

[in]

alg

PQLR algorithm instance

See also

pqlr_alg

Returns

Null terminated string, PQLR_ALG_UNKNOWN in case of error.

pqlr_alg_new()

PQLR_API pqlr_alg pqlr_alg_new

(

const char *

alg_str

)

Creates pqlr_alg instance.

Note

Instance is initialized with default settings for specified algorithm

Parameters

[in]

alg_str

PQLR algorithm name

See also

pqlr_alg

pqlr_alg_free

pqlr_alg_set_defaults

Returns

new pqlr_alg instance or NULL in case of error

pqlr_alg_num_paramsets()

PQLR_API int pqlr_alg_num_paramsets

(

const pqlr_alg

alg

)

Gets available parameter sets for this algorithm. If the return value is n then all parameter sets from range [0; n) can be used.

Parameters

[in]

alg

PQLR algorithm instance

See also

pqlr_alg

Returns

Non-negative value or PQLR_ALG_ERROR in case of error

pqlr_alg_set_defaults()

PQLR_API void pqlr_alg_set_defaults

(

pqlr_alg

alg

)

Configures the PQLR algorithm with default parameter and options set.

Parameters

[in]

alg

PQLR algorithm instance

See also

pqlr_alg

pqlr_alg_new

pqlr_alg_set_paramset

pqlr_alg_set_options

pqlr_alg_set_options()

PQLR_API int pqlr_alg_set_options	(	pqlr_alg	alg,
		uint32_t	options
	)

Enables selected option.

Note

Options, unlike parameter sets, refer to algorithm implementation features such as use of hardware acceleration.

Parameters

[in]	alg	PQLR algorithm instance
[in]	options	Algorithm option to be enabled

See also

pqlr_alg

pqlr_alg_set_paramset

Returns

0 on success or non-zero value on failure

pqlr_alg_set_paramset()

PQLR_API int pqlr_alg_set_paramset	(	pqlr_alg	alg,
		int	paramset
	)

Enables selected parameter set.

Usage:

    pqlr_alg alg = pqlr_alg_new("hypericum");
    const char* param_str = "hypericum_fast_sign";
    int param_id = pqlr_alg_get_paramset_id_from_str(alg, param_str);
    pqlr_alg_set_paramset(alg, param_id);

Note

For given algorithm, the possible parameter set values are defined in enum <algorithm>_parameterset_t.

Parameters

[in]	alg	PQLR algorithm instance
[in]	paramset	Algorithm paramset to be enabled

See also

pqlr_alg

pqlr_alg_num_paramsets

pqlr_alg_get_paramset

Returns

0 on success or non-zero value on failure