1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
|
/**
* \file sig.h
* \brief 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
*/
#ifndef OQS_SIG_H
#define OQS_SIG_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <oqs/oqs.h>
#if defined(__cplusplus)
extern "C" {
#endif
///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_ALG_IDENTIFIER_START
/** Algorithm identifier for Dilithium2 */
#define OQS_SIG_alg_dilithium_2 "Dilithium2"
/** Algorithm identifier for Dilithium3 */
#define OQS_SIG_alg_dilithium_3 "Dilithium3"
/** Algorithm identifier for Dilithium5 */
#define OQS_SIG_alg_dilithium_5 "Dilithium5"
/** Algorithm identifier for Dilithium2-AES */
#define OQS_SIG_alg_dilithium_2_aes "Dilithium2-AES"
/** Algorithm identifier for Dilithium3-AES */
#define OQS_SIG_alg_dilithium_3_aes "Dilithium3-AES"
/** Algorithm identifier for Dilithium5-AES */
#define OQS_SIG_alg_dilithium_5_aes "Dilithium5-AES"
/** Algorithm identifier for Falcon-512 */
#define OQS_SIG_alg_falcon_512 "Falcon-512"
/** Algorithm identifier for Falcon-1024 */
#define OQS_SIG_alg_falcon_1024 "Falcon-1024"
/** Algorithm identifier for SPHINCS+-Haraka-128f-robust */
#define OQS_SIG_alg_sphincs_haraka_128f_robust "SPHINCS+-Haraka-128f-robust"
/** Algorithm identifier for SPHINCS+-Haraka-128f-simple */
#define OQS_SIG_alg_sphincs_haraka_128f_simple "SPHINCS+-Haraka-128f-simple"
/** Algorithm identifier for SPHINCS+-Haraka-128s-robust */
#define OQS_SIG_alg_sphincs_haraka_128s_robust "SPHINCS+-Haraka-128s-robust"
/** Algorithm identifier for SPHINCS+-Haraka-128s-simple */
#define OQS_SIG_alg_sphincs_haraka_128s_simple "SPHINCS+-Haraka-128s-simple"
/** Algorithm identifier for SPHINCS+-Haraka-192f-robust */
#define OQS_SIG_alg_sphincs_haraka_192f_robust "SPHINCS+-Haraka-192f-robust"
/** Algorithm identifier for SPHINCS+-Haraka-192f-simple */
#define OQS_SIG_alg_sphincs_haraka_192f_simple "SPHINCS+-Haraka-192f-simple"
/** Algorithm identifier for SPHINCS+-Haraka-192s-robust */
#define OQS_SIG_alg_sphincs_haraka_192s_robust "SPHINCS+-Haraka-192s-robust"
/** Algorithm identifier for SPHINCS+-Haraka-192s-simple */
#define OQS_SIG_alg_sphincs_haraka_192s_simple "SPHINCS+-Haraka-192s-simple"
/** Algorithm identifier for SPHINCS+-Haraka-256f-robust */
#define OQS_SIG_alg_sphincs_haraka_256f_robust "SPHINCS+-Haraka-256f-robust"
/** Algorithm identifier for SPHINCS+-Haraka-256f-simple */
#define OQS_SIG_alg_sphincs_haraka_256f_simple "SPHINCS+-Haraka-256f-simple"
/** Algorithm identifier for SPHINCS+-Haraka-256s-robust */
#define OQS_SIG_alg_sphincs_haraka_256s_robust "SPHINCS+-Haraka-256s-robust"
/** Algorithm identifier for SPHINCS+-Haraka-256s-simple */
#define OQS_SIG_alg_sphincs_haraka_256s_simple "SPHINCS+-Haraka-256s-simple"
/** Algorithm identifier for SPHINCS+-SHA256-128f-robust */
#define OQS_SIG_alg_sphincs_sha256_128f_robust "SPHINCS+-SHA256-128f-robust"
/** Algorithm identifier for SPHINCS+-SHA256-128f-simple */
#define OQS_SIG_alg_sphincs_sha256_128f_simple "SPHINCS+-SHA256-128f-simple"
/** Algorithm identifier for SPHINCS+-SHA256-128s-robust */
#define OQS_SIG_alg_sphincs_sha256_128s_robust "SPHINCS+-SHA256-128s-robust"
/** Algorithm identifier for SPHINCS+-SHA256-128s-simple */
#define OQS_SIG_alg_sphincs_sha256_128s_simple "SPHINCS+-SHA256-128s-simple"
/** Algorithm identifier for SPHINCS+-SHA256-192f-robust */
#define OQS_SIG_alg_sphincs_sha256_192f_robust "SPHINCS+-SHA256-192f-robust"
/** Algorithm identifier for SPHINCS+-SHA256-192f-simple */
#define OQS_SIG_alg_sphincs_sha256_192f_simple "SPHINCS+-SHA256-192f-simple"
/** Algorithm identifier for SPHINCS+-SHA256-192s-robust */
#define OQS_SIG_alg_sphincs_sha256_192s_robust "SPHINCS+-SHA256-192s-robust"
/** Algorithm identifier for SPHINCS+-SHA256-192s-simple */
#define OQS_SIG_alg_sphincs_sha256_192s_simple "SPHINCS+-SHA256-192s-simple"
/** Algorithm identifier for SPHINCS+-SHA256-256f-robust */
#define OQS_SIG_alg_sphincs_sha256_256f_robust "SPHINCS+-SHA256-256f-robust"
/** Algorithm identifier for SPHINCS+-SHA256-256f-simple */
#define OQS_SIG_alg_sphincs_sha256_256f_simple "SPHINCS+-SHA256-256f-simple"
/** Algorithm identifier for SPHINCS+-SHA256-256s-robust */
#define OQS_SIG_alg_sphincs_sha256_256s_robust "SPHINCS+-SHA256-256s-robust"
/** Algorithm identifier for SPHINCS+-SHA256-256s-simple */
#define OQS_SIG_alg_sphincs_sha256_256s_simple "SPHINCS+-SHA256-256s-simple"
/** Algorithm identifier for SPHINCS+-SHAKE256-128f-robust */
#define OQS_SIG_alg_sphincs_shake256_128f_robust "SPHINCS+-SHAKE256-128f-robust"
/** Algorithm identifier for SPHINCS+-SHAKE256-128f-simple */
#define OQS_SIG_alg_sphincs_shake256_128f_simple "SPHINCS+-SHAKE256-128f-simple"
/** Algorithm identifier for SPHINCS+-SHAKE256-128s-robust */
#define OQS_SIG_alg_sphincs_shake256_128s_robust "SPHINCS+-SHAKE256-128s-robust"
/** Algorithm identifier for SPHINCS+-SHAKE256-128s-simple */
#define OQS_SIG_alg_sphincs_shake256_128s_simple "SPHINCS+-SHAKE256-128s-simple"
/** Algorithm identifier for SPHINCS+-SHAKE256-192f-robust */
#define OQS_SIG_alg_sphincs_shake256_192f_robust "SPHINCS+-SHAKE256-192f-robust"
/** Algorithm identifier for SPHINCS+-SHAKE256-192f-simple */
#define OQS_SIG_alg_sphincs_shake256_192f_simple "SPHINCS+-SHAKE256-192f-simple"
/** Algorithm identifier for SPHINCS+-SHAKE256-192s-robust */
#define OQS_SIG_alg_sphincs_shake256_192s_robust "SPHINCS+-SHAKE256-192s-robust"
/** Algorithm identifier for SPHINCS+-SHAKE256-192s-simple */
#define OQS_SIG_alg_sphincs_shake256_192s_simple "SPHINCS+-SHAKE256-192s-simple"
/** Algorithm identifier for SPHINCS+-SHAKE256-256f-robust */
#define OQS_SIG_alg_sphincs_shake256_256f_robust "SPHINCS+-SHAKE256-256f-robust"
/** Algorithm identifier for SPHINCS+-SHAKE256-256f-simple */
#define OQS_SIG_alg_sphincs_shake256_256f_simple "SPHINCS+-SHAKE256-256f-simple"
/** Algorithm identifier for SPHINCS+-SHAKE256-256s-robust */
#define OQS_SIG_alg_sphincs_shake256_256s_robust "SPHINCS+-SHAKE256-256s-robust"
/** Algorithm identifier for SPHINCS+-SHAKE256-256s-simple */
#define OQS_SIG_alg_sphincs_shake256_256s_simple "SPHINCS+-SHAKE256-256s-simple"
///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_ALG_IDENTIFIER_END
// EDIT-WHEN-ADDING-SIG
///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_ALGS_LENGTH_START
/** Number of algorithm identifiers above. */
#define OQS_SIG_algs_length 44
///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_ALGS_LENGTH_END
/**
* 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.
*
* @param[in] i Index of the algorithm identifier to return, 0 <= i < OQS_SIG_algs_length
* @return Algorithm identifier as a string, or NULL.
*/
OQS_API const char *OQS_SIG_alg_identifier(size_t i);
/**
* 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.
*
* @return The number of signature mechanisms.
*/
OQS_API int OQS_SIG_alg_count(void);
/**
* Indicates whether the specified algorithm was enabled at compile-time or not.
*
* @param[in] method_name Name of the desired algorithm; one of the names in `OQS_SIG_algs`.
* @return 1 if enabled, 0 if disabled or not found
*/
OQS_API int OQS_SIG_alg_is_enabled(const char *method_name);
/**
* Signature schemes object
*/
typedef struct OQS_SIG {
/** Printable string representing the name of the signature scheme. */
const char *method_name;
/**
* Printable string representing the version of the cryptographic algorithm.
*
* Implementations with the same method_name and same alg_version will be interoperable.
* See README.md for information about algorithm compatibility.
*/
const char *alg_version;
/** The NIST security level (1, 2, 3, 4, 5) claimed in this algorithm's original NIST submission. */
uint8_t claimed_nist_level;
/** Whether the signature offers EUF-CMA security (TRUE) or not (FALSE). */
bool euf_cma;
/** The (maximum) length, in bytes, of public keys for this signature scheme. */
size_t length_public_key;
/** The (maximum) length, in bytes, of secret keys for this signature scheme. */
size_t length_secret_key;
/** The (maximum) length, in bytes, of signatures for this signature scheme. */
size_t length_signature;
/**
* 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_*`.
*
* @param[out] public_key The public key represented as a byte string.
* @param[out] secret_key The secret key represented as a byte string.
* @return OQS_SUCCESS or OQS_ERROR
*/
OQS_STATUS (*keypair)(uint8_t *public_key, uint8_t *secret_key);
/**
* Signature generation algorithm.
*
* 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_*`.
*
* @param[out] signature The signature on the message represented as a byte string.
* @param[out] signature_len The actual length of the signature. May be smaller than `length_signature` for some algorithms since some algorithms have variable length signatures.
* @param[in] message The message to sign represented as a byte string.
* @param[in] message_len The length of the message to sign.
* @param[in] secret_key The secret key represented as a byte string.
* @return OQS_SUCCESS or OQS_ERROR
*/
OQS_STATUS (*sign)(uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len, const uint8_t *secret_key);
/**
* Signature verification algorithm.
*
* @param[in] message The message represented as a byte string.
* @param[in] message_len The length of the message.
* @param[in] signature The signature on the message represented as a byte string.
* @param[in] signature_len The length of the signature.
* @param[in] public_key The public key represented as a byte string.
* @return OQS_SUCCESS or OQS_ERROR
*/
OQS_STATUS (*verify)(const uint8_t *message, size_t message_len, const uint8_t *signature, size_t signature_len, const uint8_t *public_key);
} OQS_SIG;
/**
* 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.
*
* @param[in] method_name Name of the desired algorithm; one of the names in `OQS_SIG_algs`.
* @return An OQS_SIG for the particular algorithm, or `NULL` if the algorithm has been disabled at compile-time.
*/
OQS_API OQS_SIG *OQS_SIG_new(const char *method_name);
/**
* 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_*`.
*
* @param[in] sig The OQS_SIG object representing the signature scheme.
* @param[out] public_key The public key represented as a byte string.
* @param[out] secret_key The secret key represented as a byte string.
* @return OQS_SUCCESS or OQS_ERROR
*/
OQS_API OQS_STATUS OQS_SIG_keypair(const OQS_SIG *sig, uint8_t *public_key, 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_*`.
*
* @param[in] sig The OQS_SIG object representing the signature scheme.
* @param[out] signature The signature on the message represented as a byte string.
* @param[out] signature_len The length of the signature.
* @param[in] message The message to sign represented as a byte string.
* @param[in] message_len The length of the message to sign.
* @param[in] secret_key The secret key represented as a byte string.
* @return OQS_SUCCESS or OQS_ERROR
*/
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 verification algorithm.
*
* @param[in] sig The OQS_SIG object representing the signature scheme.
* @param[in] message The message represented as a byte string.
* @param[in] message_len The length of the message.
* @param[in] signature The signature on the message represented as a byte string.
* @param[in] signature_len The length of the signature.
* @param[in] public_key The public key represented as a byte string.
* @return OQS_SUCCESS or OQS_ERROR
*/
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);
/**
* Frees an OQS_SIG object that was constructed by OQS_SIG_new.
*
* @param[in] sig The OQS_SIG object to free.
*/
OQS_API void OQS_SIG_free(OQS_SIG *sig);
///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_INCLUDE_START
#ifdef OQS_ENABLE_SIG_DILITHIUM
#include <oqs/sig_dilithium.h>
#endif /* OQS_ENABLE_SIG_DILITHIUM */
#ifdef OQS_ENABLE_SIG_FALCON
#include <oqs/sig_falcon.h>
#endif /* OQS_ENABLE_SIG_FALCON */
#ifdef OQS_ENABLE_SIG_SPHINCS
#include <oqs/sig_sphincs.h>
#endif /* OQS_ENABLE_SIG_SPHINCS */
///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_INCLUDE_END
// EDIT-WHEN-ADDING-SIG
#if defined(__cplusplus)
} // extern "C"
#endif
#endif // OQS_SIG_H
|
