idnits 2.17.1 draft-hardt-gnap-jose-01.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 (4 July 2020) is 1364 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) == Unused Reference: 'RFC3966' is defined on line 455, but no explicit reference was found in the text == Unused Reference: 'RFC5322' is defined on line 459, but no explicit reference was found in the text == Unused Reference: 'RFC7516' is defined on line 471, but no explicit reference was found in the text ** 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 (~~), 5 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 4 July 2020 5 Expires: 5 January 2021 7 JOSE Authentication 8 draft-hardt-gnap-jose-01 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 5 January 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 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 70 1. Introduction 72 TBD 74 *Terminology* 76 This document uses the following terms defined in [GNAP]: 78 * Authorization URI (AZ URI) 80 * Client 82 * Client Handle 84 * Registered Client 86 * Dynamic Client 88 * Grant 90 * Grant Server (GS) 92 * GS URI 94 * NumericDate 96 * Resource Server (RS) 97 *Notational Conventions* 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 101 specification are to be interpreted as described in [RFC2119]. 103 Certain security-related terms are to be understood in the sense 104 defined in [RFC4949]. These terms include, but are not limited to, 105 "attack", "authentication", "authorization", "certificate", 106 "confidentiality", "credential", "encryption", "identity", "sign", 107 "signature", "trust", "validate", and "verify". 109 Unless otherwise noted, all the protocol parameter names and values 110 are case sensitive. 112 2. JOSE Authentication 114 How the Client authenticates to the GS and RS are independent of each 115 other. One mechanism can be used to authenticate to the GS, and a 116 different mechanism to authenticate to the RS. 118 Other documents that specify other Client authentication mechanisms 119 will replace this section. 121 In the JOSE Authentication Mechanism, the Client authenticates by 122 using its private key to sign a JSON document with JWS per [RFC7515] 123 which results in a token using JOSE compact serialization. 125 [Editor: are there advantages to using JSON serialization in the 126 body?] 128 Different instances of a Registered Client MAY have different private 129 keys, but each instance has a certificate to bind its private key to 130 to a public key the GS has for the Client ID. An instance of a 131 Client will use the same private key for all signing operations. 133 The Client and the GS MUST both use HTTP/2 ([RFC7540]) or later, and 134 TLS 1.3 ([RFC8446]) or later, when communicating with each other. 136 [Editor: too aggressive to mandate HTTP/2 and TLS 1.3?] 138 The token may be included in an HTTP header, or as the HTTP message 139 body. 141 The following sections specify how the Client uses JOSE to 142 authenticate to the GS and RS. 144 2.1. Grant Server Access 146 The Client authenticates to the GS by passing either a signed header 147 parameter, or a signed message body. The following table shows the 148 method, uri and token location for each Client request to the GS: 150 +===============+=============+===========+==========+ 151 | request | http method | uri | token in | 152 +===============+=============+===========+==========+ 153 | Create Grant | POST | GS URI | body | 154 +---------------+-------------+-----------+----------+ 155 | Verify Grant | PATCH | Grant URI | body | 156 +---------------+-------------+-----------+----------+ 157 | Read Grant | GET | Grant URI | header | 158 +---------------+-------------+-----------+----------+ 159 | Update Grant | PUT | Grant URI | body | 160 +---------------+-------------+-----------+----------+ 161 | Delete Grant | DELETE | Grant URI | header | 162 +---------------+-------------+-----------+----------+ 163 | Read AuthZ | GET | AZ URI | header | 164 +---------------+-------------+-----------+----------+ 165 | Update AuthZ | PUT | AZ URI | body | 166 +---------------+-------------+-----------+----------+ 167 | Delete AuthZ | DELETE | AZ URI | header | 168 +---------------+-------------+-----------+----------+ 169 | GS Options | OPTIONS | GS URI | header | 170 +---------------+-------------+-----------+----------+ 171 | Grant Options | OPTIONS | Grant URI | header | 172 +---------------+-------------+-----------+----------+ 173 | AuthZ Options | OPTIONS | AZ URI | header | 174 +---------------+-------------+-----------+----------+ 176 Table 1 178 2.1.1. Authorization Header 180 For requests with the token in the header, the JWS payload MUST 181 contain the following attributes: 183 *iat* - the time the token was created as a NumericDate. 185 *jti* - a unique identifier for the token per [RFC7519] section 186 4.1.7. 188 *uri* - the value of the URI being called (GS URI, Grant URI, or AZ 189 URI). 191 *method* - the HTTP method being used in the call ("GET", "DELETE", 192 "OPTIONS") 194 The HTTP authorization header is set to the "jose" parameter followed 195 by one or more white space characters, followed by the resulting 196 token. 198 A non-normative example of a JWS payload and the HTTP request 199 follows: 201 { 202 "iat" : 15790460234, 203 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 204 "uri" : "https://as.example/endpoint/grant/example6", 205 "method" : "GET" 206 } 208 GET /endpoint/example.grant HTTP/2 209 Host: as.example 210 Authorization: jose eyJhbGciOiJIUzI1NiIsIn ... 212 [Editor: make a real example token] 214 *GS Verification* 216 The GS MUST verify the token by: 218 * TBD 220 2.1.2. Signed Body 222 For requests with the token in the body, the Client uses the Request 223 JSON as the payload in a JWS. The resulting token is sent with the 224 content-type set to "application/jose". 226 A non-normative example (line breaks added to the body for 227 readability): 229 POST /endpoint HTTP/2 230 Host: as.example 231 Content-Type: application/jose 232 Content-Length: 155 234 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyzdWIiOiIxMjM0NTY3ODkwIiwibmF 235 tZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMe 236 Jf36POk6yJV_adQssw5c 238 [Editor: make a real example token] 239 *GS Verification* 241 The GS MUST verify the token by: 243 * TBD 245 2.1.3. Public Key Resolution 247 * *Registered Clients* MAY use any of the JWS header values to 248 direct the GS to resolve the public key matching the private key 249 linked to the Client ID. The GS MAY restrict which JWS headers a 250 Client can use. 252 [Editor: would examples help here so that implementors understand the 253 full range of options, and how an instance can have its own asymetric 254 key pair] 256 A non-normative example of a JOSE header for a Registered Client with 257 a key identifier of "12": 259 { 260 "alg" : "ES256", 261 "typ" : "JOSE", 262 "kid" : "12" 263 } 265 * *Dynamic Clients* MUST include their public key in the "jwk" JWS 266 header in a GNAP Create Grant request, unless they have a Client 267 Handle and include it in the GNAP Request JSON "client" object. 269 A non-normative example of a JOSE header for a Dynamic Client: 271 { 272 "alg" : "ES256", 273 "typ" : "JOSE", 274 "jwk" : { 275 "kty" : "EC", 276 "crv" : "P-256", 277 "x" : "Kgl5DJSgLyV-G32osmLhFKxJ97FoMW0dZVEqDG-Cwo4", 278 "y" : "GsL4mOM4x2e6iON8BHvRDQ6AgXAPnw0m0SfdlREV7i4" 279 } 280 } 282 2.2. Resource Server Access 284 In the "jose" mechanism Section 2.2.2, all Client requests to the RS 285 include a proof-of-possession token in the HTTP authorization header. 286 In the "jose+body" mechanism Section 2.2.3, the Client signs the JSON 287 document in the request if the POST or PUT methods are used, 288 otherwise it is the same as the "jose" mechanism. 290 2.2.1. JOSE header 292 The GS provides the Client one or more JWS header parameters and 293 values for a a certificate, or a reference to a certificate or 294 certificate chain, that the RS can use to resolve the public key 295 matching the private key being used by the Client. 297 A non-normative examples JOSE header: 299 { 300 "alg" : "ES256", 301 "typ" : "JOSE", 302 "x5u" : "https://as.example/cert/example2" 303 } 305 [Editor: this enables Dynamic Clients to make proof-of-possession API 306 calls the same as Registered Clients.] 308 2.2.2. "jose" Mechanism 310 The JWS payload MUST contain the following attributes: 312 *iat* - the time the token was created as a NumericDate. 314 *jti* - a unique identifier for the token per [RFC7519] section 315 4.1.7. 317 *uri* - the value of the RS URI being called. 319 *method* - the HTTP method being used in the call 321 *token* - the access token provided by the GS to the Client 323 The HTTP authorization header is set to the "jose" parameter followed 324 by one or more white space characters, followed by the resulting 325 token. 327 A non-normative example of a JWS payload and the HTTP request 328 follows: 330 { 331 "iat" : 15790460234, 332 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 333 "uri" : "https://calendar.example/calendar", 334 "method" : "GET", 335 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA" 336 } 338 GET /calendar HTTP/2 339 Host: calendar.example 340 Authorization: jose eyJhbG.example.jose.token.adks 342 [Editor: make a real example token] 344 *RS Verification* 346 The RS MUST verify the token by: 348 * verify access token is bound to the public key - include key 349 fingerprint in access token? 351 * TBD 353 2.2.3. "jose+body" Mechanism 355 The "jose+body" mechanism can only be used if the content being sent 356 to the RS is a JSON document. 358 Any requests not sending a message body will use the "jose" mechanism 359 Section 2.2.2. 361 Requests sending a message body MUST have the following JWS payload: 363 *iat* - the time the token was created as a NumericDate. 365 *jti* - a unique identifier for the token per [RFC7519] section 366 4.1.7. 368 *uri* - the value of the RS URI being called. 370 *method* - the HTTP method being used in the call 372 *token* - the access token provided by the GS to the Client 374 *body* - the message body being sent to the RS 376 A non-normative example of a JWS payload and the HTTP request 377 follows: 379 { 380 "iat" : 15790460234, 381 "jti" : "f6d72254-4f23-417f-b55e-14ad323b1dc1", 382 "uri" : "https://calendar.example/calendar", 383 "method": "POST", 384 "token" : "eyJJ2D6.example.access.token.mZf9pTSpA", 385 "payload" : { 386 "event" : { 387 "title" : "meeting with joe", 388 "start_date_utc" : "2020-02-21 11:00:00", 389 "end_date_utc" : "2020-02-21 11:00:00" 390 } 391 } 392 } 394 POST /calendar HTTP/2 395 Host: calendar.example 396 Content-Type: application/jose 397 Content-Length: 155 399 eyJhbGciOi.example.jose+body.adasdQssw5c 401 [Editor: make a real example token] 403 *RS Verification* 405 The RS MUST verify the token by: 407 * TBD 409 2.2.4. Public Key Resolution 411 The RS has a public key for the GS that it uses to verify the 412 certificate or certificate chain the Client includes in the JWS 413 header. 415 2.3. Request Encryption 417 [Editor: to be fleshed out] 419 The Client encrypts a request when ??? using the GS public key 420 returned as the ??? attribute in GS Options. 422 2.4. Response Signing 424 [Editor: to be fleshed out] 425 The Client verifies a signed response ??? using the GS public key 426 returned as the ??? attribute in GS Options. 428 2.5. Response Encryption 430 [Editor: to be fleshed out] 432 The Client decrypts a response when ??? using the private key 433 matching the public key included in the request as the ??? attribute 434 in [GNAP] Grant Request JSON. 436 3. Acknowledgments 438 TBD 440 4. IANA Considerations 442 TBD 444 5. Security Considerations 446 TBD 448 6. Normative References 450 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 451 Requirement Levels", BCP 14, RFC 2119, 452 DOI 10.17487/RFC2119, March 1997, 453 . 455 [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", 456 RFC 3966, DOI 10.17487/RFC3966, December 2004, 457 . 459 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 460 DOI 10.17487/RFC5322, October 2008, 461 . 463 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 464 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 465 . 467 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 468 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 469 2015, . 471 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 472 RFC 7516, DOI 10.17487/RFC7516, May 2015, 473 . 475 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 476 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 477 . 479 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 480 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 481 DOI 10.17487/RFC7540, May 2015, 482 . 484 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 485 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 486 . 488 [GNAP] Hardt, D., "The Grant Negotiation and Authorization 489 Protocol", June 2020, 490 . 492 Appendix A. Document History 494 A.1. draft-hardt-gnap-jose-00 496 * Initial version 498 A.2. draft-hardt-gnap-jose-01 500 * renamed HTTP verb to method 502 Author's Address 504 Dick Hardt (editor) 505 SignIn.Org 506 United States 508 Email: dick.hardt@gmail.com