git.ozlabs.org Git - ccan/blob - ccan/rune/rune.h

   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>
   8
   9 /* A rune is a series of restrictions. */
  10 struct rune {
  11         /* unique_id (if any) */
  12         const char *unique_id;
  13         /* Version (if any) */
  14         const char *version;
  15
  16         /* SHA-2 256 of restrictions so far. */
  17         struct sha256_ctx shactx;
  18         /* Length given by tal_count() */
  19         struct rune_restr **restrs;
  20 };
  21
  22 /* A restriction is one or more alternatives (altern) */
  23 struct rune_restr {
  24         /* Length given by tal_count() */
  25         struct rune_altern **alterns;
  26 };
  27
  28 enum rune_condition {
  29         RUNE_COND_IF_MISSING = '!',
  30         RUNE_COND_EQUAL = '=',
  31         RUNE_COND_NOT_EQUAL = '/',
  32         RUNE_COND_BEGINS = '^',
  33         RUNE_COND_ENDS = '$',
  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 = '#',
  40 };
  41
  42 /* An alternative is a utf-8 fieldname, a condition, and a value */
  43 struct rune_altern {
  44         enum rune_condition condition;
  45         /* Strings. */
  46         const char *fieldname, *value;
  47 };
  48
  49 /**
  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.
  55  *
  56  * This allocates a new, unrestricted rune (sometimes called a master rune).
  57  *
  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.
  60  *
  61  * Example:
  62  *  u8 secret[16];
  63  *  struct rune *master;
  64  *
  65  *  // A secret determined with a fair die roll!
  66  *  memset(secret, 5, sizeof(secret));
  67  *  master = rune_new(NULL, secret, sizeof(secret), NULL);
  68  *  assert(master);
  69  */
  70 struct rune *rune_new(const tal_t *ctx, const u8 *secret, size_t secret_len,
  71                       const char *version);
  72
  73 /**
  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.
  78  *
  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.
  82  *
  83  * The rune version will be the same as the master: if that's non-zero,
  84  * you *must* set unique_id.
  85  *
  86  * @unique_id cannot contain '-'.
  87  *
  88  * Example:
  89  *  struct rune *rune;
  90  *  // In reality, some global incrementing variable.
  91  *  const char *id = "1";
  92  *  rune = rune_derive_start(NULL, master, id);
  93  *  assert(rune);
  94  */
  95 struct rune *rune_derive_start(const tal_t *ctx,
  96                                const struct rune *master,
  97                                const char *unique_id);
  98
  99 /**
 100  * rune_dup - Copy a rune.
 101  * @ctx: tal context, or NULL.
 102  * @altern: the altern to copy.
 103  *
 104  * If @altern is take(), then simply returns it, otherwise copies.
 105  */
 106 struct rune *rune_dup(const tal_t *ctx, const struct rune *rune TAKES);
 107
 108 /**
 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
 115  *         is allowed.
 116  *
 117  * An altern is the basis of rune restrictions (technically, a restriction
 118  * is one or more alterns, but it's often just one).
 119  *
 120  * Example:
 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");
 124  *  assert(a1 && a2);
 125  */
 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);
 130
 131 /**
 132  * rune_altern_dup - copy an alternative.
 133  * @ctx: tal context, or NULL.
 134  * @altern: the altern to copy.
 135  *
 136  * If @altern is take(), then simply returns it, otherwise copies.
 137  */
 138 struct rune_altern *rune_altern_dup(const tal_t *ctx,
 139                                     const struct rune_altern *altern TAKES);
 140
 141 /**
 142  * rune_restr_new - Create a new (empty) restriction.
 143  * @ctx: tal context, or NULL.  Freeing @ctx will free the returned restriction.
 144  *
 145  * Example:
 146  *  struct rune_restr *restr = rune_restr_new(NULL);
 147  *  assert(restr);
 148  */
 149 struct rune_restr *rune_restr_new(const tal_t *ctx);
 150
 151 /**
 152  * rune_restr_dup - copy a restr.
 153  * @ctx: tal context, or NULL.
 154  * @restr: the restr to copy.
 155  *
 156  * If @resttr is take(), then simply returns it, otherwise copies.
 157  */
 158 struct rune_restr *rune_restr_dup(const tal_t *ctx,
 159                                   const struct rune_restr *restr TAKES);
 160
 161 /**
 162  * rune_restr_add_altern - add an altern to this restriction
 163  * @restr: the restriction to add to
 164  * @alt: the altern.
 165  *
 166  * If the alt is take(alt) then the alt will be owned by the restriction,
 167  * otherwise it's copied.
 168  *
 169  * Example:
 170  *  rune_restr_add_altern(restr, take(a1));
 171  *  rune_restr_add_altern(restr, take(a2));
 172  */
 173 void rune_restr_add_altern(struct rune_restr *restr,
 174                            const struct rune_altern *alt TAKES);
 175
 176 /**
 177  * rune_add_restr - add a restriction to this rune
 178  * @rune: the rune to add to.
 179  * @restr: the (non-empty) restriction.
 180  *
 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!).
 183  *
 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.
 187  *
 188  * Example:
 189  *  rune_add_restr(rune, take(restr));
 190  */
 191 bool rune_add_restr(struct rune *rune,
 192                     const struct rune_restr *restr TAKES);
 193
 194 /**
 195  * rune_altern_eq - are two rune_altern equivalent?
 196  * @alt1: the first
 197  * @alt2: the second
 198  */
 199 bool rune_altern_eq(const struct rune_altern *alt1,
 200                     const struct rune_altern *alt2);
 201
 202 /**
 203  * rune_restr_eq - are two rune_restr equivalent?
 204  * @rest1: the first
 205  * @rest2: the second
 206  */
 207 bool rune_restr_eq(const struct rune_restr *rest1,
 208                    const struct rune_restr *rest2);
 209
 210 /**
 211  * rune_eq - are two runes equivalent?
 212  * @rest1: the first
 213  * @rest2: the second
 214  */
 215 bool rune_eq(const struct rune *rune1, const struct rune *rune2);
 216
 217 /**
 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
 223  */
 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);
 228
 229 /**
 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.
 234  */
 235 const char *rune_alt_single_int(const tal_t *ctx,
 236                                 const struct rune_altern *alt,
 237                                 s64 fieldval_int);
 238
 239 /**
 240  * rune_alt_single_missing - helper to implement check().
 241  * @ctx: context to allocate any error return from.
 242  * @alt: alternative to test.
 243  *
 244  * Use this if alt->fieldname is unknown (it could still pass, if
 245  * the test is that the fieldname is missing).
 246  */
 247 const char *rune_alt_single_missing(const tal_t *ctx,
 248                                     const struct rune_altern *alt);
 249
 250
 251 /**
 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.
 255  *
 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?
 258  *
 259  * It also checks that the versions match: if you want to allow more than
 260  * one version, see rune_is_derived_anyversion.
 261  */
 262 const char *rune_is_derived(const struct rune *source, const struct rune *rune);
 263
 264 /**
 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.
 268  *
 269  * This does not check source->version against rune->version: if you issue
 270  * different rune versions you will need to check that yourself.
 271  */
 272 const char *rune_is_derived_anyversion(const struct rune *source,
 273                                        const struct rune *rune);
 274
 275 /**
 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
 281  *
 282  * This is the second part of "is this rune valid?".
 283  */
 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,
 289                                                       void *arg),
 290                                  void *arg);
 291
 292 /* Typesafe wrapper */
 293 #define rune_meets_criteria(ctx, rune, check, arg)                      \
 294         rune_meets_criteria_(typesafe_cb_preargs(const char *, void *,  \
 295                                                  (ctx), (rune),         \
 296                                                  (check), (arg),        \
 297                                                  const tal_t *,         \
 298                                                  const struct rune *,   \
 299                                                  const struct rune_altern *), \
 300                              (arg))
 301
 302 /**
 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
 310  *
 311  * Simple call for rune_is_derived() and rune_meets_criteria().  If
 312  * it's not OK, returns non-NULL.
 313  */
 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,
 320                                             void *arg),
 321                        void *arg);
 322
 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 *,            \
 327                                        (check_), (arg_),                \
 328                                        const tal_t *,                   \
 329                                        const struct rune *,             \
 330                                        const struct rune_altern *),     \
 331                    (arg_))
 332
 333
 334 /**
 335  * rune_from_base64 - convert base64 string to rune.
 336  * @ctx: context to allocate rune off.
 337  * @str: base64 string.
 338  *
 339  * Returns NULL if it's malformed.
 340  */
 341 struct rune *rune_from_base64(const tal_t *ctx, const char *str);
 342
 343 /**
 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.
 348  *
 349  * Returns NULL if it's malformed.
 350  */
 351 struct rune *rune_from_base64n(const tal_t *ctx, const char *str, size_t len);
 352
 353 /**
 354  * rune_to_base64 - convert run to base64 string.
 355  * @ctx: context to allocate rune off.
 356  * @rune: the rune.
 357  *
 358  * Only returns NULL if you've allowed tal allocations to return NULL.
 359  */
 360 char *rune_to_base64(const tal_t *ctx, const struct rune *rune);
 361
 362 /**
 363  * This is a much more convenient working form.
 364  */
 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);
 367
 368 /**
 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.
 373  *
 374  * This is useful for writing simple tests and making simple runes.
 375  */
 376 struct rune_restr *rune_restr_from_string(const tal_t *ctx,
 377                                           const char *str,
 378                                           size_t len);
 379
 380 /**
 381  * rune_condition_is_valid: is this a valid condition?
 382  * @cond: potential condition character.
 383  *
 384  * Returns true if it's one of enum rune_condition.
 385  */
 386 bool rune_condition_is_valid(enum rune_condition cond);
 387
 388 /**
 389  * rune_altern_fieldname_len: how much of this string is condition?
 390  * @alternstr: potential alternative string
 391  * @alternstrlen: length
 392  *
 393  * This helps parsing your own runes.
 394  *
 395  * Returns the first possible condition (check with rune_condition_is_valid)
 396  * or alternstrlen if none found.
 397  */
 398 size_t rune_altern_fieldname_len(const char *alternstr, size_t alternstrlen);
 399
 400 #endif /* CCAN_RUNE_RUNE_H */