sfinx.h (10687B)
1 #ifndef __SFINX_H__ 2 #define __SFINX_H__ 3 4 /// sfinx api 5 /// ========= 6 /// 7 /// Reference for the sfinx C library, generated from `src/sfinx.h`. The scheme 8 /// is described in [scheme.md](scheme.md), the command line in 9 /// [cli.md](cli.md). 10 /// 11 /// Sizing calls are pure and return a byte count, or 0 when the arguments do 12 /// not describe a valid signature. Every other entry point returns an 13 /// `sfinx_status`. 14 /// 15 16 #include <stddef.h> 17 #include <stdint.h> 18 #include <sys/types.h> 19 20 // Hash sizes {{{ 21 22 /// Hash sizes 23 /// ---------- 24 /// 25 /// SHA3 digest size in bits, `L` is the byte size: 224 -> 28, 256 -> 32, 26 /// 384 -> 48, 512 -> 64. 27 ///< c 28 #define SFINX_HASH_DEFAULT SFINX_HASH_256 29 #define SFINX_HASH_LEN_MAX 64 30 31 typedef enum { 32 SFINX_HASH_224 = 224, 33 SFINX_HASH_256 = 256, 34 SFINX_HASH_384 = 384, 35 SFINX_HASH_512 = 512 36 } sfinx_hash; 37 ///> 38 39 /// <details> 40 /// <summary>sfinx_hash_len(hash)</summary> 41 /// 42 /// Byte length `L` of a hash size, 0 when the size is not supported 43 ///< c 44 size_t sfinx_hash_len(sfinx_hash hash); 45 ///> 46 /// </details> 47 48 // }}} 49 50 // Path {{{ 51 52 /// 53 /// Path and seed 54 /// ------------- 55 /// 56 /// `N` is the path length in bytes, and the number of subtrees. The path is 57 /// the randomizer, so it is drawn fresh per signature rather than derived from 58 /// the message. The upper bound is what E4M4 can represent. 59 ///< c 60 #define SFINX_PATH_LEN_DEFAULT 32 61 #define SFINX_PATH_LEN_MAX 507904 62 ///> 63 64 // }}} 65 66 // Seed {{{ 67 68 /// The seed is the secret, any byte string up to 64 MiB. Random bytes are 69 /// recommended, a passphrase is allowed. 70 ///< c 71 #define SFINX_SEED_LEN_MAX (64u * 1024u * 1024u) 72 ///> 73 74 // }}} 75 76 // Status {{{ 77 78 /// Status 79 /// ------ 80 /// 81 /// Returned by every entry point that can fail. 82 ///< c 83 typedef enum { 84 SFINX_OK = 0, 85 SFINX_ERR_ARGS, 86 SFINX_ERR_PATH_LEN, 87 SFINX_ERR_NOSPACE, 88 SFINX_ERR_FORMAT, 89 SFINX_ERR_VERIFY, 90 SFINX_ERR_RANDOM, 91 SFINX_ERR_UNIMPLEMENTED 92 } sfinx_status; 93 ///> 94 95 /// <details> 96 /// <summary>sfinx_strerror(status)</summary> 97 /// 98 /// Names a status code, never null 99 ///< c 100 const char *sfinx_strerror(sfinx_status status); 101 ///> 102 /// </details> 103 /// <details> 104 /// <summary>sfinx_version()</summary> 105 /// 106 /// Library version as a dotted string 107 ///< c 108 const char *sfinx_version(void); 109 ///> 110 /// </details> 111 112 // }}} 113 114 // API {{{ 115 116 /// 117 /// Sizing 118 /// ------ 119 /// 120 121 /// <details> 122 /// <summary>sfinx_signature_len(hash, path_len)</summary> 123 /// 124 /// Exact signature size for a hash size and path length 125 ///< c 126 size_t sfinx_signature_len(sfinx_hash hash, size_t path_len); 127 ///> 128 /// </details> 129 /// <details> 130 /// <summary>sfinx_signature_len_max(hash)</summary> 131 /// 132 /// Signature size at the longest representable path 133 ///< c 134 size_t sfinx_signature_len_max(sfinx_hash hash); 135 ///> 136 /// </details> 137 /// <details> 138 /// <summary>sfinx_path_len_valid(path_len)</summary> 139 /// 140 /// Non-zero when the length fits both the bound and the E4M4 encoding 141 ///< c 142 int sfinx_path_len_valid(size_t path_len); 143 ///> 144 /// </details> 145 /// <details> 146 /// <summary>sfinx_signature_info(sig, sig_len, hash_out, path_len_out)</summary> 147 /// 148 /// Read the hash size and path length out of a signature, without verifying 149 /// it. Either output may be null. 150 ///< c 151 sfinx_status sfinx_signature_info(const uint8_t *sig, size_t sig_len, sfinx_hash *hash_out, size_t *path_len_out); 152 ///> 153 /// </details> 154 155 /// 156 /// Signing 157 /// ------- 158 /// 159 /// Signing and key derivation take the seed, verification takes raw bytes. The 160 /// `_cap` argument is the size of the caller's buffer, and the `_len_out` 161 /// argument reports what was written and may be null. 162 163 /// <details> 164 /// <summary>sfinx_single_public_key(hash, seed, seed_len, pubkey_out, pubkey_cap, pubkey_len_out)</summary> 165 /// 166 /// Derive the single-key (`N = 0`) public key from a seed 167 ///< c 168 sfinx_status sfinx_single_public_key(sfinx_hash hash, const uint8_t *seed, size_t seed_len, uint8_t *pubkey_out, 169 size_t pubkey_cap, size_t *pubkey_len_out); 170 ///> 171 /// </details> 172 /// <details> 173 /// <summary>sfinx_single_sign(hash, seed, seed_len, msg, msg_len, sig, sig_cap, sig_len_out)</summary> 174 /// 175 /// Sign `H(message)` with one Winternitz key. One-time: signing two 176 /// different messages under one seed destroys unforgeability. 177 ///< c 178 sfinx_status sfinx_single_sign(sfinx_hash hash, const uint8_t *seed, size_t seed_len, const uint8_t *msg, 179 size_t msg_len, uint8_t *sig, size_t sig_cap, size_t *sig_len_out); 180 ///> 181 /// </details> 182 /// <details> 183 /// <summary>sfinx_tree_public_key(hash, seed, seed_len, path_len, pubkey_out, pubkey_cap, pubkey_len_out)</summary> 184 /// 185 /// Derive the tree public key from a seed. `N` is bound into every key, so a 186 /// public key verifies one path length. 187 ///< c 188 sfinx_status sfinx_tree_public_key(sfinx_hash hash, const uint8_t *seed, size_t seed_len, size_t path_len, 189 uint8_t *pubkey_out, size_t pubkey_cap, size_t *pubkey_len_out); 190 ///> 191 /// </details> 192 /// <details> 193 /// <summary>sfinx_tree_sign(hash, seed, seed_len, path, path_len, msg, msg_len, sig, sig_cap, sig_len_out)</summary> 194 /// 195 /// Sign a message under a path. The caller supplies the path, which must not 196 /// repeat across messages. 197 ///< c 198 sfinx_status sfinx_tree_sign(sfinx_hash hash, const uint8_t *seed, size_t seed_len, const uint8_t *path, 199 size_t path_len, const uint8_t *msg, size_t msg_len, uint8_t *sig, size_t sig_cap, 200 size_t *sig_len_out); 201 ///> 202 /// </details> 203 /// <details> 204 /// <summary>sfinx_verify(pubkey, pubkey_len, msg, msg_len, sig, sig_len)</summary> 205 /// 206 /// Verify a signature, reading the mode and hash size from the signature 207 /// itself. Returns `SFINX_OK` or `SFINX_ERR_VERIFY`. 208 ///< c 209 sfinx_status sfinx_verify(const uint8_t *pubkey, size_t pubkey_len, const uint8_t *msg, size_t msg_len, 210 const uint8_t *sig, size_t sig_len); 211 ///> 212 /// </details> 213 /// <details> 214 /// <summary>sfinx_random_bytes(out, len)</summary> 215 /// 216 /// Fill a buffer from the system entropy source 217 ///< c 218 sfinx_status sfinx_random_bytes(uint8_t *out, size_t len); 219 ///> 220 /// </details> 221 222 // }}} 223 224 // Key {{{ 225 226 /// 227 /// Keys 228 /// ---- 229 /// 230 /// A key holds a seed, a public key, or both. A null `seed` means public-only. 231 /// Decoding allocates into the key, `sfinx_key_free` releases it. `path_len` 232 /// is the length the public half was derived for, -1 when not recorded. 233 ///< c 234 typedef struct { 235 uint8_t *seed; 236 size_t seed_len; 237 uint8_t *pub; 238 size_t pub_len; 239 ssize_t path_len; 240 sfinx_hash hash; 241 } sfinx_key; 242 ///> 243 244 /// <details> 245 /// <summary>sfinx_key_init(key)</summary> 246 /// 247 /// Zero a key and set the default hash size and path length 248 ///< c 249 void sfinx_key_init(sfinx_key *key); 250 ///> 251 /// </details> 252 /// <details> 253 /// <summary>sfinx_key_free(key)</summary> 254 /// 255 /// Release both halves and zero the key 256 ///< c 257 void sfinx_key_free(sfinx_key *key); 258 ///> 259 /// </details> 260 /// <details> 261 /// <summary>sfinx_key_derive(key)</summary> 262 /// 263 /// Fill in the public key from the seed, for the key's `path_len`. A key 264 /// that already carries one is left alone. 265 ///< c 266 sfinx_status sfinx_key_derive(sfinx_key *key); 267 ///> 268 /// </details> 269 270 // }}} 271 272 // Formats {{{ 273 274 /// 275 /// Formats 276 /// ------- 277 /// 278 /// Key and signature encodings are pluggable and register themselves on load, 279 /// so the encode and decode code is shared with anything linking the library. 280 /// The bundled set is `hdr`, `raw`, `hex`, `rawpub` and `hexpub`, described in 281 /// [cli.md](cli.md). 282 ///< c 283 typedef struct sfinx_format { 284 struct sfinx_format *next; 285 const char *name; 286 287 int (*key_detect)(const uint8_t *data, size_t len); 288 sfinx_status (*key_decode)(const uint8_t *data, size_t len, sfinx_key *out); 289 size_t (*key_encode_len)(const sfinx_key *key); 290 sfinx_status (*key_encode)(const sfinx_key *key, uint8_t *out, size_t cap, size_t *len_out); 291 292 int (*sig_detect)(const uint8_t *data, size_t len); 293 sfinx_status (*sig_decode)(const uint8_t *data, size_t len, uint8_t *out, size_t cap, size_t *len_out); 294 size_t (*sig_encode_len)(const uint8_t *sig, size_t sig_len); 295 sfinx_status (*sig_encode)(const uint8_t *sig, size_t sig_len, uint8_t *out, size_t cap, size_t *len_out); 296 } sfinx_format; 297 ///> 298 299 /// <details> 300 /// <summary>sfinx_format_register(format)</summary> 301 /// 302 /// Add a format. Registration prepends, so a later format wins a name tie. 303 ///< c 304 void sfinx_format_register(sfinx_format *format); 305 ///> 306 /// </details> 307 /// <details> 308 /// <summary>sfinx_format_find(name)</summary> 309 /// 310 /// Look up a registered format by name, null when there is no match 311 ///< c 312 const sfinx_format *sfinx_format_find(const char *name); 313 ///> 314 /// </details> 315 316 /// 317 /// Passing a null `format` to either decode call auto-detects. Signature 318 /// auto-detect falls back to `raw` when nothing matches, key auto-detect does 319 /// not. Call `encode_len` to size the buffer before `encode`. 320 321 /// <details> 322 /// <summary>sfinx_key_decode(data, len, format, out)</summary> 323 /// 324 /// Decode a key file, allocating into `out` 325 ///< c 326 sfinx_status sfinx_key_decode(const uint8_t *data, size_t len, const char *format, sfinx_key *out); 327 ///> 328 /// </details> 329 /// <details> 330 /// <summary>sfinx_key_encode_len(key, format)</summary> 331 /// 332 /// Encoded size of a key, 0 when the format is unknown 333 ///< c 334 size_t sfinx_key_encode_len(const sfinx_key *key, const char *format); 335 ///> 336 /// </details> 337 /// <details> 338 /// <summary>sfinx_key_encode(key, format, out, cap, len_out)</summary> 339 /// 340 /// Encode a key into the caller's buffer 341 ///< c 342 sfinx_status sfinx_key_encode(const sfinx_key *key, const char *format, uint8_t *out, size_t cap, size_t *len_out); 343 ///> 344 /// </details> 345 /// <details> 346 /// <summary>sfinx_sig_decode(data, len, format, out, cap, len_out)</summary> 347 /// 348 /// Decode a signature into the caller's buffer 349 ///< c 350 sfinx_status sfinx_sig_decode(const uint8_t *data, size_t len, const char *format, uint8_t *out, size_t cap, 351 size_t *len_out); 352 ///> 353 /// </details> 354 /// <details> 355 /// <summary>sfinx_sig_encode_len(sig, sig_len, format)</summary> 356 /// 357 /// Encoded size of a signature, 0 when the format is unknown 358 ///< c 359 size_t sfinx_sig_encode_len(const uint8_t *sig, size_t sig_len, const char *format); 360 ///> 361 /// </details> 362 /// <details> 363 /// <summary>sfinx_sig_encode(sig, sig_len, format, out, cap, len_out)</summary> 364 /// 365 /// Encode a signature into the caller's buffer 366 ///< c 367 sfinx_status sfinx_sig_encode(const uint8_t *sig, size_t sig_len, const char *format, uint8_t *out, size_t cap, 368 size_t *len_out); 369 ///> 370 /// </details> 371 372 // }}} 373 374 #endif // __SFINX_H__ 375 376 // vim:fdm=marker:fdl=0