]> Transmute

orie@transmute.industries

Security Secure Patterns for Internet CrEdentials credential presentation identity metadata Entities interested in digital credentials need to express and discover preferences for working with them. Before issuance, holders need to discover what credentials are supported, and issuers need to discover if a holder's wallet is safe enough to store their credentials. Before presentation, holder's need to discovery verifier's encryption keys, and which presentation formats a verifier supports. After presentation, verifiers need to discover any new key material or status changes related to credentials. This document enables issuers, holders and verifiers to discover supported protocols and formats for keys, claims, credentials and proofs. 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 Secure Patterns for Internet CrEdentials Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The abstractions and relationships that have evolved to support digital credentials and secure systems are challenging to comprehend and used in conflciting and contradictory ways in different organizations, and security specifications. An identity (also known an entity), is identified (distinguished) through identifiers (names), and can fulfill multiple roles, including being an Issuer, Holder, Relying Party or Verifier of digital credentials and presentations. The attributes (claims, or reputation statements), capabilities, and relations associated with an identifier are expressed as metadata regarding the identifier. Because it remains easier to rediscover the fundamentals of digital identity and credentials than it is to read or comprehend the previous work, very similar, yet unfortunately incompatible systems are continiously created, and through their adoption the digital identity ecosystem becomes increasingly difficult to comprehend or support. This document is not meant to solve all the challenges facing organizations seeking to adopt digital identity and credentialing technology. However, this document attempts to describe an identifier and metadata architecture, that reflects the current state of the art, and addresses the challenge of fragmentation and data siloing, through a distillation of the essentials needed to support digital credentials.

Terminology 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.

Background In Open ID Connect , and , identifiers are URLs, metadata is discovered through URLs, claims are expressed in JSON, , and content is described using content types. Request: Response: In and the identifiers are URLs, metadata is discovered through dereferencing URLs, claims are expressed in , and content is described using content types. For example: Request: Response: In the identifiers are URLs, metadata discovered through dereferencing URLs, attributes are expressed in CBOR, , and content is described using content types. For example: Request: > , "get_creds": [true, ["sender"], []], "client_cred": AUTH_CRED, "cnonce": h'25a8991cd700ac01', "client_cred_verify": POP_EVIDENCE } ]]> Response: These examples highlight perhaps the only common attributes of modern digital credential systems: structured identifiers (URLs and URNs) and content types.

The layering problem Effective standards limit optionality, improve interoperability, and connect bounded contexts, through interfaces that require trivial to acquire and well understood tooling. With respect to structured identifiers and content types, the simplest solutions select a single identifier type, and a single content type. For example, a hypothetical AcmeHyperProtocol might rely only on URLs and JSON. Support for AcmeHyperProtocol would be easy, developers would need only to have reliable libraries for working with URLs and JSON. Software does not evolve this way. It is common to see dependencies that solve several seperate problems efficiently, bundled together, such that it is impossible to take a dependency on just the part that is needed. This problem is then reflected in standards, because effective standards describe effective software systems. In OpenID Connect, we see URLs, but we also see URNs; we see application/json, but we also see application/jwt nested inside of it. In DIDs and VCs, we see URLs, but we also see DIDs (URNs); we see application/json, but we also see application/ld+json nested inside of it, even further, we see application/n-quads constraining what application/json can express through the use of application/ld+json. We see URLs contraining what DIDs can express, through reuse of the path, query and fragment. We see a desire to wrap easily understood content types such as application/jwk+json or application/jwt in less easy to understand JSON-LD content types. Where does this nesting come from? explains in Section 4.7: "standards efforts should focus on providing concrete utility to the majority of their users as published, rather than being a "framework" where interoperability is not immediately available. Internet functions should not make every aspect of their operation extensible; boundaries between modules should be designed in a way that allows evolution, while still offering meaningful functionality." In order to enable consumers leverage their prefered identifiers and content types, some specifications take a "big tent" approach, created an open ended extensibility mechansism, and then providing a single mandatory to implement instantiation of it. In the worst cases, , standards insist on providing the estensiblity mechanisms, and refuse to provide mandatory to implement instances, and through doing so, ensure no interoperability is achievable without a second document, enabling a profile that is actually usable. It could be argued that OAuth has similar deficiencies, and that OpenID Connect solved this same problem through a suite of secondary documents. It might seem impossible to support extensibility and interoperability simultaneously, but as the authors on and Martin Fowler in points out, the key to succeeding is ensuring the layering is correct.

