]> Bespoke Engineering

ietf@justin.richer.org

access token http In many use cases, particularly in workload environments, a single access token or similar security artifact is not sufficient for conveying the type of security and provenance information necessary. This draft describes a data model and format for an additive data container to address these concerns. Discussion Venues Source for this draft and an issue tracker can be found at .

Introduction In most HTTP-based protocols, there's a single item sent with the message to represent authentication and authorization - an OAuth access token, a username/password pair, or a TLS client certificate. Within many API deployments, multiple independent services are tied together into webs of processes that work together in a concerted fashion to fulfill the incoming requests. These systems need a means for different nodes to:

• convey the current state of the transaction to processing nodes further down the graph
• augment this state with new information, optionally tied to existing elements of this state
• attest to the state at the time it was processed by the node
• work in a non-linear fashion

In order to address this set of concerns, this draft defines a data structure for a single element of transactional state as well as a container for holding multiples of these elements in a cohesive and addressable structure.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Single Element Containers A single element container represents a token and its set of properties. The token value is a string whose contents are opaque to the container. Commonly, the token value will contain things like an OAuth access token, a JWT assertion, or another security artifact. The token value is REQUIRED, MUST NOT be the empty string, is covered by the hash, and is immutable. The single element has a deterministic hash that is calculated from the token value and several core properties.

Properties

format:

A string that indicates the format of the token value, to aid downstream nodes in reading and processing the token value. This is covered by the hash.

tag:

A string that indicates an application-specific tag, to aid downstream nodes in identifying the source and purpose of a given single element within a collection. This is covered by the hash.

parents:

An ordered set of single element hashes, indicating other single element containers that this element is dependent on or otherwise related to. This is covered by the hash.

signatures:

An ordered set of signatures for this element, coupled with the identifiers of the key that created the signature. This is not covered by the hash.

Calculating the Hash In order to calculate a hash, the element needs to be canonicalized and serialized in a deterministic fashion. For the purposes of this exercise, a serialization algorithm is defined that is inspired by, but not compatible with, HTTP Structured Fields defined in . An interoperable implementation of this data structure would need to define a more robust hash base generation algorithm. For example, this algorithm defines a fixed order for properties, and does not allow for extension. Additionally, the values are not appropriately mapped to robust serializations (accounting for escaping syntax-relevant characters like double quotes, semicolons, and equal signs). All of these would need to be addressed for a full specification.

1. Start with an empty string
2. Take the token value and represent it as an sf-string value (enclosed in double quotes with internal double quotes, control characters, and escape characters escaped).
3. If the tag property is set, append ";tag=" and the tag value.
4. If the format property is set, append ";format=" and the format value.
5. If the parents property is set and is not empty, append ";parents=("
   1. For each parent, append the hash value encoded in base64
   2. If there are more parents, append "," and repeat the previous step on the next parent
   3. When all parents are accounted for, append ")"
6. Take the resulting string and hash it using SHA256 (note: there should be some crypto agility here probably?)
7. Encode the resulting hash value in base64

Note that this algorithm does not include the signatures property in the hash calculation.

Immutability Once the hash is calculated on a single element, all properties included in the hash calculation MUST be immutable. Additional properties that would be including in the hash calculation MUST NOT be added to the single element. Effectively this means that an element is considered immutable once it is added as the parent of another element, is added to a multiple element container, or is signed.

Adding a Signature To add a signature of a single element, the signer takes the hash value of the element, decoded from base64, as the input to the signature algorithm. The signer calculates the signed value (note: there needs to be some form of crypto agility here) and adds it to the signatures dictionary with the key identifier as the key and the signed output (encoded in base64) as the value. Note that since signatures are not covered by the element's hash, signatures can be added or removed from the set without violating the element's immutability requirement.

Multiple Element Collection The container for multiple single element containers is a dictionary, where the key is the hash of the single element and its set of properties (including signatures). The dictionary structure SHOULD preserve insertion order. There are no properties tied to the collection itself, nor is there an identifier for the collection. There is not a provision to sign the entire collection, but it is possible to add an element that lists every other node as its parent and apply a signature to that node, effectively giving a signature over a specific state of the collection. The elements are tied together using the parent property. If an element has a parent property, all hashes listed in that property MUST exist as keys in the collection before the single element can be added to the collection. Adding an element with an unlisted parent MUST produce an error. Adding an element with a conflicting hash MUST produce an error. Single elements in the collection MAY be removed if they are not the target of any parent properties. Removing an element that is the parent of another element MUST produce an error.

Allowable Actions Due to the nature of the data structure, the following actions can be taken by processing nodes without affecting existing items in the data structure.

Adding a new single element:

A new node can be added to the multiple element collection without affecting any of the existing elements in the collection.

Adding a signature to an existing single element:

A new signature can be calculated on any single element without affecting its hash or relationship to any other elements in the collection.

Removing an unattached single element:

An element that is not listed as the parent of any other node can be safely removed without affecting the collection.

Re-ordering the collection

The collection can be re-ordered, though insertion order should be kept to facilitate processing of element relationships.

Consequently, if a node wants to attest to the existing state of a multiple-element collection, the node can add a new element to the collection that lists a sufficient set of existing nodes as parents and signs the new element.

Example Implementation An example implementation of this data structure is available at https://github.com/bspk/token-bucket In this implementation, the single element structure is called a Bucket, and the multiple element container is called a Crate. Immutability is enforced from the time the hash is calculated. An example of the program's output follows, where a single crate is filled with several interrelated buckets. The serialization here is inspired by, but not compatible with, HTTP Structured Fields defined in .

Security Considerations TODO Security

IANA Considerations This document has no IANA actions.

Normative References This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields that wish to use a common syntax that is more restrictive than traditional HTTP field values. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.

Why Not HTTP-SF? HTTP Structured Fields defines a set of data structures and strict serializations for those structures that would be a perfect fit for this multi-token format. The serialization is HTTP-native, not requiring any additional encoding. Furthermore, SF seems to support all of the core elements we need: dictionaries, lists, properties, strings, etc. And finally, unlike general-purpose formats like JSON or CBOR, SF does not provide infinite recursion. Lists can only be two levels deep, dictionaries can't contain other dictionaries, etc. Unfortunately, SF falls short of being able to naturally represent the data structure here in a couple key ways:

• the multi element collection uses hashes as keys, but binary objects (the natural representation for hashes) cannot be keys
• the value of the parents parameter is a list and the value of the signature parameter is a dictionary, but the values of parameters have to be bare items, not lists or dictionaries

For the purpose of this draft, a new syntax was invented to be able to show the core functions required. Ultimately, a fully robust serialization will need to be specified. Ideally that would be based on SF in some way, but initial experiments in defining that were met with having to follow undesirable workarounds such as using multiple headers to convey a single data structure.

Acknowledgments The author would like to thank UberEther for supporting the initial conception of this work. The author would also like to thank Pieter Kasselman, George Fletcher, and Rifaat Shekh-Yusef for feedback.