]>

rohan.ietf@gmail.com

Applications and Real-Time More Instant Messaging Interoperability preauthorization credential CWT JWT X.509 ASN.1 DER credential matching credential comparison This document describes a Work-In-Progress syntax called claim pointers that identify specific items in structured credentials, which often have nested levels of hierarchy; and claim matchers that facilitate comparisons between items in credentials and a target value. It also describes a new version of the More Instant Messaging Interoperability (MIMI) preauthorization format using claim pointers and claim matchers. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the More Instant Messaging Interoperability Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction More Instant Messaging Interoperability (MIMI) room policy () defines a format that allows potential joiners that are not enumerated beforehand to be preauthorized based on properties found in their Messaging Layer Security (MLS) credentials. The current version of the preauthorization format in is underspecified and was designed to work with individual claims in a JSON Web Token (JWT) or CBOR Web Token (CWT) . This document describes a Work-In-Progress syntax called claim pointers that can address claims nested inside JWT, CWT, and X.509 certificates , and provides richer matching rules called claim matchers, capable of matching sub parts of those claims and predicates based on them. It could also be extended to credentials based on most general purpose structured data formats.

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.

Structure of Credentials Structured data formats use a handful of strategies for representing and organizing data. All common structured data formats offer some type of record structure semantics. In this context this means a record contains a group of fields. The names for record and fields differ across formats, as do their specific representations, as shown in the table below.

Format	Representation of record	Identifier of field	Name of field
JSON	object (preferred)	name (quoted string)	value
JSON	array	position	value
CBOR	map (slight preference)	map key (often an integer)	value
CBOR	array	position	element
ASN.1	sequence	position or OID	element
TLS PL	struct	field name	value
TLS PL	vector (not used for records)	position	value
ProtoBuf	struct or record?	integer field identifier	??
msgpack
XML	element	XMLPath or id attribute	contents of element
XML	attribute	XMLPath	value of attribute
CSV	line	position	field
TOML	group	name	entry?
SQL	row	column name	column/field
YANG

In this document, we are primarily interested in structured formats commonly used in credentials, specifically JSON Web Tokens (JWT), CBOR Web Tokens (CWT), and X.509 certificates (which use ASN.1) and their derivatives. In the context of credentials, each of these specific fields is often described as a claim. In JSON, a record is represented as an object by convention. The individual fields in the record are identified by the object name, which is always a quoted string. Very rarely a record is represented as an array of heterogeneous elements. Credential claims in a JWT are present in the JWT payload object. Lists of homogenous elements are also arrays. In CBOR a record is typically represented as a map (very often with assigned integer map keys). Records could also be represented as an array of heterogeneous elements. Lists of homogenous elements are also arrays. In X.509v3, a certificate contains an ASN.1 SEQUENCE of exactly 3 elements, the tbsCertificate ("to be signed certificate", which is analogous to the certificate payload), the signature algorithm, and the signature. The certificate "payload" record is an ASN.1 SEQUENCE of 6 mandatory elements (certificate serial number, signature algorithm, issuer, validity, subject, and subject public key) and up to four optional elements (version, issuer unique ID, subject unique ID, and extensions). For the purpose of matching elements in the sequence we will assign an index to each field (starting from 0) as if all 10 elements were present. In this way, the overall structure is addressed by absolute position, while specific names, types, and extensions are identified using registered Object Identifiers (OIDs). The X.509 certificate extensions field contains a further syntax with a potentially large and varied basket of data structures. Lists of items are represented as an ASN.1 SEQUENCE OF type, which is always of a single basic or composite type. A composite type can contain a CHOICE of multiple subtypes. Records and lists in JSON, CBOR, and ASN.1 can be nested, sometimes deeply. For example, the X.509 subjectAltName extension can contain a list of different types of names (DNS, URI, email, etc.) that all represent the subject. In JWT or CWT credentials, an address claim might consist of several component claims (ex: country or postal code); a language claim might consist of a list of languages; or a groups claim might contain nested claims only relevant to that specific group. It is common to have a list of specific permission that have been granted in one context but not another. For example a public relations manager might have regular access to resource A by virtue of being part of a company, access to resource B by virtue of being a full-time employee, regular access to resource C by virtue of being located in a particular country or office, moderator access to resource D by virtue of being a in public relations, and administrator access to resource E by virtue of being a manager.

Requirements for Credential Inspection The following requirements were considered necessary to have a successful credential matching mechanism.

