Internet-Draft SPICE Metadata Discovery January 2024
Steele Expires 25 July 2024 [Page]
Secure Patterns for Internet CrEdentials
Intended Status:
O. Steele

SPICE Metadata Discovery


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

This note is to be removed before publishing as an RFC.

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

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

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 25 July 2024.

Table of Contents

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

2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

3. Background

In Open ID Connect [OpenIDConnect], and [I-D.draft-ietf-oauth-sd-jwt-vc], identifiers are URLs, metadata is discovered through URLs, claims are expressed in JSON, [RFC8259], and content is described using content types.


NOTE: '\' line wrapping per RFC 8792

GET /.well-known/openid-configuration HTTP/1.1
Host: issuer.example
Accept: \
  application/json;charset=utf-8, \


NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 200 Ok
Content-Type: \

  "issuer": "https://issuer.example",
  "token_endpoint": "https://issuer.example/api/oauth/token",
  "jwks_uri": "https://issuer.example/.well-known/jwks.json",
  "response_types_supported": [
  "claims_supported": [
  "id_token_signing_alg_values_supported": [
  "token_endpoint_auth_signing_alg_values_supported": [
  "id_token_encrypted_response_alg": [
  "id_token_encrypted_response_enc": [

In [DIDs] and [VCs] the identifiers are URLs, metadata is discovered through dereferencing URLs, claims are expressed in [JSON-LD], and content is described using content types.

For example:


NOTE: '\' line wrapping per RFC 8792

GET /identifiers/did:example:123 HTTP/1.1
Host: resolver.example
Accept: \


NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 200 Ok
Content-Type: \

  "id": "did:example:123"

In [I-D.draft-ietf-ace-key-groupcomm] the identifiers are URLs, metadata discovered through dereferencing URLs, attributes are expressed in CBOR, [RFC8949], and content is described using content types.

For example:


Header: POST (Code=0.02)
Uri-Host: ""
Uri-Path: "ace-group"
Uri-Path: "g1"
Content-Format: "application/ace-groupcomm+cbor"
Payload (in CBOR diagnostic notation,
         with AUTH_CRED and POP_EVIDENCE being CBOR byte strings):
  { "scope": << [ "group1", ["sender", "receiver"] ] >> ,
    "get_creds": [true, ["sender"], []], "client_cred": AUTH_CRED,
    "cnonce": h'25a8991cd700ac01', "client_cred_verify": POP_EVIDENCE }


Header: Created (Code=2.01)
Content-Format: "application/ace-groupcomm+cbor"
Location-Path: ""
Location-Path: "g1"
Location-Path: "nodes"
Location-Path: "c101"
Payload (in CBOR diagnostic notation,
         with KEY being a CBOR byte strings):
  { "gkty": 13, "key": KEY, "num": 12, "exp": 1609459200,
    "creds": [ AUTH_CRED_1, AUTH_CRED_2 ],
    "peer_roles": ["sender", ["sender", "receiver"]],
    "peer_identifiers": [ ID1, ID2 ] }

These examples highlight perhaps the only common attributes of modern digital credential systems: structured identifiers (URLs and URNs) and content types.

3.1. The layering problem

Effective standards limit optionality, improve interoperability, and connect bounded contexts, [BoundedContexts] 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?

[RFC9518] 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, [DIDsFO], 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 [RFC9518] and Martin Fowler in [BoundedContexts] points out, the key to succeeding is ensuring the layering is correct.

4. Structured Identifiers

Structured identifiers, such as URLs are helpful for naming unique identities, but can introduce security and privacy issues while attempting to reduce implementation burden or improve user experience.

A common pattern is to have a single service provider, operating a domain identity.provider.example, deploy unqiue URLs for each identity under its domain, for example https://identity.provider.example/handle.

Traffic analysis of https://identity.provider.example can reveal a distribution of interest in an identity by region and over time.

Additionally, the service provider might serve unique key material for this identifier based on the timing and regional information.

[RFC9458] can address some of these privacy concerns, see [I-D.draft-steele-spice-oblivious-credential-state] for more details.

Another solution can be to rely on decentralized and distributed systems such as DHTs or Blockchains, so that the latest keys and metadata regarding and identifier can be resolved without the interest in that specific identifer to a specific service provider.

Both of these appraoches bring with them signifcant deployment challenges, which may have already been committed to, depending on the identity layer used in a protocol.

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

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

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

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

5.1. Structured Suffixes

[RFC7071] defined a JSON based media type for expressing reputation, application/reputon+json.

The +json part is a structured suffix as described in [RFC6839].

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 [RFC8725] 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.

5.2. 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".


NOTE: '\' line wrapping per RFC 8792

GET /keys/assertion HTTP/1.1
Host: issuer.example
Accept: \


NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 200 Ok
Content-Type: \

  "keys": [
      "kid": "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Nz2...sXs"
      "kty": "EC",
      "crv": "P-256",
      "alg": "ES256",
      "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
      "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"

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.

6. 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:


NOTE: '\' line wrapping per RFC 8792

GET / HTTP/1.1
Host: issuer.example
Accept: \


NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 200 Ok
Content-Type: \

  "capabilities": "https://issuer.example/capabilities",

Content type specific sub resources MUST be expressved by reference, and MUST NOT be expressed by value.

For example:


NOTE: '\' line wrapping per RFC 8792

GET / HTTP/1.1
Host: issuer.example
Accept: \


NOTE: '\' line wrapping per RFC 8792

HTTP/1.1 200 Ok
Content-Type: \

  "jwks": "https://issuer.example/keys",

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 might be used to sign assertions to create credentials, or challenges to enable authentication.

7. Security Considerations

TODO Security

8. IANA Considerations

This document has no IANA actions.

9. References

9.1. Normative References

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <>.
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <>.

9.2. Informative References

"Bounded Context", n.d., <>.
"Decentralized Identifiers (DIDs) v1.0", n.d., <>.
"DID 1.0 Formal Objections Report", n.d., <>.
Palombini, F. and M. Tiloca, "Key Provisioning for Group Communication using ACE", Work in Progress, Internet-Draft, draft-ietf-ace-key-groupcomm-18, , <>.
Terbu, O. and D. Fett, "SD-JWT-based Verifiable Credentials (SD-JWT VC)", Work in Progress, Internet-Draft, draft-ietf-oauth-sd-jwt-vc-01, , <>.
Steele, O., "Oblivious Credential State", Work in Progress, Internet-Draft, draft-steele-spice-oblivious-credential-state-00, , <>.
"A JSON-based Serialization for Linked Data", n.d., <>.
"Open ID Connect", n.d., <>.
Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", RFC 6839, DOI 10.17487/RFC6839, , <>.
Borenstein, N. and M. Kucherawy, "A Media Type for Reputation Interchange", RFC 7071, DOI 10.17487/RFC7071, , <>.
Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, , <>.
Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, , <>.
Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, , <>.
Thomson, M. and C. A. Wood, "Oblivious HTTP", RFC 9458, DOI 10.17487/RFC9458, , <>.
Nottingham, M., "Centralization, Decentralization, and Internet Standards", RFC 9518, DOI 10.17487/RFC9518, , <>.
"Securing Verifiable Credentials using JOSE and COSE", n.d., <>.


TODO acknowledge.

Author's Address

Orie Steele