liboqs
Loading...
Searching...
No Matches
sig.h File Reference

Signature schemes. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <oqs/oqs.h>

Go to the source code of this file.

Data Structures

struct  OQS_SIG
 

Macros

#define OQS_SIG_alg_dilithium_2   "Dilithium2"
 
#define OQS_SIG_alg_dilithium_3   "Dilithium3"
 
#define OQS_SIG_alg_dilithium_5   "Dilithium5"
 
#define OQS_SIG_alg_ml_dsa_44_ipd   "ML-DSA-44-ipd"
 
#define OQS_SIG_alg_ml_dsa_44   "ML-DSA-44"
 
#define OQS_SIG_alg_ml_dsa_65_ipd   "ML-DSA-65-ipd"
 
#define OQS_SIG_alg_ml_dsa_65   "ML-DSA-65"
 
#define OQS_SIG_alg_ml_dsa_87_ipd   "ML-DSA-87-ipd"
 
#define OQS_SIG_alg_ml_dsa_87   "ML-DSA-87"
 
#define OQS_SIG_alg_falcon_512   "Falcon-512"
 
#define OQS_SIG_alg_falcon_1024   "Falcon-1024"
 
#define OQS_SIG_alg_falcon_padded_512   "Falcon-padded-512"
 
#define OQS_SIG_alg_falcon_padded_1024   "Falcon-padded-1024"
 
#define OQS_SIG_alg_sphincs_sha2_128f_simple   "SPHINCS+-SHA2-128f-simple"
 
#define OQS_SIG_alg_sphincs_sha2_128s_simple   "SPHINCS+-SHA2-128s-simple"
 
#define OQS_SIG_alg_sphincs_sha2_192f_simple   "SPHINCS+-SHA2-192f-simple"
 
#define OQS_SIG_alg_sphincs_sha2_192s_simple   "SPHINCS+-SHA2-192s-simple"
 
#define OQS_SIG_alg_sphincs_sha2_256f_simple   "SPHINCS+-SHA2-256f-simple"
 
#define OQS_SIG_alg_sphincs_sha2_256s_simple   "SPHINCS+-SHA2-256s-simple"
 
#define OQS_SIG_alg_sphincs_shake_128f_simple   "SPHINCS+-SHAKE-128f-simple"
 
#define OQS_SIG_alg_sphincs_shake_128s_simple   "SPHINCS+-SHAKE-128s-simple"
 
#define OQS_SIG_alg_sphincs_shake_192f_simple   "SPHINCS+-SHAKE-192f-simple"
 
#define OQS_SIG_alg_sphincs_shake_192s_simple   "SPHINCS+-SHAKE-192s-simple"
 
#define OQS_SIG_alg_sphincs_shake_256f_simple   "SPHINCS+-SHAKE-256f-simple"
 
#define OQS_SIG_alg_sphincs_shake_256s_simple   "SPHINCS+-SHAKE-256s-simple"
 
#define OQS_SIG_alg_mayo_1   "MAYO-1"
 
#define OQS_SIG_alg_mayo_2   "MAYO-2"
 
#define OQS_SIG_alg_mayo_3   "MAYO-3"
 
#define OQS_SIG_alg_mayo_5   "MAYO-5"
 
#define OQS_SIG_alg_cross_rsdp_128_balanced   "cross-rsdp-128-balanced"
 
#define OQS_SIG_alg_cross_rsdp_128_fast   "cross-rsdp-128-fast"
 
#define OQS_SIG_alg_cross_rsdp_128_small   "cross-rsdp-128-small"
 
#define OQS_SIG_alg_cross_rsdp_192_balanced   "cross-rsdp-192-balanced"
 
#define OQS_SIG_alg_cross_rsdp_192_fast   "cross-rsdp-192-fast"
 
#define OQS_SIG_alg_cross_rsdp_192_small   "cross-rsdp-192-small"
 
#define OQS_SIG_alg_cross_rsdp_256_balanced   "cross-rsdp-256-balanced"
 
#define OQS_SIG_alg_cross_rsdp_256_fast   "cross-rsdp-256-fast"
 
#define OQS_SIG_alg_cross_rsdp_256_small   "cross-rsdp-256-small"
 
#define OQS_SIG_alg_cross_rsdpg_128_balanced   "cross-rsdpg-128-balanced"
 