1. The mechanism can represent the difference between no match, and a match with a null or undefined value.
2. The mechanism can find a value in a JSON object or CBOR map by the object name or key name.
3. The mechanism can find an element in ASN.1 by its OID in a SET containing a two-element SEQUENCE.
4. The mechanism can find an element in a list, array, or SEQUENCE OF by its position.
5. The mechanism can find an element in an ASN.1 SEQUENCE that has any combination of its optional elements.
6. The mechanism can find a single element in an list or array where one of the list/array elements contains a single "identifying" field somewhere in the array value.
7. The mechanism can find an element among array elements that requires identification by multiple claim matchers joined with boolean logical ANDs (Maybe).
8. The mechanism can find a numerical value matching simple numeric predicates, such as greater than, or less than or equal to a target value.
9. The mechanism can match a target value to a well-defined part of a URI and email address claim.
10. The mechanism can compare a target value to an arbitrary substring of a value identified by a claim pointer (Maybe).

The following requirements were considered and rejected as out of scope.

• Can the mechanism find claim values matching regular expressions? No, since regular expressions often present a security footgun; as we are defining a mechanism expressly to be used with credentials, this is an unacceptable risk.
• Can the mechanism find claims using arbitrary combinations of boolean logical statements containing OR statements in a claim pointer? No, as this is likely to allow an unbounded explosion of claim combinations, and an OR mechanism can be introduced at the level of the application using the claim pointer mechanism.
• Can the mechanism find claims with information from partial or incomplete nested map keys? No, since JSON only supports strings as object names, and CWT does not map keys with maps or arrays. However, this might be a straightforward extension.
• Can the mechanism find multiple claims with a given query? No, this would imply a mechanism that could return a set of arbitrarily disjoint trees, instead of returning a single result (or no match).

Matching claims In this section we introduce a method of matching claims in credentials that we describe here as Claim Pointers (which find a particular value), and Claim Matchers (which compare a value from a Claim Pointer to a specific value). A claim pointer follows the hierarchy of a credential from its root to a specific claim, through a sequence of specifiers per level. Each level is described using a ClaimPointerItem object. For the purposes of this section, a level of hierarchy in JSON is the value of any object, or an element of an array. In CBOR a level of hierarchy is the value of any map key, an element of an array, or the contents of a tag. In ASN.1 a level of hierarchy is generally an element of either a SEQUENCE or SEQUENCE OF. For explanatory purposes, we will provide an example JWT payload here to demonstrate some of the claim matching options. Additional examples will be introduced as needed.

Matching Map Keys, Object Names, and OIDs The value of an object in JSON or the value of a map in CBOR is accessed by its JSON name or CBOR map key, using the via_key pointer item type. For JSON the key to be compared with the key is a double-quoted JSON string that matches the object name. For CBOR the key is the ordinary encoding that matches the map key. For example the CBOR map keys of 1 (unsigned integer), -1 (negative integer), '1' (byte string), "1" (text string), 1(0) (a timestamp at the start of the UNIX epoch), and 1.0 (float) match the keys of 0x01, 0x20, 0x41 0x31, 0x61 0x31, 0xC1 0x00, and 0xF9 0x3C 0x00 respectively. In X.509, a common pattern is to have a single element SET of a SEQUENCE of two elements consisting of an OID and data element (its "value"). The data element of such a 2 element SEQUENCE matches when its key is equal to the DER representation of its OID (excluding the OID type and length). This pointer item points to ("returns") the value corresponding to the object name, map key, or element in the SEQUENCE. When evaluating the JWT payload above, the following claim pointer points at the value true, since that is the value of the known_entity claim.

Matching Lists and Sequences by Absolute Position The value of an element in an absolute position in a list is accessed using the array_position pointer item type. The index value corresponds to the position counting from 0. The claim pointer below using the example JSON document above would point at the value true as well, the 3rd element of the service_flags array. If there is no array, or the array does not have an element at the requested position, the claim pointer does not point at anything. If the index above was instead 7, or the value of service_flags was not an array, the claim pointer would not point at any value. As previously mentioned, the elements of an X.509 SEQUENCE with optional elements (such as tbsCertificate) are given a logical position from zero as if all possible optional elements are present.

Matching an Element in a List by an Identifier in the List The array_search claim pointer item type, can search a JSON or CBOR array, or an ASN.1 SEQUNCE OF, for the first entry which matched the nested claim matchers in nested_claim_pointer. The claim pointer below begins by pointing at the value of the entire nodes array. Then, starting from the nodes array, its nested claim pointer points at the value of the processor object and compares it to the string value "DCBA-10177". Finding a match, the top-level claim_pointer now points at the first element in the nodes array. Finally, the next claim pointer item looks for a domain object in the first element of the nodes array. The claim pointer now points at the value "smart.example". Instead imagine searching for the value of processor in the first element that matches the domain "smart.example". We would use the following claim_pointer instead, which would point to the value "DCBA-10177" in the first element's processor object. Finally, imagine that the value of the domain field was instead "xn--ingnieux-d1a.example", the match_as type was "punycode" and the test_value was "ingénieux.example". This would also point to the same value ("DCBA-10177") since the punycode representation of the Internationalized Domain Name (IDN) or "punycode" representation of "ingénieux.example" is "xn--ingnieux-d1a.example". Full explanation of comparison rules will be discussed in section .

