1 /* Copyright 2024 The BoringSSL Authors 2 * 3 * Permission to use, copy, modify, and/or distribute this software for any 4 * purpose with or without fee is hereby granted, provided that the above 5 * copyright notice and this permission notice appear in all copies. 6 * 7 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 8 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 9 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 10 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 11 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION 12 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 13 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ 14 15 #ifndef OPENSSL_HEADER_SLHDSA_H 16 #define OPENSSL_HEADER_SLHDSA_H 17 18 #include <openssl/base.h> 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 25 // SLHDSA_SHA2_128S_PUBLIC_KEY_BYTES is the number of bytes in an 26 // SLH-DSA-SHA2-128s public key. 27 #define SLHDSA_SHA2_128S_PUBLIC_KEY_BYTES 32 28 29 // SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES is the number of bytes in an 30 // SLH-DSA-SHA2-128s private key. 31 #define SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES 64 32 33 // SLHDSA_SHA2_128S_SIGNATURE_BYTES is the number of bytes in an 34 // SLH-DSA-SHA2-128s signature. 35 #define SLHDSA_SHA2_128S_SIGNATURE_BYTES 7856 36 37 // SLHDSA_SHA2_128S_generate_key generates a SLH-DSA-SHA2-128s key pair and 38 // writes the result to |out_public_key| and |out_private_key|. 39 OPENSSL_EXPORT void SLHDSA_SHA2_128S_generate_key( 40 uint8_t out_public_key[SLHDSA_SHA2_128S_PUBLIC_KEY_BYTES], 41 uint8_t out_private_key[SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES]); 42 43 // SLHDSA_SHA2_128S_public_from_private writes the public key corresponding to 44 // |private_key| to |out_public_key|. 45 OPENSSL_EXPORT void SLHDSA_SHA2_128S_public_from_private( 46 uint8_t out_public_key[SLHDSA_SHA2_128S_PUBLIC_KEY_BYTES], 47 const uint8_t private_key[SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES]); 48 49 // SLHDSA_SHA2_128S_sign slowly generates a SLH-DSA-SHA2-128s signature of |msg| 50 // using |private_key| and writes it to |out_signature|. The |context| argument 51 // is also signed over and can be used to include implicit contextual 52 // information that isn't included in |msg|. The same value of |context| must be 53 // presented to |SLHDSA_SHA2_128S_verify| in order for the generated signature 54 // to be considered valid. |context| and |context_len| may be |NULL| and 0 to 55 // use an empty context (this is common). It returns 1 on success and 0 if 56 // |context_len| is larger than 255. 57 OPENSSL_EXPORT int SLHDSA_SHA2_128S_sign( 58 uint8_t out_signature[SLHDSA_SHA2_128S_SIGNATURE_BYTES], 59 const uint8_t private_key[SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES], 60 const uint8_t *msg, size_t msg_len, const uint8_t *context, 61 size_t context_len); 62 63 // SLHDSA_SHA2_128S_verify verifies that |signature| is a valid 64 // SLH-DSA-SHA2-128s signature of |msg| by |public_key|. The value of |context| 65 // must equal the value that was passed to |SLHDSA_SHA2_128S_sign| when the 66 // signature was generated. It returns 1 if the signature is valid and 0 67 // otherwise. 68 OPENSSL_EXPORT int SLHDSA_SHA2_128S_verify( 69 const uint8_t *signature, size_t signature_len, 70 const uint8_t public_key[SLHDSA_SHA2_128S_PUBLIC_KEY_BYTES], 71 const uint8_t *msg, size_t msg_len, const uint8_t *context, 72 size_t context_len); 73 74 75 // Prehashed SLH-DSA-SHA2-128s. 76 // 77 // These functions sign the hash of a message. They should generally not be 78 // used. The general functions are perfectly capable of signing a hash if you 79 // wish. These functions should only be used when: 80 // 81 // a) Compatibility with an external system that uses prehashed messages is 82 // required. (The general signature of a hash is not compatible with a 83 // "prehash" signature of the same hash.) 84 // b) A single private key is used to sign both prehashed and raw messages, 85 // and there's no other way to prevent ambiguity. 86 87 // SLHDSA_SHA2_128S_prehash_sign slowly generates a SLH-DSA-SHA2-128s signature 88 // of the prehashed |hashed_msg| using |private_key| and writes it to 89 // |out_signature|. The |context| argument is also signed over and can be used 90 // to include implicit contextual information that isn't included in 91 // |hashed_msg|. The same value of |context| must be presented to 92 // |SLHDSA_SHA2_128S_prehash_verify| in order for the generated signature to be 93 // considered valid. |context| and |context_len| may be |NULL| and 0 to use an 94 // empty context (this is common). 95 // 96 // The |hash_nid| argument must specify the hash function that was used to 97 // generate |hashed_msg|. This function only accepts hash functions listed in 98 // FIPS 205. 99 // 100 // This function returns 1 on success and 0 if |context_len| is larger than 255, 101 // if the hash function is not supported, or if |hashed_msg| is the wrong 102 // length. 103 OPENSSL_EXPORT int SLHDSA_SHA2_128S_prehash_sign( 104 uint8_t out_signature[SLHDSA_SHA2_128S_SIGNATURE_BYTES], 105 const uint8_t private_key[SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES], 106 const uint8_t *hashed_msg, size_t hashed_msg_len, int hash_nid, 107 const uint8_t *context, size_t context_len); 108 109 // SLHDSA_SHA2_128S_prehash_verify verifies that |signature| is a valid 110 // SLH-DSA-SHA2-128s signature of the prehashed |hashed_msg| by |public_key|, 111 // using the hash algorithm identified by |hash_nid|. The value of |context| 112 // must equal the value that was passed to |SLHDSA_SHA2_128S_prehash_sign| when 113 // the signature was generated. 114 // 115 // The |hash_nid| argument must specify the hash function that was used to 116 // generate |hashed_msg|. This function only accepts hash functions that are 117 // listed in FIPS 205. 118 // 119 // This function returns 1 if the signature is valid and 0 if the signature is 120 // invalid, the hash function is not supported, or if |hashed_msg| is the wrong 121 // length. 122 OPENSSL_EXPORT int SLHDSA_SHA2_128S_prehash_verify( 123 const uint8_t *signature, size_t signature_len, 124 const uint8_t public_key[SLHDSA_SHA2_128S_PUBLIC_KEY_BYTES], 125 const uint8_t *hashed_msg, size_t hashed_msg_len, int hash_nid, 126 const uint8_t *context, size_t context_len); 127 128 // SLHDSA_SHA2_128S_prehash_warning_nonstandard_sign slowly generates a 129 // SLH-DSA-SHA2-128s signature of the prehashed |hashed_msg| using |private_key| 130 // and writes it to |out_signature|. The |context| argument is also signed over 131 // and can be used to include implicit contextual information that isn't 132 // included in |hashed_msg|. The same value of |context| must be presented to 133 // |SLHDSA_SHA2_128S_prehash_warning_nonstandard_verify| in order for the 134 // generated signature to be considered valid. |context| and |context_len| may 135 // be |NULL| and 0 to use an empty context (this is common). 136 // 137 // The |hash_nid| argument must specify the hash function that was used to 138 // generate |hashed_msg|. This function only accepts non-standard hash functions 139 // that are not compliant with FIPS 205. 140 // 141 // This function returns 1 on success and 0 if |context_len| is larger than 255, 142 // if the hash function is not supported, or if |hashed_msg| is the wrong 143 // length. 144 OPENSSL_EXPORT int SLHDSA_SHA2_128S_prehash_warning_nonstandard_sign( 145 uint8_t out_signature[SLHDSA_SHA2_128S_SIGNATURE_BYTES], 146 const uint8_t private_key[SLHDSA_SHA2_128S_PRIVATE_KEY_BYTES], 147 const uint8_t *hashed_msg, size_t hashed_msg_len, int hash_nid, 148 const uint8_t *context, size_t context_len); 149 150 // SLHDSA_SHA2_128S_prehash_warning_nonstandard_verify verifies that |signature| 151 // is a valid SLH-DSA-SHA2-128s signature of the prehashed |hashed_msg| by 152 // |public_key|, using the hash algorithm identified by |hash_nid|. The value of 153 // |context| must equal the value that was passed to 154 // |SLHDSA_SHA2_128S_prehash_sign| when the signature was generated. 155 // 156 // The |hash_nid| argument must specify the hash function that was used to 157 // generate |hashed_msg|. This function only accepts non-standard hash functions 158 // that are not compliant with FIPS 205. 159 // 160 // This function returns 1 if the signature is valid and 0 if the signature is 161 // invalid, the hash function is not supported, or if |hashed_msg| is the wrong 162 // length. 163 OPENSSL_EXPORT int SLHDSA_SHA2_128S_prehash_warning_nonstandard_verify( 164 const uint8_t *signature, size_t signature_len, 165 const uint8_t public_key[SLHDSA_SHA2_128S_PUBLIC_KEY_BYTES], 166 const uint8_t *hashed_msg, size_t hashed_msg_len, int hash_nid, 167 const uint8_t *context, size_t context_len); 168 169 170 #if defined(__cplusplus) 171 } // extern C 172 #endif 173 174 #endif // OPENSSL_HEADER_SLHDSA_H 175