Strategy & Tactics Editors note: This whole section is far too ranty... the objective is to provide generic guidance to address the problem, before providing concrete recommendations and a single set of mandatory to implement APIs. Be honest about the hierarchical model. Digital identity solutions always assume supremacy of certain building blocks. Open ID Connect assumes HTTP, JSON and JWT. DIDs and VCs assume URNs and JSON-LD. CBOR is frequently assumed for new work, due to its similarity to JSON and superior storage and transmission costs. It is better to build a very useful, and easy to implement specification that solves a problem, than it is to build a hard to use, and hard to implement specification that seeks inclusivity at the cost of efficiency, interoperability and simplicity. Once the essential components, and their relative priorities (read importance or rank) are established, assemble them such that each might be replaced in the future, for example HTTP might be replaced with some other transport, JSON with CBOR, JWT with CWT, etc. It is ok, if replacing a single component, requires replacing a set of connected sub components, for example moving from JSON to CBOR, might also require moving from JWT to CWT. While it might seem valuable to support multiple formats, it is one of the highest cost decisions a standard can fail to make for implementers, and it should be avoided at all costs.

Structured Identifiers

Compound Identifiers Compound identifiers are commonly used to address the challend of expressing relations between distinct identifiers. In URLS for http resources, depending on the content type, the compount identifier https://issuer.example/capabilities#f81d4fae-7dec-11d0-a765-00a0c91e6bf6 might express that "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" is a sub resource of "https://issuer.example/capabilities" which is a sub resource of "https://issuer.example". When constructing compoind identifiers, it is important to consider how negotiation is impacted by leveraging different parts of a structured identifier. For example, a server can assist with negotiation for response types for https://issuer.example/capabilities, but sub resources identified by a fragment have their response type controlled by their parent resource.

Global Uniqueness Global uniqueness is a deseriable property of structed identifiers. Ensuring global uniquess often tends towards centralization or federation, because some system or entity must ensure that distinct identities are not able to contest, or claim a single unique identifier. One way to achieve global uniqueness is to produce a compound identifier where the authority or structure of the identifier establishes the uniquenss through relation to itself. For example https://issuer.example/f81d4fae-7dec-11d0-a765-00a0c91e6bf6 relies on the authority https://issuer.example to maintain the linkage between resource identifier and resource representations. Another example https://issuer.example/urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 uses a URN namespace to establish a globally unique identifier urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 and then uses https://issuer.example to establish a compound identifier which is globally unique.

Sharing Structured Identifiers Some systems might wish to share structured identifiers, while maintaining authority for representations. For example https://issuer.example/urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 and https://verifier.example/urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 might both use urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 to express a globally unique identifier for an attribute key or attribute value. When independent entities share globally unique identifiers, they are responsible for ensuring that the identifier is used consistently. For example: https://resolver1.example/identifiers/did:example:123 could serve completely different JSON-LD for did:example:123 than https://resolver2.example/identifiers/did:example:123. Because unlike URLs, URNs are not resolvable by themselves, trust in resources represented with URNs comes from the system you are communicating with, and unlike URLs, there is no commonly understood scheme for communiation, such as http encoded in the identifier.

Content Types Type systems such as the Hindley–Milner type system, can provide much stronger security properties than well defined content types, but both serve a similar purpose, which is to express the intended processing and capabilies of data structures.

Structured Suffixes defined a JSON based media type for expressing reputation, application/reputon+json. The +json part is a structured suffix as described in . Defining a new media type with a structured suffix, allows for systems that support content type negotiation to respond with more precise content types. This property of responding with less ambigious content types is part of secure system design, and notes that using more specific types can help protect against certain attacks. Using a more specific content type comes at the cost of being "generally understood", for example application/json is often expected or hard coded in software, and returning application/reputon+json could cause software to fail higher up in the application stack.

