src/sig/sig.h
Signature schemes.
The file tests/example_sig.c contains two examples on using the OQS_SIG API.
The first example uses the individual scheme's algorithms directly and uses no dynamic memory allocation – all buffers are allocated on the stack, with sizes indicated using preprocessor macros. Since algorithms can be disabled at compile-time, the programmer should wrap the code in #ifdefs.
The second example uses an OQS_SIG object to use an algorithm specified at runtime. Therefore it uses dynamic memory allocation – all buffers must be malloc'ed by the programmer, with sizes indicated using the corresponding length member of the OQS_SIG object in question. Since algorithms can be disabled at compile-time, the programmer should check that the OQS_SIG object is not NULL.
SPDX-License-Identifier: MIT
Includes
#include <stdbool.h> #include <stddef.h> #include <stdint.h> #include <oqs/oqs.h> Typedefs
|
Signature schemes object |
Functions
OQS_API const char * | OQS_SIG_alg_identifier(size_t i) |
OQS_API int | OQS_SIG_alg_count(void) |
OQS_API int | OQS_SIG_alg_is_enabled(const char *method_name) |
OQS_API OQS_SIG * | OQS_SIG_new(const char *method_name) |
OQS_API OQS_STATUS | OQS_SIG_keypair(const OQS_SIG *sig, uint8_t *public_key, uint8_t *secret_key) |
OQS_API OQS_STATUS | OQS_SIG_sign(const OQS_SIG *sig, uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len, const uint8_t *secret_key) |
OQS_API OQS_STATUS | OQS_SIG_verify(const OQS_SIG *sig, const uint8_t *message, size_t message_len, const uint8_t *signature, size_t signature_len, const uint8_t *public_key) |
OQS_API void | OQS_SIG_free(OQS_SIG *sig) |
OQS_SIG_alg_identifier
OQS_API const char * OQS_SIG_alg_identifier(size_t i)Returns identifiers for available signature schemes in liboqs. Used with OQS_SIG_new.
Note that algorithm identifiers are present in this list even when the algorithm is disabled at compile time.
Parameters
size_t | i | Index of the algorithm identifier to return, 0 <= i < OQS_SIG_algs_length |
Returns
Algorithm identifier as a string, or NULL.
OQS_SIG_alg_is_enabled
OQS_API int OQS_SIG_alg_is_enabled(const char *method_name)Indicates whether the specified algorithm was enabled at compile-time or not.
Parameters
const char * | method_name | Name of the desired algorithm; one of the names in |
Returns
1 if enabled, 0 if disabled or not found
OQS_SIG_new
OQS_API OQS_SIG * OQS_SIG_new(const char *method_name)Constructs an OQS_SIG object for a particular algorithm.
Callers should always check whether the return value is NULL, which indicates either than an invalid algorithm name was provided, or that the requested algorithm was disabled at compile-time.
Parameters
const char * | method_name | Name of the desired algorithm; one of the names in |
Returns
An OQS_SIG for the particular algorithm, or NULL if the algorithm has been disabled at compile-time.
OQS_SIG_keypair
OQS_API OQS_STATUS OQS_SIG_keypair(const OQS_SIG *sig, uint8_t *public_key, uint8_t *secret_key)Keypair generation algorithm.
Caller is responsible for allocating sufficient memory for public_key and secret_key, based on the length_* members in this object or the per-scheme compile-time macros OQS_SIG_*_length_*.
Parameters
const OQS_SIG * | sig | The OQS_SIG object representing the signature scheme. |
uint8_t * | public_key | The public key represented as a byte string. |
uint8_t * | secret_key | The secret key represented as a byte string. |
Returns
OQS_SUCCESS or OQS_ERROR
OQS_SIG_sign
OQS_API OQS_STATUS OQS_SIG_sign(const OQS_SIG *sig, uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len, const uint8_t *secret_key)Signature generation algorithm.
Caller is responsible for allocating sufficient memory for signnature, based on the length_* members in this object or the per-scheme compile-time macros OQS_SIG_*_length_*.
Parameters
const OQS_SIG * | sig | The OQS_SIG object representing the signature scheme. |
uint8_t * | signature | The signature on the message represented as a byte string. |
size_t * | signature_len | The length of the signature. |
const uint8_t * | message | The message to sign represented as a byte string. |
size_t | message_len | The length of the message to sign. |
const uint8_t * | secret_key | The secret key represented as a byte string. |
Returns
OQS_SUCCESS or OQS_ERROR
OQS_SIG_verify
OQS_API OQS_STATUS OQS_SIG_verify(const OQS_SIG *sig, const uint8_t *message, size_t message_len, const uint8_t *signature, size_t signature_len, const uint8_t *public_key)Signature verification algorithm.
Parameters
const OQS_SIG * | sig | The OQS_SIG object representing the signature scheme. |
const uint8_t * | message | The message represented as a byte string. |
size_t | message_len | The length of the message. |
const uint8_t * | signature | The signature on the message represented as a byte string. |
size_t | signature_len | The length of the signature. |
const uint8_t * | public_key | The public key represented as a byte string. |
Returns
OQS_SUCCESS or OQS_ERROR
Macros
|
Algorithm identifier for Dilithium2 |
|
Algorithm identifier for Dilithium3 |
|
Algorithm identifier for Dilithium5 |
|
Algorithm identifier for Falcon-512 |
|
Algorithm identifier for Falcon-1024 |
|
Algorithm identifier for SPHINCS+-SHA2-128f-simple |
|
Algorithm identifier for SPHINCS+-SHA2-128s-simple |
|
Algorithm identifier for SPHINCS+-SHA2-192f-simple |
|
Algorithm identifier for SPHINCS+-SHA2-192s-simple |
|
Algorithm identifier for SPHINCS+-SHA2-256f-simple |
|
Algorithm identifier for SPHINCS+-SHA2-256s-simple |
|
Algorithm identifier for SPHINCS+-SHAKE-128f-simple |
|
Algorithm identifier for SPHINCS+-SHAKE-128s-simple |
|
Algorithm identifier for SPHINCS+-SHAKE-192f-simple |
|
Algorithm identifier for SPHINCS+-SHAKE-192s-simple |
|
Algorithm identifier for SPHINCS+-SHAKE-256f-simple |
|
Algorithm identifier for SPHINCS+-SHAKE-256s-simple |
|
Number of algorithm identifiers above. |