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