Matching multiple claim pointers If no single value in an array element is sufficient to uniquely identify the target element, an array_search can search multiple claim_match elements. While implementations may choose a variety of techniques to match multiple items, be aware that the claim matches need to be evaluated together. One way to do this would be to start with the first item in an array, try each claim_match with that item until one of them fails to find a match, stopping at the first item that matches every claim_match, or returning no match if none is found. The following example presents the value of the processor object for the first element of the nodes item which matches both the domain "smart.example", and the origin country "us".

Matching with Numerical Predicates In this example we use the concept of predicates to find an element with a numerical value in designed ranges. In our example we are looking for an element of the nodes array with a eur_per_hour value greater than or equal to 200.

Matching Parts of URIs and email addresses Standard URIs and email addresses have a complicated but predictable internal structure. It is often useful to compare a specific component of a URI or an email address to a specific value. In the example fragments below the first claim_match will match when the domain of the URI matches "example.com". The second matches when the email hostpart matches "example.com". The last one matches when a MIMI URI where the first item in the URI path matches "r" (room).

Matching Arbitrary Substrings mimi://example.com/u/46133c9e-df4c-4c88-91d2-00a527bdd0f7

Match Syntax Definition ; case array_index: uint index; } } JwtToken; struct { JwtToken claim_pointer; } JwtClaimRoot; enum { map_key (0), array_position (1), array_search (2), tagged_value (3), bstr_encoded (4), any (5), (255) } ItemType; struct { ItemType item_type; select (item_type) { case map_key: opaque opaque_key; case array_position: uint index; case array_search: ClaimMatcher nested_matches; case tagged_value: uint tag; case bstr_encoded: struct {}; case any: struct {}; }; } ClaimPointerItem; enum { equal (0), less_than (1), less_than_or_equal (2), greater_than (3), greater_than_or_equal (4), contains (7), starts_with (8), ends_with (9), substring (10), path_slice (11), } OperationType; struct { OperationType operation_type; select (operation_type) { case equal: case less_than: case less_than_or_equal: case greater_than: case greater_than_or_equal: case contains: struct {}; case starts_with: optional length; case ends_width: optional length; case substring: uint start_position; optional length; case path_slice: uint path_index; }; } Operation; struct { ClaimPointerItem claim_pointer; ClaimSemantics claim_semantics; MatchAs match_as; optional operation; opaque test_value; } ClaimMatcher; struct { ClaimFamily claim_family; select (claim_family) { case json: String object_name; case cbor: Bytes cbor_encoding; case asn1: Bytes der_encoded_oid; }; } MapKey; struct { bool claim_exists; select (claim_exists) { case false: select {}; case true: ClaimFamily claim_family; select (claim_family) { case json: JsonType json_type; select (json_type) { case number: Double value; case string: case object: case array: Bytes value; case true: case false: case null: struct {}; }; case cbor: Bytes cbor_encoding; case asn1: /* we might need another option */ Bytes der_encoding; }; }; } FoundValue; struct { CborType type; select (type) { case no_match: struct {}; case uint: case nint: uint64 value; case float Double value; case array: CborValue elements; case map: CborKeyAndValue map_entries; case text_string: Bytes value; case byte_string: Bytes value; case tag: uint64 tag; CborValue value; case undefined: select {}; case simple: uint8 value; }; } CborValue; struct { CborValue key; CborValue value; } CborKeyAndValue; enum { no_match (0), number (1), string (2), object (3), array (4), true (5), false (6), null (7) (255) } JsonType; enum { uint (0), nint (1), array (2), map (3), byte_string (4), text_string (5), tag (6), simple (7), true (8), false (9), null (10), undefined (11), float (12), no_match (13), (255) } CborType; struct { CwtToken claim_pointer; } CwtClaimRoot; struct { ClaimFamily claim_family; select (claim_family) { case x509: opaque oid; case jwt: JwtClaimRoot claim_root; case cwt: CwtClaimRoot claim_root; } ClaimSemantics claim_semantics; MatchAs match_as; bool match_any_in_list; opaque target_value; } Claim; ]]>

