1 /** 2 * \file sig.h 3 * \brief Signature schemes 4 * 5 * The file `tests/example_sig.c` contains two examples on using the OQS_SIG API. 6 * 7 * The first example uses the individual scheme's algorithms directly and uses 8 * no dynamic memory allocation -- all buffers are allocated on the stack, with 9 * sizes indicated using preprocessor macros. Since algorithms can be disabled at 10 * compile-time, the programmer should wrap the code in \#ifdefs. 11 * 12 * The second example uses an OQS_SIG object to use an algorithm specified at 13 * runtime. Therefore it uses dynamic memory allocation -- all buffers must be 14 * malloc'ed by the programmer, with sizes indicated using the corresponding length 15 * member of the OQS_SIG object in question. Since algorithms can be disabled at 16 * compile-time, the programmer should check that the OQS_SIG object is not `NULL`. 17 * 18 * SPDX-License-Identifier: MIT 19 */ 20 21 #ifndef OQS_SIG_H 22 #define OQS_SIG_H 23 24 #include <stdbool.h> 25 #include <stddef.h> 26 #include <stdint.h> 27 28 #include <oqs/oqs.h> 29 30 #if defined(__cplusplus) 31 extern "C" { 32 #endif 33 34 /** Algorithm identifier for picnic_L1_FS */ 35 #define OQS_SIG_alg_picnic_L1_FS "picnic_L1_FS" 36 /** Algorithm identifier for picnic_L1_UR */ 37 #define OQS_SIG_alg_picnic_L1_UR "picnic_L1_UR" 38 /** Algorithm identifier for picnic_L1_full */ 39 #define OQS_SIG_alg_picnic_L1_full "picnic_L1_full" 40 /** Algorithm identifier for picnic_L3_FS */ 41 #define OQS_SIG_alg_picnic_L3_FS "picnic_L3_FS" 42 /** Algorithm identifier for picnic_L3_UR */ 43 #define OQS_SIG_alg_picnic_L3_UR "picnic_L3_UR" 44 /** Algorithm identifier for picnic_L3_full */ 45 #define OQS_SIG_alg_picnic_L3_full "picnic_L3_full" 46 /** Algorithm identifier for picnic_L5_FS */ 47 #define OQS_SIG_alg_picnic_L5_FS "picnic_L5_FS" 48 /** Algorithm identifier for picnic_L5_FS */ 49 #define OQS_SIG_alg_picnic_L5_UR "picnic_L5_UR" 50 /** Algorithm identifier for picnic_L5_full */ 51 #define OQS_SIG_alg_picnic_L5_full "picnic_L5_full" 52 /** Algorithm identifier for picnic3_L1 */ 53 #define OQS_SIG_alg_picnic3_L1 "picnic3_L1" 54 /** Algorithm identifier for picnic3_L3 */ 55 #define OQS_SIG_alg_picnic3_L3 "picnic3_L3" 56 /** Algorithm identifier for picnic3_L5 */ 57 #define OQS_SIG_alg_picnic3_L5 "picnic3_L5" 58 ///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_ALG_IDENTIFIER_START 59 /** Algorithm identifier for Dilithium2 */ 60 #define OQS_SIG_alg_dilithium_2 "Dilithium2" 61 /** Algorithm identifier for Dilithium3 */ 62 #define OQS_SIG_alg_dilithium_3 "Dilithium3" 63 /** Algorithm identifier for Dilithium5 */ 64 #define OQS_SIG_alg_dilithium_5 "Dilithium5" 65 /** Algorithm identifier for Dilithium2-AES */ 66 #define OQS_SIG_alg_dilithium_2_aes "Dilithium2-AES" 67 /** Algorithm identifier for Dilithium3-AES */ 68 #define OQS_SIG_alg_dilithium_3_aes "Dilithium3-AES" 69 /** Algorithm identifier for Dilithium5-AES */ 70 #define OQS_SIG_alg_dilithium_5_aes "Dilithium5-AES" 71 /** Algorithm identifier for Falcon-512 */ 72 #define OQS_SIG_alg_falcon_512 "Falcon-512" 73 /** Algorithm identifier for Falcon-1024 */ 74 #define OQS_SIG_alg_falcon_1024 "Falcon-1024" 75 /** Algorithm identifier for Rainbow-I-Classic */ 76 #define OQS_SIG_alg_rainbow_I_classic "Rainbow-I-Classic" 77 /** Algorithm identifier for Rainbow-I-Circumzenithal */ 78 #define OQS_SIG_alg_rainbow_I_circumzenithal "Rainbow-I-Circumzenithal" 79 /** Algorithm identifier for Rainbow-I-Compressed */ 80 #define OQS_SIG_alg_rainbow_I_compressed "Rainbow-I-Compressed" 81 /** Algorithm identifier for Rainbow-III-Classic */ 82 #define OQS_SIG_alg_rainbow_III_classic "Rainbow-III-Classic" 83 /** Algorithm identifier for Rainbow-III-Circumzenithal */ 84 #define OQS_SIG_alg_rainbow_III_circumzenithal "Rainbow-III-Circumzenithal" 85 /** Algorithm identifier for Rainbow-III-Compressed */ 86 #define OQS_SIG_alg_rainbow_III_compressed "Rainbow-III-Compressed" 87 /** Algorithm identifier for Rainbow-V-Classic */ 88 #define OQS_SIG_alg_rainbow_V_classic "Rainbow-V-Classic" 89 /** Algorithm identifier for Rainbow-V-Circumzenithal */ 90 #define OQS_SIG_alg_rainbow_V_circumzenithal "Rainbow-V-Circumzenithal" 91 /** Algorithm identifier for Rainbow-V-Compressed */ 92 #define OQS_SIG_alg_rainbow_V_compressed "Rainbow-V-Compressed" 93 /** Algorithm identifier for SPHINCS+-Haraka-128f-robust */ 94 #define OQS_SIG_alg_sphincs_haraka_128f_robust "SPHINCS+-Haraka-128f-robust" 95 /** Algorithm identifier for SPHINCS+-Haraka-128f-simple */ 96 #define OQS_SIG_alg_sphincs_haraka_128f_simple "SPHINCS+-Haraka-128f-simple" 97 /** Algorithm identifier for SPHINCS+-Haraka-128s-robust */ 98 #define OQS_SIG_alg_sphincs_haraka_128s_robust "SPHINCS+-Haraka-128s-robust" 99 /** Algorithm identifier for SPHINCS+-Haraka-128s-simple */ 100 #define OQS_SIG_alg_sphincs_haraka_128s_simple "SPHINCS+-Haraka-128s-simple" 101 /** Algorithm identifier for SPHINCS+-Haraka-192f-robust */ 102 #define OQS_SIG_alg_sphincs_haraka_192f_robust "SPHINCS+-Haraka-192f-robust" 103 /** Algorithm identifier for SPHINCS+-Haraka-192f-simple */ 104 #define OQS_SIG_alg_sphincs_haraka_192f_simple "SPHINCS+-Haraka-192f-simple" 105 /** Algorithm identifier for SPHINCS+-Haraka-192s-robust */ 106 #define OQS_SIG_alg_sphincs_haraka_192s_robust "SPHINCS+-Haraka-192s-robust" 107 /** Algorithm identifier for SPHINCS+-Haraka-192s-simple */ 108 #define OQS_SIG_alg_sphincs_haraka_192s_simple "SPHINCS+-Haraka-192s-simple" 109 /** Algorithm identifier for SPHINCS+-Haraka-256f-robust */ 110 #define OQS_SIG_alg_sphincs_haraka_256f_robust "SPHINCS+-Haraka-256f-robust" 111 /** Algorithm identifier for SPHINCS+-Haraka-256f-simple */ 112 #define OQS_SIG_alg_sphincs_haraka_256f_simple "SPHINCS+-Haraka-256f-simple" 113 /** Algorithm identifier for SPHINCS+-Haraka-256s-robust */ 114 #define OQS_SIG_alg_sphincs_haraka_256s_robust "SPHINCS+-Haraka-256s-robust" 115 /** Algorithm identifier for SPHINCS+-Haraka-256s-simple */ 116 #define OQS_SIG_alg_sphincs_haraka_256s_simple "SPHINCS+-Haraka-256s-simple" 117 /** Algorithm identifier for SPHINCS+-SHA256-128f-robust */ 118 #define OQS_SIG_alg_sphincs_sha256_128f_robust "SPHINCS+-SHA256-128f-robust" 119 /** Algorithm identifier for SPHINCS+-SHA256-128f-simple */ 120 #define OQS_SIG_alg_sphincs_sha256_128f_simple "SPHINCS+-SHA256-128f-simple" 121 /** Algorithm identifier for SPHINCS+-SHA256-128s-robust */ 122 #define OQS_SIG_alg_sphincs_sha256_128s_robust "SPHINCS+-SHA256-128s-robust" 123 /** Algorithm identifier for SPHINCS+-SHA256-128s-simple */ 124 #define OQS_SIG_alg_sphincs_sha256_128s_simple "SPHINCS+-SHA256-128s-simple" 125 /** Algorithm identifier for SPHINCS+-SHA256-192f-robust */ 126 #define OQS_SIG_alg_sphincs_sha256_192f_robust "SPHINCS+-SHA256-192f-robust" 127 /** Algorithm identifier for SPHINCS+-SHA256-192f-simple */ 128 #define OQS_SIG_alg_sphincs_sha256_192f_simple "SPHINCS+-SHA256-192f-simple" 129 /** Algorithm identifier for SPHINCS+-SHA256-192s-robust */ 130 #define OQS_SIG_alg_sphincs_sha256_192s_robust "SPHINCS+-SHA256-192s-robust" 131 /** Algorithm identifier for SPHINCS+-SHA256-192s-simple */ 132 #define OQS_SIG_alg_sphincs_sha256_192s_simple "SPHINCS+-SHA256-192s-simple" 133 /** Algorithm identifier for SPHINCS+-SHA256-256f-robust */ 134 #define OQS_SIG_alg_sphincs_sha256_256f_robust "SPHINCS+-SHA256-256f-robust" 135 /** Algorithm identifier for SPHINCS+-SHA256-256f-simple */ 136 #define OQS_SIG_alg_sphincs_sha256_256f_simple "SPHINCS+-SHA256-256f-simple" 137 /** Algorithm identifier for SPHINCS+-SHA256-256s-robust */ 138 #define OQS_SIG_alg_sphincs_sha256_256s_robust "SPHINCS+-SHA256-256s-robust" 139 /** Algorithm identifier for SPHINCS+-SHA256-256s-simple */ 140 #define OQS_SIG_alg_sphincs_sha256_256s_simple "SPHINCS+-SHA256-256s-simple" 141 /** Algorithm identifier for SPHINCS+-SHAKE256-128f-robust */ 142 #define OQS_SIG_alg_sphincs_shake256_128f_robust "SPHINCS+-SHAKE256-128f-robust" 143 /** Algorithm identifier for SPHINCS+-SHAKE256-128f-simple */ 144 #define OQS_SIG_alg_sphincs_shake256_128f_simple "SPHINCS+-SHAKE256-128f-simple" 145 /** Algorithm identifier for SPHINCS+-SHAKE256-128s-robust */ 146 #define OQS_SIG_alg_sphincs_shake256_128s_robust "SPHINCS+-SHAKE256-128s-robust" 147 /** Algorithm identifier for SPHINCS+-SHAKE256-128s-simple */ 148 #define OQS_SIG_alg_sphincs_shake256_128s_simple "SPHINCS+-SHAKE256-128s-simple" 149 /** Algorithm identifier for SPHINCS+-SHAKE256-192f-robust */ 150 #define OQS_SIG_alg_sphincs_shake256_192f_robust "SPHINCS+-SHAKE256-192f-robust" 151 /** Algorithm identifier for SPHINCS+-SHAKE256-192f-simple */ 152 #define OQS_SIG_alg_sphincs_shake256_192f_simple "SPHINCS+-SHAKE256-192f-simple" 153 /** Algorithm identifier for SPHINCS+-SHAKE256-192s-robust */ 154 #define OQS_SIG_alg_sphincs_shake256_192s_robust "SPHINCS+-SHAKE256-192s-robust" 155 /** Algorithm identifier for SPHINCS+-SHAKE256-192s-simple */ 156 #define OQS_SIG_alg_sphincs_shake256_192s_simple "SPHINCS+-SHAKE256-192s-simple" 157 /** Algorithm identifier for SPHINCS+-SHAKE256-256f-robust */ 158 #define OQS_SIG_alg_sphincs_shake256_256f_robust "SPHINCS+-SHAKE256-256f-robust" 159 /** Algorithm identifier for SPHINCS+-SHAKE256-256f-simple */ 160 #define OQS_SIG_alg_sphincs_shake256_256f_simple "SPHINCS+-SHAKE256-256f-simple" 161 /** Algorithm identifier for SPHINCS+-SHAKE256-256s-robust */ 162 #define OQS_SIG_alg_sphincs_shake256_256s_robust "SPHINCS+-SHAKE256-256s-robust" 163 /** Algorithm identifier for SPHINCS+-SHAKE256-256s-simple */ 164 #define OQS_SIG_alg_sphincs_shake256_256s_simple "SPHINCS+-SHAKE256-256s-simple" 165 ///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_ALG_IDENTIFIER_END 166 // EDIT-WHEN-ADDING-SIG 167 ///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_ALGS_LENGTH_START 168 /** Number of algorithm identifiers above. */ 169 #define OQS_SIG_algs_length 65 170 ///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_ALGS_LENGTH_END 171 172 /** 173 * Returns identifiers for available signature schemes in liboqs. Used with OQS_SIG_new. 174 * 175 * Note that algorithm identifiers are present in this list even when the algorithm is disabled 176 * at compile time. 177 * 178 * @param[in] i Index of the algorithm identifier to return, 0 <= i < OQS_SIG_algs_length 179 * @return Algorithm identifier as a string, or NULL. 180 */ 181 OQS_API const char *OQS_SIG_alg_identifier(size_t i); 182 183 /** 184 * Returns the number of signature mechanisms in liboqs. They can be enumerated with 185 * OQS_SIG_alg_identifier. 186 * 187 * Note that some mechanisms may be disabled at compile time. 188 * 189 * @return The number of signature mechanisms. 190 */ 191 OQS_API int OQS_SIG_alg_count(void); 192 193 /** 194 * Indicates whether the specified algorithm was enabled at compile-time or not. 195 * 196 * @param[in] method_name Name of the desired algorithm; one of the names in `OQS_SIG_algs`. 197 * @return 1 if enabled, 0 if disabled or not found 198 */ 199 OQS_API int OQS_SIG_alg_is_enabled(const char *method_name); 200 201 /** 202 * Signature schemes object 203 */ 204 typedef struct OQS_SIG { 205 206 /** Printable string representing the name of the signature scheme. */ 207 const char *method_name; 208 209 /** 210 * Printable string representing the version of the cryptographic algorithm. 211 * 212 * Implementations with the same method_name and same alg_version will be interoperable. 213 * See README.md for information about algorithm compatibility. 214 */ 215 const char *alg_version; 216 217 /** The NIST security level (1, 2, 3, 4, 5) claimed in this algorithm's original NIST submission. */ 218 uint8_t claimed_nist_level; 219 220 /** Whether the signature offers EUF-CMA security (TRUE) or not (FALSE). */ 221 bool euf_cma; 222 223 /** The (maximum) length, in bytes, of public keys for this signature scheme. */ 224 size_t length_public_key; 225 /** The (maximum) length, in bytes, of secret keys for this signature scheme. */ 226 size_t length_secret_key; 227 /** The (maximum) length, in bytes, of signatures for this signature scheme. */ 228 size_t length_signature; 229 230 /** 231 * Keypair generation algorithm. 232 * 233 * Caller is responsible for allocating sufficient memory for `public_key` and 234 * `secret_key`, based on the `length_*` members in this object or the per-scheme 235 * compile-time macros `OQS_SIG_*_length_*`. 236 * 237 * @param[out] public_key The public key represented as a byte string. 238 * @param[out] secret_key The secret key represented as a byte string. 239 * @return OQS_SUCCESS or OQS_ERROR 240 */ 241 OQS_STATUS (*keypair)(uint8_t *public_key, uint8_t *secret_key); 242 243 /** 244 * Signature generation algorithm. 245 * 246 * Caller is responsible for allocating sufficient memory for `signature`, 247 * based on the `length_*` members in this object or the per-scheme 248 * compile-time macros `OQS_SIG_*_length_*`. 249 * 250 * @param[out] signature The signature on the message represented as a byte string. 251 * @param[out] signature_len The length of the signature. 252 * @param[in] message The message to sign represented as a byte string. 253 * @param[in] message_len The length of the message to sign. 254 * @param[in] secret_key The secret key represented as a byte string. 255 * @return OQS_SUCCESS or OQS_ERROR 256 */ 257 OQS_STATUS (*sign)(uint8_t *signature, size_t *signature_len, const uint8_t *message, size_t message_len, const uint8_t *secret_key); 258 259 /** 260 * Signature verification algorithm. 261 * 262 * @param[in] message The message represented as a byte string. 263 * @param[in] message_len The length of the message. 264 * @param[in] signature The signature on the message represented as a byte string. 265 * @param[in] signature_len The length of the signature. 266 * @param[in] public_key The public key represented as a byte string. 267 * @return OQS_SUCCESS or OQS_ERROR 268 */ 269 OQS_STATUS (*verify)(const uint8_t *message, size_t message_len, const uint8_t *signature, size_t signature_len, const uint8_t *public_key); 270 271 } OQS_SIG; 272 273 /** 274 * Constructs an OQS_SIG object for a particular algorithm. 275 * 276 * Callers should always check whether the return value is `NULL`, which indicates either than an 277 * invalid algorithm name was provided, or that the requested algorithm was disabled at compile-time. 278 * 279 * @param[in] method_name Name of the desired algorithm; one of the names in `OQS_SIG_algs`. 280 * @return An OQS_SIG for the particular algorithm, or `NULL` if the algorithm has been disabled at compile-time. 281 */ 282 OQS_API OQS_SIG *OQS_SIG_new(const char *method_name); 283 284 /** 285 * Keypair generation algorithm. 286 * 287 * Caller is responsible for allocating sufficient memory for `public_key` and 288 * `secret_key`, based on the `length_*` members in this object or the per-scheme 289 * compile-time macros `OQS_SIG_*_length_*`. 290 * 291 * @param[in] sig The OQS_SIG object representing the signature scheme. 292 * @param[out] public_key The public key represented as a byte string. 293 * @param[out] secret_key The secret key represented as a byte string. 294 * @return OQS_SUCCESS or OQS_ERROR 295 */ 296 OQS_API OQS_STATUS OQS_SIG_keypair(const OQS_SIG *sig, uint8_t *public_key, uint8_t *secret_key); 297 298 /** 299 * Signature generation algorithm. 300 * 301 * Caller is responsible for allocating sufficient memory for `signnature`, 302 * based on the `length_*` members in this object or the per-scheme 303 * compile-time macros `OQS_SIG_*_length_*`. 304 * 305 * @param[in] sig The OQS_SIG object representing the signature scheme. 306 * @param[out] signature The signature on the message represented as a byte string. 307 * @param[out] signature_len The length of the signature. 308 * @param[in] message The message to sign represented as a byte string. 309 * @param[in] message_len The length of the message to sign. 310 * @param[in] secret_key The secret key represented as a byte string. 311 * @return OQS_SUCCESS or OQS_ERROR 312 */ 313 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); 314 315 /** 316 * Signature verification algorithm. 317 * 318 * @param[in] sig The OQS_SIG object representing the signature scheme. 319 * @param[in] message The message represented as a byte string. 320 * @param[in] message_len The length of the message. 321 * @param[in] signature The signature on the message represented as a byte string. 322 * @param[in] signature_len The length of the signature. 323 * @param[in] public_key The public key represented as a byte string. 324 * @return OQS_SUCCESS or OQS_ERROR 325 */ 326 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); 327 328 /** 329 * Frees an OQS_SIG object that was constructed by OQS_SIG_new. 330 * 331 * @param[in] sig The OQS_SIG object to free. 332 */ 333 OQS_API void OQS_SIG_free(OQS_SIG *sig); 334 335 #ifdef OQS_ENABLE_SIG_PICNIC 336 #include <oqs/sig_picnic.h> 337 #endif /* OQS_ENABLE_SIG_PICNIC */ 338 ///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_INCLUDE_START 339 #ifdef OQS_ENABLE_SIG_DILITHIUM 340 #include <oqs/sig_dilithium.h> 341 #endif /* OQS_ENABLE_SIG_DILITHIUM */ 342 #ifdef OQS_ENABLE_SIG_FALCON 343 #include <oqs/sig_falcon.h> 344 #endif /* OQS_ENABLE_SIG_FALCON */ 345 #ifdef OQS_ENABLE_SIG_RAINBOW 346 #include <oqs/sig_rainbow.h> 347 #endif /* OQS_ENABLE_SIG_RAINBOW */ 348 #ifdef OQS_ENABLE_SIG_SPHINCS 349 #include <oqs/sig_sphincs.h> 350 #endif /* OQS_ENABLE_SIG_SPHINCS */ 351 ///// OQS_COPY_FROM_UPSTREAM_FRAGMENT_INCLUDE_END 352 // EDIT-WHEN-ADDING-SIG 353 354 #if defined(__cplusplus) 355 } // extern "C" 356 #endif 357 358 #endif // OQS_SIG_H 359