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_str - 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_strlen: length of @fieldval_str
224 const char *rune_alt_single_str(const tal_t *ctx,
225 const struct rune_altern *alt,
226 const char *fieldval_str,
227 size_t fieldval_strlen);
230 * rune_alt_single_int - helper to implement check().
231 * @ctx: context to allocate any error return from.
232 * @alt: alternative to test.
233 * @fieldval_int: field value as an integer.
235 const char *rune_alt_single_int(const tal_t *ctx,
236 const struct rune_altern *alt,
240 * rune_alt_single_missing - helper to implement check().
241 * @ctx: context to allocate any error return from.
242 * @alt: alternative to test.
244 * Use this if alt->fieldname is unknown (it could still pass, if
245 * the test is that the fieldname is missing).
247 const char *rune_alt_single_missing(const tal_t *ctx,
248 const struct rune_altern *alt);
252 * rune_is_derived - is a rune derived from this other rune?
253 * @source: the base rune (usually the master rune)
254 * @rune: the rune to check.
256 * This is the first part of "is this rune valid?": does the cryptography
257 * check out, such that they validly made the rune from this source rune?
259 * It also checks that the versions match: if you want to allow more than
260 * one version, see rune_is_derived_anyversion.
262 const char *rune_is_derived(const struct rune *source, const struct rune *rune);
265 * rune_is_derived_anyversion - is a rune derived from this other rune?
266 * @source: the base rune (usually the master rune)
267 * @rune: the rune to check.
269 * This does not check source->version against rune->version: if you issue
270 * different rune versions you will need to check that yourself.
272 const char *rune_is_derived_anyversion(const struct rune *source,
273 const struct rune *rune);
276 * rune_meets_criteria - do we meet the criteria specified by the rune?
277 * @ctx: the tal context to allocate the returned error off.
278 * @rune: the rune to check.
279 * @check: the callback to check values
280 * @arg: data to hand to @check
282 * This is the second part of "is this rune valid?".
284 const char *rune_meets_criteria_(const tal_t *ctx,
285 const struct rune *rune,
286 const char *(*check)(const tal_t *ctx,
287 const struct rune *rune,
288 const struct rune_altern *alt,
292 /* Typesafe wrapper */
293 #define rune_meets_criteria(ctx, rune, check, arg) \
294 rune_meets_criteria_(typesafe_cb_preargs(const char *, void *, \
298 const struct rune *, \
299 const struct rune_altern *), \
303 * rune_test - is a rune authorized?
304 * @ctx: the tal context to allocate @errstr off.
305 * @master: the master rune created from secret.
306 * @rune: the rune to check.
307 * @errstr: if non-NULL, descriptive string of failure.
308 * @get: the callback to get values
309 * @arg: data to hand to callback
311 * Simple call for rune_is_derived() and rune_meets_criteria(). If
312 * it's not OK, returns non-NULL.
314 const char *rune_test_(const tal_t *ctx,
315 const struct rune *master,
316 const struct rune *rune,
317 const char *(*check)(const tal_t *ctx,
318 const struct rune *rune,
319 const struct rune_altern *alt,
323 /* Typesafe wrapper */
324 #define rune_test(ctx_, master_, rune_, check_, arg_) \
325 rune_test_((ctx_), (master_), (rune_), \
326 typesafe_cb_preargs(const char *, void *, \
329 const struct rune *, \
330 const struct rune_altern *), \
335 * rune_from_base64 - convert base64 string to rune.
336 * @ctx: context to allocate rune off.
337 * @str: base64 string.
339 * Returns NULL if it's malformed.
341 struct rune *rune_from_base64(const tal_t *ctx, const char *str);
344 * rune_from_base64n - convert base64 string to rune.
345 * @ctx: context to allocate rune off.
346 * @str: base64 string.
347 * @len: length of @str.
349 * Returns NULL if it's malformed.
351 struct rune *rune_from_base64n(const tal_t *ctx, const char *str, size_t len);
354 * rune_to_base64 - convert run to base64 string.
355 * @ctx: context to allocate rune off.
358 * Only returns NULL if you've allowed tal allocations to return NULL.
360 char *rune_to_base64(const tal_t *ctx, const struct rune *rune);
363 * This is a much more convenient working form.
365 struct rune *rune_from_string(const tal_t *ctx, const char *str);
366 char *rune_to_string(const tal_t *ctx, const struct rune *rune);
369 * rune_restr_from_string - convenience routine to parse a single restriction.
370 * @ctx: context to allocate rune off.
371 * @str: the string of form "<field><cond><val>[|<field><cond><val>]*"
372 * @len: the length of @str.
374 * This is useful for writing simple tests and making simple runes.
376 struct rune_restr *rune_restr_from_string(const tal_t *ctx,
379 #endif /* CCAN_RUNE_RUNE_H */