Allowing Additional Properties It is common for content types to rely on map or object datastructures for their top level serializations. This is because a MAP is easily extended with new key value pairs, which when not understood can be ignored, whereas a string or array, might cause processing errors if extended. application/jwk-set+json builds on application/json and expresses a set of cryptographic keys represented by values, that are consistent with application/jwk+json. In cases where additional properties can be present, implementations should take advantage of this and avoid creating new media types, until the number of new properties is substantial enough to justify ensuring security and processing considerations specific to the new type cause faults. For example, consider the following URL and resource expressing "keys that are use to make attribute assertions about a subject". Request: Response: The keys property is part of application/jwk-set+json, and additional properties can be added at this layer, without creating a new media type, however, those properties will not be well understood in the context of application/jwk-set+json. Similarly inside each key the alg property is optional, but when present it signals the algorithm the key is restricted to be used with. Additional properties might be added to the keys themselves, however, those properties will not be well understood in the context of application/jwk+json.

SPICE Metadata Discovery Identifiers for issuer, holders and verifiers MUST be URLs. For example: The scheme of the URL MUST support resolving content types. For example: Request: Response: Content type specific sub resources MUST be expressved by reference, and MUST NOT be expressed by value. For example: Request: Response: It is RECOMMENDED to avoid registering new media types, except in cases where a response might be confused for an existing media type in a way that impacts security. It is RECOMMENDED to return content types that have message level integrity, to protect authenticity, and ensure transport agility is less impacted by transport specific security considerations. It is RECOMMENDED to submit content types that have messsage level encryption, to protect confidentiality, and ensure transport agility is less impacted by transport specific security considerations. It is RECOMMENDED that "purpose" be encoded in identifiers, not attributes of representations. This allows for negotiation of different content types satisfying the same purpose. Purpose is more than just "which algorithms", it is also the intended use of the algorithm. For example, a key migth be used to sign assertions to create credentials, or challenges to enable authentication.

Security Considerations TODO Security

IANA Considerations This document has no IANA actions.

References Normative References 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. Informative References Ericsson AB RISE AB This document defines how to use the Authentication and Authorization for Constrained Environments (ACE) framework to distribute keying material and configuration parameters for secure group communication. Candidate group members acting as Clients and authorized to join a group can do so by interacting with a Key Distribution Center (KDC) acting as Resource Server, from which they obtain the keying material to communicate with other group members. While defining general message formats as well as the interface and operations available at the KDC, this document supports different approaches and protocols for secure group communication. Therefore, details are delegated to separate application profiles of this document, as specialized instances that target a particular group communication approach and define how communications in the group are protected. Compliance requirements for such application profiles are also specified. Spruce Systems, Inc. Authlete Inc. This specification describes data formats as well as validation and processing rules to express Verifiable Credentials with JSON payloads with and without selective disclosure based on the SD-JWT [I-D.ietf-oauth-selective-disclosure-jwt] format. n.d. The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This document discusses aspects of centralization that relate to Internet standards efforts. It argues that, while standards bodies have a limited ability to prevent many forms of centralization, they can still make contributions that assist in the decentralization of the Internet. This document defines the format of reputation response data ("reputons"), the media type for packaging it, and definition of a registry for the names of reputation applications and response sets. A content media type name sometimes includes partitioned meta- information distinguished by a structured syntax to permit noting an attribute of the media as a suffix to the name. This document defines several structured syntax suffixes for use with media type registrations. In particular, it defines and registers the "+json", "+ber", "+der", "+fastinfoset", "+wbxml" and "+zip" structured syntax suffixes, and provides a media type structured syntax suffix registration form for the "+xml" structured syntax suffix. This document is not an Internet Standards Track specification; it is published for informational purposes. JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security tokens that contain a set of claims that can be signed and/or encrypted. JWTs are being widely used and deployed as a simple security token format in numerous protocols and applications, both in the area of digital identity and in other application areas. This Best Current Practices document updates RFC 7519 to provide actionable guidance leading to secure implementation and deployment of JWTs. n.d. n.d. n.d. n.d. n.d.

Acknowledgments TODO acknowledge.