RFC 7800
Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)
RFC 7800 ✨ Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)
okay bestie, let's get into this one 💅 it's an IETF Standards Track doc (so it's the real deal, not just a suggestion 🫶), published April 2016, and it's giving "how do I prove I'm the one holding this token without anyone just taking my word for it" 🔐. The authors are M. Jones (Microsoft), J. Bradley (Ping Identity), and H. Tschofenig (ARM Limited) 👑. It's ISSN 2070-1721 and it doesn't obsolete or update any other RFCs, so no drama there 🌸.
The whole vibe: it's about how a JSON Web Token can say "hey, the person presenting me has a specific proof-of-possession key," and how the recipient can check that cryptographically 🦋. That's the "holder-of-key" thing, and it's lowkey the main character of this doc 🎀.
Status of This Memo ✨
This is an Internet Standards Track document 💖
It's a product of the Internet Engineering Task Force (IETF) and it represents the consensus of the IETF community 🫶. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more info about Internet Standards, check out Section 2 of RFC 5741 🍓.
Info about the current status, any errata, and how to give feedback lives at http://www.rfc-editor.org/info/rfc7800 🧚
Copyright Notice ✨
Copyright (c) 2016 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 (http://trustee.ietf.org/license-info) as they were on the date of publication. Please read these carefully, bestie, because they describe your rights and restrictions 🙈. Code Components pulled out of this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty as described in the Simplified BSD License 💅.
Table of Contents 🌈
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Representations for Proof-of-Possession Keys . . . . . . . . 5
3.1. Confirmation Claim . . . . . . . . . . . . . . . . . . . 6
3.2. Representation of an Asymmetric Proof-of-Possession Key . 7
3.3. Representation of an Encrypted Symmetric Proof-of-
Possession Key . . . . . . . . . . . . . . . . . . . . . 7
3.4. Representation of a Key ID for a Proof-of-Possession Key 8
3.5. Representation of a URL for a Proof-of-Possession Key . . 9
3.6. Specifics Intentionally Not Specified . . . . . . . . . . 10
4. Security Considerations . . . . . . . . . . . . . . . . . . . 10
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 11
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
6.1. JSON Web Token Claims Registration . . . . . . . . . . . 12
6.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 12
6.2. JWT Confirmation Methods Registry . . . . . . . . . . . . 12
6.2.1. Registration Template . . . . . . . . . . . . . . . . 12
6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 13
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
7.1. Normative References . . . . . . . . . . . . . . . . . . 13
7.2. Informative References . . . . . . . . . . . . . . . . . 14
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 151. Introduction 🦋
1.1. Notational Conventions 💖
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 RFC 2119 [RFC2119] 🫶. Unless otherwise noted, all the protocol parameter names and values are case sensitive 🎀.
2. Terminology 📚
This spec uses terms from the JSON Web Token [JWT], JSON Web Key [JWK], and JSON Web Encryption [JWE] specs 🍓.
These terms are defined by this spec:
- Issuer: the party that creates the JWT and binds the proof-of-possession key to it 👑.
- Presenter: the party that proves possession of a private key (for asymmetric key cryptography) or secret key (for symmetric key cryptography) to a recipient 🔐.
- Recipient: the party that receives the JWT containing the proof-of-possession key information from the presenter 🧚.
Part 1 of 3 done, bestie 🌸. Keep your eyes peeled for part 2, where we get into the actual representations for proof-of-possession keys, and it's about to get spicy 🔥💖.
3. Representations for Proof-of-Possession Keys ✨
okay so bestie, when the issuer adds a "cnf" (confirmation) claim to a JWT, it's basically saying "hey, the person presenting this token totally has a specific key, and you can cryptographically check that they do" 🔐💅. The value of "cnf" is a JSON object, and its members are what identify the proof-of-possession key 🗝️🦋.
The presenter can be identified a few different ways, depending on what the app needs 🌸. If the JWT has a "sub" (subject) claim [JWT], the presenter is normally the subject the JWT names. (In some apps, the subject identifier is relative to the issuer named by the "iss" (issuer) claim [JWT].) If there's no "sub" claim, the presenter is normally the issuer identified by the "iss" claim. The subject version is giving the same energy as the SAML 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation usage 🎀. At least one of the "sub" and "iss" claims MUST be present in the JWT. Some use cases may require that both be present ✨.
Some apps identify the presenter with an explicit claim instead, like the "azp" (authorized party) claim that OpenID Connect [OpenID.Core] defines 🧚. Honestly, how you identify the presenter is app-specific, and so is how you confirm the key possession that gets communicated 💜.
3.1. Confirmation Claim
The "cnf" claim is the thing in the JWT that holds the members used to identify the proof-of-possession key 🫶. Other members of the "cnf" object can be defined too, because a proof-of-possession key isn't the only way to confirm a token is legit 👑. It's like SAML 2.0 [OASIS.saml-core-2.0-os] SubjectConfirmation, where you can include a bunch of different confirmation methods (proof-of-possession key info included) 🌈.
The set of confirmation members a JWT must contain to count as valid depends on context, and it's outside the scope of this specification 🙈. Specific applications may need implementations to understand and process some confirmation members in particular ways. But if there's no such requirement, every confirmation member an implementation doesn't understand MUST be ignored 💅.
This specification sets up the IANA "JWT Confirmation Methods" registry for these members in Section 6.2, and registers the members defined here 🍓. Other specifications can register their own confirmation members, including other ways to convey proof-of-possession keys using different key representations ✨.
The "cnf" claim value MUST represent only a single proof-of-possession key. So at most one of the "jwk", "jwe", and "jku" (JWK Set URL) confirmation values defined below may be present 🔥. Now, if an app needs several proof-of-possession keys in the same JWT, one way to do it is to use other claim names, alongside "cnf", to hold the extra key info 🌸. Those claims could use the same syntax and semantics as "cnf". Apps or other specifications would define them, and they could be registered in the IANA "JSON Web Token Claims" registry [IANA.JWT.Claims] 💖.
3.2. Representation of an Asymmetric Proof-of-Possession Key
When the presenter's key is an asymmetric private key, the "jwk" member is a JSON Web Key [JWK] representing the matching asymmetric public key 🦋. Here's what that looks like in the JWT Claims Set:
{
"iss": "https://server.example.com",
"aud": "https://client.example.org",
"exp": 1361398824,
"cnf":{
"jwk":{
"kty": "EC",
"use": "sig",
"crv": "P-256",
"x": "18wHLeIgW9wVN6VD1Txgpqy2LszYkMf6J8njVAibvhM",
"y": "-V4dS4UaLMgP_4fY4j8ir7cl1TXlFdAgcx55o7TkcSA"
}
}
}The JWK MUST contain the required key members for a JWK of that key type, and it MAY contain other JWK members too, including the "kid" (Key ID) member 💜.
The "jwk" member MAY also be used for a JWK representing a symmetric key, but only if the JWT is encrypted so the key doesn't get revealed to unintended parties 🔐. The JWT [JWT] spec explains how to encrypt a JWT. If the JWT is not encrypted, the symmetric key MUST be encrypted as described below 🙈.
3.3. Representation of an Encrypted Symmetric Proof-of-Possession Key
When the presenter's key is a symmetric key, the "jwe" member is an encrypted JSON Web Key [JWK]. It's encrypted to a key the recipient already knows, using the JWE Compact Serialization that contains the symmetric key 🧚. The rules for encrypting a JWK live in Section 7 of the JSON Web Key [JWK] specification 🎀.
This is a symmetric key that could later get encrypted for the "jwe" member:
{
"kty": "oct",
"alg": "HS256",
"k": "ZoRSOrFzN_FzUA5XKMYoVHyzff5oRJxl-IXRtztJ6uE"
}The UTF-8 [RFC3629] encoding of this JWK is what gets used as the JWE Plaintext when encrypting the key 💅.
Here's a JWE Header that could be used when encrypting this key:
{
"alg": "RSA-OAEP",
"enc": "A128CBC-HS256"
}And this JWT Claims Set shows an encrypted symmetric key as the "jwe" member value 🌈:
{
"iss": "https://server.example.com",
"sub": "24400320",
"aud": "s6BhdRkqt3",
"nonce": "n-0S6_WzA2Mj",
"exp": 1311281970,
"iat": 1311280970,
"cnf":{
"jwe":
"eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ.
(remainder of JWE omitted for brevity)"
}
}3.4. Representation of a Key ID for a Proof-of-Possession Key
Sometimes you don't have to send the actual key at all 🙌. The proof-of-possession key can be identified with a Key ID instead, as long as the recipient can get the identified key using that Key ID 🔑. In this case, the issuer declares that the presenter possesses a particular key, and the recipient can cryptographically confirm that proof by the presenter. The issuer does this by including a "cnf" claim in the JWT whose value is a JSON object, and that object contains a "kid" member identifying the key 💖.
Here's what that declaration looks like in the JWT Claims Set:
{
"iss": "https://server.example.com",
"aud": "https://client.example.org",
"exp": 1361398824,
"cnf":{
"kid": "dfd1aa97-6d8d-4575-a0fe-34b96de2bfad"
}
}What goes in the "kid" value is app-specific 🦋. For example, some apps may choose to use a JWK Thumbprint [JWK.Thumbprint] value as the "kid" value 🍓.
3.5. Representation of a URL for a Proof-of-Possession Key
The proof-of-possession key can be passed by reference instead of by value 🌸. You do that with the "jku" member. Its value is a URI [RFC3986] pointing to a resource with a set of JSON-encoded public keys, shown as a JWK Set [JWK], and one of those keys is the proof-of-possession key 🗂️. If the referenced JWK Set document has multiple keys, a "kid" member MUST also be included, and the referenced key's JWK also has to contain that same "kid" value 🔥.
The protocol used to get that resource MUST provide integrity protection 🔐. An HTTP GET request to retrieve the JWK Set MUST use TLS [RFC5246], and the identity of the server MUST be validated, as per Section 6 of RFC 6125 [RFC6125] 🫶.
Here's an example of that declaration in a JWT Claims Set:
{
"iss": "https://server.example.com",
"sub": "17760704",
"aud": "https://client.example.org",
"exp": 1440804813,
"cnf":{
"jku": "https://keys.example.net/pop-keys.json",
"kid": "2015-08-28"
}
}3.6. Specifics Intentionally Not Specified
Proof of possession usually works like this: the presenter signs a value the recipient picked, using the key the presenter holds 🧚. That value is sometimes called a "nonce" or a "challenge" 💜.
How the nonce gets communicated, and what its contents look like, are intentionally not described in this spec 🙈. Different protocols will pass that info around in different ways. The same goes for how the signed nonce gets sent back, since that's protocol specific too 🌈.
Also, if the key is symmetric, another way to prove possession is to encrypt the key to the recipient 🔐. How the recipient's key gets obtained is also protocol specific 🎀.
If you want examples using the mechanisms in this specification, check out [OAUTH-POP-ARCH] 👑.
4. Security Considerations 🔐
Okay this section is SO important, bestie, so read it closely 😭. Everything discussed in [JWT] about security applies here too. On top of that, proof of possession brings its own unique security issues 💀. Having a key is only valuable if it stays secret. You have to use appropriate means to make sure unintended parties never learn private key or symmetric key values 🫢.
Apps using proof of possession should also use audience restriction, as described in Section 4.1.3 of [JWT], because the two give you different protections 🛡️. Proof of possession lets recipients reject messages from unauthorized senders. Audience restriction lets recipients reject messages meant for different recipients ✨.
A recipient might not understand the "cnf" claim 🙈. Apps that need the proof-of-possession keys communicated to them to be understood and processed must make sure they implement the parts of this specification they use 💅.
Proof of possession via encrypted symmetric secrets is open to replay attacks 😱. You can avoid this, for example, by using a signed nonce or challenge, since the recipient can use a distinct nonce or challenge for each interaction. Replay can also be avoided if a sub-key gets derived from a shared secret that's specific to the instance of the PoP demonstration 🦋.
As with any other info in a JWT, you need data origin authentication and integrity protection (through a keyed message digest or a digital signature) 🔒. Data origin authentication makes sure the recipient learns who created the JWT, which matters a lot for policy decisions 👑. Integrity protection stops an adversary from changing any elements carried in the JWT payload 🛡️. Be extra careful when you carry symmetric keys inside the JWT, because those need integrity protection AND confidentiality protection 😭.
5. Privacy Considerations 🙈
A proof-of-possession key can work as a correlation handle if the same key gets used with multiple parties 👀. So for privacy reasons, it is recommended that different proof-of-possession keys be used when interacting with different parties 🫶💜
6. IANA Considerations ✨
okay so the registration process is the same for every registry this spec sets up 📋 bestie, it's giving consistency 💅
Values get registered on a Specification Required [RFC5226] basis 🦋. That means there's a three-week review period on the jwt-reg-review@ietf.org mailing list, and one or more Designated Experts give advice on it. BUT 👀 so values can be allocated before publication, the Designated Experts are allowed to approve a registration once they're satisfied the specification will get published.
Registration requests sent to that list should use a clear subject, like "Request to Register JWT Confirmation Method: example" 🎀. If a request is still undecided after 21 days, it can be brought to the IESG's attention through iesg@ietf.org for resolution 🫶
The Designated Experts should weigh a few things. They check whether the proposed registration duplicates functionality that already exists, whether it's likely to be generally useful or only useful for a single application, and the security properties of the item being registered, plus whether the registration actually makes sense 🧐
It's suggested that several Designated Experts get appointed, and that they represent the different applications using this specification 🌈 That way the review is broadly informed. If a registration decision could look like a conflict of interest for a particular Expert, that Expert should defer to the judgment of the other Experts 🙈
6.1. JSON Web Token Claims Registration
This spec registers the "cnf" claim in the IANA "JSON Web Token Claims" registry [IANA.JWT.Claims], which was established by [JWT] 🍓
6.1.1. Registry Contents
o Claim Name: "cnf"
o Claim Description: Confirmation
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [RFC7800]6.2. JWT Confirmation Methods Registry
This spec sets up the IANA "JWT Confirmation Methods" registry for JWT "cnf" member values 🌸 The registry records the confirmation method member, plus a reference to the specification that defines it.
6.2.1. Registration Template
Here's what each field needs, bestie 📝
- Confirmation Method Value: the name being requested, like
"kid". A core goal here is for the resulting representations to be compact, so it is RECOMMENDED that the name be short, not going over eight characters unless there's a compelling reason. The name is case sensitive. Names may not match other registered names in a case-insensitive manner, unless the Designated Experts state there's a compelling reason to allow an exception 💅 - Confirmation Method Description: a brief description of the confirmation method, like "Key Identifier" 🔑
- Change Controller: for Standards Track RFCs, list "IESG". For everything else, give the name of the responsible party. Other details, like a postal address, email address, or home page URI, may also be included 🦋
- Specification Document(s): a reference to the document or documents that specify the parameter, ideally with URIs where copies can be retrieved. Indicating the relevant sections may also be included, but it isn't required ✨
6.2.2. Initial Registry Contents
Here are the starter entries, all set up and ready to go 🎀
o Confirmation Method Value: "jwk"
o Confirmation Method Description: JSON Web Key Representing Public
Key
o Change Controller: IESG
o Specification Document(s): Section 3.2 of [RFC7800]
o Confirmation Method Value: "jwe"
o Confirmation Method Description: Encrypted JSON Web Key
o Change Controller: IESG
o Specification Document(s): Section 3.3 of [RFC7800]
o Confirmation Method Value: "kid"
o Confirmation Method Description: Key Identifier
o Change Controller: IESG
o Specification Document(s): Section 3.4 of [RFC7800]
o Confirmation Method Value: "jku"
o Confirmation Method Description: JWK Set URL
o Change Controller: IESG
o Specification Document(s): Section 3.5 of [RFC7800]7. References 📚
7.1. Normative References
These are the must-read ones, the foundation of the whole spec 🧠
[IANA.JWT.Claims]
IANA, "JSON Web Token Claims",
<http://www.iana.org/assignments/jwt>.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, DOI 10.17487/RFC7156, May 2015,
<http://www.rfc-editor.org/info/rfc7516>.
[JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7157, May 2015,
<http://www.rfc-editor.org/info/rfc7517>.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7159, May 2015,
<http://www.rfc-editor.org/info/rfc7519>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <http://www.rfc-editor.org/info/rfc3629>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March
2011, <http://www.rfc-editor.org/info/rfc6125>.7.2. Informative References
These are the extra-credit reads, super helpful but not required 🌈
[JWK.Thumbprint]
Jones, M. and N. Sakimura, "JSON Web Key (JWK)
Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September
2015, <http://www.rfc-editor.org/info/rfc7638>.
[OASIS.saml-core-2.0-os]
Cantor, S., Kemp, J., Philpott, R., and E. Maler,
"Assertions and Protocol for the OASIS Security Assertion
Markup Language (SAML) V2.0", OASIS Standard saml-core-
2.0-os, March 2005,
<http://docs.oasis-open.org/security/saml/v2.0/>.
[OAUTH-POP-ARCH]
Hunt, P., Ed, Richer, J., Mills, W., Mishra, P., and H.
Tschofenig, "OAuth 2.0 Proof-of-Possession (PoP) Security
Architecture", Work in Progress, draft-ietf-oauth-pop-
architecture-07, December 2015.
[OpenID.Core]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
C. Mortimore, "OpenID Connect Core 1.0", November 2014,
<http://openid.net/specs/openid-connect-core-1_0.html>.Acknowledgements 🫶
The authors want to thank Brian Campbell, Stephen Farrell, Barry Leiba, Kepeng Li, Chris Lonvick, James Manger, Kathleen Moriarty, Justin Richer, and Nat Sakimura for reviewing the specification 💖 The squad really showed up for this one, periodt 👑
Authors' Addresses 🌸
Michael B. Jones
Microsoft
Email: mbj@microsoft.com
URI: http://self-issued.info/
John Bradley
Ping Identity
Email: ve7jtb@ve7jtb.com
URI: http://www.thread-safe.com/
Hannes Tschofenig
ARM Limited
Austria
Email: Hannes.Tschofenig@gmx.net
URI: http://www.tschofenig.priv.at📦 where this page comes from
- ietf: rfc7800 2016-04
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms