git.ozlabs.org Git - ccan/blob - ccan/crypto/shachain/shachain.h

   1 /* MIT (BSD) license - see LICENSE file for details */
   2 #ifndef CCAN_CRYPTO_SHACHAIN_H
   3 #define CCAN_CRYPTO_SHACHAIN_H
   4 #include "config.h"
   5 #include <ccan/crypto/sha256/sha256.h>
   6 #include <stdbool.h>
   7 #include <stdint.h>
   8
   9 /* Useful for testing. */
  10 #ifndef shachain_index_t
  11 #define shachain_index_t uint64_t
  12 #endif
  13
  14 #ifndef SHACHAIN_BITS
  15 #define SHACHAIN_BITS (sizeof(shachain_index_t) * 8)
  16 #endif
  17
  18 /**
  19  * shachain_from_seed - Generate an unpredictable SHA from a seed value.
  20  * @seed: (secret) seed value to use
  21  * @index: index of value to generate (0 == seed)
  22  * @hash: value generated
  23  *
  24  * There will be no way to derive the result from that generated for
  25  * any *greater* index.
  26  *
  27  * Example:
  28  * #include <time.h>
  29  *
  30  * static void next_hash(struct sha256 *hash)
  31  * {
  32  *      static uint64_t index = 0xFFFFFFFFFFFFFFFFULL;
  33  *      static struct sha256 seed;
  34  *
  35  *      // First time, initialize seed.
  36  *      if (index == 0xFFFFFFFFFFFFFFFFULL) {
  37  *              // DO NOT DO THIS!  Very predictable!
  38  *              time_t now = time(NULL);
  39  *              memcpy(&seed, &now, sizeof(now));
  40  *      }
  41  *
  42  *      shachain_from_seed(&seed, index--, hash);
  43  * }
  44  */
  45 void shachain_from_seed(const struct sha256 *seed, shachain_index_t index,
  46                         struct sha256 *hash);
  47
  48 /**
  49  * shachain - structure for recording/deriving decrementing chain members
  50  * @min_index: minimum index value successfully shachain_add_hash()ed.
  51  * @num_valid: number of known[] array valid.  If non-zero, @min_index valid.
  52  * @known: known values to allow us to derive those >= @min_index.
  53  *
  54  * This is sufficient storage to derive any shachain hash value previously
  55  * added.
  56  */
  57 struct shachain {
  58         shachain_index_t min_index;
  59         unsigned int num_valid;
  60         struct {
  61                 shachain_index_t index;
  62                 struct sha256 hash;
  63         } known[SHACHAIN_BITS + 1];
  64 };
  65
  66 /**
  67  * shachain_init - initialize an shachain
  68  * @chain: the chain to initialize
  69  *
  70  * Alternately, ensure that it's all zero.
  71  */
  72 void shachain_init(struct shachain *chain);
  73
  74 /**
  75  * shachain_add_hash - record the hash for the next index.
  76  * @chain: the chain to add to
  77  * @index: the index of the hash
  78  * @hash: the hash value.
  79  *
  80  * You can only add index 0xFFFFFFFFFFFFFFFF (for a freshly
  81  * initialized chain), or one less than the previously successfully
  82  * added value.
  83  *
  84  * This can fail (return false without altering @chain) if the hash
  85  * for this index isn't consistent with previous hashes (ie. wasn't
  86  * generated from the same seed), though it can't always detect that.
  87  * If the hash is inconsistent yet undetected, the next addition will
  88  * fail.
  89  *
  90  * Example:
  91  * static void next_hash(const struct sha256 *hash)
  92  * {
  93  *      static uint64_t index = 0xFFFFFFFFFFFFFFFFULL;
  94  *      static struct shachain chain;
  95  *
  96  *      if (!shachain_add_hash(&chain, index--, hash))
  97  *              errx(1, "Corrupted hash value?");
  98  * }
  99  */
 100 bool shachain_add_hash(struct shachain *chain,
 101                        shachain_index_t index, const struct sha256 *hash);
 102
 103 /**
 104  * shachain_get_hash - get the hash for a given index.
 105  * @chain: the chain query
 106  * @index: the index of the hash to get
 107  * @hash: the hash value.
 108  *
 109  * This will return true and set @hash to that given in the successful
 110  * shachain_get_hash() call for that index.  If there was no
 111  * successful shachain_get_hash() for that index, it will return
 112  * false.
 113  *
 114  * Example:
 115  * #include <ccan/structeq/structeq.h>
 116  *
 117  * static void next_hash(const struct sha256 *hash)
 118  * {
 119  *      static uint64_t index = 0xFFFFFFFFFFFFFFFFULL;
 120  *      static struct shachain chain;
 121  *
 122  *      if (!shachain_add_hash(&chain, index--, hash))
 123  *              errx(1, "Corrupted hash value?");
 124  *      else {
 125  *              struct sha256 check;
 126  *              assert(shachain_get_hash(&chain, index+1, &check));
 127  *              assert(structeq(&check, hash));
 128  *      }
 129  * }
 130  */
 131 bool shachain_get_hash(const struct shachain *chain,
 132                        shachain_index_t index, struct sha256 *hash);
 133 #endif /* CCAN_CRYPTO_SHACHAIN_H */