Types of comparisons TODO

More examples

CBOR Examples

CBOR example with tagged value accessed directly as opaque_value

CBOR example parsing into tagged value

CBOR example with custom simple values ?? - maybe not needed

X.509 Examples

Simple X.509 example (CN)

X.509 Matching one DNS item in issuerAltName

X.509 matching one URI part of subjectAltName

X.509 matching one URI part of subjectAltName with a domain substring RFC5820 matches only host part of URIs??

Old text on Preauth Preauthorized users are MIMI users and external senders that have authorization to adopt a role in a room by virtue of certain credential claims or properties, as opposed to being individually enumerated in the participant list. For example, a room for employee benefits might be available to join with the regular participant role to all full-time employees with a residence in a specific country; while anyone working in the human resources department might be able to join the same room as a moderator. This data structure is consulted in two situations: for external joins (external commits) and external proposals when the requester does not already appear in the participant list; and separately when an existing participant explicitly tries to change its own role.

• Only consulting Preauthorized users in these cases prevents several attacks. For example, it prevents an explicitly banned user from rejoining a group based on a preauthorization.

PreAuthData is the format of the data field inside the ComponentData struct for the Preauthorized Participants component in the application_data GroupContext extension. The individual PreAuthRoleEntry rules in PreAuthData are consulted one at a time. A PreAuthRoleEntry matches for a requester when every Claim.claim_id has a corresponding claim in the requester's MLS Credential which exactly matches the corresponding claim_value. When the rules in a Preauthorized users struct match multiple roles, the requesting client receives the first role which matches its claims.

• TODO: refactor Claims

; } ClaimId; struct { ClaimId claim_id; opaque claim_value; } Claim; struct { /* when all claims in the claimset are satisfied, the claimset */ */ is satisfied */ Claim claimset; Role target_role; } PreAuthRoleEntry; struct { PreAuthRoleEntry preauthorized_entries; } PreAuthData; PreAuthData preauth_list; PreAuthData PreAuthUpdate; ]]> PreAuthUpdate (which has the same format as PreAuthData) is the format of the update field inside the AppDataUpdate struct in an AppDataUpdate Proposal for the Preauthorized Participants component. If the contents of the update field are valid and if the proposer is authorized to generate such an update, the value of the update field completely replaces the value of the data field.

• As with the definition of roles, in MIMI it is not expected that the definition of Preauthorized users would change frequently. Instead the claims in the underlying credentials would be modified without modifying the preauthorization policy.

Changing Preauthorized user definitions is sufficiently disruptive, that an update to this component is not valid if it appears in the same commit as any Participant List change, except for user removals. Because the Preauthorized users component usually authorizes non-members, it is also a natural choice for providing concrete authorization for policy enforcing systems incorporated into or which run in coordination with the MIMI Hub provider or specific MLS Distribution Services. For example, a preauthorized role could allow the Hub to remove participants and to ban them, but not to add any users or devices. This unifies the authorization model for members and non-members.

Security Considerations TODO Security

IANA Considerations This document has no IANA actions.

Normative References Rohan Mahy Consulting Services This document describes a set of concrete room policies for the More Instant Messaging Interoperability (MIMI) Working Group. It describes several independent properties and policy attributes which can be combined to model a wide range of chat and multimedia conference types. Messaging applications are increasingly making use of end-to-end security mechanisms to ensure that messages are only accessible to the communicating endpoints, and not to any servers involved in delivering messages. Establishing keys to provide such protections is challenging for group chat settings, in which more than two clients need to agree on a key but may not be online at the same time. In this document, we specify a key establishment protocol that provides efficient asynchronous group key establishment with forward secrecy (FS) and post-compromise security (PCS) for groups in size ranging from two to thousands. JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. CBOR Web Token (CWT) is a compact means of representing claims to be transferred between two parties. The claims in a CWT are encoded in the Concise Binary Object Representation (CBOR), and CBOR Object Signing and Encryption (COSE) is used for added application-layer security protection. A claim is a piece of information asserted about a subject and is represented as a name/value pair consisting of a claim name and a claim value. CWT is derived from JSON Web Token (JWT) but uses CBOR rather than JSON. This memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK] 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. Security Theory LLC This document defines two CBOR serializations: "preferred-plus serialization" and "deterministic serialization." It also introduces the term "general serialization" to name the complete set of all serializations defined in RFC 8949. Together, these three form a set of serializations that cover the majority of CBOR serialization use cases. These serializations are largely compatible with those widely implemented by the CBOR community.

More example documents to match against

Acknowledgments TODO acknowledge.