idnits 2.17.1 draft-williams-http-rest-auth-03.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 15, 2012) is 4269 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC6631' is defined on line 798, 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 15, 2012 5 Expires: February 16, 2013 7 RESTful Authentication Pattern for the Hypertext Transport Protocol 8 (HTTP) 9 draft-williams-http-rest-auth-03 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 16, 2013. 42 Copyright Notice 44 Copyright (c) 2012 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 2. Conventions used in this document . . . . . . . . . . . . 6 61 3. API-Imposed Constraints . . . . . . . . . . . . . . . . . 7 62 4. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 4.1. Negotiable Parameters . . . . . . . . . . . . . . . . . . 8 64 4.1.1. Strong Binding to TLS . . . . . . . . . . . . . . . . . . 9 65 4.1.2. WWW-Authenticate Header Value Prefix Syntax . . . . . . . 9 66 4.1.3. WWW-ChannelBinding-Types Header . . . . . . . . . . . . . 9 67 4.1.4. WWW-ChannelBinding-Type Header . . . . . . . . . . . . . . 10 68 4.1.5. WWW-SessionBinding-Type Header . . . . . . . . . . . . . . 10 69 4.1.6. WWW-ReplayProtection Header . . . . . . . . . . . . . . . 10 70 4.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 10 71 4.2.1. One Round Trip Optimization: Challenges Born in 72 WWW-Authenticate Headers . . . . . . . . . . . . . . . . . 11 73 4.3. Session Binding Types: Cookie, URI, and MAC . . . . . . . 11 74 4.3.1. The New WWW-Session-URI Header . . . . . . . . . . . . . . 12 75 4.3.2. The New WWW-Session-MAC Header . . . . . . . . . . . . . . 12 76 4.3.3. A MAC Trailer?? . . . . . . . . . . . . . . . . . . . . . 12 77 5. HTTP "Routing" and Authentication . . . . . . . . . . . . 13 78 6. In-band HTTP Authentication Alternatives . . . . . . . . . 14 79 7. Sample/Potential RESTauth Authentication Mechanisms . . . 15 80 7.1. OAuth via RESTauth . . . . . . . . . . . . . . . . . . . . 15 81 7.1.1. OAuth 1.0 . . . . . . . . . . . . . . . . . . . . . . . . 15 82 7.1.2. OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . 15 83 7.2. Adapting SSHv2 Authentication Mechanisms to RESTauth . . . 15 84 7.2.1. RESTauth Mechanism Names for SSHv2 Userauth Methods . . . 15 85 7.2.2. Nonces . . . . . . . . . . . . . . . . . . . . . . . . . . 16 86 7.2.3. "Session ID" . . . . . . . . . . . . . . . . . . . . . . . 16 87 7.3. Adapting IKEv2 Authentication Mechanisms to RESTauth . . . 16 88 7.3.1. Adapting IKEv2 Password Authenticated Connection 89 Establishment (PACE) to RESTauth . . . . . . . . . . . . . 16 90 7.4. Using SASL Authentication Mechanisms with RESTauth . . . . 16 91 7.4.1. Using SCRAM in RESTauth . . . . . . . . . . . . . . . . . 17 92 7.4.2. Using SCRAM with Round Trip Optimization in RESTauth . . . 18 93 7.5. Using GSS-API Authentication Mechanisms with RESTauth . . 19 94 8. IANA Considerations . . . . . . . . . . . . . . . . . . . 20 95 9. Security Considerations . . . . . . . . . . . . . . . . . 21 96 10. TODO . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 97 11. References . . . . . . . . . . . . . . . . . . . . . . . . 23 98 11.1. Normative References . . . . . . . . . . . . . . . . . . . 23 99 11.2. Informative References . . . . . . . . . . . . . . . . . . 23 100 Author's Address . . . . . . . . . . . . . . . . . . . . . 25 102 1. Introduction 104 We propose a pattern for HTTP [RFC2616] [XXX add reference to 105 HTTP/2.0 as well] authentication mechanisms that, by being "RESTful", 106 obtains a number of benefits: 108 o authentication that works with all versions of HTTP, even when the 109 authentication mechanism requires multiple round trips; 111 o compatibility with "HTTP routing" by making no assumptions that 112 related requests are sent over the same TCP/TLS connection; 114 o a "session URI" results that can be used to multiplex multiple 115 sessions onto the same TCP/TLS connections; 117 o a "session URI" results that can be DELETEd to effect logout; 119 o a "session URI" results that has better security semantics than 120 HTTP cookies; 122 o the ability to refer to multiple sessions in one request wherever 123 such a concept might be useful; 125 o can be implemented by any application without changes being 126 required to any HTTP stack; 128 o can be implemented by the HTTP stack; 130 o on the server side this can be implemented entirely via CGI and 131 FastCGI; 133 o by its RESTful nature, multi-legged authentication message 134 exchanges are naturally handled without making any changes to 135 HTTP. 137 There are probably other benefits not listed above. 139 The rough outline of the protocol is quite simple: 141 1. initial authentication messages are POSTed to an agreed-upon or 142 indicated resource... 144 2. ....which then results in a new resource being created with the 145 authentication reply message as the new resource's 146 representation. 148 3. Thereafter any additional authentication message exchanges needed 149 (for multi-legged mechanisms) are POSTed to the new resource 150 creating additional resources. 152 4. The resource created by the POSTing of the initial authentication 153 mechanism identifies the resulting session, and its URI is known 154 as the session URI. 156 5. Session URIs can be used to multiplex multiple sessions over the 157 same TCP/TLS connections, implement logout, and share sessions 158 across multiple related servers. 160 Server-initiated authentication is also possible, whereby the server 161 sends a challenge in 401 errors in headers. If the server gives the 162 client a choice of mechanisms (multiple WWW-Authenticate header 163 values) and the client picks one where the server sent a challenge, 164 then the client consumes that message and POSTs subsequent ones to 165 the indicated URI. 167 2. Conventions used in this document 169 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 170 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 171 document are to be interpreted as described in [RFC2119]. 173 3. API-Imposed Constraints 175 To the extent that existing Application Programming Interfaces (APIs) 176 assume specific styles of HTTP authentication message flows, if we 177 want those APIs to support RESTauth backwards-compatibly, then those 178 APIs may impose constraints on RESTauth. 180 For example, the Android Account Manager API assumes a single round 181 trip for authentication. But the Android Account Manager could 182 perform all but the last round trip on behalf of the application, 183 then let the application perform the last round trip. In order for 184 that to work we need the authentication message exchange to be 185 orthogonal to TCP/TLS connections - that is, we need it to be 186 possible to use multiple TCP/TLS connections for completing a single 187 authentication exchange. 189 A typical constraining characteristic might be that an API assumes 190 the use of GET with tokens encoded into the URI, or that the API 191 makes no room for the use of headers in authentication message 192 exchanges. 194 One way to work around such constraints may be to provide various 195 options in this framework. Another might be to use OAuth 1.0 196 [RFC5849] or 2.0 [I-D.ietf-oauth-v2] as a bridge: the API would use 197 this framework under the covers then obtain OAuth credentials from 198 the server that the application can then use in any way that the 199 API's form allows for. 201 [[anchor1: TODO: Add a table/list of various APIs and their 202 characteristics that might constrain this framework.]] 204 4. Protocol 206 The are very few normative protocol elements here besides the outline 207 given in Section 1. The normative protocol elements are: 209 o the form of the WWW-Authenticate header values for RESTauth 210 mechanisms; 212 o several new headers for advertising negotiable parameters that are 213 orthogonal to WWW-Authenticate; 215 o the POSTing of authentication messages from the client, with the 216 initial client authentication message going to either a pre-agreed 217 URI or to a URI named in the WWW-Authenticate headers; 219 o the creation of a session URI as a result of the initial POST, and 220 the subsequent POSTing of any additional authentication messages 221 to the session URI; 223 o the new session URI resource representation resulting from POSTs 224 being the server's response authentication message, if any; 226 o the DELETEion of session URIs as signaling logout; 228 o a new header for referencing session URIs in normal HTTP requests; 230 o the use of channel binding [RFC5056] to TLS [RFC5246] for session 231 protection; 233 o the use of session keys as an option for integrity protection when 234 TLS is not used (a light-weight security mode). 236 4.1. Negotiable Parameters 238 As can be seen in the ABNF in the preceding section, the server can 239 offer some negotiable parameters. These are: 241 o Mechanism names; 243 o Channel binding types; 245 o Session binding types; 247 o Replay protection; 249 Each WWW-Authenticate header value offers a single mechanism and 250 negotiable parameters for it. The WWW-ChannelBinding-Types header 251 allows the server to offer channel binding types. 253 4.1.1. Strong Binding to TLS 255 Strong binding to TLS is provided via channel binding [RFC5056]. 256 When a RESTauth mechanism provides strong authentication of the 257 service to the user, the combination of RESTauth and channel binding 258 results in strong authentication of the server to the user even 259 though TLS is used for session transport protection. 261 4.1.2. WWW-Authenticate Header Value Prefix Syntax 263 The ABNF for RESTauth WWW-Authenticate header values is as follows: 265 challenge = ( "RA-" mechname SP restauth-challenge ) 266 mechname = TBD 267 restauth-challenge = ( login-uri SP session-types SP 268 replay-prot SP *1(mech-challenge) ) 269 login-uri = absoluteURI 270 session-types = "s=" session-type / 271 (session-type ":" session-types) 272 session-type = "cookie" / "session-ID" / "MAC" 273 replay-prot = "r=" ("yes" / "no") 274 ; TODO: add production for 275 ; mech-challenge as a base64 string 276 ; TODO: add MAC algorithm offers for alg agility? 278 Figure 1: WWW-Authenticate ABNF 280 For a DIGEST-like mechanism it might look like "WWW-Authenticate: RA- 281 Digest-SHA-256 tls-server-end-point session-ID no HE4SgWGrd/ 282 3+O7t16HqusA==". For example, the mechname for the Kerberos V5 GSS- 283 API mechanism might be "gss-krb5", and a WWW-Authenticate header 284 value for it might look like "WWW-Authenticate: RA-gss-krb5 285 http://foo.example/restauth-login tls-server-end-point session-ID 286 no". 288 Note that mechanisms that may be used include: GSS mechanisms, SASL 289 mechanisms, ad-hoc mechanisms, and so on. 291 4.1.3. WWW-ChannelBinding-Types Header 293 A new header is added by which servers MUST indicate which channel 294 binding [RFC5056] types -if any- they support for RESTauth 295 authentication; if the server does not support channel binding then 296 this header MUST be absent. The header is named WWW-ChannelBinding- 297 Types. Its values are channel binding types from the channel binding 298 type registry [RFC5929]. 300 4.1.4. WWW-ChannelBinding-Type Header 302 A new header is added by which clients MUST indicate what channel 303 binding type they used when POSTing RESTauth authentication messages, 304 if any; if the client did not use channel binding then this header 305 MUST be absent. If the mechanism used has its own method for 306 indicating the use of channel binding, then this header MAY be 307 ommitted. The header is named WWW-ChannelBinding-Type. Its value is 308 a channel binding type from the channel binding type registry 309 [RFC5929]. 311 4.1.5. WWW-SessionBinding-Type Header 313 A new header is added by which clients MUST indicate what session 314 binding type they choose when POSTing RESTauth authentication 315 messages. The header is named WWW-SessionBinding-Type. Its value is 316 a session binding type as shown in Figure 1. This header SHOULD be 317 present in RESTauth authentication HTTP requests, but may be ommitted 318 when the selected mechanism provides its own session binding facility 319 that is distinct from RESTauth's (this helps adapt OAuth to RESTauth 320 with minimal or no changes). 322 4.1.6. WWW-ReplayProtection Header 324 A new header is added by which clients MUST indicate whether they 325 desire replay protection when POSTing RESTauth authentication 326 messages. The header is named WWW-SessionBinding-Type. Its value is 327 "yes" or "no" (defaults to "no" if absent) as shown in Figure 1. 329 Replay protection is to be used only when TLS [RFC5246] is not, and 330 only if a session binding type of "MAC" is also requested. 332 4.2. Protocol Flow 334 RESTauth can be initiated by a client that knows a priori that it 335 needs to or wants to use RESTauth. Servers can also tell clients 336 that access to certain resources require authentication, possibly 337 including RESTauth mechanisms. When the server tells the client that 338 it must authenticate, the server may also give the client an initial 339 authentication message for one or more mechanisms. 341 When the client knows a priori that it must authenticate then the 342 client MUST know the RESTauth login URI a priori as well, as well as 343 negotiable parameters, all of which the client might know from either 344 an application protocol specification, or from caching this 345 information from earlier RESTauth exchanges. 347 The server MUST use a 401 HTTP status code and WWW-Authenticate 348 headers to inform the client of the need to authenticate in order to 349 access a given resource. For RESTauth mechanisms the WWW- 350 Authenticate header values MUST conform to the ABNF given in 351 Section 4.1.2. 353 To proceed the client chooses a suitable authentication mechanism 354 (for which, presumably, it has credentials for a desired client 355 identity), possibly a channel binding type, possibly a session type, 356 and whether to use replay protection. 358 4.2.1. One Round Trip Optimization: Challenges Born in WWW-Authenticate 359 Headers 361 Some mechanisms may optimize the protocol flow by allowing the server 362 to include challenges in the 401 response's WWW-Authenticate header 363 values. DIGEST-MD5 works this way, for example, sending a challenge 364 nonce to be fed into the digest function (along with other client- 365 side inputs). 367 RESTauth allows this, but this feature is OPTIONAL: it must always be 368 possible for a client to initiate RESTauth without first obtaining a 369 challenge in a WWW-Authenticate header value, in which case the 370 client must incur an extra protocol leg by obtaining the challenge 371 (if it is at all necessary) in the server's reply to the client's 372 first authentication message. There are two reasons for making this 373 optional: 375 1. to allow client applications that know a priori that they must 376 authenticate, requiring no further negotiation; 378 2. to support authentication frameworks that require that the client 379 initiate authentication message exchanges. 381 A challenge may consist of a nonce, some encrypted or MACed nonce, a 382 time-stamp, certificates and digital signatures, etcetera. The 383 server may include a login URI in challenge-laden WWW-Authenticate 384 headers where the login URI encodes secure state regarding the 385 challenge (e.g., the challenge encrypted in a symmetric key known 386 only to the server). 388 4.3. Session Binding Types: Cookie, URI, and MAC 390 A notion of session binding type is added for binding HTTP requests 391 to specific RESTauth login sessions. Three types are provided: 393 Cookies The traditional HTTP cookie approach to session binding; 395 Session URI HTTP requests carry a WWW-Session-URI header identifying 396 the session(s) (similar to cookies, but without all the associated 397 baggage); 399 MAC HTTP requests carry a WWW-Session-URI header identifying the 400 session(s) and a WWW-Session-MAC header that carries a MAC or MACs 401 binding the session URI(s) to the request. 403 4.3.1. The New WWW-Session-URI Header 405 A new HTTP header is added called WWW-Session-URI whose values 406 consist of session URIs. At least one session URI MUST be included. 407 Each session URI is an absoluteURI. Session URIs MUST NOT have 408 unescaped commas (',') embedded in them. Servers MAY fail to 409 implement support for multiple session URIs being referenced by a 410 single request, in which case they MUST answer with error code . 411 Servers MUST validate the session URI before processing the request; 412 if the session URI is invalid the server MUST respond with a 401 (or 413 TBD?) status code. 415 Note that referencing multiple session URIs is permitted, but this 416 may not be meaningful for the application, thus the server MAY reject 417 this (TODO: specify a status code for this?). 419 [[anchor2: I can imagine a webmail application where a client can be 420 logged in as multiple users and get a unified view of the users' 421 mailboxes. This seems unlikely, but why rule out such use cases?]] 423 4.3.2. The New WWW-Session-MAC Header 425 [[anchor3: Describe the header, its values, algorithm agility, and 426 what the MAC is to be taken over. Note too that this cannot apply to 427 request contents as we have to consider chunking, and besides, a MAC 428 of contents really has to go as a trailer, not a header.]] 430 4.3.3. A MAC Trailer?? 432 [[anchor4: ... This is only needed for RESTauth *without* TLS, which 433 will probably not be the common mode of use for RESTauth... unless we 434 can produce a MAC trailer extension for HTTP/2.0, in which case this 435 may well become a common mode of RESTauth usage.]] 437 5. HTTP "Routing" and Authentication 439 It is common to deploy HTTP services with load-balanced servers 440 behind a load balancer and TLS concentrator. Other techniques may 441 also result in a multiplicity of servers acting on behalf of a single 442 service. The load balancers may even behave like routers and route 443 HTTP requests to the same server for all requests in a single 444 connection, or even route HTTP requests according to the verb and 445 resource. It helps to be able to have a notion of authenticated 446 sessions that can be referenced by all servers responding to a given 447 service name. 449 The server end of a RESTauth authentication message exchange may be 450 terminated by one server, by many servers sharing session state (via 451 the resources named by session URIs), or by a server-side HTTP 452 router. Once a RESTauth session is established we assume that all 453 servers responding to the same service name will be able to access 454 the session resource, validate session URIs, and obtain keys for 455 computing and validating session binding MACs. Alternatively, the 456 router may take responsibility for session binding and signal 457 authorization information from the established session to the HTTP 458 servers behind the router (however, we do not here specify any 459 methods for such signaling). 461 By using REST for the authentication message exchange we allow this 462 disconnection between "session" and "connection", which therefore 463 facilitates "routing" of HTTP requests and even off-loading of 464 authentication and/or session binding to HTTP "routers". 466 This approach should be flexible enough for all existing 467 architectures for deploying HTTP services. 469 6. In-band HTTP Authentication Alternatives 471 RESTauth is "out-of-band" in the sense that the authentication 472 messages are exchanged independently of the application's requests 473 for normal resources. Of course, RESTauth exchanges may well (and 474 often will) happen in the same TCP/TLS connection as normal 475 application requests, so RESTauth is not really out-of-band. We use 476 "out-of-band" and "in-band" very loosely in this section. 478 There exist several "in-band" HTTP authentication alternatives where 479 the authentication message exchanges happen in the context of 480 application resources. Here the HTTP verb and resource are 481 application-specific and have nothing to do with authentication, and 482 the authentication messages are exchanged via HTTP request and 483 response headers with the server responding with a 401 status code 484 until authentication is complete. 486 The extant "Basic" and "DIGEST-MD5" [RFC2617] HTTP authentication 487 methods, as well as HTTP/Negotiate [RFC4559] are "in-band" HTTP 488 authentication methods. 490 In so far as an in-band authentication method results in a cookie or 491 session URI/ID the distinction between in-band and out-of-band is 492 almost trivial, as described above: authentication messages in 493 headers vs. bodies, and HTTP verb and URL. However, if in-line 494 authentication methods are strongly tied to the TCP/TLS connections 495 over which they were utilized then that is a big disadvantage over 496 RESTauth: each connection requires re-authenticating, and support for 497 HTTP routing schemes is not clear. 499 HTTP/Negotiate is more troublesome because historically it has 500 required re-authentication per-HTTP request(!). 502 Even if the only difference between in-band and out-of-band is a 503 trivial one, using the REST pattern means that authentication can be 504 implemented using with no help from the HTTP stack (even though it's 505 desirable to have it implemented within/by the HTTP stack), whereas 506 there may not be a way to implement in-band authentication without 507 help from the HTTP stack for some stacks. 509 7. Sample/Potential RESTauth Authentication Mechanisms 511 Here we describe (informatively, for the time being) how to use or 512 adapt a variety of authentication mechanisms, from SSHv2, IKEv2, 513 SASL, GSS-API, and other frameworks, so as to quickly gain a set of 514 usable mechanisms, both, specification- and implementation-wise. 515 This section is also intended to show that adding RESTauth mechanisms 516 is easy. 518 7.1. OAuth via RESTauth 520 OAuth 1.0 RFC5849 and OAuth 2.0 [I-D.ietf-oauth-v2] are commonly 521 deployed. Being able to use OAuth via RESTauth would be useful. We 522 attempt to make RESTauth such that at least for OAuth 1.0 there is a 523 standard way to use OAuth such that it conforms to RESTauth. 525 7.1.1. OAuth 1.0 527 For OAuth 1.0 [RFC5849] the "form-encoded body" form (see section 528 3.5.2 of [RFC5849]) of OAuth 1.0 conforms to RESTauth without further 529 changes. 531 7.1.2. OAuth 2.0 533 [It looks like OAuth 2.0 [I-D.ietf-oauth-v2] also uses POST to send 534 tokens to the server, and it looks like it too effectively conforms 535 to RESTauth.] 537 7.2. Adapting SSHv2 Authentication Mechanisms to RESTauth 539 SSHv2 "userauth" mechanisms [RFC4252] typically involve a digital 540 signature (or similar) of an SSHv2 session ID. There is no such 541 thing as an SSHv2 session ID in HTTP. A session URI cannot serve as 542 a stand-in for an SSHv2 session ID because a) the session URI is an 543 outcome of authentication in RESTauth, b) to prevent cut-n-paste and 544 replay attacks the client and the server both must contribute to the 545 entropy of the session ID that is signed by the client. 547 In order to adapt SSHv2 userauth methods properly (i.e., securely), 548 we have replace the SSHv2 session ID in the to-be-signed data with a 549 hash of the channel binding and nonces contributed by the client and 550 the server. As an optimization the server nonce can be sent as a 551 challenge (this saves a round trip). 553 7.2.1. RESTauth Mechanism Names for SSHv2 Userauth Methods 555 For hash agility reasons the hash function name is part of the SSHv2 556 RESTauth mechanism name. To avoid "multi-level negotiation" the 557 SSHv2 userauth method name is also part of the RESTauth mechanism 558 name. 560 The RESTauth mechanism name form for SSHv2 userauth methods, then, 561 is: ssh--. 563 The following RESTauth mechanisms are defined here: 565 o ssh-publickey-SHA-256 567 o ssh-hostbased-SHA-256 569 7.2.2. Nonces 571 The client and the server must each contribute 128-bit nonces. 573 7.2.3. "Session ID" 575 The ssh-publickey-SHA-256 and ssh-hostbased-SHA-256 mechanisms use 576 the following instead of a traditional SSHv2 session ID: 578 o SHA-256(channel_binding || server_nonce || client_nonce) 580 Here the is as per-[RFC5056]: the channel binding 581 type name, followed by the channel binding data (e.g., 'tls-server- 582 end-point' followed by the server EE certificate as sent in the 583 server's TLS Certificate message). 585 Note that use of channel binding when using SSHv2 mechanisms is 586 REQUIRED so as to defeat cut-n-paste attacks by weakly-authenticated 587 servers. 589 7.3. Adapting IKEv2 Authentication Mechanisms to RESTauth 591 [[anchor5: TBD.]] 593 7.3.1. Adapting IKEv2 Password Authenticated Connection Establishment 594 (PACE) to RESTauth 596 [[anchor6: TBD.]] 598 7.4. Using SASL Authentication Mechanisms with RESTauth 600 Simple Authentication and Security Layers (SASL) [RFC4422] is a 601 simple, pluggable framework for authentication mechanisms. 603 To use a SASL mechanism in RESTauth just prefix "SA-" to the SASL 604 mechanism name and use that as the RESTauth mechanism name. If the 605 SASL mechanism is server-initiated then the server's challenge is 606 sent in the server's WWW-Authenticate header value as described 607 above. All other SASL authentication messages are exchanged as 608 described above (i.e., via POSTs, first to the login URI, then to the 609 session URI, with response messages as the new representation of the 610 session resource). 612 The HTTP status code functions as the application's outcome of 613 authentication message. If SASL succeeds but authorization fails 614 then the server should respond with a 401 status code to the POST of 615 the final SASL authentication message from the client. 617 The server's WWW-Authenticate header values function as the mechanism 618 listing operation. SASL security considerations [RFC4422] [RFC5801] 619 apply (particularly regarding the negotiation of channel binding 620 support). 622 7.4.1. Using SCRAM in RESTauth 624 The Salted Challenge Response Authentication Mechanism (SCRAM) 625 [RFC5802] is a DIGEST-like mechanism for SASL. Nothing special is 626 needed to use SCRAM versus any other SASL mechanism, except for a 627 round trip optimized form of SCRAM, if we decide to pursue that (see 628 Section 7.4.2). 630 The following figure shows what SCRAM in RESTauth looks like. Note 631 that the resource representations are taken verbatim from [RFC5802]. 633 C->S: GET /some-resources HTTP/1.1 634 Host: A.example 636 S->C: HTTP/1.1 401 Unauthorized 637 WWW-Authenticate: RA-SA-SCRAM-SHA-1 \ 638 http://A.example/rest-sa-scram \ 639 s=session-ID,MIC r=no 640 WWW-ChannelBinding-Types: tls-server-end-point 642 C->S: POST /rest-sa-scram HTTP/1.1 643 Host: A.example 644 WWW-ChannelBinding-Type: tls-server-end-point 645 WWW-SessionBinding-Type: session-ID 646 Content-Type: application/octet-stream 647 Content-Length: nnn 649 n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL 651 S->C: HTTP/1.1 201 652 Location http://A.example/restauth-9d0af5f680d4ff46 653 Content-Type: application/octet-stream 654 Content-Length: nnn 656 r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j, 657 s=QSXCR+Q6sek8bf92,i=4096 659 C->S: POST /restauth-9d0af5f680d4ff46 HTTP/1.1 660 Host: A.example 661 Content-Type: application/octet-stream 662 Content-Length: nnn 664 c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j, 665 p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts= 667 S->C: HTTP/1.1 200 668 Content-Type: application/octet-stream 669 Content-Length: nnn 671 v=rmF9pqV8S7suAoZWja4dJRkFsKQ= 673 Figure 2: RESTauth w/ SCRAM 675 7.4.2. Using SCRAM with Round Trip Optimization in RESTauth 677 [[anchor7: This might work by having the authentication ID function 678 as the salt and the server offering a challenge nonce and iteration 679 count in its optimistic challenge. However, it's not clear that a 680 round trip optimized form of SCRAM is desirable.]] 681 The following figure shows what a round trip optimized RESTauth w/ 682 SCRAM exchange might look like. 684 [[anchor8: NOTE: SCRAM was not intended to be used this way. In 685 particular this approach forces the use of an algorithmic salt, to be 686 derived only from either the username or the username and the 687 server's name (or else to be remembered by the user, but that's not 688 likely).]] 690 C->S: GET /some-resources HTTP/1.1 691 Host: A.example 693 S->C: HTTP/1.1 401 Unauthorized 694 WWW-Authenticate: RA-SA-SCRAM-SHA-1 \ 695 http://A.example/rest-sa-scram \ 696 s=session-ID,MIC r=no \ 697 r=fyko+d2l...JY1ZVvWVs7j,i=4096 698 WWW-ChannelBinding-Types: tls-server-end-point 700 C->S: POST /rest-sa-scram HTTP/1.1 701 Host: A.example 702 WWW-ChannelBinding-Type: tls-server-end-point 703 WWW-SessionBinding-Type: session-ID 704 Content-Type: application/octet-stream 705 Content-Length: nnn 707 n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL, 708 c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j, 709 p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts= 711 S->C: HTTP/1.1 200 712 Content-Type: application/octet-stream 713 Content-Length: nnn 715 v=rmF9pqV8S7suAoZWja4dJRkFsKQ= 717 Figure 3: RESTauth w/ round trip optimized SCRAM 719 7.5. Using GSS-API Authentication Mechanisms with RESTauth 721 The Generic Security Services Application Programming Interface (GSS- 722 API) [RFC2743] is another pluggable mechanism framework. Any GSS-API 723 mechanism that supports channel binding [RFC5056] can be used as SASL 724 mechanisms via the "SASL/GS2" bridge [RFC5801]. This includes the 725 Kerberos V5 GSS-API mechanism [RFC4121]. 727 8. IANA Considerations 729 TBD (header registrations, ...) 731 9. Security Considerations 733 This entire document deals with security considerations. [Add more, 734 like about channel binding, same-origin-like constraints on the login 735 and session absolute URIs', ...] 737 10. TODO 739 [[anchor9: Add references (to HTTP/2.0, CGI/fCGI, ...).]] 741 [[anchor10: Describe MAC session binding option and replay protection 742 in detail. Describe how to extract keys for MAC keying from SASL/ 743 GSS/PACE.]] 745 [[anchor11: Figure out how to adapt IKEv2 password-based methods to 746 RESTauth. This may not be worthwhile (since each method tends to 747 depend heavily on the entire IKEv2 framework in ways that add 748 messaging that we'd not need in RESTauth).]] 750 11. References 752 11.1. Normative References 754 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 755 Requirement Levels", BCP 14, RFC 2119, March 1997. 757 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 758 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 759 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 761 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 762 Leach, P., Luotonen, A., and L. Stewart, "HTTP 763 Authentication: Basic and Digest Access Authentication", 764 RFC 2617, June 1999. 766 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 767 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 769 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 770 Channels", RFC 5056, November 2007. 772 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 773 for TLS", RFC 5929, July 2010. 775 11.2. Informative References 777 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 778 April 2010. 780 [I-D.ietf-oauth-v2] 781 Hardt, D., "The OAuth 2.0 Authorization Framework", 782 draft-ietf-oauth-v2-31 (work in progress), August 2012. 784 [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and 785 Security Layer (SASL)", RFC 4422, June 2006. 787 [RFC5802] Newman, C., Menon-Sen, A., Melnikov, A., and N. Williams, 788 "Salted Challenge Response Authentication Mechanism 789 (SCRAM) SASL and GSS-API Mechanisms", RFC 5802, July 2010. 791 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 792 Authentication Protocol", RFC 4252, January 2006. 794 [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based 795 Kerberos and NTLM HTTP Authentication in Microsoft 796 Windows", RFC 4559, June 2006. 798 [RFC6631] Kuegler, D. and Y. Sheffer, "Password Authenticated 799 Connection Establishment with the Internet Key Exchange 800 Protocol version 2 (IKEv2)", RFC 6631, June 2012. 802 [RFC2743] Linn, J., "Generic Security Service Application Program 803 Interface Version 2, Update 1", RFC 2743, January 2000. 805 [RFC5801] Josefsson, S. and N. Williams, "Using Generic Security 806 Service Application Program Interface (GSS-API) Mechanisms 807 in Simple Authentication and Security Layer (SASL): The 808 GS2 Mechanism Family", RFC 5801, July 2010. 810 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos 811 Version 5 Generic Security Service Application Program 812 Interface (GSS-API) Mechanism: Version 2", RFC 4121, 813 July 2005. 815 Author's Address 817 Nicolas Williams 818 Cryptonector, LLC 820 Email: nico@cryptonector.com