idnits 2.17.1 draft-hardt-gnap-jose-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (15 August 2020) is 1349 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) -- Possible downref: Non-RFC (?) normative reference: ref. 'GNAP' Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Hardt, Ed. 3 Internet-Draft SignIn.Org 4 Intended status: Standards Track 15 August 2020 5 Expires: 16 February 2021 7 JOSE Authentication 8 draft-hardt-gnap-jose-02 10 Abstract 12 TBD 14 Status of This Memo 16 This Internet-Draft is submitted in full conformance with the 17 provisions of BCP 78 and BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF). Note that other groups may also distribute 21 working documents as Internet-Drafts. The list of current Internet- 22 Drafts is at https://datatracker.ietf.org/drafts/current/. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 This Internet-Draft will expire on 16 February 2021. 31 Copyright Notice 33 Copyright (c) 2020 IETF Trust and the persons identified as the 34 document authors. All rights reserved. 36 This document is subject to BCP 78 and the IETF Trust's Legal 37 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 38 license-info) in effect on the date of publication of this document. 39 Please review these documents carefully, as they describe your rights 40 and restrictions with respect to this document. Code Components 41 extracted from this document must include Simplified BSD License text 42 as described in Section 4.e of the Trust Legal Provisions and are 43 provided without warranty as described in the Simplified BSD License. 45 Table of Contents 47 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 48 2. JOSE Authentication . . . . . . . . . . . . . . . . . . . . . 3 49 2.1. Grant Server Access . . . . . . . . . . . . . . . . . . . 4 50 2.1.1. Authorization Header . . . . . . . . . . . . . . . . 4 51 2.1.2. Signed Body . . . . . . . . . . . . . . . . . . . . . 5 52 2.1.3. Public Key Resolution . . . . . . . . . . . . . . . . 6 53 2.2. Resource Server Access . . . . . . . . . . . . . . . . . 7 54 2.2.1. JOSE header . . . . . . . . . . . . . . . . . . . . . 7 55 2.2.2. "jose" Mechanism . . . . . . . . . . . . . . . . . . 7 56 2.2.3. "jose+body" Mechanism . . . . . . . . . . . . . . . . 8 57 2.2.4. Public Key Resolution . . . . . . . . . . . . . . . . 9 58 2.3. Request Encryption . . . . . . . . . . . . . . . . . . . 9 59 2.4. Response Signing . . . . . . . . . . . . . . . . . . . . 9 60 2.5. Response Encryption . . . . . . . . . . . . . . . . . . . 10 61 3. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 62 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 63 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 64 6. Normative References . . . . . . . . . . . . . . . . . . . . 10 65 Appendix A. Document History . . . . . . . . . . . . . . . . . . 11 66 A.1. draft-hardt-gnap-jose-00 . . . . . . . . . . . . . . . . 11 67 A.2. draft-hardt-gnap-jose-01 . . . . . . . . . . . . . . . . 11 68 A.3. draft-hardt-gnap-jose-02 . . . . . . . . . . . . . . . . 11 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 71 1. Introduction 73 TBD 75 *Terminology* 77 This document uses the following terms defined in [GNAP]: 79 * Grant Client (GC) 81 * Client Handle 83 * Registered Client 85 * Dynamic Client 87 * Grant 89 * Grant Server (GS) 91 * GS URI 93 * NumericDate 95 * Resource Server (RS) 96 *Notational Conventions* 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 100 specification are to be interpreted as described in [RFC2119]. 102 Certain security-related terms are to be understood in the sense 103 defined in [RFC4949]. These terms include, but are not limited to, 104 "attack", "authentication", "authorization", "certificate", 105 "confidentiality", "credential", "encryption", "identity", "sign", 106 "signature", "trust", "validate", and "verify". 108 Unless otherwise noted, all the protocol parameter names and values 109 are case sensitive. 111 2. JOSE Authentication 113 How the GC authenticates to the GS and RS are independent of each 114 other. One mechanism can be used to authenticate to the GS, and a 115 different mechanism to authenticate to the RS. 117 Other documents that specify other GC authentication mechanisms will 118 replace this section. 120 In the JOSE Authentication Mechanism, the GC authenticates by using 121 its private key to sign a JSON document with JWS per [RFC7515] which 122 results in a token using JOSE compact serialization. 124 [Editor: are there advantages to using JSON serialization in the 125 body?] 127 Different instances of a Registered GC MAY have different private 128 keys, but each instance has a certificate to bind its private key to 129 to a public key the GS has for the Client ID. An instance of a GC 130 will use the same private key for all signing operations. 132 The GC and the GS MUST both use HTTP/2 ([RFC7540]) or later, and TLS 133 1.3 ([RFC8446]) or later, when communicating with each other. 135 [Editor: too aggressive to mandate HTTP/2 and TLS 1.3?] 137 The token may be included in an HTTP header, or as the HTTP message 138 body. 140 The following sections specify how the GC uses JOSE to authenticate 141 to the GS and RS. 143 2.1. Grant Server Access 145 The GC authenticates to the GS by passing either a signed header 146 parameter, or a signed message body. The following table shows the 147 method, uri and token location for each GC request to the GS: 149 +===============+=============+===========+==========+ 150 | request | http method | uri | token in | 151 +===============+=============+===========+==========+ 152 | Create Grant | POST | GS URI | body | 153 +---------------+-------------+-----------+----------+ 154 | Verify Grant | PATCH | Grant URI | body | 155 +---------------+-------------+-----------+----------+ 156 | Read Grant | GET | Grant URI | header | 157 +---------------+-------------+-----------+----------+ 158 | Update Grant | PUT | Grant URI | body | 159 +---------------+-------------+-----------+----------+ 160 | Delete Grant | DELETE | Grant URI | header | 161 +---------------+-------------+-----------+----------+ 162 | Read AuthZ | GET | AZ URI | header | 163 +---------------+-------------+-----------+----------+ 164 | Update AuthZ | PUT | AZ URI | body | 165 +---------------+-------------+-----------+----------+ 166 | Delete AuthZ | DELETE | AZ URI | header | 167 +---------------+-------------+-----------+----------+ 168 | GS Options | OPTIONS | GS URI | header | 169 +---------------+-------------+-----------+----------+ 170 | Grant Options | OPTIONS | Grant URI | header | 171 +---------------+-------------+-----------+----------+ 172 | AuthZ Options | OPTIONS | AZ URI | header | 173 +---------------+-------------+-----------+----------+ 175 Table 1 177 2.1.1. Authorization Header 179 For requests with the token in the header, the JWS payload MUST 180 contain the following attributes: 182 *iat* - the time the token was created as a NumericDate. 184 *jti* - a unique identifier for the token per [RFC7519] section 185 4.1.7. 187 *uri* - the value of the URI being called (GS URI, Grant URI, or AZ 188 URI). 190 *method* - the HTTP method being used in the call ("GET", "DELETE", 191 "OPTIONS") 193 The HTTP authorization header is set to the "jose" parameter followed 194 by one or more white space characters, followed by the resulting 195 token. 197 A non-normative example of a JWS payload and the HTTP request 198 follows: 200 { 201 "iat" : 15790460234, 202 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 203 "uri" : "https://as.example/endpoint/grant/example6", 204 "method" : "GET" 205 } 207 GET /endpoint/example.grant HTTP/2 208 Host: as.example 209 Authorization: jose eyJhbGciOiJIUzI1NiIsIn ... 211 [Editor: make a real example token] 213 *GS Verification* 215 The GS MUST verify the token by: 217 * TBD 219 2.1.2. Signed Body 221 For requests with the token in the body, the GC uses the Request JSON 222 as the payload in a JWS. The resulting token is sent with the 223 content-type set to "application/jose". 225 A non-normative example (line breaks added to the body for 226 readability): 228 POST /endpoint HTTP/2 229 Host: as.example 230 Content-Type: application/jose 231 Content-Length: 155 233 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF 234 tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe 235 Jf36POk6yJV_adQssw5c 237 [Editor: make a real example token] 238 *GS Verification* 240 The GS MUST verify the token by: 242 * TBD 244 2.1.3. Public Key Resolution 246 * *Registered Clients* MAY use any of the JWS header values to 247 direct the GS to resolve the public key matching the private key 248 linked to the Client ID. The GS MAY restrict which JWS headers a 249 GC can use. 251 [Editor: would examples help here so that implementors understand the 252 full range of options, and how an instance can have its own asymetric 253 key pair] 255 A non-normative example of a JOSE header for a Registered Client with 256 a key identifier of "12": 258 { 259 "alg" : "ES256", 260 "typ" : "JOSE", 261 "kid" : "12" 262 } 264 * *Dynamic Clients* MUST include their public key in the "jwk" JWS 265 header in a GNAP Create Grant request, unless they have a Client 266 Handle and include it in the GNAP Request JSON "client" object. 268 A non-normative example of a JOSE header for a Dynamic Client: 270 { 271 "alg" : "ES256", 272 "typ" : "JOSE", 273 "jwk" : { 274 "kty" : "EC", 275 "crv" : "P-256", 276 "x" : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4", 277 "y" : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4" 278 } 279 } 281 2.2. Resource Server Access 283 In the "jose" mechanism Section 2.2.2, all GC requests to the RS 284 include a proof-of-possession token in the HTTP authorization header. 285 In the "jose+body" mechanism Section 2.2.3, the GC signs the JSON 286 document in the request if the POST or PUT methods are used, 287 otherwise it is the same as the "jose" mechanism. 289 2.2.1. JOSE header 291 The GS provides the GC one or more JWS header parameters and values 292 for a a certificate, or a reference to a certificate or certificate 293 chain, that the RS can use to resolve the public key matching the 294 private key being used by the GC. 296 A non-normative examples JOSE header: 298 { 299 "alg" : "ES256", 300 "typ" : "JOSE", 301 "x5u" : "https://as.example/cert/example2" 302 } 304 [Editor: this enables Dynamic Clients to make proof-of-possession API 305 calls the same as Registered Clients.] 307 2.2.2. "jose" Mechanism 309 The JWS payload MUST contain the following attributes: 311 *iat* - the time the token was created as a NumericDate. 313 *jti* - a unique identifier for the token per [RFC7519] section 314 4.1.7. 316 *uri* - the value of the RS URI being called. 318 *method* - the HTTP method being used in the call 320 *token* - the access token provided by the GS to the GC 322 The HTTP authorization header is set to the "jose" parameter followed 323 by one or more white space characters, followed by the resulting 324 token. 326 A non-normative example of a JWS payload and the HTTP request 327 follows: 329 { 330 "iat" : 15790460234, 331 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 332 "uri" : "https://calendar.example/calendar", 333 "method" : "GET", 334 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA" 335 } 337 GET /calendar HTTP/2 338 Host: calendar.example 339 Authorization: jose eyJhbG.example.jose.token.adks 341 [Editor: make a real example token] 343 *RS Verification* 345 The RS MUST verify the token by: 347 * verify access token is bound to the public key - include key 348 fingerprint in access token? 350 * TBD 352 2.2.3. "jose+body" Mechanism 354 The "jose+body" mechanism can only be used if the content being sent 355 to the RS is a JSON document. 357 Any requests not sending a message body will use the "jose" mechanism 358 Section 2.2.2. 360 Requests sending a message body MUST have the following JWS payload: 362 *iat* - the time the token was created as a NumericDate. 364 *jti* - a unique identifier for the token per [RFC7519] section 365 4.1.7. 367 *uri* - the value of the RS URI being called. 369 *method* - the HTTP method being used in the call 371 *token* - the access token provided by the GS to the GC 373 *body* - the message body being sent to the RS 375 A non-normative example of a JWS payload and the HTTP request 376 follows: 378 { 379 "iat" : 15790460234, 380 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 381 "uri" : "https://calendar.example/calendar", 382 "method": "POST", 383 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA", 384 "payload" : { 385 "event" : { 386 "title" : "meeting with joe", 387 "start_date_utc" : "2020-02-21 11:00:00", 388 "end_date_utc" : "2020-02-21 11:00:00" 389 } 390 } 391 } 393 POST /calendar HTTP/2 394 Host: calendar.example 395 Content-Type: application/jose 396 Content-Length: 155 398 eyJhbGciOi.example.jose+body.adasdQssw5c 400 [Editor: make a real example token] 402 *RS Verification* 404 The RS MUST verify the token by: 406 * TBD 408 2.2.4. Public Key Resolution 410 The RS has a public key for the GS that it uses to verify the 411 certificate or certificate chain the GC includes in the JWS header. 413 2.3. Request Encryption 415 [Editor: to be fleshed out] 417 The GC encrypts a request when ??? using the GS public key returned 418 as the ??? attribute in GS Options. 420 2.4. Response Signing 422 [Editor: to be fleshed out] 424 The GC verifies a signed response ??? using the GS public key 425 returned as the ??? attribute in GS Options. 427 2.5. Response Encryption 429 [Editor: to be fleshed out] 431 The GC decrypts a response when ??? using the private key matching 432 the public key included in the request as the ??? attribute in [GNAP] 433 Grant Request JSON. 435 3. Acknowledgments 437 TBD 439 4. IANA Considerations 441 TBD 443 5. Security Considerations 445 TBD 447 6. Normative References 449 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 450 Requirement Levels", BCP 14, RFC 2119, 451 DOI 10.17487/RFC2119, March 1997, 452 . 454 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 455 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 456 . 458 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 459 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 460 2015, . 462 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 463 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 464 . 466 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 467 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 468 DOI 10.17487/RFC7540, May 2015, 469 . 471 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 472 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 473 . 475 [GNAP] Hardt, D., "The Grant Negotiation and Authorization 476 Protocol", June 2020, 477 . 479 Appendix A. Document History 481 A.1. draft-hardt-gnap-jose-00 483 * Initial version 485 A.2. draft-hardt-gnap-jose-01 487 * renamed HTTP verb to method 489 A.3. draft-hardt-gnap-jose-02 491 * renamed Client to Grant Client (GC) 493 Author's Address 495 Dick Hardt (editor) 496 SignIn.Org 497 United States 499 Email: dick.hardt@gmail.com