idnits 2.17.1 draft-williams-rest-gss-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 contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 2, 2012) is 4339 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) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-09) exists of draft-ietf-abfab-gss-eap-07 -- Obsolete informational reference (is this intentional?): RFC 4013 (Obsoleted by RFC 7613) -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 3 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: Standards Track June 2, 2012 5 Expires: December 4, 2012 7 RESTful Hypertext Transfer Protocol Application-Layer Authentication 8 Using Generic Security Services 9 draft-williams-rest-gss-01 11 Abstract 13 This document describes a method for application-layer authentication 14 in Hypertext Transfer Protocol (HTTP) applications using Generic 15 Security Services Application Programming Interface (GSS-API) 16 mechanisms via, for simplicity, the Simple Authentication and 17 Security Layers (SASL) mechanism bridge known as "GS2". This 18 approach to authentication allows for pluggability, mutual 19 authentication, and channel binding, all with no changes to HTTP nor 20 the Transport Layer Security (TLS). 22 We hope that the use of mutual authentication and channel binding at 23 the application layer will make phishing more difficult. We hope 24 that the use of authentication at the application layer will make 25 REST-GSS deployable. 27 Status of this Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on December 4, 2012. 44 Copyright Notice 46 Copyright (c) 2012 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 This document may contain material from IETF Documents or IETF 60 Contributions published or made publicly available before November 61 10, 2008. The person(s) controlling the copyright in some of this 62 material may not have granted the IETF Trust the right to allow 63 modifications of such material outside the IETF Standards Process. 64 Without obtaining an adequate license from the person(s) controlling 65 the copyright in such materials, this document may not be modified 66 outside the IETF Standards Process, and derivative works of it may 67 not be created outside the IETF Standards Process, except to format 68 it for publication as an RFC or to translate it into languages other 69 than English. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 74 1.1. On Application-Layer Authentication Services . . . . . . . 5 75 1.2. Conventions used in this document . . . . . . . . . . . . 5 76 1.3. GSS-API and SASL Primer . . . . . . . . . . . . . . . . . 5 77 1.4. Channel Binding Primer . . . . . . . . . . . . . . . . . . 7 78 1.5. Glossary . . . . . . . . . . . . . . . . . . . . . . . . . 7 79 2. The Protocol . . . . . . . . . . . . . . . . . . . . . . . 9 80 2.1. Authentication Message Format . . . . . . . . . . . . . . 10 81 2.1.1. ABNF for Initial Authentication Message Header . . . . . . 10 82 2.2. Authentication State Cookies . . . . . . . . . . . . . . . 11 83 2.3. Target Service Naming . . . . . . . . . . . . . . . . . . 11 84 2.4. Authorization ID Form . . . . . . . . . . . . . . . . . . 12 85 2.5. Mechanism, Channel Binding Type, and Other Negotiation . . 12 86 2.6. Session Status Representation . . . . . . . . . . . . . . 13 87 2.7. Session Binding via MIC Tokens . . . . . . . . . . . . . . 13 88 2.8. Alternative Session Binding Options . . . . . . . . . . . 14 89 2.9. Server Indication of Authentication Requirement . . . . . 15 90 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 15 91 3.1. Server Decides When to Authenticate . . . . . . . . . . . 15 92 3.2. Mechanism and Other Negotiation . . . . . . . . . . . . . 15 93 3.3. Login, Session, and Logout, with SCRAM . . . . . . . . . . 16 94 4. Implementation and Deployment Considerations . . . . . . . 17 95 4.1. Desired GSS-API Extensions . . . . . . . . . . . . . . . . 18 96 5. IANA Considerations . . . . . . . . . . . . . . . . . . . 18 97 6. Security Considerations . . . . . . . . . . . . . . . . . 18 98 6.1. User Interface and Scripting Interface Recommendations . . 20 99 6.2. Platform Integration . . . . . . . . . . . . . . . . . . . 21 100 6.3. Anti-Phishing . . . . . . . . . . . . . . . . . . . . . . 21 101 7. References . . . . . . . . . . . . . . . . . . . . . . . . 21 102 7.1. Normative References . . . . . . . . . . . . . . . . . . . 21 103 7.2. Informative References . . . . . . . . . . . . . . . . . . 22 104 Author's Address . . . . . . . . . . . . . . . . . . . . . 23 106 1. Introduction 108 Hypertext transfer Protocol (HTTP) [RFC2616] applications often 109 require authentication and related security services. These 110 applications have a plethora of odd choices for authentication 111 functioning at various different network layers. For example: 112 Transport Layer Security (TLS) [RFC5246] with pre-shared secret keys 113 (PSK), TLS with user certificates [RFC5280], HTTP Basic and Digest 114 authentication, HTTP/Negotiate, posting of HTML forms with usernames 115 and passwords filled in, and various methods based on passing tokens 116 via HTTP redirection, such as OAuth and OpenID [add references]. 118 All the authentication methods currently available to HTTP 119 applications leave something to be desired. For example these 120 authentication methods operate at various different network layers, 121 making abstraction of security services particularly difficult. 122 Another problem is the lack of a secure method of tying all of a 123 logged-in session's HTTP requests and responses to the session, with 124 most browser-based applications using "cookies". 126 We propose an alternative method of authentication that operates at 127 the application layer, and which provides applications with access to 128 a large number of actual security mechanisms. This method is based 129 on an exchange of authentication messages via HTTP POST to either a 130 well-known URI or to a URI indicated by the server or agreed a 131 priori. These authentication messages are mostly those of mechanisms 132 defined for the GSS-API [RFC2743]. Channel binding [RFC5056] is used 133 to bind authentication to TLS channels. Sessions are referenced via 134 a session URI that is indicated and authenticated in all requests for 135 a session. 137 The appeal of this solution is that a) it is build on off-the-shelf 138 technologies, b) requiring no modifications to either HTTP nor TLS, 139 c) that puts the application in control of authentication, and d) is 140 pluggable, all the while improving security for HTTP applications 141 whenever GSS mechanisms are used that provide mutual authentication. 143 The GSS-API, and through the "GS2" mechanism bridge, Simple 144 Authentication and Security Layers (SASL), enjoys a large and growing 145 number of security mechanisms, such as Kerberos V5 [RFC4121], SCRAM 146 [RFC5802], as well as a PKI-based mechanism [Add reference to PKU2U], 147 mechanisms based on OAuth [RFC5849], OpenID 148 [I-D.ietf-kitten-sasl-openid], SAML [I-D.ietf-kitten-sasl-saml], and 149 EAP [I-D.ietf-abfab-gss-eap], as well as various legacy mechanisms 150 such as NTLM [add reference] and a Diffie-Hellman mechanism [add 151 reference]. 153 Much of this document assumes some reader familiarity with the GSS- 154 API and SASL. To aid readers new to the GSS-API we provide a GSS 155 primer section, below. 157 1.1. On Application-Layer Authentication Services 159 The application layer is generally the most convenient for running 160 authentication services that applications require. On the other 161 hand, lower network layers have usually been more convenient for 162 implementing transport security. As a result many existing Internet 163 applications provide for both, but historically with no binding 164 between authentication and transport security, and often providing 165 two transport security options: one at the application layer, and one 166 below. [Add a list of representative SASL and GSS-API apps and 167 references, such as IMAP, POP3, SMTP/SUBMIT, LDAP, DNS (GSS-TSIG), 168 FTP, SSHv2, etcetera]. 170 The main disadvantage of application-layer authentication has been 171 that until recently many applications had to provide options for two 172 different "security layers": TLS (below the application layer) and 173 SASL (at the application layer), and sometimes both might be used at 174 the same time without any binding between them. The advent of 175 standards for channel binding [RFC5056] [RFC5929] makes the 176 combination of application-layer authentication with transport 177 security at lower layers realistic. Therefore we may now consider 178 solutions that we might once not have. 180 1.2. Conventions used in this document 182 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 183 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 184 document are to be interpreted as described in [RFC2119] . 186 1.3. GSS-API and SASL Primer 188 The GSS-API and SASL are both simple security frameworks providing 189 pluggable authentication services and transport protection facilities 190 to applications. By "pluggable" we mean that multiple "security 191 mechanisms" may be used by applications without requiring different 192 specifications for how the applications use each security mechanism. 193 Moreover, application programming interfaces (APIs) for GSS and SASL 194 can also be pluggable, requiring no changes to applications in order 195 for them to use new mechanisms. 197 A "security mechanism" is an authentication protocol that conforms to 198 the requirements of the framework in which it fits, and it provides 199 the requisite authentication facilities. There are many examples of 200 security mechanisms [add some]. 202 The two frameworks are sufficiently similar to each other that a 203 "bridge" has been added such that all GSS mechanisms may be used as 204 SASL mechanisms as well. This bridge is known as "GS2" [RFC5801]. 205 For the remainder of this section we'll describe SASL only as it 206 works with only GS2 mechanisms. 208 Authentication proceeds by having a client ("initiator", in GSS 209 terminology) send an initial authentication message ("security 210 context token", in GSS terminology). The server ("acceptor") 211 consumes said token and produces one of three results -success, 212 failure, or "continue needed"-, as well as, possibly, a message to 213 return to the client. The security mechanism may require an 214 arbitrary number of security context tokens be exchanged, always in a 215 synchronous fashion, until ultimate success or failure. Upon success 216 the peers are said to have a fully-established security context, 217 which may then be used to provide security services such as 218 encryption. 220 In SASL the server may be the one to initiate the authentication 221 message exchange, but, when using GSS mechanisms via the GS2 bridge 222 it will always be the client that initiates the exchange. SASL also 223 requires that the application define an "outcome of authentication 224 message", which is distinct from any such message that the mechanism 225 may provide. 227 Both frameworks allow mechanisms to provide facilities for 228 application data transport protection -- "security layers", in SASL 229 terminology. SASL's security layers are stream oriented (requiring 230 ordered delivery), while GSS' are message oriented (allowing out-of- 231 order delivery), and thus the GSS-API's security layers facilities 232 are the more general ones. The GSS-API provides two methods of 233 protecting application data: "wrap tokens" and "message integrity 234 check (MIC) tokens". Wrap tokens bear application data within them, 235 while MIC tokens do not. Thus wrap tokens may provide encryption 236 ("confidentiality protection"), while MIC tokens only provide 237 integrity protection. MIC tokens are very similar to HMAC -- readers 238 should think of HMAC output with a header affixed to both, the HMAC 239 output and the input. 241 The GSS-API also provides a keyed pseudo-random function (PRF) 242 [RFC4401] for keying any application's non-standard security layers, 243 if any. 245 SASL application protocols almost all have an option to use TLS, 246 therefore SASL's security layers are now eschewed in favor of using 247 TLS (with channel binding -- see below). Not all GSS-API application 248 have an option to use a separate system for transport security, thus 249 GSS applications continue to use the GSS-API's transport security 250 facilities. 252 1.4. Channel Binding Primer 254 Channel binding is a method for composing two or more end-to-end 255 security facilities such that one facility is used to show that the 256 end-points of the other are logically the same as those of the first. 257 This allows applications to perform authentication at the application 258 layer while leaving transport protection to a lower layer (e.g., TLS) 259 without compromising security. 261 There are two key aspects to channel binding: a) "channels" (lower 262 layers) must export "channel bindings data" that are 263 cryptographically bound to the channel, and b) authentication 264 mechanisms must be able to consume channel bindings data to ensure 265 that those channel bindings data are seen to be the same by both end- 266 points of the authentication mechanism. 268 There exists a specification for TLS channel bindings data: RFC5929 269 [RFC5929]. 271 Most GSS-API and SASL/GS2 mechanisms support channel binding. 273 An application that supports a TLS channel for transport protection, 274 and application-layer authentication-layer authentication using the 275 GSS-API or SASL/GS2 can perform channel binding to ensure that the 276 application-layer and TLS-layer end-points are the same -- that there 277 is no unauthorized man-in-the-middle (MITM) below the application 278 layer. (An authorized MITM might be an authorized proxy.) This is 279 quite simple: first establish a TLS connection, then extract its 280 channel bindings data, then initiate GSS or SASL/GS2 authentication 281 using those channel bindings data as a channel binding input -- if 282 authentication succeeds, then the TLS channel is bound into the GSS 283 or SASL/GS2 authentication. 285 1.5. Glossary 287 This section is purely INFORMATIVE, being intended to inform readers 288 who are not familiar with SASL and the GSS-API. Implementors should 289 refer to the relevant RFCs. 291 Application protocol 292 The protocol that is at the top of the protocol stack, such as, 293 for example, IMAP, LDAP, WebDAV, etcetera [Add lots of 294 references]. 296 Authentication 297 A process by which one or more parties are identify themselves and 298 prove (for some value of "prove") their identities to other 299 parties. 301 Authentication message 302 In SASL this this refers to an opaque message to be exchanged 303 during authentication and which should carry authentication 304 information, possibly (likely) cryptographic in nature. 306 Channel 307 A security facility providing secure, end-to-end transport of 308 application data. For example: TLS. 310 Channel binding 311 A method of ensuring that the logical end-points of one secure 312 channel are the same as those of another channel at a lower 313 network layer. 315 GS2 316 An adaptation of GSS-API mechanisms to SASL. As SASL originally 317 had such an adaptation, we now term that original adaptation "GS1" 318 and the new adaptation is "GS2". GS2 is significantly simpler 319 than GS1, provides channel binding (whereas GS1 did not), and 320 requires one fewer round-trip for its authentication message 321 exchange than GS1 does. GS2's simplicity stems from replacing a 322 binary header required by the GSS-API with a text header, as well 323 as not requring the use of any per-message tokens. 325 GSS 326 Generic Security Services. An abstraction around security 327 mechanisms involving two entities (a client and a server, 328 effectively, though a mechanism is allowed to use trusted third 329 parties). 331 MIC token 332 Message Integrity Check. A per-message token providing integrity 333 protection to application data. A MIC token does not carry 334 application data within it. See also per-message tokens. 336 Outcome of authentication message 337 SASL requires that applications define, for themselves, a message 338 known as the "outcome of authentication message", which should 339 carry at least a bit of information indicating whether 340 authentication succeeded or failed. This is distinct from any 341 such outcome of authentication messages in security mechanisms 342 (which the GSS-API effectively requires, at least for 343 authentication success) in that it also indicates success of 344 authorization of the authenticated client entity to the requested 345 authorization ID (if any) on the target service. 347 Per-message tokens 348 An octet string ("token") emitted, and consumed, by the GSS-API, 349 and bearing or authenticating application data, with cryptographic 350 integrity protection and, optionally, confidentiality protection. 351 There are two types of per-message tokens: MIC tokens, and wrap 352 tokens, only the latter of which bears application data. Per- 353 message tokens may include headers with data, with cryptographic 354 integrity protection and, optionally, confidentiality protection. 356 SASL 357 Simple Authenication and Security Layers (SASL) is a framework for 358 authentication and transport security for applications. SASL 359 supports many security mechanisms, including all GSS mechanisms 360 via the "GS2" bridge. 362 Security mechanism 363 A security mechanism is a protocol that defines an authentication 364 message (or "security context token") exchange for authenticating 365 one or two principals (a client and a server). A security 366 mechanism may also provide for key exchange and transport security 367 facilities. Examples include [list some]. 369 Security context 370 A security context is the shared secret session keys and 371 authenticated peer names that results from an authentication 372 message exchange between two parties. 374 Security context token 375 An opaque octet string that is to be sent by the application to a 376 peer as part of the act of authentication and security context 377 establishment. See also authentication message. 379 Wrap token 380 A wrap token is a per-message token that bears application data, 381 providing integrity protection to it, and possibly confidentiality 382 protection as well. See also per-message tokens. 384 2. The Protocol 386 At some point the client application determines that REST-GSS 387 authentication is required. How the client does this is discussed in 388 a sub-section below, but for the purposes of this discussion, the 389 client MUST learn or know a URI that will be used to initiate REST- 390 GSS authentication. Once the client knows that REST-GSS 391 authentication is required the client begins by constructing an 392 initial message as described below, then it POSTs it to the agreed- 393 upon URI. 395 The server SHOULD respond to initial authentication messages with 396 either an error or a 201 response. If there is no error and there is 397 a response authentication message, it will be returned to the client 398 as the representation of the resource created and named in the 201 399 response, otherwise, if there is no error then the new resource will 400 have an empty representation. The new resource name shall be the 401 name of the REST-GSS session, known as the 'session URI'. 403 For security mechanisms that require multiple round-trips then 404 additional messages from the client SHALL be POSTed to the session 405 URI, and any response messages from the server will be returned in 406 200 results as the new representation of the session resource. 408 The server generally responds to all POSTs to the REST-GSS login and 409 session URIs with a 201 or a 200 status, respectively. Failure is 410 signalled by the authentication messages described below. 412 Any GETs of a valid session URI SHALL return a representation of the 413 status of that session, else the response to the GET SHALL be an 414 error. 416 A DELETE of the session URI logs the session out. 418 The requests and responses that make up a session are tied to the 419 session via the session URI, which is sent in a header. The requests 420 and responses that make up a session SHOULD be authenticated by a 421 Message Integrity Check (MIC) token taken over inputs such that the 422 request or response is bound to the session. 424 2.1. Authentication Message Format 426 The authentication messages from clients to servers SHALL be formed 427 as per SASL's [RFC4422] GSS-API bridge (known as "GS2") [RFC5801], 428 with the initial authentication message prefixed with a text header 429 indicating what options were selected. The reason for this is 430 simple: implementors who lack a GSS-API implementation will find it 431 simpler to implement certain mechanisms if the GS2 framework is used. 433 The authentication messages from servers to clients SHALL be formed 434 SASL GS2 authentication messages pre-fixed with a header indicating 435 authentication status. The header consists of a single byte: an 436 ASCII character 'S' (success), 'F' (failure), or 'C' (the server 437 expects more authentication messages from the client), followed by an 438 ASCII newline. 440 2.1.1. ABNF for Initial Authentication Message Header 442 As described above, the initial authentication message from the 443 client to the server must include a small text header described by 444 the following Augmented Backus-Naur Form (ABNF) [RFC5234]: 446 [Add ABNF for a header consisting of a) the selected SASL/GS2 447 mechanism name, b) the name of the channel binding type selected, c) 448 the session protection options selected, d) room for extensions. 449 -Nico] 451 2.2. Authentication State Cookies 453 REST-GSS application server implementations must build and preserve 454 authentication state via a "GSS security context". Clients must 455 identify such state in the case of security mechanisms that require 456 multiple authentication message round trips. The REST-GSS session 457 URI may suffice for this purpose. 459 Such state might, for example consist of a timestamp and a partially- 460 established security context handle. Some implementations might 461 serialize partially-established security contexts and store them 462 somewhere, including on the client. The timestamp would be used for 463 expiring old partially-established security contexts. The GSS-API 464 allows for serializing security contexts into something known as a 465 "exported security context token". Some GSS-API implementations 466 allow for exporting partially-established security contexts. 468 Some servers may benefit from being able to store such authentication 469 state temporarily on the client -- such servers MAY assign, in every 470 authentication response message when the server expects additional 471 authentication messages from the client. Such cookies, if present, 472 MUST be base64-encoded and MUST be set in a REST-GSS-AuthenCookie 473 response field, and the client MUST echo such a cookie, if present, 474 in the next authentication message. 476 Note that serialization of partially-established security contexts is 477 currently not a standard feature of the GSS-API, but it is available 478 in some implementations. Servers that lack this feature may need to 479 preserve authentication state in the form of an identifier for a 480 process that holds the GSS-API security context, and an opaque 481 security context handle, and then they must route all subsequent 482 authentication messages through that process. 484 2.3. Target Service Naming 486 When mutual authentication facilities are available the client SHOULD 487 set the target acceptor (service) name to be a GSS-API name of 488 GSS_C_NT_HOSTBASED_SERVICE, with the hostname portion of the name 489 being the name of the host to which the client is authenticating. 490 The service name SHOULD be set as required by the application, or, if 491 not specified, then to "HTTP". For example, "HTTP@foo.example". 493 [It'd be good to explore a form of domain-based service naming 494 without host naming. Thus one could login to a large site without 495 having to login to each of many services hosted by different hosts in 496 the same domain. -Nico] 498 2.4. Authorization ID Form 500 The form of the authorization ID, if any is supported, SHALL be 501 specified by the application. Applications that make no use of the 502 authorization ID SHOULD reject authentication attempts requesting any 503 non-empty authorization ID. 505 Applications that intend to use the SASL authorization ID feature 506 should specify a method of preparing the authorization ID, such as 507 SASLprep [RFC4013]. 509 2.5. Mechanism, Channel Binding Type, and Other Negotiation 511 The representation returned by a GET of the resource to which initial 512 authentication messages are POSTed MUST be as follows: 514 o [Add ABNF for a field/value list with fields for: 516 * SASL/GS2 mechanism list; 518 * supported channel binding type list; 520 * an indication of what session security facility the server 521 prefers (cookies or MICs, and if MICs, whether TLS must always 522 be used and, if not, whether the body of requests and responses 523 should be protected by the MICs); 525 * an indication of whether replay protection is required by the 526 server, in which case MIC tokens MUST be used, and they MUST be 527 taken over data that includes Request-Date and Request- 528 Nanoseconds header fields.] 530 Clients that don't know a priori what mechanism, channel binding 531 type, or session protection method to use, MUST GET this resource 532 prior to initiatin authentication. 534 If a channel binding type list is not advertised by the server then 535 the client SHOULD pick a channel binding type as agreed a priori. 536 Applications must specify any pre-agreed channel binding type 537 selection criteria. 539 In any case of ambiguity or failure to specify, the client SHOULD 540 pick the tls-server-end-point channel binding type [RFC5929] if a 541 server certificate was used to authenticate the server end-point of 542 the TLS channel, else the client SHOULD pick tls-unique. 544 2.6. Session Status Representation 546 The status of a session SHALL be obtained by a GET of the session 547 URI. The status of a session SHALL consist of: 549 o [Add an ABNF for a field/value list with the following elements: 551 * a boolean to indicate whether the session is fully established; 553 * a timestamp indicating hard expiration, if any; 555 * a relative time specification indicating what the session idle 556 timer, if any, is; 558 * possibly some items indicating authorization attributes of the 559 client, such as the SASL authorization ID selected or accepted 560 by the server, if any.] 562 2.7. Session Binding via MIC Tokens 564 MIC tokens are used to bind HTTP requests and responses to containing 565 sessions. Requests (and their responses) can be bound to more than 566 one session for session combination purposes. 568 [A word about MIC tokens: they are quite similar to HMAC [RFC2104]. 569 For simple GSS-API mechanisms they might be nothing more than an 570 HMAC, with, perhaps a header affixed to the application data that the 571 MIC is applied to.] 573 MIC tokens for requests are generated by applying GSS_Get_MIC() to a 574 a minimized form of the request containing only the following items: 576 o the request start line; 578 o the Host header field, if any; 580 o optionally a Request-Date field with the same value form as the 581 'Date' field (this field MUST be sent in the request as well if 582 present in the MIC input); 584 o optionally a Request-Nanoseconds field bearing a nanoseconds 585 component of the time at which the request was made, as an 586 unsigned integer in decimal, ASCII respresentation (e.g., 1234567) 587 (this field MUST be sent in the request as well if present in the 588 MIC input); 590 o a Channel-Binding field bearing the channel bindings data (base64- 591 encoded) of the channel over which the message is being sent 592 (note: the channel bindings should be prefixed with the channel 593 binding type as described in RFC5056, and prior to base64 594 encoding)), if there is a channel (this field MUST NOT be included 595 in the request); 597 o the request body if and only if there is no channel to bind to, 598 else an empty request body. 600 The request MIC is base64-encoded, prefixed with the session URI 601 (separated by an ASCII semi-colon) and placed in a header field named 602 REST-GSS-Request-MIC. Multiple MICs may be placed in this field, 603 separated by whitespace. [XXX Add ABNF for this! Also, add an 604 indication of what CB type is used in the request MIC token.] 606 The optional timestamp in the request SHOULD be used for replay 607 detection on the server side. GSS-API per-message token replay 608 detection facilities exist, but an implementation may not make it 609 easier to share a security context's replay state easily across 610 multiple processes or even servers in a cluster. 612 MIC tokens for responses are generated by applying GSS_Get_MIC() to a 613 a minimized form of the response containing only the following items: 615 o the request status line; 617 o the REST-GSS-Request-MIC from the request, with runs of whitespace 618 characters replaced with a single ASCII space. 620 o the response body if and only if there is no channel to bind to, 621 else an empty response body. 623 The response MIC is base64-encoded, prefixed with the session URI 624 (separated by an ASCII semi-colon) and placed in a header field named 625 REST-GSS-Response-MIC. Multiple MICs may be placed in this field, 626 separated by whitespace. 628 These MIC tokens are validated by calling GSS_Verify_MIC() with the 629 same input data as GSS_Get_MIC(). 631 2.8. Alternative Session Binding Options 633 [Add text describing the use of cookies instead of MIC tokens.] 635 [Add text describing a method of associating REST-GSS session URIs 636 with TLS session IDs instead of using MIC tokens on every request/ 637 response. This is only workable when the client's and server's HTTP/ 638 TLS stacks expose enough information to the application.] 640 2.9. Server Indication of Authentication Requirement 642 When the server wishes to indicate that the client must authenticate 643 in order to access a given resource, then the server MUST respond to 644 the client's HTTP request with either a redirection to a web page 645 with a 303 redirect to a login page (this in the case of browser 646 applications) or a TBD 4xx error indicating that access requires 647 REST-GSS login and, optionally directing the client to the REST-GSS 648 login URI by listing that URI in a response header field named 'REST- 649 GSS-Authenticate'. 651 3. Examples 653 3.1. Server Decides When to Authenticate 655 C->S: HTTP/1.1 GET /some/resource 656 Host: A.example 658 S->C: HTTP/1.1 303 http://A.example/login.html& 660 Authentication required indication browser apps 662 C->S: HTTP/1.1 GET /some/resource 663 Host: A.example 665 S->C: HTTP/1.1 4xx 666 REST-GSS-URI: http://A.example/rest-gss-login 668 Authentication required indication for non-browser apps 670 3.2. Mechanism and Other Negotiation 672 C->S: HTTP/1.1 GET /rest-gss-login 673 Host: A.example 675 S->C: HTTP/1.1 200 676 Content-Type: application/rest-gss-login 677 Content-Length: nnn 679 mechs: SCRAM-SHA-1-PLUS,GSS-KRB5-PLUS 680 channel-binding-types: tls-server-end-point 681 session-binding: MIC-CB, MIC-body 682 replay-protection: optional 684 Negotiation 686 3.3. Login, Session, and Logout, with SCRAM 688 The following example is shamefully stolen from RFC5802, and adapted 689 to REST-GSS. 691 C->S: HTTP/1.1 POST /rest-gss-login 692 Host: A.example 693 Content-Type: application/rest-gss-login 694 Content-Length: nnn 696 SCRAM-SHA-1,,MIC 697 n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL 699 S->C: HTTP/1.1 201 700 Location http://A.example/rest-gss-session-9d0af5f680d4ff46 701 Content-Type: application/rest-gss-login 702 Content-Length: nnn 704 C 705 r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j, 706 s=QSXCR+Q6sek8bf92,i=4096 708 C->S: HTTP/1.1 POST /rest-gss-session-9d0af5f680d4ff46 709 Host: A.example 710 Content-Type: application/rest-gss-login 711 Content-Length: nnn 713 c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j, 714 p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts= 716 S->C: HTTP/1.1 200 717 Content-Type: application/rest-gss-login 718 Content-Length: nnn 720 A 721 v=rmF9pqV8S7suAoZWja4dJRkFsKQ= 723 Authentication message exchange using SCRAM 724 without channel 725 binding 727 C->S: HTTP/1.1 GET /some/doc.html 728 Host: A.example 729 REST-GSS-Request-MIC: 730 http://A.example/rest-gss-session-9d0af5f680d4ff46 731 740 S->C: HTTP/1.1 200 741 Content-Type: text/html 742 Content-Length: nnn 744 746 Example request and response using MIC tokens 748 C->S: HTTP/1.1 DELETE /rest-...-session-9d0af5f680d4ff46 749 Host: A.example 750 REST-GSS-Request-MIC: 751 http://A.example/rest-gss-session-9d0af5f680d4ff46 752 761 S->C: HTTP/1.1 200 763 Example of session logout 765 4. Implementation and Deployment Considerations 767 It is possible to implement REST-GSS with no changes to HTTP 768 implementations, on the client and server sides both. [Hmmm, maybe 769 we should make sure not to add any new return codes! -Nico]. It is 770 also possible to implement REST-GSS with no changes to TLS 771 implementations, though it is preferable to use TLS implementations 772 that output channel bindings data [RFC5929]. 774 All that is required in order to implement REST-GSS is one or more 775 GSS-API security mechanisms, whether used directly or via an actual 776 GSS-API framework implementation. Note that an implementation of the 777 full GSS-API framework is _not_ required. A minimal implementation 778 of a security mechanism such as SCRAM [RFC5802] is feasible that 779 provides nothing like the API that is the GSS-API. 781 Similarly, a GS2 [RFC5801] implementation is required, but given how 782 simple GS2 is there's no need for a full-blown SASL [RFC4422] nor GS2 783 framework implementation. 785 The largest obstacle for REST-GSS implementation lies in the web 786 browser, in the case of browser-based applications: without a native 787 implementation of REST-GSS in the browser (or the platform, but 788 accessed via the browser), the only way to implement REST-GSS is by 789 implementing a security mechanism JavaScript [XXX Add reference. 790 -Nico]. Implementing security mechanisms in scripts downloaded as 791 needed from the same origin as the page that will use them presents a 792 number of obvious security considerations, but as a technology 793 demonstrator, this approach will work. 795 As for deployment, the availability of security mechanisms and 796 federations is critical. Work is in progress to produce federatable 797 security mechanisms for the GSS-API. In the meantime, there are 798 security mechanisms such as Kerberos V5 [RFC4121] and others, that 799 make deployment in the enterprise scale, if not the Internet scale, 800 an immediately available option. 802 4.1. Desired GSS-API Extensions 804 At least one GSS-API extension is desired, though not required: the 805 ability to export (serialize) partially-established security 806 contexts. It is possible to implement REST-GSS on the server without 807 this feature, but especially for clustered servers using multi-round- 808 trip security mechanisms, it would be much easier to implement where 809 this extension is available. 811 5. IANA Considerations 813 This document has IANA considerations: new HTTP fields, and, 814 possibly, new HTTP status codes. These need to be registered. 815 Registration information to-be-added. 817 6. Security Considerations 819 The security considerations of HTTP [RFC2616], TLS [RFC5246], the 820 GSS-API [RFC2743], SASL [RFC4422], and GS2 [RFC5801] apply. When 821 channel binding is used the security considerations of [RFC5056] and 822 [RFC5929] also apply. Some of the security considerations of HTTP 823 and TLS are addressed by the use of mutual authentication and channel 824 binding in REST-GSS. 826 REST-GSS provide a number of optional facilities, both by itself and 827 because the GSS-API itself provides optional facilities. These 828 facilities can provide excellent security to users and service 829 providers, particularly mutual authentication and channel binding, 830 which together can significantly strengthen the authentication of 831 services otherwise provided only by TLS. 833 Some GSS-API security mechanisms are not secure against eavesdroppers 834 or active attacks. Therefore REST-GSS applications MUST use TLS with 835 confidentiality protection to protect all REST-GSS authentication 836 message exchanges, and SHOULD require the use of a server certificate 837 [RFC5280] unless mutual authentication and channel binding are being 838 used. 840 REST-GSS applications SHOULD prefer security mechanisms that provide 841 for mutual authentication to ones that do not, and SHOULD use channel 842 binding to TLS whenever it's available. REST-GSS applications SHOULD 843 NOT, by default, use security mechanisms that do not support mutual 844 authentication or channel binding. REST-GSS applications that allow 845 the use of security mechanisms that do not provide mutual 846 authentication MUST require that the server be authenticated by a 847 server certificate [RFC5280]. 849 REST-GSS applications SHOULD use channel binding to TLS, using the 850 channel binding data of the TLS connection that will carry the 851 client's initial authentication message. 853 REST-GSS does not provide a confidentiality protection option. 854 Therefore REST-GSS applications MUST use TLS if confidentiality 855 protection is desired. 857 REST-GSS applications SHOULD use TLS if integrity protection is 858 desired. Where they do not use TLS then they SHOULD use MIC tokens 859 to protect the bodies of the requests and responses, not just the 860 HTTP method and URI. 862 REST-GSS applications SHOULD use MIC tokens instead of cookies to tie 863 requests to sessions. REST-GSS applications SHOULD use channel 864 binding to TLS for session requests. 866 REST-GSS applications that are sensitive to replays of requests 867 SHOULD use MIC tokens with Request-Date and Request-Nanoseconds 868 fields present in the data that the MIC is taken over, unless the 869 server supports tls-unique channel bindings, in which case the 870 application SHOULD NOT include Request-Date and Request-Nanoseconds 871 fields in the MIC data. But servers that have suitable GSS-API per- 872 message token replay detection implementations SHOULD NOT request 873 that Request-Date and Request-Nanoseconds header fields be used. 875 REST-GSS applications SHOULD use the extended GSS mechanism inquiry 876 API [RFC5587] to help select mechanisms that provide the features 877 required by the application. 879 While it is convenient to have servers decide when authentication is 880 required on the basis of the URIs being accessed by the client, this 881 can leak information. It is best to require authentication, or not, 882 for an entire site. 884 ... 886 6.1. User Interface and Scripting Interface Recommendations 888 User interface (UI) and scripting interfaces are out of scope for 889 this document. However, in the interest of seeding works-in- 890 progress, we describe some such UIs and scripting APIs here, in broad 891 strokes. 893 For browser-based applications we recommend the addition of an 894 element to the HTML DOM for rendering a "login" button on a web page 895 such that the user may activate it to initiate REST-GSS 896 authentication. Such a DOM element should include a URI to POST 897 initial authentication messages to. For non-browser applications we 898 recommend a similar UI. 900 For all REST-GSS applications we also recommend non-DOM element by 901 which the client may indicate REST-GSS login status to the user, as 902 well as by which the user may initiate a logout. The status 903 displayed to users of logged-in REST-GSS sessions should include 904 information such as: what security mechanism was used, the 905 authenticated client and server principal names, session protection 906 options, etcetera. 908 For scripting we recommend extensions to XMLHttpRequest that allows 909 the application to request a REST-GSS session URI as an output, 910 implying that a session will be logged in. We also recommend inputs 911 to XMLHttpRequest to specify what REST-GSS session to use, and/or a 912 REST-GSS login URI. An extension should be provided for inquiring 913 the status of a REST-GSS session. 915 Cross-site scripting note: browsers MUST apply same-origin-like 916 constraints to the REST-GSS target service names, if any, specified 917 by scripts downloaded from a site. 919 6.2. Platform Integration 921 [Add notes about platform integration. -Nico] 923 6.3. Anti-Phishing 925 [Add notes about how mutual authentication via federated security 926 mechanisms may reduce the scope of phishing attacks by effectively 927 adding a service whitelist of sorts. -Nico] 929 7. References 931 7.1. Normative References 933 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 934 Requirement Levels", BCP 14, RFC 2119, March 1997. 936 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 937 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 938 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 940 [RFC2743] Linn, J., "Generic Security Service Application Program 941 Interface Version 2, Update 1", RFC 2743, January 2000. 943 [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and 944 Security Layer (SASL)", RFC 4422, June 2006. 946 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 947 Channels", RFC 5056, November 2007. 949 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 950 Specifications: ABNF", STD 68, RFC 5234, January 2008. 952 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 953 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 955 [RFC5587] Williams, N., "Extended Generic Security Service Mechanism 956 Inquiry APIs", RFC 5587, July 2009. 958 [RFC5801] Josefsson, S. and N. Williams, "Using Generic Security 959 Service Application Program Interface (GSS-API) Mechanisms 960 in Simple Authentication and Security Layer (SASL): The 961 GS2 Mechanism Family", RFC 5801, July 2010. 963 [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings 964 for TLS", RFC 5929, July 2010. 966 7.2. Informative References 968 [I-D.ietf-abfab-gss-eap] 969 Hartman, S. and J. Howlett, "A GSS-API Mechanism for the 970 Extensible Authentication Protocol", 971 draft-ietf-abfab-gss-eap-07 (work in progress), May 2012. 973 [I-D.ietf-kitten-sasl-openid] 974 Lear, E., Tschofenig, H., Mauldin, H., and S. Josefsson, 975 "A SASL & GSS-API Mechanism for OpenID", 976 draft-ietf-kitten-sasl-openid-08 (work in progress), 977 February 2012. 979 [I-D.ietf-kitten-sasl-saml] 980 Wierenga, K., Lear, E., and S. Josefsson, "A SASL and GSS- 981 API Mechanism for SAML", draft-ietf-kitten-sasl-saml-09 982 (work in progress), February 2012. 984 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 985 Hashing for Message Authentication", RFC 2104, 986 February 1997. 988 [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names 989 and Passwords", RFC 4013, February 2005. 991 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos 992 Version 5 Generic Security Service Application Program 993 Interface (GSS-API) Mechanism: Version 2", RFC 4121, 994 July 2005. 996 [RFC4401] Williams, N., "A Pseudo-Random Function (PRF) API 997 Extension for the Generic Security Service Application 998 Program Interface (GSS-API)", RFC 4401, February 2006. 1000 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1001 Housley, R., and W. Polk, "Internet X.509 Public Key 1002 Infrastructure Certificate and Certificate Revocation List 1003 (CRL) Profile", RFC 5280, May 2008. 1005 [RFC5802] Newman, C., Menon-Sen, A., Melnikov, A., and N. Williams, 1006 "Salted Challenge Response Authentication Mechanism 1007 (SCRAM) SASL and GSS-API Mechanisms", RFC 5802, July 2010. 1009 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 1010 April 2010. 1012 Author's Address 1014 Nicolas Williams 1015 Cryptonector LLC 1017 Email: nico@cryptonector.com