#define OQS_SIG_alg_cross_rsdpg_128_fast   "cross-rsdpg-128-fast"
 
#define OQS_SIG_alg_cross_rsdpg_128_small   "cross-rsdpg-128-small"
 
#define OQS_SIG_alg_cross_rsdpg_192_balanced   "cross-rsdpg-192-balanced"
 
#define OQS_SIG_alg_cross_rsdpg_192_fast   "cross-rsdpg-192-fast"
 
#define OQS_SIG_alg_cross_rsdpg_192_small   "cross-rsdpg-192-small"
 
#define OQS_SIG_alg_cross_rsdpg_256_balanced   "cross-rsdpg-256-balanced"
 
#define OQS_SIG_alg_cross_rsdpg_256_fast   "cross-rsdpg-256-fast"
 
#define OQS_SIG_alg_cross_rsdpg_256_small   "cross-rsdpg-256-small"
 
#define OQS_SIG_algs_length   47
 

Typedefs

typedef struct OQS_SIG OQS_SIG
 

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_SIGOQS_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)
 

Detailed Description

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

Macro Definition Documentation

◆ OQS_SIG_alg_cross_rsdp_128_balanced

#define OQS_SIG_alg_cross_rsdp_128_balanced   "cross-rsdp-128-balanced"

Algorithm identifier for cross-rsdp-128-balanced

◆ OQS_SIG_alg_cross_rsdp_128_fast

#define OQS_SIG_alg_cross_rsdp_128_fast   "cross-rsdp-128-fast"

Algorithm identifier for cross-rsdp-128-fast

◆ OQS_SIG_alg_cross_rsdp_128_small

#define OQS_SIG_alg_cross_rsdp_128_small   "cross-rsdp-128-small"

Algorithm identifier for cross-rsdp-128-small

◆ OQS_SIG_alg_cross_rsdp_192_balanced

#define OQS_SIG_alg_cross_rsdp_192_balanced   "cross-rsdp-192-balanced"

Algorithm identifier for cross-rsdp-192-balanced

◆ OQS_SIG_alg_cross_rsdp_192_fast

#define OQS_SIG_alg_cross_rsdp_192_fast   "cross-rsdp-192-fast"

Algorithm identifier for cross-rsdp-192-fast

◆ OQS_SIG_alg_cross_rsdp_192_small

#define OQS_SIG_alg_cross_rsdp_192_small   "cross-rsdp-192-small"

Algorithm identifier for cross-rsdp-192-small

◆ OQS_SIG_alg_cross_rsdp_256_balanced

#define OQS_SIG_alg_cross_rsdp_256_balanced   "cross-rsdp-256-balanced"

Algorithm identifier for cross-rsdp-256-balanced

◆ OQS_SIG_alg_cross_rsdp_256_fast

#define OQS_SIG_alg_cross_rsdp_256_fast   "cross-rsdp-256-fast"

Algorithm identifier for cross-rsdp-256-fast

◆ OQS_SIG_alg_cross_rsdp_256_small

#define OQS_SIG_alg_cross_rsdp_256_small   "cross-rsdp-256-small"

Algorithm identifier for cross-rsdp-256-small

◆ OQS_SIG_alg_cross_rsdpg_128_balanced

#define OQS_SIG_alg_cross_rsdpg_128_balanced   "cross-rsdpg-128-balanced"

Algorithm identifier for cross-rsdpg-128-balanced

◆ OQS_SIG_alg_cross_rsdpg_128_fast

#define OQS_SIG_alg_cross_rsdpg_128_fast   "cross-rsdpg-128-fast"

Algorithm identifier for cross-rsdpg-128-fast

◆ OQS_SIG_alg_cross_rsdpg_128_small

#define OQS_SIG_alg_cross_rsdpg_128_small   "cross-rsdpg-128-small"

Algorithm identifier for cross-rsdpg-128-small

◆ OQS_SIG_alg_cross_rsdpg_192_balanced

#define OQS_SIG_alg_cross_rsdpg_192_balanced   "cross-rsdpg-192-balanced"

Algorithm identifier for cross-rsdpg-192-balanced

◆ OQS_SIG_alg_cross_rsdpg_192_fast

#define OQS_SIG_alg_cross_rsdpg_192_fast   "cross-rsdpg-192-fast"

Algorithm identifier for cross-rsdpg-192-fast

◆ OQS_SIG_alg_cross_rsdpg_192_small

