Document the caveat structure #6

KellerFuchs · 2019-01-08T21:49:41Z

Add a first description of caveats
Document the algorithm for interpreting caveats

KellerFuchs · 2019-01-08T21:55:09Z

DESIGN.md

+channel-binding value (like the TLS transcript hash).
+
+Available attributes, and their type, are known ahead of time by the verifier.
+Some of those attributes are *critical*, and all caveats must provide a *bound*


Suggested change

Some of those attributes are *critical*, and all caveats must provide a *bound*

Some of those attributes are *critical*, and the first caveat must provide a *bound*

That's @tarcieri version. I would rather enforce the property for all caveats because it means we guard against the same kind of mistake in attenuation too:

the minting of new credentials may be done by a service which already has a caveat on its biscuit (for instance, an login system might get a biscuit with time-limited validity, but valid for all users, ressources, and operations);

there are other contexts than credential minting (such as delegation) where accidental authority in attenuation is a major issue.

adding bounds for all those attributes might make a token that is too large (let's remember, it should fit in a cookie), especially for the first caveat that might have the largest access. How could we make that as small as possible?

@Geal How big would the representation of foo: Any be? That is the max. overhead, per caveat and per-critical property, and we can likely shrink it down to a handful of bytes.

The main thing is that you want to always provide bounds for critical properties (cf. the discussion in Slack. TL;DR: unbounded critical properties confer accidental authority when the property is added or the property gains new possible values), so it's not so much of an overhead rather than preventing people from accidentally issuing tokens missing those caveats.

I guess that, if biscuit size becomes an issue, we could support a compression scheme in settings where preceeding caveats are readable (i.e. in a public-key-signed token). For example, the representation of a predicate could refer to predicates in preceeding caveats when they share a (sub)term.
I'm not super sure that it makes a ton of sense to argue about size when the representation format isn't nailed down, as we can't yet measure the overhead (in bytes).

KellerFuchs · 2019-01-08T21:55:56Z

DESIGN.md

+Caveats describe which operations are authorized by providing predicates over
+the operation's attributes.
+
+Attributes are data, associated with the operation,


Renamed from (initially) properties.

KellerFuchs · 2019-01-08T21:57:46Z

DESIGN.md

+Some of those attributes are *critical*, and all caveats must provide a *bound*
+for each critical attribute.
+
+Bounds are a subset of predicates, that only allow the following:


Do we want to allow non-bounds predicates at all?
If so, should it be possible to put an arbitrary predicate on a critical attribute in addition to a bound?

some predicates could add data. Specifically, I'm thinking of revocation ids. You put that in a caveat, and then if it gets compromised, you send that id to the revocation system (revocation lists, etc) to invalidate that token and all of its derivated ones

@Geal I didn't include anything about additional data in here, because that felt like an orthogonal issue, but I had a (short) discussion with @tarcieri about adding another append-only structure for identity data.

The use-cases I had in mind included revocation, but also authn and non-repudiability/audit, allowing the biscuit to carry the chain of delegations that it went through. For instance, if I have a biscuit for a service, that I attenuate, mark for delegation to you, and send to you, on every (mis)use, there is a clear indication that it was the biscuit I sent you (i.e. you cannot claim it wasn't your biscuit).

I think that really deserves its own issue, because there is a bunch of pretty-subtle things to take care of, there.

KellerFuchs · 2019-01-08T21:58:57Z

DESIGN.md

+
+Bounds are a subset of predicates, that only allow the following:
+- `any <property>`: all values match;
+- `<property> in <subset>`: only elements in `subset` match; this can be an


Do we want specific syntax for none and only <value>?
They are equivalent to <property> in [] and <property> in [ <value> ] (empty set and singleton)

KellerFuchs · 2019-01-08T22:08:23Z

DESIGN.md

+  - if developers accidentally fail to provide a bound, the biscuit is invalid;
+  - biscuits issued before the attribute was defined are implicitely revoked.
+
+For example, consider a data store, which initially only provides read access.


Is the example useful?

what happens when an attribute is already critical, for which we provided a bound, yet it changed and got more general? The biscuit would still be valid, but still suddenly get more access.

(the example is useful, btw)

@Geal That's the second part of the example: when new values (there, Create and Delete IIRC?) are added, no new access is granted (unless the bound was Any, in which case that was arguably on purpose?).

KellerFuchs · 2019-01-08T22:10:13Z

DESIGN.md

+By requiring that all caveats provide a bound for each critical attribute, we
+can guarantee that a biscuit does not gain unintended authority when new
+attributes, or new values for them, are added in the system.  (The use of `any`
+is considered intentional.)


Can we make a more precise statement?

Without any, we can precisely say that no change to critical attributes (or the values they can take) results in operations being allowed that weren't previously (for the same biscuit).

KellerFuchs · 2019-01-08T22:10:47Z

DESIGN.md

 ## Format

+XXXTODO: Update for caveats


Should we just remove the wire-format spec for now?

I'd rather keep the format and the rights management part for now, but maybe adding a comment indicating we're working on those.

OK; keeping as-is then (“XXXTODO: Update for [...]” should convey clearly that the section is out-of-date).

Geal · 2019-01-09T17:37:12Z

DESIGN.md

+Bounds are a subset of predicates, that only allow the following:
+- `any`: all values match;
+- `in <subset>`: only elements in `subset` match; this can be an explicit
+  enumeration, or a (non-infinite) range in the case of numeric types.


trying to think of other things we might need here, but none coming right now

@Geal Disjunctions of bounds (or [<bound>; <bound>; ...]) bring more expressiveness, but I can't really think of a case where I would want that.

DESIGN.md

@Geal

Issue pointed out by @Geal in review: #6 (comment)

Describe caveats, as discussed with tarcieri and geal

cd5b112

KellerFuchs requested review from tarcieri and Geal January 8, 2019 21:49

KellerFuchs commented Jan 8, 2019

View reviewed changes

Replace the obsoleted evaluation algorithm with Pythonish pseudocode

bae7c39

KellerFuchs force-pushed the proposal/caveat-structure branch from 62d9984 to bae7c39 Compare January 8, 2019 22:06

KellerFuchs commented Jan 8, 2019

View reviewed changes

Geal reviewed Jan 9, 2019

View reviewed changes

DESIGN.md Outdated Show resolved Hide resolved

DESIGN: Fix the critical bounds check in pseudocode

79a47fc

Issue pointed out by @Geal in review: #6 (comment)

Geal merged commit 5930f49 into master Jan 18, 2019

KellerFuchs mentioned this pull request Jan 19, 2019

Clarify attenuation semantics #8

Closed

KellerFuchs deleted the proposal/caveat-structure branch January 19, 2019 12:12

Geal mentioned this pull request Feb 8, 2019

Roadmap #12

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document the caveat structure #6

Document the caveat structure #6

KellerFuchs commented Jan 8, 2019

KellerFuchs Jan 8, 2019

Geal Jan 9, 2019

KellerFuchs Jan 17, 2019

KellerFuchs Jan 8, 2019

KellerFuchs Jan 8, 2019

Geal Jan 9, 2019

KellerFuchs Jan 17, 2019

KellerFuchs Jan 8, 2019

KellerFuchs Jan 8, 2019

Geal Jan 9, 2019

Geal Jan 9, 2019

KellerFuchs Jan 17, 2019

KellerFuchs Jan 8, 2019

KellerFuchs Jan 8, 2019

Geal Jan 9, 2019

KellerFuchs Jan 17, 2019

Geal Jan 9, 2019

KellerFuchs Jan 17, 2019

	Some of those attributes are critical, and all caveats must provide a bound
	Some of those attributes are critical, and the first caveat must provide a bound

Document the caveat structure #6

Document the caveat structure #6

Conversation

KellerFuchs commented Jan 8, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment