Network Working Group N. Williams
Internet-Draft Cryptonector
Intended status: Informational August 11, 2012
Expires: February 12, 2013
RESTful Authentication Pattern for the HyperText Transport Protocol
(HTTP)
draft-williams-http-rest-auth-00
Abstract
This document proposes a "RESTful" pattern of authentication for
HTTP/1.0, 1.1, and 2.0. The existing 401 status code and WWW-
Authenticate header are used to indicate that authentication is
required and for negotiation purposes. The client POSTs an initial
authentication message to an indicated login URI, and reply messages
are returned as new representations of a session resource named by a
session URI.
This approach has a number of benefits: it can be implemented with or
without help from the HTTP stack, it can be universally implemented
on the server side using the Common Information Gateway (CGI) and
FastCGI, it results in a session Uniform Resource Identifier (URI)
that can be DELETEd to logout, it is completely orthogonal to any
HTTP "routers" and proxies, and it naturally (i.e., without changing
HTTP) handles multi-legged authentication mechanisms.
Among other features supported are: channel binding, an optional
round trip optimization for challenge/response mechanisms,
somecryptographic protection options for clients that don't use
Transport Layer Security (TLS), stronger authentication of servers/
services to users (where authentication mechanisms provide that) and
more.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
Williams Expires February 12, 2013 [Page 1]
Internet-Draft RESTful Authentication August 2012
material or to cite them other than as "work in progress."
This Internet-Draft will expire on February 12, 2013.
Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Williams Expires February 12, 2013 [Page 2]
Internet-Draft RESTful Authentication August 2012
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions used in this document . . . . . . . . . . . . 6
3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Negotiable Parameters . . . . . . . . . . . . . . . . . . 7
3.1.1. WWW-Authenticate Header Value Prefix Syntax . . . . . . . 8
3.1.2. WWW-ChannelBinding-Types Header . . . . . . . . . . . . . 8
3.1.3. WWW-ChannelBinding-Type Header . . . . . . . . . . . . . . 8
3.1.4. WWW-SessionType Header . . . . . . . . . . . . . . . . . . 9
3.1.5. WWW-ReplayProtection Header . . . . . . . . . . . . . . . 9
3.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 9
3.2.1. One Round Trip Optimization: Challenges Born in
WWW-Authenticate Headers . . . . . . . . . . . . . . . . . 9
3.3. Session Binding Types: Cookie, URI, and MAC . . . . . . . 10
3.3.1. The New WWW-Session-URI Header . . . . . . . . . . . . . . 10
3.3.2. The New WWW-Session-MAC Header . . . . . . . . . . . . . . 10
3.3.3. A MAC Trailer?? . . . . . . . . . . . . . . . . . . . . . 11
4. HTTP "Routing" and RESTauth . . . . . . . . . . . . . . . 12
5. Sample/Potential RESTauth Authentication Mechanisms . . . 13
5.1. Adapting SSHv2 Authentication Mechanisms to RESTauth . . . 13
5.1.1. Adaptinve SSHv2 'publickey userauth' to RESTauth . . . . . 13
5.1.2. Adaptinve SSHv2 'hostbased userauth' to RESTauth . . . . . 13
5.2. Adapting IKEv2 Authentication Mechanisms to RESTauth . . . 13
5.2.1. Adaptinve IKEv2 Password Authenticated Connection
Establishment (PACE) to RESTauth . . . . . . . . . . . . . 13
5.3. Using SASL Authentication Mechanisms with RESTauth . . . . 13
5.3.1. Using SCRAM in RESTauth . . . . . . . . . . . . . . . . . 13
5.3.2. Using SCRAM with Round Trip Optimization in RESTauth . . . 13
5.4. Using GSS-API Authentication Mechanisms with RESTauth . . 13
6. IANA Considerations . . . . . . . . . . . . . . . . . . . 14
7. Security Considerations . . . . . . . . . . . . . . . . . 15
8. TODO . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
9. References . . . . . . . . . . . . . . . . . . . . . . . . 17
Author's Address . . . . . . . . . . . . . . . . . . . . . 18
Williams Expires February 12, 2013 [Page 3]
Internet-Draft RESTful Authentication August 2012
1. Introduction
We propose a pattern for HTTP authentication mechanisms that, by
being "RESTful", obtains a number of benefits:
o compatibility with "HTTP routing" by making no assumptions that
related requests are sent over the same TCP/TLS connection;
o a "session URI" results that can be used to multiplex multiple
sessions onto the same TCP/TLS connections;
o a "session URI" results that can be DELETEd to effect logout;
o a "session URI" results that has better security semantics than
web cookies;
o the ability to refer to multiple sessions in one request wherever
such a concept might be useful;
o can be implemented by any application without changes being
required to any HTTP stack;
o can be implemented by the HTTP stack;
o on the server side this can be implemented entirely via CGI and
FastCGI;
o by its RESTful nature, multi-legged authentication message
exchanges are naturally handled without making any changes to
HTTP.
There are probably other benefits not listed above.
The rough outline of the protocol is quite simple: initial
authentication messages are POSTed to an agreed-upon or indicated
resource, which then results in a new resource being created with the
authentication reply message as the new resource's representation.
Thereafter any additional authentication message exchanges needed
(for multi-legged mechanisms) are POSTed to the new resource without
a new resource being created. The resource created by the POSTing of
the initial authentication mechanism identifies the resulting
session, and its URI is known as the session URI. Session URIs can
be used to multiplex multiple sessions over the same TCP/TLS
connections, implement logout, and share sessions across multiple
related servers.
Server-initiated authentication is also possible, whereby the server
sends a challenge (not much else can be sent of value in an initial
Williams Expires February 12, 2013 [Page 4]
Internet-Draft RESTful Authentication August 2012
authentication message from the server besides a challenge,
negotiation parameters, and, perhaps, a digital signature) in 401
errors in headers. If the server gives the client has a choice of
mechanisms and the client picks one where the server sent the initial
authentication message, then the client consumes that message and
POSTs subsequent ones to the agreed URI.
This document replaces [I-D.williams-rest-gss].
Williams Expires February 12, 2013 [Page 5]
Internet-Draft RESTful Authentication August 2012
2. Conventions used in this document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
Williams Expires February 12, 2013 [Page 6]
Internet-Draft RESTful Authentication August 2012
3. Protocol
The are very few normative protocol elements here besides the outline
given in Section 1. The normative protocol elements are:
o the form of the WWW-Authenticate header values for RESTauth
mechanisms;
o several new headers for advertising negotiable paramters that are
orthogonal to WWW-Authenticate;
o the POSTing of authentication messages from the client, with the
initial client authentication message going to either a pre-agreed
URI or to a URI named in the WWW-Authenticate headers;
o the creation of a session URI as a result of the initial POST, and
the subsequent POSTing of any additional authentication messages
to the session URI;
o the new session URI resource representation resulting from POSTs
being the server's response authentication message, if any;
o the DELETEion of session URIs as signalling logout;
o a new header for referencing session URIs in normal HTTP requests;
o the use of channel binding to TLS for session protection;
o the use of session keys as an option for integrity protection when
TLS is not used.
3.1. Negotiable Parameters
As can be seen in the ABNF in the preceding section, the server can
offer some negotiable parameters. These are:
o Mechanism names;
o Channel binding types;
o Session binding types;
o Replay protection;
Each WWW-Authenticate header value offers a single mechanism and
negotiable parameters for it. The WWW-ChannelBinding-Types header
allows the server to offer channel binding types.
Williams Expires February 12, 2013 [Page 7]
Internet-Draft RESTful Authentication August 2012
3.1.1. WWW-Authenticate Header Value Prefix Syntax
The ABNF for RESTauth WWW-Authenticate header values is as follows:
challenge = ( "RA-" mechname SP restauth-challenge )
mechname = TBD
restauth-challenge = ( login-uri SP session-types SP
replay-prot SP *1(mech-challenge) )
login-uri = absoluteURI
session-types = "s=" session-type /
(session-type ":" session-types)
session-type = "cookie" / "session-ID" / "MAC"
replay-prot = "r=" ("yes" / "no")
; TODO: add production for
; mech-challenge as a base64 string
; TODO: add MAC algorithm offers for alg agility
Figure 1: WWW-Authenticate ABNF
Figure 1
For a DIGEST-like mechanism it might look like "WWW-Authenticate: RA-
Digest-SHA-256 tls-server-end-point session-ID no HE4SgWGrd/
3+O7t16HqusA==". For example, the mechname for the Kerberos V5 GSS-
API mechanism might be "gss-krb5", and a WWW-Authenticate header
value for it might look like "WWW-Authenticate: RA-gss-krb5
http://foo.example/restauth-login tls-server-end-point session-ID
no".
Note that mechanisms that may be used include: GSS mechanisms, SASL
mechanisms, ad-hoc mechanisms, and so on.
3.1.2. WWW-ChannelBinding-Types Header
A new header is added by which servers MUST indicate which channel
binding [RFC5056] types -if any- they support for RESTauth
authentication; if the server does not support channel binding then
this header MUST be absent. The header is named WWW-ChannelBinding-
Types. Its values are channel binding types from the channel binding
type registry [RFC5929].
3.1.3. WWW-ChannelBinding-Type Header
A new header is added by which clients MUST indicate what channel
binding type they used when POSTing RESTauth authentication messages,
if any; if the client did not use channel binding then this header
MUST be absent. The header is named WWW-ChannelBinding-Type. Its
value is a channel binding type from the channel binding type
registry [RFC5929].
Williams Expires February 12, 2013 [Page 8]
Internet-Draft RESTful Authentication August 2012
3.1.4. WWW-SessionType Header
A new header is added by which clients MUST indicate what session
binding type they choose when POSTing RESTauth authentication
messages. The header is named WWW-SessionBinding-Type. Its value is
a session binding type as shown in Figure 1. This header MUST be
present in RESTauth authentication HTTP requests.
3.1.5. WWW-ReplayProtection Header
A new header is added by which clients MUST indicate whether they
desire replay protection when POSTing RESTauth authentication
messages. The header is named WWW-SessionBinding-Type. Its value is
"yes" or "no" (defaults to "no" if absent) as shown in Figure 1.
Replay protection is to be used only when TLS [RFC5246] is not, and
only if a session binding type of "MAC" is also requested.
3.2. Protocol Flow
RESTauth can be initiated by a client that knows a priori that it
needs to or wants to use RESTauth. Servers can also tell clients
that access to certain resources require authentication, possibly
including RESTauth mechanisms. When the server tells the client that
it must authenticate the server may also give the client an initial
authentication message for one or more mechanisms.
When the client knows a priori that it must authenticate then the
client MUST know the RESTauth login URI a priori as well, as well as
negotiable parameters, all of which the client might know from either
an application protocol specification, or from caching this
information from earlier RESTauth exchanges.
The server MUST use a 401 HTTP status code and WWW-Authenticate
headers to inform the client of the need to authenticate in order to
access a given resource. For RESTauth mechanisms the WWW-
Authenticate header values MUST conform to the ABNF given in
Section 3.1.1.
To proceed the client chooses a suitable authentication mechanism
(for which, presumably, it has credentials for a desired client
identity), possibly a channel binding type, possibly a session type,
and whether to use replay protection.
3.2.1. One Round Trip Optimization: Challenges Born in WWW-Authenticate
Headers
Some mechanisms may optimize the protocol flow by allowing the server
Williams Expires February 12, 2013 [Page 9]
Internet-Draft RESTful Authentication August 2012
to include challenges in the 401 response's WWW-Authenticate header
values. RESTauth allows this, but this feature is OPTIONAL: it must
always be possible for a client to initiate RESTauth without first
obtaining a challenge in a WWW-Authenticate header value, in which
case the client must incur an extra protocol leg by obtaining the
challenge (if it is at all necessary) in the server's reply to the
client's first authentication message. The reason that this
optimization is optional is to allow the implementation of RESTauth
mechanisms with frameworks that only support client-initiated
authentication.
A challenge may consist of a nonce, some encrypted or MACed nonce, a
timestamp, and even seemingly unrelated contents such as certificates
and digital signatures. The server MAY include a login URI in
challenge-laden WWW-Authenticate headers where the login URI encodes
secure state regarding the challenge.
3.3. Session Binding Types: Cookie, URI, and MAC
A notion of session binding type is added for binding HTTP requests
to specific RESTauth login sessions. Three types are provided:
Cookies The traditional web cookie approach to session binding;
Session URI HTTP requests carry a WWW-Session-URI header identifying
the session(s) (similar to cookies, but without all the associated
baggage);
MAC HTTP requests carry a WWW-Session-URI header identifying the
session(s) and a WWW-Session-MAC header that carries a MAC or MACs
binding the session URI(s) to the request.
3.3.1. The New WWW-Session-URI Header
A new HTTP header is added called WWW-Session-URI whose values
consist of session URIs. At least one session URI MUST be included.
Each session URI is an absoluteURI. Session URIs MUST NOT have
unescaped commas (',') embedded in them. Servers MAY fail to
implement support for multiple session URIs being referenced by a
single request, in which case they MUST answer with error code <TBD>.
Servers MUST validate the session URI before processing the request;
if the session URI is invalid the server MUST respond with a 401 (or
TBD?) status code.
3.3.2. The New WWW-Session-MAC Header
[[anchor1: Describe the header, its values, algorithm agility, and
what the MAC is to be taken over. Note too that this cannot apply to
Williams Expires February 12, 2013 [Page 10]
Internet-Draft RESTful Authentication August 2012
request contents as we have to consider chunking, and besides, a MAC
of contents really has to go as a trailer, not a header.]]
3.3.3. A MAC Trailer??
[[anchor2: ...]]
Williams Expires February 12, 2013 [Page 11]
Internet-Draft RESTful Authentication August 2012
4. HTTP "Routing" and RESTauth
It is common to deploy HTTP services with load-balanced servers
behind a load balancer and TLS concentrator. Other techniques may
also result in a multiplicity of servers acting on behalf of a single
service. The load balancers may even behave like routers and route
HTTP requests to the same server for all requests in a single
connection, or even route HTTP requests according to the verb and
resource. It helps to be able to have a notion of authenticated
sessions that can be referenced by all servers responding to a given
service name.
The server end of a RESTauth authentication message exchange may be
terminated by one server, by many servers sharing session state (via
the resources named by session URIs), or by a server-side HTTP
router. Once a RESTauth session is established we assume that all
servers responding to the same service name will be able to access
the session resource, validate session URIs, and obtain keys for
computing and validating session binding MACs. Alternatively, the
router may take responsibility for session binding and signal
authorization information from the established session to the HTTP
servers behind the router (however, we do not here specify any
methods for such signalling).
By using REST for the authentication message exchange we allow this
disconnection between "session" and "connection", which therefore
facilitates "routing" of HTTP requests and even off-loading of
authentication and/or session binding to HTTP "routers".
This approach should be flexible enough for all existing
architectures for deploying HTTP services.
Williams Expires February 12, 2013 [Page 12]
Internet-Draft RESTful Authentication August 2012
5. Sample/Potential RESTauth Authentication Mechanisms
[[anchor3: TODO: Describe how to use or adapt a variety of
authentication mechanisms, from SSHv2, IKEv2, SASL, GSS-API, and
other frameworks, to gain a set of usable mechanisms quickly, both,
specification- and implementation-wise. Although I've not done this
yet, it seems likely to be quite simple to adapt all these
authentication mechanism types to RESTauth.]]
5.1. Adapting SSHv2 Authentication Mechanisms to RESTauth
5.1.1. Adaptinve SSHv2 'publickey userauth' to RESTauth
5.1.2. Adaptinve SSHv2 'hostbased userauth' to RESTauth
5.2. Adapting IKEv2 Authentication Mechanisms to RESTauth
5.2.1. Adaptinve IKEv2 Password Authenticated Connection Establishment
(PACE) to RESTauth
5.3. Using SASL Authentication Mechanisms with RESTauth
5.3.1. Using SCRAM in RESTauth
5.3.2. Using SCRAM with Round Trip Optimization in RESTauth
5.4. Using GSS-API Authentication Mechanisms with RESTauth
Williams Expires February 12, 2013 [Page 13]
Internet-Draft RESTful Authentication August 2012
6. IANA Considerations
TBD (header registrations, ...)
Williams Expires February 12, 2013 [Page 14]
Internet-Draft RESTful Authentication August 2012
7. Security Considerations
This entire document deals with security considerations. [Add more,
like about channel binding, same-origin-like constraints on the login
and session absolute URIs', ...]
Williams Expires February 12, 2013 [Page 15]
Internet-Draft RESTful Authentication August 2012
8. TODO
[[anchor4: Add references (to HTTP, CGI/fCGI, SSHv2, IKEv2, SASL,
GSS, PACE, ...).]]
[[anchor5: Describe MAC session binding option and replay protection
in detail.]]
[[anchor6: Add text to and complete sections describing how to use
various existing security mechanisms with RESTauth, such as SASL,
GSS-API, and other mechanisms.]]
[[anchor7: Add text to and complete sections describing mechanisms
for adapting to RESTauth SSHv2 publickey, SSHv2 host-based
authentication, IKEv2 methods, and other such authentication
mechanisms as a way of showcasing RESTauth.]]
Williams Expires February 12, 2013 [Page 16]
Internet-Draft RESTful Authentication August 2012
9. References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5056] Williams, N., "On the Use of Channel Bindings to Secure
Channels", RFC 5056, November 2007.
[RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings
for TLS", RFC 5929, July 2010.
[I-D.williams-rest-gss]
Williams, N., "RESTful Hypertext Transfer Protocol
Application-Layer Authentication Using Generic Security
Services", draft-williams-rest-gss-02 (work in progress),
July 2012.
Williams Expires February 12, 2013 [Page 17]
Internet-Draft RESTful Authentication August 2012
Author's Address
Nicolas Williams
Cryptonector, LLC
Email: nico@cryptonector.com
Williams Expires February 12, 2013 [Page 18]