#define OQS_SIG_alg_cross_rsdpg_192_small   "cross-rsdpg-192-small"

Algorithm identifier for cross-rsdpg-192-small

◆ OQS_SIG_alg_cross_rsdpg_256_balanced

#define OQS_SIG_alg_cross_rsdpg_256_balanced   "cross-rsdpg-256-balanced"

Algorithm identifier for cross-rsdpg-256-balanced

◆ OQS_SIG_alg_cross_rsdpg_256_fast

#define OQS_SIG_alg_cross_rsdpg_256_fast   "cross-rsdpg-256-fast"

Algorithm identifier for cross-rsdpg-256-fast

◆ OQS_SIG_alg_cross_rsdpg_256_small

#define OQS_SIG_alg_cross_rsdpg_256_small   "cross-rsdpg-256-small"

Algorithm identifier for cross-rsdpg-256-small

◆ OQS_SIG_alg_dilithium_2

#define OQS_SIG_alg_dilithium_2   "Dilithium2"

Algorithm identifier for Dilithium2

◆ OQS_SIG_alg_dilithium_3

#define OQS_SIG_alg_dilithium_3   "Dilithium3"

Algorithm identifier for Dilithium3

◆ OQS_SIG_alg_dilithium_5

#define OQS_SIG_alg_dilithium_5   "Dilithium5"

Algorithm identifier for Dilithium5

◆ OQS_SIG_alg_falcon_1024

#define OQS_SIG_alg_falcon_1024   "Falcon-1024"

Algorithm identifier for Falcon-1024

◆ OQS_SIG_alg_falcon_512

#define OQS_SIG_alg_falcon_512   "Falcon-512"

Algorithm identifier for Falcon-512

◆ OQS_SIG_alg_falcon_padded_1024

#define OQS_SIG_alg_falcon_padded_1024   "Falcon-padded-1024"

Algorithm identifier for Falcon-padded-1024

◆ OQS_SIG_alg_falcon_padded_512

#define OQS_SIG_alg_falcon_padded_512   "Falcon-padded-512"

Algorithm identifier for Falcon-padded-512

◆ OQS_SIG_alg_mayo_1

#define OQS_SIG_alg_mayo_1   "MAYO-1"

Algorithm identifier for MAYO-1

◆ OQS_SIG_alg_mayo_2

#define OQS_SIG_alg_mayo_2   "MAYO-2"

Algorithm identifier for MAYO-2

◆ OQS_SIG_alg_mayo_3

#define OQS_SIG_alg_mayo_3   "MAYO-3"

Algorithm identifier for MAYO-3

◆ OQS_SIG_alg_mayo_5

#define OQS_SIG_alg_mayo_5   "MAYO-5"

Algorithm identifier for MAYO-5

◆ OQS_SIG_alg_ml_dsa_44

#define OQS_SIG_alg_ml_dsa_44   "ML-DSA-44"

Algorithm identifier for ML-DSA-44 SIG.

◆ OQS_SIG_alg_ml_dsa_44_ipd

#define OQS_SIG_alg_ml_dsa_44_ipd   "ML-DSA-44-ipd"

Algorithm identifier for ML-DSA-44-ipd

◆ OQS_SIG_alg_ml_dsa_65

#define OQS_SIG_alg_ml_dsa_65   "ML-DSA-65"

Algorithm identifier for ML-DSA-65 SIG.

◆ OQS_SIG_alg_ml_dsa_65_ipd

#define OQS_SIG_alg_ml_dsa_65_ipd   "ML-DSA-65-ipd"

Algorithm identifier for ML-DSA-65-ipd

◆ OQS_SIG_alg_ml_dsa_87

#define OQS_SIG_alg_ml_dsa_87   "ML-DSA-87"

Algorithm identifier for ML-DSA-87 SIG.

◆ OQS_SIG_alg_ml_dsa_87_ipd

#define OQS_SIG_alg_ml_dsa_87_ipd   "ML-DSA-87-ipd"

Algorithm identifier for ML-DSA-87-ipd

◆ OQS_SIG_alg_sphincs_sha2_128f_simple

#define OQS_SIG_alg_sphincs_sha2_128f_simple   "SPHINCS+-SHA2-128f-simple"

Algorithm identifier for SPHINCS+-SHA2-128f-simple

◆ OQS_SIG_alg_sphincs_sha2_128s_simple

