Network Working Group J. Richer, Ed. Internet-Draft Bespoke Engineering Intended status: Informational 15 September 2023 Expires: 18 March 2024 Multi-token Container Data Structure draft-richer-wimse-token-container-00 Abstract 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 This note is to be removed before publishing as an RFC. Source for this draft and an issue tracker can be found at https://github.com/bspk/draft-richer-wimse-token-container. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 18 March 2024. Copyright Notice Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved. Richer Expires 18 March 2024 [Page 1] Internet-Draft Multi-token Container Data Structure September 2023 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 3. Single Element Containers . . . . . . . . . . . . . . . . . . 3 3.1. Properties . . . . . . . . . . . . . . . . . . . . . . . 3 3.2. Calculating the Hash . . . . . . . . . . . . . . . . . . 4 3.3. Immutability . . . . . . . . . . . . . . . . . . . . . . 5 3.4. Adding a Signature . . . . . . . . . . . . . . . . . . . 5 4. Multiple Element Collection . . . . . . . . . . . . . . . . . 5 5. Allowable Actions . . . . . . . . . . . . . . . . . . . . . . 6 6. Example Implementation . . . . . . . . . . . . . . . . . . . 7 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 9. Normative References . . . . . . . . . . . . . . . . . . . . 8 Appendix A. Why Not HTTP-SF? . . . . . . . . . . . . . . . . . . 8 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 1. 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 Richer Expires 18 March 2024 [Page 2] Internet-Draft Multi-token Container Data Structure September 2023 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. 2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. 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. 3.1. 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. Richer Expires 18 March 2024 [Page 3] Internet-Draft Multi-token Container Data Structure September 2023 3.2. 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 [RFC8941]. 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. Richer Expires 18 March 2024 [Page 4] Internet-Draft Multi-token Container Data Structure September 2023 3.3. 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. 3.4. 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. 4. 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. Richer Expires 18 March 2024 [Page 5] Internet-Draft Multi-token Container Data Structure September 2023 ,--------, ,--------, | token1 | | token3 | | tag=1 |<---------+---+ tag=b | `--------` parents | `--------` ^ v | ,--------, parents ,--------, | | token2 |<--------+ token4 | | parents | | `--------` `---------+ format | `--------` 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. 5. 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. Richer Expires 18 March 2024 [Page 6] Internet-Draft Multi-token Container Data Structure September 2023 6. 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 [RFC8941]. CNgfrWGz8iIRndkFis9RjozfdNUKnx5drNDl_qtmVNE="876ytghj4nb2ghj23rjnfdu o2i3rj asdflk 23r" ;tag=weird ;format=illgal-probably ;parents=(6IdWzEZCGGRbA_mFtcO2Msm2_J2n5lFgARFxcpuJen8) ;sig=(k2=MEUCIQDWKyxZdprVENPWrd12MCwXefLBYYa0_7S9wflpNWkTjAIgaCmRB4A0GHf62vV34I2An4UFJacoT3pL6xyNL5J12Wg), 6IdWzEZCGGRbA_mFtcO2Msm2_J2n5lFgARFxcpuJen8="2wsdfghgfr45tyhjkiuytg" ;tag=gateway ;format=jwt ;parents=(NJSQl7yrzij1338sfK4XDE9aP0tZzw7R71cySlQwQ7I) ;sig=(k1=KNLuDTHrf9f_rBDwFwsnE-MdGYgGEeqPhlKmEFRoFSoiZ65txKizNTsfW2TXvUJ3zq7BuQa4xn0riBYlfCUiyHUgz6F38LmZkEN9qhFdii5cBY5ite-hQV--2nsKdeyvGrh21wtLhQu4NRhu91lYppn_j8L30nRQ1RlbNlrgpAQ,k2=MEYCIQDJQ-lm_sFnVynXP1BvdwUpH5hwFIGpEPY2DBx9wY523QIhAIsQIlzwGtN_8sAor8eLp-O43N66XHT9wdGsm4RbXFz2), fV_0qN9qExdZKa46O0i6UE_UfNkxltH_QZjMlZMrCJA="a" ;format=secure ;parents=(NJSQl7yrzij1338sfK4XDE9aP0tZzw7R71cySlQwQ7I,ISdNpXb-StTmZvWZDTZLHlzhmpyivMorHOSL3UKTP7k) ;sig=(k1=O1NlrhtrtQ9ykDTR2uBOwk6ofFcL1_WvF0tj3CkrRbbLaBwVxUVslswCa4iHCbza8GS1G4mhNhJXUJ6O-Y6xG9xupoql1QVl_04a4oJOOStfNnptZ8embVMksXfAJQDhog7XAtsZ0vWmG_VkekIG7ZmvbhfAsS9QalC6oMiiVQs), NJSQl7yrzij1338sfK4XDE9aP0tZzw7R71cySlQwQ7I="8765trfghjuyt5rtghjki987y6tfghj" ;tag=api ;format=opaque ;sig=(k1=Os27rze-ZOKNAX0BuQUr91ztA59vJIUXznzoG87Ka0IkuwTcWjz6DDsDLhh42Qh9UGH2C6oO9n9TSc41Y0EhUWi8oGt3LKwjHzNm7ziwolosl_JmpaNUDWVn8VabxYGDFUGnieUGMfb7DqRi59qAs6RpH-qTEZMF3Ihw2mPZinc), ISdNpXb-StTmZvWZDTZLHlzhmpyivMorHOSL3UKTP7k="vcxsawertghju7654rtyuikjhgfr54refghjukjhgtr54redfghj" ;tag=magic ;parents=(NJSQl7yrzij1338sfK4XDE9aP0tZzw7R71cySlQwQ7I,6IdWzEZCGGRbA_mFtcO2Msm2_J2n5lFgARFxcpuJen8) ;sig=(k2=MEUCIHS9M_TkQouH5Icb731gBmKhB5FCKNfiUu6bJc7x0H-tAiEAmVe0mlQcfqASWIGaJYkOc3f6e3iDopJS58YKYBTKSJA) 7. Security Considerations TODO Security Richer Expires 18 March 2024 [Page 7] Internet-Draft Multi-token Container Data Structure September 2023 8. IANA Considerations This document has no IANA actions. 9. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8941] Nottingham, M. and P. Kamp, "Structured Field Values for HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, . Appendix A. Why Not HTTP-SF? HTTP Structured Fields [RFC8941] 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. Richer Expires 18 March 2024 [Page 8] Internet-Draft Multi-token Container Data Structure September 2023 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. Author's Address Justin Richer (editor) Bespoke Engineering Email: ietf@justin.richer.org Richer Expires 18 March 2024 [Page 9]