sfinx

sphincs+ inspired signing utility
git clone git://git.finwo.net/app/sfinx
Log | Files | Refs | README | LICENSE

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>