#define OQS_SIG_alg_sphincs_sha2_128s_simple   "SPHINCS+-SHA2-128s-simple"

Algorithm identifier for SPHINCS+-SHA2-128s-simple

◆ OQS_SIG_alg_sphincs_sha2_192f_simple

#define OQS_SIG_alg_sphincs_sha2_192f_simple   "SPHINCS+-SHA2-192f-simple"

Algorithm identifier for SPHINCS+-SHA2-192f-simple

◆ OQS_SIG_alg_sphincs_sha2_192s_simple

#define OQS_SIG_alg_sphincs_sha2_192s_simple   "SPHINCS+-SHA2-192s-simple"

Algorithm identifier for SPHINCS+-SHA2-192s-simple

◆ OQS_SIG_alg_sphincs_sha2_256f_simple

#define OQS_SIG_alg_sphincs_sha2_256f_simple   "SPHINCS+-SHA2-256f-simple"

Algorithm identifier for SPHINCS+-SHA2-256f-simple

◆ OQS_SIG_alg_sphincs_sha2_256s_simple

#define OQS_SIG_alg_sphincs_sha2_256s_simple   "SPHINCS+-SHA2-256s-simple"

Algorithm identifier for SPHINCS+-SHA2-256s-simple

◆ OQS_SIG_alg_sphincs_shake_128f_simple

#define OQS_SIG_alg_sphincs_shake_128f_simple   "SPHINCS+-SHAKE-128f-simple"

Algorithm identifier for SPHINCS+-SHAKE-128f-simple

◆ OQS_SIG_alg_sphincs_shake_128s_simple

#define OQS_SIG_alg_sphincs_shake_128s_simple   "SPHINCS+-SHAKE-128s-simple"

Algorithm identifier for SPHINCS+-SHAKE-128s-simple

◆ OQS_SIG_alg_sphincs_shake_192f_simple

#define OQS_SIG_alg_sphincs_shake_192f_simple   "SPHINCS+-SHAKE-192f-simple"

Algorithm identifier for SPHINCS+-SHAKE-192f-simple

◆ OQS_SIG_alg_sphincs_shake_192s_simple

#define OQS_SIG_alg_sphincs_shake_192s_simple   "SPHINCS+-SHAKE-192s-simple"

Algorithm identifier for SPHINCS+-SHAKE-192s-simple

◆ OQS_SIG_alg_sphincs_shake_256f_simple

#define OQS_SIG_alg_sphincs_shake_256f_simple   "SPHINCS+-SHAKE-256f-simple"

Algorithm identifier for SPHINCS+-SHAKE-256f-simple

◆ OQS_SIG_alg_sphincs_shake_256s_simple

#define OQS_SIG_alg_sphincs_shake_256s_simple   "SPHINCS+-SHAKE-256s-simple"

Algorithm identifier for SPHINCS+-SHAKE-256s-simple

◆ OQS_SIG_algs_length

#define OQS_SIG_algs_length   47

Number of algorithm identifiers above.

Typedef Documentation

◆ OQS_SIG

typedef struct OQS_SIG OQS_SIG

Signature schemes object

Function Documentation

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

◆ 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
[in]iIndex 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
[in]method_nameName of the desired algorithm; one of the names in OQS_SIG_algs.
Returns
1 if enabled, 0 if disabled or not found

◆ 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
[in]sigThe OQS_SIG object to free.

◆ 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
[in]sigThe OQS_SIG object representing the signature scheme.
[out]public_keyThe public key represented as a byte string.
[out]secret_keyThe secret key represented as a byte string.
Returns
OQS_SUCCESS or OQS_ERROR

◆ 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
[in]method_nameName 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.

◆ 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
[in]sigThe OQS_SIG object representing the signature scheme.
[out]signatureThe signature on the message represented as a byte string.
[out]signature_lenThe length of the signature.
[in]messageThe message to sign represented as a byte string.
[in]message_lenThe length of the message to sign.
[in]secret_keyThe 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
[in]sigThe OQS_SIG object representing the signature scheme.
[in]messageThe message represented as a byte string.
[in]message_lenThe length of the message.
[in]signatureThe signature on the message represented as a byte string.
[in]signature_lenThe length of the signature.
[in]public_keyThe public key represented as a byte string.
Returns
OQS_SUCCESS or OQS_ERROR