1 /* MIT (BSD) license - see LICENSE file for details */
2 #ifndef CCAN_RUNE_RUNE_H
3 #define CCAN_RUNE_RUNE_H
4 #include <ccan/crypto/sha256/sha256.h>
5 #include <ccan/typesafe_cb/typesafe_cb.h>
6 #include <ccan/tal/tal.h>
7 #include <ccan/short_types/short_types.h>
9 /* A rune is a series of restrictions. */
11 /* unique_id (if any) */
12 const char *unique_id;
13 /* Version (if any) */
16 /* SHA-2 256 of restrictions so far. */
17 struct sha256_ctx shactx;
18 /* Length given by tal_count() */
19 struct rune_restr **restrs;
22 /* A restriction is one or more alternatives (altern) */
24 /* Length given by tal_count() */
25 struct rune_altern **alterns;
29 RUNE_COND_IF_MISSING = '!',
30 RUNE_COND_EQUAL = '=',
31 RUNE_COND_NOT_EQUAL = '/',
32 RUNE_COND_BEGINS = '^',
34 RUNE_COND_CONTAINS = '~',
35 RUNE_COND_INT_LESS = '<',
36 RUNE_COND_INT_GREATER = '>',
37 RUNE_COND_LEXO_BEFORE = '{',
38 RUNE_COND_LEXO_AFTER = '}',
39 RUNE_COND_COMMENT = '#',
42 /* An alternative is a utf-8 fieldname, a condition, and a value */
44 enum rune_condition condition;
46 const char *fieldname, *value;
50 * rune_new - Create an unrestricted rune from this secret.
51 * @ctx: tal context, or NULL. Freeing @ctx will free the returned rune.
52 * @secret: secret bytes.
53 * @secret_len: number of @secret bytes (must be 55 bytes or less)
54 * @version: if non-NULL, sets a version for this rune.
56 * This allocates a new, unrestricted rune (sometimes called a master rune).
58 * Setting a version allows for different interpretations of a rune if
59 * things change in future, at cost of some space when it's used.
63 * struct rune *master;
65 * // A secret determined with a fair die roll!
66 * memset(secret, 5, sizeof(secret));
67 * master = rune_new(NULL, secret, sizeof(secret), NULL);
70 struct rune *rune_new(const tal_t *ctx, const u8 *secret, size_t secret_len,
74 * rune_derive_start - Copy master rune, add a unique id.
75 * @ctx: context to allocate rune off
76 * @master: master rune.
77 * @unique_id: unique id; can be NULL, but that's not recommended.
79 * It's usually recommended to assign each rune a unique_id, so that
80 * specific runes can be blacklisted later (otherwise you need to disable
81 * all runes). This enlarges the rune string by '=<unique_id>' however.
83 * The rune version will be the same as the master: if that's non-zero,
84 * you *must* set unique_id.
86 * @unique_id cannot contain '-'.
90 * // In reality, some global incrementing variable.
91 * const char *id = "1";
92 * rune = rune_derive_start(NULL, master, id);
95 struct rune *rune_derive_start(const tal_t *ctx,
96 const struct rune *master,
97 const char *unique_id);
100 * rune_dup - Copy a rune.
101 * @ctx: tal context, or NULL.
102 * @altern: the altern to copy.
104 * If @altern is take(), then simply returns it, otherwise copies.
106 struct rune *rune_dup(const tal_t *ctx, const struct rune *rune TAKES);
109 * rune_altern_new - Create a new alternative.
110 * @ctx: tal context, or NULL. Freeing @ctx will free the returned altern.
111 * @fieldname: the UTF-8 field for the altern. You can only have
112 * alphanumerics, '.', '-' and '_' here.
113 * @condition: the condition, defined above.
114 * @value: the value for comparison; use "" if you don't care. Any UTF-8 value
117 * An altern is the basis of rune restrictions (technically, a restriction
118 * is one or more alterns, but it's often just one).
121 * struct rune_altern *a1, *a2;
122 * a1 = rune_altern_new(NULL, "val", RUNE_COND_EQUAL, "7");
123 * a2 = rune_altern_new(NULL, "val2", '>', "-1");
126 struct rune_altern *rune_altern_new(const tal_t *ctx,
127 const char *fieldname TAKES,
128 enum rune_condition condition,
129 const char *value TAKES);
132 * rune_altern_dup - copy an alternative.
133 * @ctx: tal context, or NULL.
134 * @altern: the altern to copy.
136 * If @altern is take(), then simply returns it, otherwise copies.
138 struct rune_altern *rune_altern_dup(const tal_t *ctx,
139 const struct rune_altern *altern TAKES);
142 * rune_restr_new - Create a new (empty) restriction.
143 * @ctx: tal context, or NULL. Freeing @ctx will free the returned restriction.
146 * struct rune_restr *restr = rune_restr_new(NULL);
149 struct rune_restr *rune_restr_new(const tal_t *ctx);
152 * rune_restr_dup - copy a restr.
153 * @ctx: tal context, or NULL.
154 * @restr: the restr to copy.
156 * If @resttr is take(), then simply returns it, otherwise copies.
158 struct rune_restr *rune_restr_dup(const tal_t *ctx,
159 const struct rune_restr *restr TAKES);
162 * rune_restr_add_altern - add an altern to this restriction
163 * @restr: the restriction to add to
166 * If the alt is take(alt) then the alt will be owned by the restriction,
167 * otherwise it's copied.
170 * rune_restr_add_altern(restr, take(a1));
171 * rune_restr_add_altern(restr, take(a2));
173 void rune_restr_add_altern(struct rune_restr *restr,
174 const struct rune_altern *alt TAKES);
177 * rune_add_restr - add a restriction to this rune
178 * @rune: the rune to add to.
179 * @restr: the (non-empty) restriction.
181 * If the alt is take(alt) then the alt will be owned by the restr,
182 * otherwise it's copied (and all its children are copied!).
184 * This fails (and returns false) if restr tries to set unique_id/version
185 * and is not the first restriction, or has more than one alternative,
186 * or uses a non '=' condition.
189 * rune_add_restr(rune, take(restr));
191 bool rune_add_restr(struct rune *rune,
192 const struct rune_restr *restr TAKES);
195 * rune_altern_eq - are two rune_altern equivalent?
199 bool rune_altern_eq(const struct rune_altern *alt1,
200 const struct rune_altern *alt2);
203 * rune_restr_eq - are two rune_restr equivalent?
207 bool rune_restr_eq(const struct rune_restr *rest1,
208 const struct rune_restr *rest2);
211 * rune_eq - are two runes equivalent?
215 bool rune_eq(const struct rune *rune1, const struct rune *rune2);
218 * rune_alt_single - helper to implement check().
219 * @ctx: context to allocate any error return from.
220 * @alt: alternative to test.
221 * @fieldval_str: field value as a string.
222 * @fieldval_int: field value as an integer.
224 * If the field value is missing, set neither fieldval_str nor fieldval_int,
225 * otherwise you must set exactly one.
227 const char *rune_alt_single(const tal_t *ctx,
228 const struct rune_altern *alt,
229 const char *fieldval_str,
230 const s64 *fieldval_int);
233 * rune_is_derived - is a rune derived from this other rune?
234 * @source: the base rune (usually the master rune)
235 * @rune: the rune to check.
237 * This is the first part of "is this rune valid?": does the cryptography
238 * check out, such that they validly made the rune from this source rune?
240 * It also checks that the versions match: if you want to allow more than
241 * one version, see rune_is_derived_anyversion.
243 const char *rune_is_derived(const struct rune *source, const struct rune *rune);
246 * rune_is_derived_anyversion - is a rune derived from this other rune?
247 * @source: the base rune (usually the master rune)
248 * @rune: the rune to check.
250 * This does not check source->version against rune->version: if you issue
251 * different rune versions you will need to check that yourself.
253 const char *rune_is_derived_anyversion(const struct rune *source,
254 const struct rune *rune);
257 * rune_meets_criteria - do we meet the criteria specified by the rune?
258 * @ctx: the tal context to allocate the returned error off.
259 * @rune: the rune to check.
260 * @check: the callback to check values
261 * @arg: data to hand to @check
263 * This is the second part of "is this rune valid?".
265 const char *rune_meets_criteria_(const tal_t *ctx,
266 const struct rune *rune,
267 const char *(*check)(const tal_t *ctx,
268 const struct rune *rune,
269 const struct rune_altern *alt,
273 /* Typesafe wrapper */
274 #define rune_meets_criteria(ctx, rune, check, arg) \
275 rune_meets_criteria_(typesafe_cb_preargs(const char *, void *, \
279 const struct rune *, \
280 const struct rune_altern *), \
284 * rune_test - is a rune authorized?
285 * @ctx: the tal context to allocate @errstr off.
286 * @master: the master rune created from secret.
287 * @rune: the rune to check.
288 * @errstr: if non-NULL, descriptive string of failure.
289 * @get: the callback to get values
290 * @arg: data to hand to callback
292 * Simple call for rune_is_derived() and rune_meets_criteria(). If
293 * it's not OK, returns non-NULL.
295 const char *rune_test_(const tal_t *ctx,
296 const struct rune *master,
297 const struct rune *rune,
298 const char *(*check)(const tal_t *ctx,
299 const struct rune *rune,
300 const struct rune_altern *alt,
304 /* Typesafe wrapper */
305 #define rune_test(ctx_, master_, rune_, check_, arg_) \
306 rune_test_((ctx_), (master_), (rune_), \
307 typesafe_cb_preargs(const char *, void *, \
310 const struct rune *, \
311 const struct rune_altern *), \
316 * rune_from_base64 - convert base64 string to rune.
317 * @ctx: context to allocate rune off.
318 * @str: base64 string.
320 * Returns NULL if it's malformed.
322 struct rune *rune_from_base64(const tal_t *ctx, const char *str);
325 * rune_to_base64 - convert run to base64 string.
326 * @ctx: context to allocate rune off.
329 * Only returns NULL if you've allowed tal allocations to return NULL.
331 char *rune_to_base64(const tal_t *ctx, const struct rune *rune);
334 * This is a much more convenient working form.
336 struct rune *rune_from_string(const tal_t *ctx, const char *str);
337 char *rune_to_string(const tal_t *ctx, const struct rune *rune);
340 * rune_restr_from_string - convenience routine to parse a single restriction.
341 * @ctx: context to allocate rune off.
342 * @str: the string of form "<field><cond><val>[|<field><cond><val>]*"
344 * This is really an internal routine, exposed for simple examples.
346 struct rune_restr *rune_restr_from_string(const tal_t *ctx,
349 #endif /* CCAN_RUNE_RUNE_H */