idnits 2.17.1 draft-ietf-httpauth-rest-auth-00.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 date (August 14, 2013) is 3905 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC6631' is defined on line 889, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 3 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 N. Williams 3 Internet-Draft Cryptonector 4 Intended status: Informational August 14, 2013 5 Expires: February 15, 2014 7 RESTful Authentication Pattern for the Hypertext Transport Protocol 8 (HTTP) 9 draft-ietf-httpauth-rest-auth-00 11 Abstract 13 This document proposes a "RESTful" pattern of authentication for 14 HTTP/1.0, 1.1, and 2.0. The goal is to make it easy to add 15 authentication mechanisms to HTTP and to make it easy to implement 16 them even without much help from the HTTP stack (though it is best to 17 integrate authentication into the stack, of course). 19 Among other benefits of RESTauth: it is orthogonal to "HTTP routers" 20 and proxies, it results in session Uniform Resource Identifiers 21 (URIs) that can be DELETEd to logout, naturally supports multi-legged 22 authentication schemes, and it can be universally implemented on the 23 server side with the Common Gateway Interface (CGI) and FastCGI. 25 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on February 15, 2014. 42 Copyright Notice 44 Copyright (c) 2013 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 60 1.1. Protocol Outline . . . . . . . . . . . . . . . . . . . . . 4 61 1.2. API-Imposed Constraints . . . . . . . . . . . . . . . . . 5 62 2. Conventions used in this document . . . . . . . . . . . . 7 63 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 3.1. Negotiable Parameters . . . . . . . . . . . . . . . . . . 8 65 3.1.1. Strong Binding to TLS . . . . . . . . . . . . . . . . . . 9 66 3.1.2. WWW-Authenticate Header Value Prefix Syntax . . . . . . . 9 67 3.1.3. WWW-ChannelBinding-Types Header . . . . . . . . . . . . . 10 68 3.1.4. WWW-ChannelBinding-Type Header . . . . . . . . . . . . . . 10 69 3.1.5. WWW-SessionBinding-Type Header . . . . . . . . . . . . . . 10 70 3.1.6. WWW-ReplayProtection Header . . . . . . . . . . . . . . . 10 71 3.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 10 72 3.2.1. One Round Trip Optimization: Challenges Borne in 73 WWW-Authenticate Headers . . . . . . . . . . . . . . . . . 11 74 3.3. Session Binding Types: Cookie, Session URI, and MAC . . . 12 75 3.3.1. The New WWW-Session-URI Header . . . . . . . . . . . . . . 12 76 3.3.2. The New WWW-Session-MAC Header . . . . . . . . . . . . . . 12 77 3.3.3. A MAC Trailer?? . . . . . . . . . . . . . . . . . . . . . 13 78 4. Representation of Authenticated Session Resources . . . . 14 79 5. HTTP "Routing" and Authentication . . . . . . . . . . . . 15 80 6. In-band HTTP Authentication Alternatives . . . . . . . . . 16 81 7. Sample/Potential RESTauth Authentication Mechanisms . . . 17 82 7.1. OAuth via RESTauth . . . . . . . . . . . . . . . . . . . . 17 83 7.1.1. OAuth 1.0 . . . . . . . . . . . . . . . . . . . . . . . . 17 84 7.1.2. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 17 85 7.2. Adapting SSHv2 Authentication Mechanisms to RESTauth . . . 17 86 7.2.1. RESTauth Mechanism Names for SSHv2 Userauth Methods . . . 17 87 7.2.2. Nonces . . . . . . . . . . . . . . . . . . . . . . . . . . 18 88 7.2.3. "Session ID" . . . . . . . . . . . . . . . . . . . . . . . 18 89 7.3. Adapting IKEv2 Authentication Mechanisms to RESTauth . . . 18 90 7.3.1. Adapting IKEv2 Password Authenticated Connection 91 Establishment (PACE) to RESTauth . . . . . . . . . . . . . 18 92 7.4. Using SASL Authentication Mechanisms with RESTauth . . . . 18 93 7.4.1. Using SCRAM in RESTauth . . . . . . . . . . . . . . . . . 19 94 7.4.2. Using SCRAM with Round Trip Optimization in RESTauth . . . 20 95 7.5. Using GSS-API Authentication Mechanisms with RESTauth . . 21 96 8. IANA Considerations . . . . . . . . . . . . . . . . . . . 23 97 9. Security Considerations . . . . . . . . . . . . . . . . . 24 98 10. TODO . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 99 11. References . . . . . . . . . . . . . . . . . . . . . . . . 26 100 11.1. Normative References . . . . . . . . . . . . . . . . . . . 26 101 11.2. Informative References . . . . . . . . . . . . . . . . . . 26 102 Author's Address . . . . . . . . . . . . . . . . . . . . . 28 104 1. Introduction 106 We propose a pattern for HTTP [RFC2616] [XXX add reference to 107 HTTP/2.0 as well?] authentication mechanisms that, by being 108 "RESTful", obtains a number of benefits: 110 o authentication that works with all versions of HTTP, even when the 111 authentication mechanism requires multiple round trips; 113 o compatibility with "HTTP routing" by making no assumptions that 114 related requests are sent over the same TCP/TLS connection; 116 o channel binding, or an HTTP session protocol such as 117 [I-D.williams-websec-session-continue-proto] (or any other meeting 118 requirements of HTTP session protocols, described in 119 [I-D.williams-websec-session-continue-prob]), can be used instead 120 of web cookies; 122 * a "session URI" results that can be used to multiplex multiple 123 sessions onto the same TCP/TLS connections; 125 * a "session URI" results that can be DELETEd to effect logout; 127 * a "session URI" results that has better security semantics than 128 HTTP cookies; 130 o the ability to refer to multiple sessions in one request wherever 131 such a concept might be useful; 133 o can be implemented by any application without changes being 134 required to any HTTP stack; 136 * but it can also be implemented by the HTTP stack; 138 o on the server side this can be implemented entirely via CGI, 139 FastCGI, WSGI, servlets, and so on; 141 o by its RESTful nature, multi-round trip authentication message 142 exchanges are naturally handled without making any changes to 143 HTTP. 145 There are probably other benefits not listed above. 147 1.1. Protocol Outline 149 1. initial authentication messages are POSTed to an agreed-upon or 150 indicated "login" resource... 152 2. ....which then results in a new resource being created with the 153 authentication reply message as the new resource's 154 representation. 156 3. Thereafter any additional authentication message exchanges needed 157 (for multi-legged mechanisms) are POSTed to the new resource 158 without creating additional resources. 160 4. The resource created by the POSTing of the initial authentication 161 mechanism identifies the resulting session, and its URI is known 162 as the session URI. 164 5. Session URIs can be used to multiplex multiple sessions over the 165 same TCP/TLS connections, implement logout, and share sessions 166 across multiple related servers. 168 Authentication using mechanisms that require that the server send the 169 first authentication message is also possible, in either of two ways: 170 the initial authentication message is sent in headers in a 401 171 response, or the client POSTs an empty first message to the login 172 resource. 174 1.2. API-Imposed Constraints 176 To the extent that existing Application Programming Interfaces (APIs) 177 assume specific styles of HTTP authentication message flows, if we 178 want those APIs to support RESTauth backwards-compatibly, then those 179 APIs may impose constraints on RESTauth. 181 For example, the Android Account Manager API assumes a single round 182 trip for authentication [XXX add reference!]. But the Android 183 Account Manager could perform all but the last round trip on behalf 184 of the application, then let the application perform the last round 185 trip. In order for that to work we need the authentication message 186 exchange to be orthogonal to TCP/TLS connections -- that is, we need 187 it to be possible to use multiple TCP/TLS connections for completing 188 a single authentication exchange. This is because the application 189 and the account manager will likely be using different TCP/TLS 190 connections. 192 A typical constraining characteristic might be that an API assumes 193 the use of GET with tokens encoded into the URI or into a header, or 194 that the API makes no room for the use of headers in authentication 195 message exchanges. 197 One way to work around such constraints may be to provide various 198 options in RESTauth. Another might be to use OAuth 1.0 [RFC5849] or 199 2.0 [I-D.ietf-oauth-v2] as a bridge: the API would use this framework 200 under the covers then obtain OAuth credentials from the server that 201 the application can then use in any way that the API's form allows 202 for. 204 [[anchor1: TODO: Add a table/list of various known APIs and their 205 characteristics that might constrain this and/or other frameworks.]] 207 2. Conventions used in this document 209 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 210 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 211 document are to be interpreted as described in [RFC2119]. 213 3. Protocol 215 The are few normative protocol elements here besides the outline 216 given in Section 1. The normative protocol elements are: 218 o the form of the WWW-Authenticate header values -in 401 responses- 219 for RESTauth mechanisms; 221 o several new headers for advertising negotiable parameters that are 222 orthogonal to WWW-Authenticate; 224 o the POSTing of authentication messages from the client, with the 225 initial client authentication message going to either a pre-agreed 226 URI or to a URI named in the WWW-Authenticate headers; 228 o the creation of a session URI as a result of the initial POST, and 229 the subsequent POSTing of any additional authentication messages 230 to the session URI; 232 o the new session URI resource representation resulting from POSTs 233 being the server's response authentication message, if any; 235 o the DELETEion of session URIs as signaling logout; 237 o a new header for referencing session URIs in normal HTTP requests; 239 o the use of channel binding [RFC5056] to TLS [RFC5246] for session 240 protection; 242 And for applications that may not use TLS/HTTPS: 244 o the use of session keys as an option for integrity protection when 245 TLS is not used (a light-weight security mode); see 246 [I-D.williams-websec-session-continue-proto]. 248 3.1. Negotiable Parameters 250 As can be seen in the ABNF in the preceding section, the server can 251 offer some negotiable parameters. These are: 253 o Authentication mechanism names; 255 o Channel binding types; 257 o Session binding types; 259 o Replay protection; 260 Each WWW-Authenticate [RFC2617] header value offers a single 261 mechanism and negotiable parameters for it; because headers can have 262 multiple values, WWW-Authenticate provides a method for negotiating 263 authentication mechanisms. The WWW-ChannelBinding-Types header 264 (added here) allows the server to list channel binding types 265 supported by it. 267 3.1.1. Strong Binding to TLS 269 Strong binding to TLS is provided via channel binding [RFC5056]. 270 When a RESTauth mechanism provides strong authentication of the 271 service to the user, the combination of RESTauth and channel binding 272 results in strong authentication of the server to the user even 273 though TLS is used for session transport protection. 275 3.1.2. WWW-Authenticate Header Value Prefix Syntax 277 The ABNF for RESTauth WWW-Authenticate header values is as follows: 279 challenge = ( "RA-" mechname SP restauth-challenge ) 280 mechname = 1*( ALPHA / DIGIT / "-" ) 281 restauth-challenge = ( login-uri SP session-types SP 282 replay-prot SP *1(mech-challenge) ) 283 login-uri = absoluteURI 284 session-types = "s=" session-type / 285 (session-type ":" session-types) 286 session-type = "cookie" / "session-ID" / 287 "channel-bound-session-ID" / 288 "MAC" 289 ; new session-types may be added 290 replay-prot = "r=" ("yes" / "no") 291 mech-challenge = 293 Figure 1: RESTauth WWW-Authenticate ABNF 295 For a DIGEST-like mechanism it might look like "WWW-Authenticate: RA- 296 Digest-SHA-256 tls-server-end-point session-ID no HE4SgWGrd/ 297 3+O7t16HqusA==". For example, the mechname for the Kerberos V5 GSS- 298 API mechanism might be "gss-krb5", and a WWW-Authenticate header 299 value for it might look like "WWW-Authenticate: RA-gss-krb5 300 http://foo.example/restauth-login tls-server-end-point channel-bound- 301 session-ID r=no". 303 Note that mechanisms that may be used include: GSS mechanisms, SASL 304 mechanisms, ad-hoc mechanisms, and so on. 306 3.1.3. WWW-ChannelBinding-Types Header 308 A new header is added by which servers MUST indicate which channel 309 binding [RFC5056] types -if any- they support for RESTauth 310 authentication; if the server does not support channel binding then 311 this header MUST be absent. The header is named WWW-ChannelBinding- 312 Types. Its values are channel binding types from the channel binding 313 type registry, such as the TLS channel binding types [RFC5929]. 315 3.1.4. WWW-ChannelBinding-Type Header 317 A new header is added by which clients MUST indicate what channel 318 binding type they used when POSTing RESTauth authentication messages, 319 if any; if the client did not use channel binding then this header 320 MUST be absent. If the mechanism used has its own method for 321 indicating the use of channel binding, then this header MAY be 322 ommitted. The header is named WWW-ChannelBinding-Type. Its value is 323 a channel binding type from the channel binding type registry 324 [RFC5929]. 326 3.1.5. WWW-SessionBinding-Type Header 328 A new header is added by which clients MUST indicate what session 329 binding type they choose when POSTing RESTauth authentication 330 messages. The header is named WWW-SessionBinding-Type. Its value is 331 a session binding type as shown in Figure 1. This header SHOULD be 332 present in RESTauth authentication HTTP requests, but may be ommitted 333 when the selected mechanism provides its own session binding facility 334 that is distinct from RESTauth's (this helps adapt OAuth to RESTauth 335 with minimal or no changes). 337 3.1.6. WWW-ReplayProtection Header 339 A new header is added by which clients MUST indicate whether they 340 desire replay protection when POSTing RESTauth authentication 341 messages. The header is named WWW-SessionBinding-Type. Its value is 342 "yes" or "no" (defaults to "no" if absent) as shown in Figure 1. 344 Replay protection is to be used only when TLS [RFC5246] is not used, 345 and only if a session binding type of "MAC" is also requested. 347 3.2. Protocol Flow 349 RESTauth can be initiated by a client that knows a priori that it 350 needs to or wants to use RESTauth. Servers can also tell clients 351 that access to certain resources require authentication, possibly 352 including RESTauth mechanisms. When the server tells the client that 353 it must authenticate (using a 401 response, as usual), the server may 354 also give the client an initial authentication message for one or 355 more mechanisms. 357 When the client knows a priori that it must authenticate then the 358 client MUST know the RESTauth login URI a priori as well, as well as 359 negotiable parameters, all of which the client might know from either 360 an application protocol specification, or from caching this 361 information from earlier RESTauth exchanges. 363 The server MUST use a 401 HTTP status code and WWW-Authenticate 364 headers to inform the client of the need to authenticate in order to 365 access a given resource. For RESTauth mechanisms the WWW- 366 Authenticate header values MUST conform to the ABNF given in 367 Section 3.1.2. 369 To proceed the client chooses a suitable authentication mechanism 370 (for which, presumably, it has credentials for a desired client 371 identity), possibly a channel binding type, possibly a session type, 372 and whether to use replay protection. 374 3.2.1. One Round Trip Optimization: Challenges Borne in WWW- 375 Authenticate Headers 377 Some mechanisms may optimize the protocol flow by allowing the server 378 to include challenges in the 401 response's WWW-Authenticate header 379 values. DIGEST-MD5 works this way, for example, sending a challenge 380 nonce to be fed into the digest function (along with other client- 381 side inputs). 383 RESTauth allows this, but this feature is OPTIONAL: it must always be 384 possible for a client to initiate RESTauth without first obtaining a 385 challenge in a WWW-Authenticate header value, in which case the 386 client may incur an extra protocol leg by obtaining the challenge (if 387 it is at all necessary) in the server's reply to the client's first 388 authentication message. There are two reasons for making this 389 optional: 391 1. to allow client applications that know a priori that they must 392 authenticate (and how to), requiring no further negotiation; 394 2. to support authentication mechanisms that require that the client 395 initiate authentication message exchanges. 397 A challenge may consist of a nonce, some encrypted or MACed nonce, a 398 time-stamp, certificates and digital signatures, etcetera. The 399 server may include a login URI in challenge-laden WWW-Authenticate 400 headers where the login URI encodes secure state regarding the 401 challenge (e.g., the challenge encrypted in a symmetric key known 402 only to the server). 404 3.3. Session Binding Types: Cookie, Session URI, and MAC 406 A notion of session binding type is added for binding HTTP requests 407 to specific RESTauth login sessions. Three types are provided: 409 Cookies The traditional HTTP cookie approach to session binding; 411 Session URI HTTP requests carry a WWW-Session-URI header identifying 412 the session(s) (similar to cookies, but without all the associated 413 baggage); 415 Channel Bound Session URI Like Session URI, but may only be used in 416 HTTPS connections with the same channel bindings. (This implies 417 use of the 'tls-server-end-point' channel binding type.) 419 MAC HTTP requests carry a WWW-Session-URI header identifying the 420 session(s) and a WWW-Session-MAC header that carries a MAC or MACs 421 binding the session URI(s) to the request. 423 3.3.1. The New WWW-Session-URI Header 425 A new HTTP header is added called WWW-Session-URI whose values 426 consist of session URIs. At least one session URI MUST be included. 427 Each session URI is an absoluteURI. Session URIs MUST NOT have 428 unescaped commas (',') embedded in them. Servers MAY fail to 429 implement support for multiple session URIs being referenced by a 430 single request, in which case they MUST answer with error code . 431 Servers MUST validate the session URI before processing the request; 432 if the session URI is invalid the server MUST respond with a 401 (or 433 TBD?) status code. 435 Note that referencing multiple session URIs is permitted, but this 436 may not be meaningful for the application, thus the server MAY reject 437 this (TODO: specify a status code for this?). 439 [[anchor2: I can imagine a webmail application where a client can be 440 logged in as multiple users and get a unified view of the users' 441 mailboxes. This seems unlikely, but why rule out such use cases?]] 443 3.3.2. The New WWW-Session-MAC Header 445 [[anchor3: Describe the header, its values, algorithm agility, and 446 what the MAC is to be taken over. Note too that this cannot apply to 447 request contents as we have to consider chunking, and besides, a MAC 448 of contents really has to go as a trailer, not a header.]] 450 [[anchor4: We may want to remove this anyways and leave it for a 451 session continuation spec. Or we may want to require the use of 452 HTTPS.]] 454 3.3.3. A MAC Trailer?? 456 [[anchor5: ... This is only needed for RESTauth *without* TLS, which 457 will probably not be the common mode of use for RESTauth... unless we 458 can produce a MAC trailer extension for HTTP/2.0, in which case this 459 may well become a common mode of RESTauth usage.]] 461 [[anchor6: We may want to remove this anyways and leave it for a 462 session continuation spec. Or we may want to require the use of 463 HTTPS.]] 465 4. Representation of Authenticated Session Resources 467 It will generally be useful to be able to GET a session resource to 468 obtain information about the authenticated user. A GET on a session 469 resource which is not fully established SHOULD return an empty body. 471 [[anchor7: TODO: Add a media type for session resource 472 representation.]] 474 [[anchor8: Use JSON instead of ABNF? A schema language would be 475 nice.]] 477 session = 1*( session-param ) 478 session-param = session-param-name '=' session-param-value 479 session-param-name = 1*( ALPHA / DIGIT / '-' / '_' ) 480 session-param-value = 482 Figure 2: Session resource representation ABNF 484 Session parameters include: 486 established "true" or "false" 488 expiration_time Datetime when the session expires. 490 session_key_MAC_req Session key for MACs in requests. 492 session_key_MAC_resp Session key for MACs in responses. 494 authorization_data Information about the authenticated user. 496 user_id The authenticated user identity. 498 The server MAY exclude any part of this when the entity requesting a 499 session resource is the session's user. The server MUST exclude (or 500 respond with 401) all of the session resource's representation when 501 the entity requesting it is not authenticated or authorized to see 502 it. The server SHOULD exclude locally-determined authorization_data 503 and/or user_id information when the entity requesting the resource is 504 the session's user. 506 5. HTTP "Routing" and Authentication 508 It is common to deploy HTTP services with load-balanced servers 509 behind a load balancer and TLS concentrator. Other techniques may 510 also result in a multiplicity of servers acting on behalf of a single 511 service. The load balancers may even behave like routers and route 512 HTTP requests to the same server for all requests in a single 513 connection, or even route HTTP requests according to the verb and 514 resource. It helps to be able to have a notion of authenticated 515 sessions that can be referenced by all servers responding to a given 516 service name. 518 The server end of a RESTauth authentication message exchange may be 519 terminated by one server, by many servers sharing session state (via 520 the resources named by session URIs), or by a server-side HTTP 521 router. Once a RESTauth session is established we assume that all 522 servers responding to the same service name will be able to access 523 the session resource, validate session URIs, and obtain keys for 524 computing and validating session binding MACs. Alternatively, the 525 router may take responsibility for session binding and signal 526 authorization information from the established session to the HTTP 527 servers behind the router (however, we do not here specify any 528 methods for such signaling). 530 By using REST for the authentication message exchange we allow this 531 disconnection between "session" and "connection", which therefore 532 facilitates "routing" of HTTP requests and even off-loading of 533 authentication and/or session binding to HTTP "routers". 535 This approach should be flexible enough for all existing 536 architectures for deploying HTTP services. 538 6. In-band HTTP Authentication Alternatives 540 RESTauth is "out-of-band" in the sense that the authentication 541 messages are exchanged independently of the application's requests 542 for normal resources. Of course, RESTauth exchanges may well (and 543 often will) happen in the same TCP/TLS connection as normal 544 application requests, so RESTauth is not really out-of-band. We use 545 "out-of-band" and "in-band" very loosely in this section. 547 There exist several "in-band" HTTP authentication alternatives where 548 the authentication message exchanges happen in the context of 549 application resources. Here the HTTP verb and resource are 550 application-specific and have nothing to do with authentication, and 551 the authentication messages are exchanged via HTTP request and 552 response headers with the server responding with a 401 status code 553 until authentication is complete. 555 The extant "Basic" and "DIGEST-MD5" [RFC2617] HTTP authentication 556 methods, as well as HTTP/Negotiate [RFC4559] are "in-band" HTTP 557 authentication methods. 559 In so far as an in-band authentication method results in a cookie or 560 session URI/ID the distinction between in-band and out-of-band is 561 almost trivial, as described above: authentication messages in 562 headers vs. bodies, and HTTP verb and URL. However, if in-line 563 authentication methods are strongly tied to the TCP/TLS connections 564 over which they were utilized then that is a big disadvantage over 565 RESTauth: each connection requires re-authenticating, and support for 566 HTTP routing schemes is not clear. 568 HTTP/Negotiate is more troublesome because historically it has 569 required re-authentication per-HTTP request(!). 571 Even if the only difference between in-band and out-of-band is a 572 trivial one, using the REST pattern means that authentication can be 573 implemented using with no help from the HTTP stack (even though it's 574 desirable to have it implemented within/by the HTTP stack), whereas 575 there may not be a way to implement in-band authentication without 576 help from the HTTP stack for some stacks. 578 7. Sample/Potential RESTauth Authentication Mechanisms 580 Here we describe (informatively, for the time being) how to use or 581 adapt a variety of authentication mechanisms, from SSHv2, IKEv2, 582 SASL, GSS-API, and other frameworks, so as to quickly gain a set of 583 usable mechanisms, both, specification- and implementation-wise. 584 This section is also intended to show that adding RESTauth mechanisms 585 is easy. 587 7.1. OAuth via RESTauth 589 OAuth 1.0 RFC5849 and OAuth 2.0 [I-D.ietf-oauth-v2] are commonly 590 deployed. Being able to use OAuth via RESTauth would be useful. We 591 attempt to make RESTauth such that at least for OAuth 1.0 there is a 592 standard way to use OAuth such that it conforms to RESTauth. 594 7.1.1. OAuth 1.0 596 For OAuth 1.0 [RFC5849] the "form-encoded body" form (see section 597 3.5.2 of [RFC5849]) of OAuth 1.0 conforms to RESTauth without further 598 changes. 600 7.1.2. OAuth 2.0 602 [It looks like OAuth 2.0 [I-D.ietf-oauth-v2] also uses POST to send 603 tokens to the server, and it looks like it too effectively conforms 604 to RESTauth.] 606 7.2. Adapting SSHv2 Authentication Mechanisms to RESTauth 608 SSHv2 "userauth" mechanisms [RFC4252] typically involve a digital 609 signature (or similar) of an SSHv2 session ID. There is no such 610 thing as an SSHv2 session ID in HTTP. A session URI cannot serve as 611 a stand-in for an SSHv2 session ID because a) the session URI is an 612 outcome of authentication in RESTauth, b) to prevent cut-n-paste and 613 replay attacks the client and the server both must contribute to the 614 entropy of the session ID that is signed by the client. 616 In order to adapt SSHv2 userauth methods properly (i.e., securely), 617 we have replace the SSHv2 session ID in the to-be-signed data with a 618 hash of the channel binding and nonces contributed by the client and 619 the server. As an optimization the server nonce can be sent as a 620 challenge (this saves a round trip). 622 7.2.1. RESTauth Mechanism Names for SSHv2 Userauth Methods 624 For hash agility reasons the hash function name is part of the SSHv2 625 RESTauth mechanism name. To avoid "multi-level negotiation" the 626 SSHv2 userauth method name is also part of the RESTauth mechanism 627 name. 629 The RESTauth mechanism name form for SSHv2 userauth methods, then, 630 is: ssh--. 632 The following RESTauth mechanisms are defined here: 634 o ssh-publickey-SHA-256 636 o ssh-hostbased-SHA-256 638 7.2.2. Nonces 640 The client and the server must each contribute 128-bit nonces. 642 7.2.3. "Session ID" 644 The ssh-publickey-SHA-256 and ssh-hostbased-SHA-256 mechanisms use 645 the following instead of a traditional SSHv2 session ID: 647 o SHA-256(channel_binding || server_nonce || client_nonce) 649 Here the is as per-[RFC5056]: the channel binding 650 type name, followed by the channel binding data (e.g., 'tls-server- 651 end-point' followed by the server EE certificate as sent in the 652 server's TLS Certificate message). 654 Note that use of channel binding when using SSHv2 mechanisms is 655 REQUIRED so as to defeat cut-n-paste attacks by weakly-authenticated 656 servers. 658 7.3. Adapting IKEv2 Authentication Mechanisms to RESTauth 660 [[anchor9: TBD.]] 662 7.3.1. Adapting IKEv2 Password Authenticated Connection Establishment 663 (PACE) to RESTauth 665 [[anchor10: TBD.]] 667 7.4. Using SASL Authentication Mechanisms with RESTauth 669 Simple Authentication and Security Layers (SASL) [RFC4422] is a 670 simple, pluggable framework for authentication mechanisms. 672 To use a SASL mechanism in RESTauth just prefix "SA-" to the SASL 673 mechanism name and use that as the RESTauth mechanism name. If the 674 SASL mechanism is server-initiated then the server's challenge is 675 sent in the server's WWW-Authenticate header value as described 676 above. All other SASL authentication messages are exchanged as 677 described above (i.e., via POSTs, first to the login URI, then to the 678 session URI, with response messages as the new representation of the 679 session resource). 681 The HTTP status code functions as the application's outcome of 682 authentication message. If SASL succeeds but authorization fails 683 then the server should respond with a 401 status code to the POST of 684 the final SASL authentication message from the client. 686 The server's WWW-Authenticate header values function as the mechanism 687 listing operation. SASL security considerations [RFC4422] [RFC5801] 688 apply (particularly regarding the negotiation of channel binding 689 support). 691 7.4.1. Using SCRAM in RESTauth 693 The Salted Challenge Response Authentication Mechanism (SCRAM) 694 [RFC5802] is a DIGEST-like mechanism for SASL. Nothing special is 695 needed to use SCRAM versus any other SASL mechanism, except for a 696 round trip optimized form of SCRAM, if we decide to pursue that (see 697 Section 7.4.2). 699 The following figure shows what SCRAM in RESTauth looks like. Note 700 that the resource representations are taken verbatim from [RFC5802]. 702 C->S: GET /some-resources HTTP/1.1 703 Host: A.example 705 S->C: HTTP/1.1 401 Unauthorized 706 WWW-Authenticate: RA-SA-SCRAM-SHA-1 \ 707 http://A.example/rest-sa-scram \ 708 s=session-ID,MIC r=no 709 WWW-ChannelBinding-Types: tls-server-end-point 711 C->S: POST /rest-sa-scram HTTP/1.1 712 Host: A.example 713 WWW-ChannelBinding-Type: tls-server-end-point 714 WWW-SessionBinding-Type: session-ID 715 Content-Type: application/octet-stream 716 Content-Length: nnn 718 n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL 720 S->C: HTTP/1.1 201 721 Location http://A.example/restauth-9d0af5f680d4ff46 722 Content-Type: application/octet-stream 723 Content-Length: nnn 725 r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j, 726 s=QSXCR+Q6sek8bf92,i=4096 728 C->S: POST /restauth-9d0af5f680d4ff46 HTTP/1.1 729 Host: A.example 730 Content-Type: application/octet-stream 731 Content-Length: nnn 733 c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j, 734 p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts= 736 S->C: HTTP/1.1 200 737 Content-Type: application/octet-stream 738 Content-Length: nnn 740 v=rmF9pqV8S7suAoZWja4dJRkFsKQ= 742 Figure 3: RESTauth w/ SCRAM 744 7.4.2. Using SCRAM with Round Trip Optimization in RESTauth 746 [[anchor11: This might work by having the authentication ID function 747 as the salt and the server offering a challenge nonce and iteration 748 count in its optimistic challenge. However, it's not clear that a 749 round trip optimized form of SCRAM is desirable.]] 750 The following figure shows what a round trip optimized RESTauth w/ 751 SCRAM exchange might look like. 753 [[anchor12: NOTE: SCRAM was not intended to be used this way. In 754 particular this approach forces the use of an algorithmic salt, to be 755 derived only from either the username or the username and the 756 server's name (or else to be remembered by the user, but that's not 757 likely).]] 759 C->S: GET /some-resources HTTP/1.1 760 Host: A.example 762 S->C: HTTP/1.1 401 Unauthorized 763 WWW-Authenticate: RA-SA-SCRAM-SHA-1 \ 764 http://A.example/rest-sa-scram \ 765 s=session-ID,MIC r=no \ 766 r=fyko+d2l...JY1ZVvWVs7j,i=4096 767 WWW-ChannelBinding-Types: tls-server-end-point 769 C->S: POST /rest-sa-scram HTTP/1.1 770 Host: A.example 771 WWW-ChannelBinding-Type: tls-server-end-point 772 WWW-SessionBinding-Type: session-ID 773 Content-Type: application/octet-stream 774 Content-Length: nnn 776 n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL, 777 c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j, 778 p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts= 780 S->C: HTTP/1.1 200 781 Content-Type: application/octet-stream 782 Content-Length: nnn 784 v=rmF9pqV8S7suAoZWja4dJRkFsKQ= 786 Figure 4: RESTauth w/ round trip optimized SCRAM 788 7.5. Using GSS-API Authentication Mechanisms with RESTauth 790 The Generic Security Services Application Programming Interface (GSS- 791 API) [RFC2743] is another pluggable mechanism framework. Any GSS-API 792 mechanism that supports channel binding [RFC5056] can be used as SASL 793 mechanisms via the "SASL/GS2" bridge [RFC5801]. This includes the 794 Kerberos V5 GSS-API mechanism [RFC4121]. 796 GSS-API security mechanisms could also be used without SASL/GS2, but 797 SASL/GS2 barely adds any overhead or complexity (a SASL 798 implementation is not required in order to use SASL/GS2, just a GSS 799 implementation): a simple header is to be prefixed to the initial 800 security context token and to the channel binding data, with both 801 peers always providing channel binding data. 803 8. IANA Considerations 805 TBD (header registrations, ...) 807 9. Security Considerations 809 This entire document deals with security considerations. [Add more, 810 like about channel binding, same-origin-like constraints on the login 811 and session absolute URIs', ...] 813 10. TODO 815 [[anchor13: Add references (to HTTP/2.0, CGI/fCGI, ...).]] 817 [[anchor14: Describe MAC session binding option and replay protection 818 in detail -- or remove it altogether. Describe how to extract keys 819 for MAC keying from SASL/GSS/PACE.]] 821 [[anchor15: Figure out how to adapt IKEv2 password-based methods to 822 RESTauth. This may not be worthwhile (since each method tends to 823 depend heavily on the entire IKEv2 framework in ways that add 824 messaging that we'd not need in RESTauth).]] 826 [[anchor16: Do we need to distinguish exchanges for authentication 827 from exchanges for authorization? Probably.]] 829 11. References 831 11.1. Normative References 833 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 834 Requirement Levels", BCP 14, RFC 2119, March 1997. 836 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 837 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 838 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 840 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 841 Leach, P., Luotonen, A., and L. Stewart, "HTTP 842 Authentication: Basic and Digest Access Authentication", 843 RFC 2617, June 1999. 845 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 846 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 848 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 849 Channels", RFC 5056, November 2007. 851 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 852 for TLS", RFC 5929, July 2010. 854 [I-D.williams-websec-session-continue-prob] 855 Williams, N., "Hypertext Transport Protocol (HTTP) Session 856 Continuation: Problem Statement", 857 draft-williams-websec-session-continue-prob-00 (work in 858 progress), January 2013. 860 [I-D.williams-websec-session-continue-proto] 861 Williams, N., "Hypertext Transport Protocol (HTTP) Session 862 Continuation Protocol", 863 draft-williams-websec-session-continue-proto-00 (work in 864 progress), January 2013. 866 11.2. Informative References 868 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 869 April 2010. 871 [I-D.ietf-oauth-v2] 872 Hardt, D., "The OAuth 2.0 Authorization Framework", 873 draft-ietf-oauth-v2-31 (work in progress), August 2012. 875 [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and 876 Security Layer (SASL)", RFC 4422, June 2006. 878 [RFC5802] Newman, C., Menon-Sen, A., Melnikov, A., and N. Williams, 879 "Salted Challenge Response Authentication Mechanism 880 (SCRAM) SASL and GSS-API Mechanisms", RFC 5802, July 2010. 882 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 883 Authentication Protocol", RFC 4252, January 2006. 885 [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based 886 Kerberos and NTLM HTTP Authentication in Microsoft 887 Windows", RFC 4559, June 2006. 889 [RFC6631] Kuegler, D. and Y. Sheffer, "Password Authenticated 890 Connection Establishment with the Internet Key Exchange 891 Protocol version 2 (IKEv2)", RFC 6631, June 2012. 893 [RFC2743] Linn, J., "Generic Security Service Application Program 894 Interface Version 2, Update 1", RFC 2743, January 2000. 896 [RFC5801] Josefsson, S. and N. Williams, "Using Generic Security 897 Service Application Program Interface (GSS-API) Mechanisms 898 in Simple Authentication and Security Layer (SASL): The 899 GS2 Mechanism Family", RFC 5801, July 2010. 901 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos 902 Version 5 Generic Security Service Application Program 903 Interface (GSS-API) Mechanism: Version 2", RFC 4121, 904 July 2005. 906 Author's Address 908 Nicolas Williams 909 Cryptonector, LLC 911 Email: nico@cryptonector.com