sfinx

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

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