Internet DRAFT - draft-steele-spice-metadata-discovery
draft-steele-spice-metadata-discovery
Secure Patterns for Internet CrEdentials O. Steele
Internet-Draft Transmute
Intended status: Informational 22 January 2024
Expires: 25 July 2024
SPICE Metadata Discovery
draft-steele-spice-metadata-discovery-01
Abstract
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
https://OR13.github.io/draft-steele-spice-metadata-discovery/draft-
steele-spice-metadata-discovery.html. Status information for this
document may be found at https://datatracker.ietf.org/doc/draft-
steele-spice-metadata-discovery/.
Discussion of this document takes place on the Secure Patterns for
Internet CrEdentials Working Group mailing list
(mailto:spice@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/spice/. Subscribe at
https://www.ietf.org/mailman/listinfo/spice/.
Source for this draft and an issue tracker can be found at
https://github.com/OR13/draft-steele-spice-metadata-discovery.
Steele Expires 25 July 2024 [Page 1]
Internet-Draft SPICE Metadata Discovery January 2024
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 25 July 2024.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
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 . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Background . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. The layering problem . . . . . . . . . . . . . . . . . . 7
4. Structured Identifiers . . . . . . . . . . . . . . . . . . . 8
4.1. Compound Identifiers . . . . . . . . . . . . . . . . . . 9
4.2. Global Uniqueness . . . . . . . . . . . . . . . . . . . . 9
4.3. Sharing Structured Identifiers . . . . . . . . . . . . . 10
5. Content Types . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. Structured Suffixes . . . . . . . . . . . . . . . . . . . 11
5.2. Allowing Additional Properties . . . . . . . . . . . . . 11
6. SPICE Metadata Discovery . . . . . . . . . . . . . . . . . . 12
7. Security Considerations . . . . . . . . . . . . . . . . . . . 14
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
Steele Expires 25 July 2024 [Page 2]
Internet-Draft SPICE Metadata Discovery January 2024
9.1. Normative References . . . . . . . . . . . . . . . . . . 14
9.2. Informative References . . . . . . . . . . . . . . . . . 15
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
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.
Steele Expires 25 July 2024 [Page 3]
Internet-Draft SPICE Metadata Discovery January 2024
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.
Request:
NOTE: '\' line wrapping per RFC 8792
GET /.well-known/openid-configuration HTTP/1.1
Host: issuer.example
Accept: \
application/json;charset=utf-8, \
application/json
Response:
Steele Expires 25 July 2024 [Page 4]
Internet-Draft SPICE Metadata Discovery January 2024
NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 200 Ok
Content-Type: \
application/json
{
"issuer": "https://issuer.example",
"token_endpoint": "https://issuer.example/api/oauth/token",
"jwks_uri": "https://issuer.example/.well-known/jwks.json",
"response_types_supported": [
"token"
],
"claims_supported": [
"aud",
"exp",
"iat",
"iss",
"sub"
],
"id_token_signing_alg_values_supported": [
"ES384"
],
"token_endpoint_auth_signing_alg_values_supported": [
"ES384"
],
"id_token_encrypted_response_alg": [
"ECDH-ES+A256KW
],
"id_token_encrypted_response_enc": [
"A128CBC-HS256"
]
...
}
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:
Request:
Steele Expires 25 July 2024 [Page 5]
Internet-Draft SPICE Metadata Discovery January 2024
NOTE: '\' line wrapping per RFC 8792
GET /identifiers/did:example:123 HTTP/1.1
Host: resolver.example
Accept: \
application/did+json
Response:
NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 200 Ok
Content-Type: \
application/json
{
"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:
Request:
Header: POST (Code=0.02)
Uri-Host: "kdc.example.com"
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 }
Response:
Steele Expires 25 July 2024 [Page 6]
Internet-Draft SPICE Metadata Discovery January 2024
Header: Created (Code=2.01)
Content-Format: "application/ace-groupcomm+cbor"
Location-Path: "kdc.example.com"
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.
Steele Expires 25 July 2024 [Page 7]
Internet-Draft SPICE Metadata Discovery January 2024
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.
Steele Expires 25 July 2024 [Page 8]
Internet-Draft SPICE Metadata Discovery January 2024
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.
Steele Expires 25 July 2024 [Page 9]
Internet-Draft SPICE Metadata Discovery January 2024
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.
Steele Expires 25 July 2024 [Page 10]
Internet-Draft SPICE Metadata Discovery January 2024
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".
Request:
Steele Expires 25 July 2024 [Page 11]
Internet-Draft SPICE Metadata Discovery January 2024
NOTE: '\' line wrapping per RFC 8792
GET /keys/assertion HTTP/1.1
Host: issuer.example
Accept: \
application/jwk-set+json
Response:
NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 200 Ok
Content-Type: \
application/json
{
"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:
https://issuer.example
Steele Expires 25 July 2024 [Page 12]
Internet-Draft SPICE Metadata Discovery January 2024
The scheme of the URL MUST support resolving content types.
For example:
Request:
NOTE: '\' line wrapping per RFC 8792
GET / HTTP/1.1
Host: issuer.example
Accept: \
application/json
Response:
NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 200 Ok
Content-Type: \
application/json
{
"capabilities": "https://issuer.example/capabilities",
...
}
Content type specific sub resources MUST be expressved by reference,
and MUST NOT be expressed by value.
For example:
Request:
NOTE: '\' line wrapping per RFC 8792
GET / HTTP/1.1
Host: issuer.example
Accept: \
application/json
Response:
Steele Expires 25 July 2024 [Page 13]
Internet-Draft SPICE Metadata Discovery January 2024
NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 200 Ok
Content-Type: \
application/json
{
"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
Steele Expires 25 July 2024 [Page 14]
Internet-Draft SPICE Metadata Discovery January 2024
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
9.2. Informative References
[BoundedContexts]
"Bounded Context", n.d.,
<https://martinfowler.com/bliki/BoundedContext.html>.
[DIDs] "Decentralized Identifiers (DIDs) v1.0", n.d.,
<https://www.w3.org/TR/did-core/>.
[DIDsFO] "DID 1.0 Formal Objections Report", n.d.,
<https://www.w3.org/2022/03/did-fo-report.html>.
[I-D.draft-ietf-ace-key-groupcomm]
Palombini, F. and M. Tiloca, "Key Provisioning for Group
Communication using ACE", Work in Progress, Internet-
Draft, draft-ietf-ace-key-groupcomm-18, 16 January 2024,
<https://datatracker.ietf.org/doc/html/draft-ietf-ace-key-
groupcomm-18>.
[I-D.draft-ietf-oauth-sd-jwt-vc]
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, 23 October 2023,
<https://datatracker.ietf.org/doc/html/draft-ietf-oauth-
sd-jwt-vc-01>.
[I-D.draft-steele-spice-oblivious-credential-state]
Steele, O., "Oblivious Credential State", Work in
Progress, Internet-Draft, draft-steele-spice-oblivious-
credential-state-00, 13 January 2024,
<https://datatracker.ietf.org/doc/html/draft-steele-spice-
oblivious-credential-state-00>.
[JSON-LD] "A JSON-based Serialization for Linked Data", n.d.,
<https://www.w3.org/TR/json-ld11/>.
[OpenIDConnect]
"Open ID Connect", n.d.,
<https://openid.net/specs/openid-connect-core-1_0.html>.
Steele Expires 25 July 2024 [Page 15]
Internet-Draft SPICE Metadata Discovery January 2024
[RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type
Structured Syntax Suffixes", RFC 6839,
DOI 10.17487/RFC6839, January 2013,
<https://www.rfc-editor.org/rfc/rfc6839>.
[RFC7071] Borenstein, N. and M. Kucherawy, "A Media Type for
Reputation Interchange", RFC 7071, DOI 10.17487/RFC7071,
November 2013, <https://www.rfc-editor.org/rfc/rfc7071>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/rfc/rfc8259>.
[RFC8725] Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best
Current Practices", BCP 225, RFC 8725,
DOI 10.17487/RFC8725, February 2020,
<https://www.rfc-editor.org/rfc/rfc8725>.
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020,
<https://www.rfc-editor.org/rfc/rfc8949>.
[RFC9458] Thomson, M. and C. A. Wood, "Oblivious HTTP", RFC 9458,
DOI 10.17487/RFC9458, January 2024,
<https://www.rfc-editor.org/rfc/rfc9458>.
[RFC9518] Nottingham, M., "Centralization, Decentralization, and
Internet Standards", RFC 9518, DOI 10.17487/RFC9518,
December 2023, <https://www.rfc-editor.org/rfc/rfc9518>.
[VCs] "Securing Verifiable Credentials using JOSE and COSE",
n.d., <https://www.w3.org/TR/vc-jose-cose/>.
Acknowledgments
TODO acknowledge.
Author's Address
Orie Steele
Transmute
Email: orie@transmute.industries
Steele Expires 25 July 2024 [Page 16]
