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 - 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.
 223  *
 224  * If the field value is missing, set neither fieldval_str nor fieldval_int,
 225  * otherwise you must set exactly one.
 226  */
 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);
 231
 232 /**
 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.
 236  *
 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?
 239  *
 240  * It also checks that the versions match: if you want to allow more than
 241  * one version, see rune_is_derived_anyversion.
 242  */
 243 const char *rune_is_derived(const struct rune *source, const struct rune *rune);
 244
 245 /**
 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.
 249  *
 250  * This does not check source->version against rune->version: if you issue
 251  * different rune versions you will need to check that yourself.
 252  */
 253 const char *rune_is_derived_anyversion(const struct rune *source,
 254                                        const struct rune *rune);
 255
 256 /**
 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
 262  *
 263  * This is the second part of "is this rune valid?".
 264  */
 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,
 270                                                       void *arg),
 271                                  void *arg);
 272
 273 /* Typesafe wrapper */
 274 #define rune_meets_criteria(ctx, rune, check, arg)                      \
 275         rune_meets_criteria_(typesafe_cb_preargs(const char *, void *,  \
 276                                                  (ctx), (rune),         \
 277                                                  (check), (arg),        \
 278                                                  const tal_t *,         \
 279                                                  const struct rune *,   \
 280                                                  const struct rune_altern *), \
 281                              (arg))
 282
 283 /**
 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
 291  *
 292  * Simple call for rune_is_derived() and rune_meets_criteria().  If
 293  * it's not OK, returns non-NULL.
 294  */
 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,
 301                                             void *arg),
 302                        void *arg);
 303
 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 *,            \
 308                                        (check_), (arg_),                \
 309                                        const tal_t *,                   \
 310                                        const struct rune *,             \
 311                                        const struct rune_altern *),     \
 312                    (arg_))
 313
 314
 315 /**
 316  * rune_from_base64 - convert base64 string to rune.
 317  * @ctx: context to allocate rune off.
 318  * @str: base64 string.
 319  *
 320  * Returns NULL if it's malformed.
 321  */
 322 struct rune *rune_from_base64(const tal_t *ctx, const char *str);
 323
 324 /**
 325  * rune_from_base64n - convert base64 string to rune.
 326  * @ctx: context to allocate rune off.
 327  * @str: base64 string.
 328  * @len: length of @str.
 329  *
 330  * Returns NULL if it's malformed.
 331  */
 332 struct rune *rune_from_base64n(const tal_t *ctx, const char *str, size_t len);
 333
 334 /**
 335  * rune_to_base64 - convert run to base64 string.
 336  * @ctx: context to allocate rune off.
 337  * @rune: the rune.
 338  *
 339  * Only returns NULL if you've allowed tal allocations to return NULL.
 340  */
 341 char *rune_to_base64(const tal_t *ctx, const struct rune *rune);
 342
 343 /**
 344  * This is a much more convenient working form.
 345  */
 346 struct rune *rune_from_string(const tal_t *ctx, const char *str);
 347 char *rune_to_string(const tal_t *ctx, const struct rune *rune);
 348
 349 /**
 350  * rune_restr_from_string - convenience routine to parse a single restriction.
 351  * @ctx: context to allocate rune off.
 352  * @str: the string of form "<field><cond><val>[|<field><cond><val>]*"
 353  * @len: the length of @str.
 354  *
 355  * This is useful for writing simple tests and making simple runes.
 356  */
 357 struct rune_restr *rune_restr_from_string(const tal_t *ctx,
 358                                           const char *str,
 359                                           size_t len);
 360 #endif /* CCAN_RUNE_RUNE_H */