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

[src] typedef struct OQS_SIG OQS_SIG 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_sign_with_ctx_str(const OQS_SIG *sig, uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len, const uint8_t *ctx_str, size_t ctx_str_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 OQS_STATUS	OQS_SIG_verify_with_ctx_str(const OQS_SIG *sig, const uint8_t *message, size_t message_len, const uint8_t *signature, size_t signature_len, const uint8_t *ctx_str, size_t ctx_str_len, const uint8_t *public_key)
OQS_API void	OQS_SIG_free(OQS_SIG *sig)

[src]

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.

[src]

OQS_SIG_alg_count

OQS_API int OQS_SIG_alg_count(void)

Returns the number of signature mechanisms in liboqs. They can be enumerated with OQS_SIG_alg_identifier.

Note that some mechanisms may be disabled at compile time.

Returns

The number of signature mechanisms.

[src]

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

Returns

1 if enabled, 0 if disabled or not found

[src]

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

Returns

An OQS_SIG for the particular algorithm, or NULL if the algorithm has been disabled at compile-time.

[src]

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

[src]

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

[src]

OQS_SIG_sign_with_ctx_str

OQS_API OQS_STATUS OQS_SIG_sign_with_ctx_str(const OQS_SIG *sig, uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len, const uint8_t *ctx_str, size_t ctx_str_len, const uint8_t *secret_key)

Signature generation algorithm, with custom context string.

Caller is responsible for allocating sufficient memory for signature, 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 actual length of the signature. May be smaller than length_signature for some algorithms since some algorithms have variable length signatures.
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 *	ctx_str	The context string used for the signature. This value can be set to NULL if a context string is not needed (i.e., for algorithms that do not support context strings or if an empty context string is used).
size_t	ctx_str_len	The context string used for the signature. This value can be set to 0 if a context string is not needed (i.e., for algorithms that do not support context strings or if an empty context string is used).
const uint8_t *	secret_key	The secret key represented as a byte string.

Returns

OQS_SUCCESS or OQS_ERROR

[src]

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

[src]

OQS_SIG_verify_with_ctx_str

OQS_API OQS_STATUS OQS_SIG_verify_with_ctx_str(const OQS_SIG *sig, const uint8_t *message, size_t message_len, const uint8_t *signature, size_t signature_len, const uint8_t *ctx_str, size_t ctx_str_len, const uint8_t *public_key)

Signature verification algorithm, with custom context string.

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 *	ctx_str	The context string used for the signature. This value can be set to NULL if a context string is not needed (i.e., for algorithms that do not support context strings or if an empty context string is used).
size_t	ctx_str_len	The context string used for the signature. This value can be set to 0 if a context string is not needed (i.e., for algorithms that do not support context strings or if an empty context string is used).
const uint8_t *	public_key	The public key represented as a byte string.

Returns

OQS_SUCCESS or OQS_ERROR

[src]

OQS_SIG_free

OQS_API void OQS_SIG_free(OQS_SIG *sig)

Frees an OQS_SIG object that was constructed by OQS_SIG_new.

Parameters

OQS_SIG *

sig

The OQS_SIG object to free.

Macros

[src] #define OQS_SIG_alg_dilithium_2 "Dilithium2" Algorithm identifier for Dilithium2

[src] #define OQS_SIG_alg_dilithium_3 "Dilithium3" Algorithm identifier for Dilithium3

[src] #define OQS_SIG_alg_dilithium_5 "Dilithium5" Algorithm identifier for Dilithium5

[src] #define OQS_SIG_alg_ml_dsa_44 "ML-DSA-44" Algorithm identifier for ML-DSA-44

[src] #define OQS_SIG_alg_ml_dsa_65 "ML-DSA-65" Algorithm identifier for ML-DSA-65

[src] #define OQS_SIG_alg_ml_dsa_87 "ML-DSA-87" Algorithm identifier for ML-DSA-87

[src] #define OQS_SIG_alg_falcon_512 "Falcon-512" Algorithm identifier for Falcon-512

[src] #define OQS_SIG_alg_falcon_1024 "Falcon-1024" Algorithm identifier for Falcon-1024

[src] #define OQS_SIG_alg_falcon_padded_512 "Falcon-padded-512" Algorithm identifier for Falcon-padded-512

[src] #define OQS_SIG_alg_falcon_padded_1024 "Falcon-padded-1024" Algorithm identifier for Falcon-padded-1024

[src] #define OQS_SIG_alg_sphincs_sha2_128f_simple "SPHINCS+-SHA2-128f-simple" Algorithm identifier for SPHINCS+-SHA2-128f-simple

[src] #define OQS_SIG_alg_sphincs_sha2_128s_simple "SPHINCS+-SHA2-128s-simple" Algorithm identifier for SPHINCS+-SHA2-128s-simple

[src] #define OQS_SIG_alg_sphincs_sha2_192f_simple "SPHINCS+-SHA2-192f-simple" Algorithm identifier for SPHINCS+-SHA2-192f-simple

[src] #define OQS_SIG_alg_sphincs_sha2_192s_simple "SPHINCS+-SHA2-192s-simple" Algorithm identifier for SPHINCS+-SHA2-192s-simple

[src] #define OQS_SIG_alg_sphincs_sha2_256f_simple "SPHINCS+-SHA2-256f-simple" Algorithm identifier for SPHINCS+-SHA2-256f-simple

[src] #define OQS_SIG_alg_sphincs_sha2_256s_simple "SPHINCS+-SHA2-256s-simple" Algorithm identifier for SPHINCS+-SHA2-256s-simple

[src] #define OQS_SIG_alg_sphincs_shake_128f_simple "SPHINCS+-SHAKE-128f-simple" Algorithm identifier for SPHINCS+-SHAKE-128f-simple

[src] #define OQS_SIG_alg_sphincs_shake_128s_simple "SPHINCS+-SHAKE-128s-simple" Algorithm identifier for SPHINCS+-SHAKE-128s-simple

[src] #define OQS_SIG_alg_sphincs_shake_192f_simple "SPHINCS+-SHAKE-192f-simple" Algorithm identifier for SPHINCS+-SHAKE-192f-simple

[src] #define OQS_SIG_alg_sphincs_shake_192s_simple "SPHINCS+-SHAKE-192s-simple" Algorithm identifier for SPHINCS+-SHAKE-192s-simple

[src] #define OQS_SIG_alg_sphincs_shake_256f_simple "SPHINCS+-SHAKE-256f-simple" Algorithm identifier for SPHINCS+-SHAKE-256f-simple

[src] #define OQS_SIG_alg_sphincs_shake_256s_simple "SPHINCS+-SHAKE-256s-simple" Algorithm identifier for SPHINCS+-SHAKE-256s-simple

[src] #define OQS_SIG_alg_mayo_1 "MAYO-1" Algorithm identifier for MAYO-1

[src] #define OQS_SIG_alg_mayo_2 "MAYO-2" Algorithm identifier for MAYO-2

[src] #define OQS_SIG_alg_mayo_3 "MAYO-3" Algorithm identifier for MAYO-3

[src] #define OQS_SIG_alg_mayo_5 "MAYO-5" Algorithm identifier for MAYO-5

[src] #define OQS_SIG_alg_cross_rsdp_128_balanced "cross-rsdp-128-balanced" Algorithm identifier for cross-rsdp-128-balanced

[src] #define OQS_SIG_alg_cross_rsdp_128_fast "cross-rsdp-128-fast" Algorithm identifier for cross-rsdp-128-fast

[src] #define OQS_SIG_alg_cross_rsdp_128_small "cross-rsdp-128-small" Algorithm identifier for cross-rsdp-128-small

[src] #define OQS_SIG_alg_cross_rsdp_192_balanced "cross-rsdp-192-balanced" Algorithm identifier for cross-rsdp-192-balanced

[src] #define OQS_SIG_alg_cross_rsdp_192_fast "cross-rsdp-192-fast" Algorithm identifier for cross-rsdp-192-fast

[src] #define OQS_SIG_alg_cross_rsdp_192_small "cross-rsdp-192-small" Algorithm identifier for cross-rsdp-192-small

[src] #define OQS_SIG_alg_cross_rsdp_256_balanced "cross-rsdp-256-balanced" Algorithm identifier for cross-rsdp-256-balanced

[src] #define OQS_SIG_alg_cross_rsdp_256_fast "cross-rsdp-256-fast" Algorithm identifier for cross-rsdp-256-fast

[src] #define OQS_SIG_alg_cross_rsdp_256_small "cross-rsdp-256-small" Algorithm identifier for cross-rsdp-256-small

[src] #define OQS_SIG_alg_cross_rsdpg_128_balanced "cross-rsdpg-128-balanced" Algorithm identifier for cross-rsdpg-128-balanced

[src] #define OQS_SIG_alg_cross_rsdpg_128_fast "cross-rsdpg-128-fast" Algorithm identifier for cross-rsdpg-128-fast

[src] #define OQS_SIG_alg_cross_rsdpg_128_small "cross-rsdpg-128-small" Algorithm identifier for cross-rsdpg-128-small

[src] #define OQS_SIG_alg_cross_rsdpg_192_balanced "cross-rsdpg-192-balanced" Algorithm identifier for cross-rsdpg-192-balanced

[src] #define OQS_SIG_alg_cross_rsdpg_192_fast "cross-rsdpg-192-fast" Algorithm identifier for cross-rsdpg-192-fast

[src] #define OQS_SIG_alg_cross_rsdpg_192_small "cross-rsdpg-192-small" Algorithm identifier for cross-rsdpg-192-small

[src] #define OQS_SIG_alg_cross_rsdpg_256_balanced "cross-rsdpg-256-balanced" Algorithm identifier for cross-rsdpg-256-balanced

[src] #define OQS_SIG_alg_cross_rsdpg_256_fast "cross-rsdpg-256-fast" Algorithm identifier for cross-rsdpg-256-fast

[src] #define OQS_SIG_alg_cross_rsdpg_256_small "cross-rsdpg-256-small" Algorithm identifier for cross-rsdpg-256-small

[src] #define OQS_SIG_algs_length 44 Number of algorithm identifiers above.