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