REST-GSS.xml

<?xml version="5.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes" ?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc tocindent="no" ?>
<?rfc autobreaks="no" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
  <!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
  <!ENTITY rfc2104 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2104.xml'>
  <!ENTITY rfc2616 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml'>
  <!ENTITY rfc2743 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2743.xml'>
  <!ENTITY rfc4422 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4422.xml'>
  <!ENTITY rfc5056 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5056.xml'>
  <!ENTITY rfc5234 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml'>
  <!ENTITY rfc5246 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml'>
  <!ENTITY rfc5587 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5587.xml'>
  <!ENTITY rfc5801 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5801.xml'>
  <!ENTITY rfc5929 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5929.xml'>

  <!ENTITY rfc4013 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4013.xml'>
  <!ENTITY rfc4121 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4121.xml'>
  <!ENTITY rfc4401 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4401.xml'>
  <!ENTITY rfc5802 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5802.xml'>
  <!ENTITY rfc5280 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5280.xml'>
  <!ENTITY rfc5849 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5849.xml'>

  <!ENTITY gss-openid PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-kitten-sasl-openid'>
  <!ENTITY gss-saml PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-kitten-sasl-saml'>
  <!ENTITY gss-eap PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-abfab-gss-eap'>
]>


<rfc category="std" docName="draft-williams-rest-gss-01" ipr="pre5378Trust200902">
  <front>
    <title abbrev="REST-GSS">RESTful Hypertext Transfer Protocol Application-Layer Authentication Using Generic Security Services</title>

    <author fullname="Nicolas Williams" initials="N." surname="Williams">
      <organization abbrev="Cryptonector">Cryptonector LLC</organization>

      <address>
        <email>nico@cryptonector.com</email>
      </address>
    </author>

    <date day="2" month="June" year="2012" />

    <area>Security</area>

    <workgroup>NETWORK WORKING GROUP</workgroup>

    <keyword>Internet-Draft</keyword>

    <abstract>

      <t>This document describes a method for application-layer
        authentication in Hypertext Transfer Protocol (HTTP)
        applications using Generic Security Services Application
        Programming Interface (GSS-API) mechanisms via, for simplicity,
        the Simple Authentication and Security Layers (SASL) mechanism
        bridge known as "GS2".  This approach to authentication allows
        for pluggability, mutual authentication, and channel binding,
        all with no changes to HTTP nor the Transport Layer
        Security (TLS).</t>

      <t>We hope that the use of mutual authentication and channel
        binding at the application layer will make phishing more
        difficult.  We hope that the use of authentication at the
        application layer will make REST-GSS deployable.</t>

    </abstract>

  </front>

  <middle>

    <section title="Introduction">

      <t>Hypertext transfer Protocol (HTTP) <xref target='RFC2616'/>
        applications often require authentication and related security
        services.  These applications have a plethora of odd choices for
        authentication functioning at various different network layers.
        For example: Transport Layer Security (TLS) <xref
          target='RFC5246'/> with pre-shared secret keys (PSK), TLS with
        user certificates <xref target='RFC5280'/>, HTTP Basic and
        Digest authentication, HTTP/Negotiate, posting of HTML forms
        with usernames and passwords filled in, and various methods
        based on passing tokens via HTTP redirection, such as OAuth and
        OpenID [add references].</t>
      
      <t>All the authentication methods currently available to HTTP
        applications leave something to be desired.  For example these
        authentication methods operate at various different network
        layers, making abstraction of security services particularly
        difficult.  Another problem is the lack of a secure method of
        tying all of a logged-in session's HTTP requests and responses
        to the session, with most browser-based applications using
        "cookies".</t>

      <t>We propose an alternative method of authentication that
        operates at the application layer, and which provides
        applications with access to a large number of actual security
        mechanisms.  This method is based on an exchange of
        authentication messages via HTTP POST to either a well-known URI
        or to a URI indicated by the server or agreed a priori.  These
        authentication messages are mostly those of mechanisms defined
        for the GSS-API <xref target='RFC2743'/>.  Channel binding <xref
          target='RFC5056'/> is used to bind authentication to TLS
        channels.  Sessions are referenced via a session URI that is
        indicated and authenticated in all requests for a session.</t>

      <t>The appeal of this solution is that a) it is build on
        off-the-shelf technologies, b) requiring no modifications to
        either HTTP nor TLS, c) that puts the application in control of
        authentication, and d) is pluggable, all the while improving
        security for HTTP applications whenever GSS mechanisms are used
        that provide mutual authentication.</t>

      <t>The GSS-API, and through the "GS2" mechanism bridge, Simple
        Authentication and Security Layers (SASL), enjoys a large and
        growing number of security mechanisms, such as Kerberos V5 <xref
          target='RFC4121'/>, SCRAM <xref
          target='RFC5802'/>, as well as a PKI-based mechanism [Add
        reference to PKU2U], mechanisms based on OAuth <xref
          target='RFC5849'/>, OpenID <xref
          target='I-D.ietf-kitten-sasl-openid'/>, SAML <xref
          target='I-D.ietf-kitten-sasl-saml'/>, and EAP <xref
          target='I-D.ietf-abfab-gss-eap'/>, as well as various legacy
        mechanisms such as NTLM [add reference] and a Diffie-Hellman
        mechanism [add reference].</t>

      <t>Much of this document assumes some reader familiarity with the
        GSS-API and SASL.  To aid readers new to the GSS-API we provide
        a GSS primer section, below.</t>

      <section title="On Application-Layer Authentication Services">

        <t>The application layer is generally the most convenient for
          running authentication services that applications require.  On
          the other hand, lower network layers have usually been more
          convenient for implementing transport security.  As a result
          many existing Internet applications provide for both, but
          historically with no binding between authentication and
          transport security, and often providing two transport security
          options: one at the application layer, and one below.  [Add a
          list of representative SASL and GSS-API apps and references,
          such as IMAP, POP3, SMTP/SUBMIT, LDAP, DNS (GSS-TSIG), FTP,
          SSHv2, etcetera].</t>

        <t>The main disadvantage of application-layer authentication has
          been that until recently many applications had to provide
          options for two different "security layers": TLS (below the
          application layer) and SASL (at the application layer), and
          sometimes both might be used at the same time without any
          binding between them.  The advent of standards for channel
          binding <xref target='RFC5056'/> <xref target='RFC5929'/>
          makes the combination of application-layer authentication with
          transport security at lower layers realistic.  Therefore we
          may now consider solutions that we might once not have.</t>

      </section>

      <section title="Conventions used in this document">

        <t>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 <xref
            target="RFC2119"></xref> .</t>

      </section>

      <section title='GSS-API and SASL Primer'>

        <t>The GSS-API and SASL are both simple security frameworks
          providing pluggable authentication services and transport
          protection facilities to applications.  By "pluggable" we mean
          that multiple "security mechanisms" may be used by
          applications without requiring different specifications for
          how the applications use each security mechanism.  Moreover,
          application programming interfaces (APIs) for GSS and SASL can
          also be pluggable, requiring no changes to applications in
          order for them to use new mechanisms.</t>

        <t>A "security mechanism" is an authentication protocol that
          conforms to the requirements of the framework in which it
          fits, and it provides the requisite authentication
          facilities.  There are many examples of security mechanisms
          [add some].</t>

        <t>The two frameworks are sufficiently similar to each other
          that a "bridge" has been added such that all GSS mechanisms
          may be used as SASL mechanisms as well.  This bridge is known
          as "GS2" <xref target='RFC5801'/>.  For the remainder of this
          section we'll describe SASL only as it works with only GS2
          mechanisms.</t>

        <t>Authentication proceeds by having a client ("initiator", in
          GSS terminology) send an initial authentication message
          ("security context token", in GSS terminology).  The server
          ("acceptor") consumes said token and produces one of three
          results -success, failure, or "continue needed"-, as well as,
          possibly, a message to return to the client.  The security
          mechanism may require an arbitrary number of security context
          tokens be exchanged, always in a synchronous fashion, until
          ultimate success or failure.  Upon success the peers are said
          to have a fully-established security context, which may then
          be used to provide security services such as encryption.</t>

        <t>In SASL the server may be the one to initiate the
          authentication message exchange, but, when using GSS mechanisms
          via the GS2 bridge it will always be the client that initiates
          the exchange.  SASL also requires that the application define
          an "outcome of authentication message", which is distinct from
          any such message that the mechanism may provide.</t>

        <t>Both frameworks allow mechanisms to provide facilities for
          application data transport protection -- "security layers", in
          SASL terminology.  SASL's security layers are stream oriented
          (requiring ordered delivery), while GSS' are message oriented
          (allowing out-of-order delivery), and thus the GSS-API's
          security layers facilities are the more general ones.  The
          GSS-API provides two methods of protecting application data:
          "wrap tokens" and "message integrity check (MIC) tokens".
          Wrap tokens bear application data within them, while MIC
          tokens do not.  Thus wrap tokens may provide encryption
          ("confidentiality protection"), while MIC tokens only provide
          integrity protection.  MIC tokens are very similar to HMAC --
          readers should think of HMAC output with a header affixed to
          both, the HMAC output and the input.</t>

        <t>The GSS-API also provides a keyed pseudo-random function
          (PRF) <xref target='RFC4401'/> for keying any application's
          non-standard security layers, if any.</t>

        <t>SASL application protocols almost all have an option to use
          TLS, therefore SASL's security layers are now eschewed in
          favor of using TLS (with channel binding -- see below).  Not
          all GSS-API application have an option to use a separate
          system for transport security, thus GSS applications continue
          to use the GSS-API's transport security facilities.</t>

      </section>

      <section title='Channel Binding Primer'>

        <t>Channel binding is a method for composing two or more
            end-to-end security facilities such that one facility is
            used to show that the end-points of the other are logically
            the same as those of the first.  This allows applications to
            perform authentication at the application layer while
            leaving transport protection to a lower layer (e.g., TLS)
            without compromising security.</t>

        <t>There are two key aspects to channel binding: a) "channels"
            (lower layers) must export "channel bindings data" that are
            cryptographically bound to the channel, and b)
            authentication mechanisms must be able to consume channel
            bindings data to ensure that those channel bindings data are
            seen to be the same by both end-points of the authentication
            mechanism.</t>

        <t>There exists a specification for TLS channel bindings data:
            RFC5929 <xref target='RFC5929'/>.</t>

        <t>Most GSS-API and SASL/GS2 mechanisms support channel
            binding.</t>

        <t>An application that supports a TLS channel for transport
            protection, and application-layer authentication-layer
            authentication using the GSS-API or SASL/GS2 can perform
            channel binding to ensure that the application-layer and
            TLS-layer end-points are the same -- that there is no
            unauthorized man-in-the-middle (MITM) below the application
            layer.  (An authorized MITM might be an authorized
            proxy.)  This is quite simple: first establish a TLS
            connection, then extract its channel bindings data, then
            initiate GSS or SASL/GS2 authentication using those channel
            bindings data as a channel binding input -- if
            authentication succeeds, then the TLS channel is bound into
            the GSS or SASL/GS2 authentication.</t>

      </section>

      <section title='Glossary'>

        <t>This section is purely INFORMATIVE, being intended to inform
          readers who are not familiar with SASL and the GSS-API.
          Implementors should refer to the relevant RFCs.</t>

        <t>

          <list style='hanging' hangIndent='3'>

            <t hangText='Application protocol'><vspace/>The protocol
              that is at the top of the protocol stack, such as, for
              example, IMAP, LDAP, WebDAV, etcetera [Add lots of
              references].</t>

            <t hangText='Authentication'><vspace/>A process by which one
              or more parties are identify themselves and prove (for
              some value of "prove") their identities to other
              parties.</t>
 
            <t hangText='Authentication message'><vspace/>In SASL this
              this refers to an opaque message to be exchanged during
              authentication and which should carry authentication
              information, possibly (likely) cryptographic in nature.</t>

            <t hangText='Channel'><vspace/>A security facility providing
              secure, end-to-end transport of application data.  For
              example: TLS.</t>

            <t hangText='Channel binding'><vspace/>A method of ensuring
              that the logical end-points of one secure channel are the
              same as those of another channel at a lower network
              layer.</t>

            <t hangText='GS2'><vspace/>An adaptation of GSS-API
              mechanisms to SASL.  As SASL originally had such an
              adaptation, we now term that original adaptation "GS1" and
              the new adaptation is "GS2".  GS2 is significantly simpler
              than GS1, provides channel binding (whereas GS1 did not),
              and requires one fewer round-trip for its authentication
              message exchange than GS1 does.  GS2's simplicity stems
              from replacing a binary header required by the GSS-API
              with a text header, as well as not requring the use of any
              per-message tokens.</t>

            <t hangText='GSS'><vspace/>Generic Security Services.  An
              abstraction around security mechanisms involving two
              entities (a client and a server, effectively, though a
              mechanism is allowed to use trusted third parties).</t>

            <t hangText='MIC token'><vspace/>Message Integrity Check.  A
              per-message token providing integrity protection to
              application data.  A MIC token does not carry application
              data within it.  See also per-message tokens.</t>

            <t hangText='Outcome of authentication
              message'><vspace/>SASL requires that applications define,
              for themselves, a message known as the "outcome of
              authentication message", which should carry at least a bit
              of information indicating whether authentication succeeded
              or failed.  This is distinct from any such outcome of
              authentication messages in security mechanisms (which the
              GSS-API effectively requires, at least for authentication
              success) in that it also indicates success of
              authorization of the authenticated client entity to the
              requested authorization ID (if any) on the target
              service.</t>

            <t hangText='Per-message tokens'><vspace/>An octet string
              ("token") emitted, and consumed, by the GSS-API, and
              bearing or authenticating application data, with
              cryptographic integrity protection and, optionally,
              confidentiality protection.  There are two types of
              per-message tokens: MIC tokens, and wrap tokens, only the
              latter of which bears application data.  Per-message
              tokens may include headers with data, with cryptographic
              integrity protection and, optionally, confidentiality
              protection.</t>

            <t hangText='SASL'><vspace/>Simple Authenication and
              Security Layers (SASL) is a framework for authentication
              and transport security for applications.  SASL supports
              many security mechanisms, including all GSS mechanisms via
              the "GS2" bridge.</t>

            <t hangText='Security mechanism'><vspace/>A security
              mechanism is a protocol that defines an authentication
              message (or "security context token") exchange for
              authenticating one or two principals (a client and a
              server).  A security mechanism may also provide for key
              exchange and transport security facilities.  Examples
              include [list some].</t>

            <t hangText='Security context'><vspace/>A security context
              is the shared secret session keys and authenticated peer
              names that results from an authentication message exchange
              between two parties.</t>

            <t hangText='Security context token'><vspace/>An opaque
              octet string that is to be sent by the application to a
              peer as part of the act of authentication and security
              context establishment.  See also authentication
              message.</t>

            <t hangText='Wrap token'><vspace/>A wrap token is a
              per-message token that bears application data, providing
              integrity protection to it, and possibly confidentiality
              protection as well.  See also per-message tokens.</t>

          </list>

        </t>

      </section>

    </section>

    <section title="The Protocol">

      <t>At some point the client application determines that REST-GSS
        authentication is required.  How the client does this is
        discussed in a sub-section below, but for the purposes of this
        discussion, the client MUST learn or know a URI that will be
        used to initiate REST-GSS authentication.  Once the client knows
        that REST-GSS authentication is required the client begins by
        constructing an initial message as described below, then it
        POSTs it to the agreed-upon URI.</t>

      <t>The server SHOULD respond to initial authentication messages
        with either an error or a 201 response.  If there is no error
        and there is a response authentication message, it will be
        returned to the client as the representation of the resource
        created and named in the 201 response, otherwise, if there is no
        error then the new resource will have an empty representation.
        The new resource name shall be the name of the REST-GSS session,
        known as the 'session URI'.</t>

      <t>For security mechanisms that require multiple round-trips then
        additional messages from the client SHALL be POSTed to the
        session URI, and any response messages from the server will be
        returned in 200 results as the new representation of the session
        resource.</t>

      <t>The server generally responds to all POSTs to the REST-GSS
        login and session URIs with a 201 or a 200 status, respectively.
        Failure is signalled by the authentication messages described
        below.</t>

      <t>Any GETs of a valid session URI SHALL return a representation of
        the status of that session, else the response to the GET SHALL
        be an error.</t>

      <t>A DELETE of the session URI logs the session out.</t>

      <t>The requests and responses that make up a session are tied to the
        session via the session URI, which is sent in a header.  The
        requests and responses that make up a session SHOULD be
        authenticated by a Message Integrity Check (MIC) token taken
        over inputs such that the request or response is bound to the
        session.</t>

      <section title="Authentication Message Format">

        <t>The authentication messages from clients to servers SHALL be
          formed as per SASL's <xref target='RFC4422'/> GSS-API bridge
          (known as "GS2") <xref target='RFC5801'/>, with the initial
	  authentication message prefixed with a text header indicating
	  what options were selected.  The reason for this is simple:
	  implementors who lack a GSS-API implementation will find it
	  simpler to implement certain mechanisms if the GS2 framework
	  is used.</t>

        <t>The authentication messages from servers to clients SHALL be
          formed SASL GS2 authentication messages pre-fixed with a
          header indicating authentication status.  The header consists
          of a single byte: an ASCII character 'S' (success), 'F'
          (failure), or 'C' (the server expects more authentication
          messages from the client), followed by an ASCII newline.</t>

        <section title="ABNF for Initial Authentication Message Header">

          <t>As described above, the initial authentication message from
            the client to the server must include a small text header
            described by the following Augmented Backus-Naur Form (ABNF)
            <xref target='RFC5234'/>:</t>

          <t>[Add ABNF for a header consisting of a) the selected
            SASL/GS2 mechanism name, b) the name of the channel
            binding type selected, c) the session protection options
            selected, d) room for extensions. -Nico]</t>

        </section>

      </section>

      <section title="Authentication State Cookies">

        <t>REST-GSS application server implementations must build and
          preserve authentication state via a "GSS security context".
          Clients must identify such state in the case of security
          mechanisms that require multiple authentication message round
          trips.  The REST-GSS session URI may suffice for this
          purpose.</t>

        <t>Such state might, for example consist of a timestamp and a
          partially-established security context handle.  Some
          implementations might serialize partially-established security
          contexts and store them somewhere, including on the client.
          The timestamp would be used for expiring old
          partially-established security contexts.  The GSS-API allows
          for serializing security contexts into something known as a
          "exported security context token".  Some GSS-API
          implementations allow for exporting partially-established
          security contexts.</t>

        <t>Some servers may benefit from being able to store such
          authentication state temporarily on the client -- such servers
          MAY assign, in every authentication response message when the
          server expects additional authentication messages from the
          client.  Such cookies, if present, MUST be base64-encoded and
          MUST be set in a REST-GSS-AuthenCookie response field, and the
          client MUST echo such a cookie, if present, in the next
          authentication message.</t>

        <t>Note that serialization of partially-established security
          contexts is currently not a standard feature of the GSS-API,
          but it is available in some implementations.  Servers that
          lack this feature may need to preserve authentication state in
          the form of an identifier for a process that holds the GSS-API
          security context, and an opaque security context handle, and
          then they must route all subsequent authentication messages
          through that process.</t>

      </section>

      <section title="Target Service Naming">

        <t>When mutual authentication facilities are available the
          client SHOULD set the target acceptor (service) name to be a
          GSS-API name of GSS_C_NT_HOSTBASED_SERVICE, with the hostname
          portion of the name being the name of the host to which the
          client is authenticating.  The service name SHOULD be set
          as required by the application, or, if not specified, then to
          "HTTP".  For example, "HTTP@foo.example".</t>

        <t>[It'd be good to explore a form of domain-based service
          naming without host naming.  Thus one could login to a large
          site without having to login to each of many services hosted
          by different hosts in the same domain. -Nico]</t>

      </section>

      <section title="Authorization ID Form">

        <t>The form of the authorization ID, if any is supported, SHALL
          be specified by the application.  Applications that make no
          use of the authorization ID SHOULD reject authentication
          attempts requesting any non-empty authorization ID.</t>

        <t>Applications that intend to use the SASL authorization ID
          feature should specify a method of preparing the
          authorization ID, such as SASLprep <xref
            target='RFC4013'/>.</t>

      </section>

      <section title="Mechanism, Channel Binding Type, and Other Negotiation">

        <t>The representation returned by a GET of the resource to which
          initial authentication messages are POSTed MUST be as follows:

          <list style='symbols'>

            <t>[Add ABNF for a field/value list with fields for:

              <list style='symbols'>

                <t>SASL/GS2 mechanism list;</t>

                <t>supported channel binding type list;</t>

                <t>an indication of what session security facility the
                  server prefers (cookies or MICs, and if MICs, whether
                  TLS must always be used and, if not, whether the body
                  of requests and responses should be protected by the
                  MICs);</t>

                <t>an indication of whether replay protection is
                  required by the server, in which case MIC tokens MUST
                  be used, and they MUST be taken over data that
                  includes Request-Date and Request-Nanoseconds header
                  fields.]</t>

              </list>

            </t>

          </list>
          
        </t>

        <t>Clients that don't know a priori what mechanism, channel
          binding type, or session protection method to use, MUST GET
          this resource prior to initiatin authentication.</t>

        <t>If a channel binding type list is not advertised by the
          server then the client SHOULD pick a channel binding type as
          agreed a priori.  Applications must specify any pre-agreed
          channel binding type selection criteria.</t>

        <t>In any case of ambiguity or failure to specify, the client
          SHOULD pick the tls-server-end-point channel binding type
          <xref target='RFC5929'/> if a server certificate was used to
          authenticate the server end-point of the TLS channel, else the
          client SHOULD pick tls-unique.</t>

      </section>

      <section title="Session Status Representation">

        <t>The status of a session SHALL be obtained by a GET of the
          session URI.  The status of a session SHALL consist of:

          <list style='symbols'>

            <t>[Add an ABNF for a field/value list with the following
              elements:

              <list style='symbols'>

                <t>a boolean to indicate whether the session is fully
                  established;</t>

                <t>a timestamp indicating hard expiration, if any;</t>

                <t>a relative time specification indicating what the
                  session idle timer, if any, is;</t>

                <t>possibly some items indicating authorization
                  attributes of the client, such as the SASL
                  authorization ID selected or accepted by the server,
                  if any.]</t>

              </list>

            </t>

          </list>

        </t>

      </section>

      <section title="Session Binding via MIC Tokens">

        <t>MIC tokens are used to bind HTTP requests and responses to
          containing sessions.  Requests (and their responses) can be
          bound to more than one session for session combination
          purposes.</t>

        <t>[A word about MIC tokens: they are quite similar to HMAC
          <xref target='RFC2104'/>.  For simple GSS-API mechanisms they
          might be nothing more than an HMAC, with, perhaps a header
          affixed to the application data that the MIC is applied
          to.]</t>

        <t>MIC tokens for requests are generated by applying
          GSS_Get_MIC() to a a minimized form of the request
          containing only the following items:

          <list style='symbols'>

            <t>the request start line;</t>

            <t>the Host header field, if any;</t>

            <t>optionally a Request-Date field with the same value form
              as the 'Date' field (this field MUST be sent in the
              request as well if present in the MIC input);</t>

            <t>optionally a Request-Nanoseconds field bearing a
              nanoseconds component of the time at which the request was
              made, as an unsigned integer in decimal, ASCII
              respresentation (e.g., 1234567) (this field MUST be sent
              in the request as well if present in the MIC input);</t>

            <t>a Channel-Binding field bearing the channel bindings data
              (base64-encoded) of the channel over which the message is
              being sent (note: the channel bindings should be prefixed
              with the channel binding type as described in RFC5056, and
              prior to base64 encoding)), if there is a channel (this
              field MUST NOT be included in the request);</t>

            <t>the request body if and only if there is no channel to
              bind to, else an empty request body.</t>

          </list>

        </t>

        <t>The request MIC is base64-encoded, prefixed with the session
          URI (separated by an ASCII semi-colon) and placed in a header
          field named REST-GSS-Request-MIC.  Multiple MICs may be placed
          in this field, separated by whitespace.  [XXX Add ABNF for
          this!  Also, add an indication of what CB type is used in the
          request MIC token.]</t>

        <t>The optional timestamp in the request SHOULD be used for
          replay detection on the server side.  GSS-API per-message
          token replay detection facilities exist, but an implementation
          may not make it easier to share a security context's replay
          state easily across multiple processes or even servers in a
          cluster.</t>

        <t>MIC tokens for responses are generated by applying
          GSS_Get_MIC() to a a minimized form of the response
          containing only the following items:

          <list style='symbols'>

            <t>the request status line;</t>

            <t>the REST-GSS-Request-MIC from the request, with runs of
              whitespace characters replaced with a single ASCII
              space.</t>

            <t>the response body if and only if there is no channel to
              bind to, else an empty response body.</t>

          </list>

        </t>

        <t>The response MIC is base64-encoded, prefixed with the session
          URI (separated by an ASCII semi-colon) and placed in a header
          field named REST-GSS-Response-MIC.  Multiple MICs may be placed
          in this field, separated by whitespace.</t>

        <t>These MIC tokens are validated by calling GSS_Verify_MIC()
          with the same input data as GSS_Get_MIC().</t>

      </section>

      <section title="Alternative Session Binding Options">

        <t>[Add text describing the use of cookies instead of MIC
          tokens.]</t>

        <t>[Add text describing a method of associating REST-GSS session
          URIs with TLS session IDs instead of using MIC tokens on every
          request/response.  This is only workable when the client's and
          server's HTTP/TLS stacks expose enough information to the
          application.]</t>

      </section>

      <section title="Server Indication of Authentication Requirement">

        <t>When the server wishes to indicate that the client must
          authenticate in order to access a given resource, then the
          server MUST respond to the client's HTTP request with either
          a redirection to a web page with a 303 redirect to a login
          page (this in the case of browser applications) or a
          TBD 4xx error indicating that access requires REST-GSS login
          and, optionally directing the client to the REST-GSS login URI
          by listing that URI in a response header field named
          'REST-GSS-Authenticate'.</t>

      </section>

    </section>

    <section title="Examples">

      <section title="Server Decides When to Authenticate">

        <figure title='Authentication required indication browser apps'>
          <artwork><![CDATA[
   C->S: HTTP/1.1 GET /some/resource
         Host: A.example

   S->C: HTTP/1.1 303 http://A.example/login.html&<encoded-URI>
            ]]></artwork>
        </figure>

        <figure title='Authentication required indication for non-browser apps'>
          <artwork><![CDATA[
   C->S: HTTP/1.1 GET /some/resource
         Host: A.example

   S->C: HTTP/1.1 4xx
         REST-GSS-URI: http://A.example/rest-gss-login
            ]]></artwork>
        </figure>

      </section>

      <section title="Mechanism and Other Negotiation">

        <figure title='Negotiation'>
          <artwork><![CDATA[
   C->S: HTTP/1.1 GET /rest-gss-login
         Host: A.example

   S->C: HTTP/1.1 200
         Content-Type: application/rest-gss-login
         Content-Length: nnn

         mechs: SCRAM-SHA-1-PLUS,GSS-KRB5-PLUS
         channel-binding-types: tls-server-end-point
         session-binding: MIC-CB, MIC-body
         replay-protection: optional
            ]]></artwork>
        </figure>

      </section>

      <section title="Login, Session, and Logout, with SCRAM">

        <t>The following example is shamefully stolen from RFC5802, and
          adapted to REST-GSS.</t>

        <figure title='Authentication message exchange using SCRAM
          without channel binding'>
          <artwork><![CDATA[
   C->S: HTTP/1.1 POST /rest-gss-login
         Host: A.example
         Content-Type: application/rest-gss-login
         Content-Length: nnn

         SCRAM-SHA-1,,MIC
         n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL

   S->C: HTTP/1.1 201
         Location http://A.example/rest-gss-session-9d0af5f680d4ff46
         Content-Type: application/rest-gss-login
         Content-Length: nnn

         C
         r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,
         s=QSXCR+Q6sek8bf92,i=4096

   C->S: HTTP/1.1 POST /rest-gss-session-9d0af5f680d4ff46
         Host: A.example
         Content-Type: application/rest-gss-login
         Content-Length: nnn

         c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,
         p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts=

   S->C: HTTP/1.1 200
         Content-Type: application/rest-gss-login
         Content-Length: nnn

         A
         v=rmF9pqV8S7suAoZWja4dJRkFsKQ=
            ]]></artwork>
        </figure>

        <figure title='Example request and response using MIC tokens'>
          <artwork><![CDATA[
   C->S: HTTP/1.1 GET /some/doc.html
         Host: A.example
         REST-GSS-Request-MIC:
            http://A.example/rest-gss-session-9d0af5f680d4ff46
            <base64-encoding of output of GSS_Get_MIC() using the
             named session's security context and taken over a
             minimal version of this request:

             HTTP/1.1 GET /some/doc.html
             Host: A.example

             >

   S->C: HTTP/1.1 200
         Content-Type: text/html
         Content-Length: nnn

         <HTML source of http://A.example/some/doc.html>
            ]]></artwork>
        </figure>

        <figure title='Example of session logout'>
          <artwork><![CDATA[
   C->S: HTTP/1.1 DELETE /rest-...-session-9d0af5f680d4ff46
         Host: A.example
         REST-GSS-Request-MIC:
            http://A.example/rest-gss-session-9d0af5f680d4ff46
            <base64-encoding of output of GSS_Get_MIC() using the
             named session's security context and taken over a
             minimal version of this request:

             HTTP/1.1 DELETE /rest-...-9d0af5f680d4ff46
             Host: A.example

             >

   S->C: HTTP/1.1 200

            ]]></artwork>
        </figure>

      </section>

    </section>

    <section title="Implementation and Deployment Considerations">

      <t>It is possible to implement REST-GSS with no changes to HTTP
        implementations, on the client and server sides both.
        [Hmmm, maybe we should make sure not to add any new return
        codes! -Nico].  It is also possible to implement REST-GSS with
        no changes to TLS implementations, though it is preferable to
        use TLS implementations that output channel bindings data <xref
          target='RFC5929'/>.</t>

      <t>All that is required in order to implement REST-GSS is one or
        more GSS-API security mechanisms, whether used directly or via
        an actual GSS-API framework implementation.  Note that an
        implementation of the full GSS-API framework is <spanx
          style='emph'>not</spanx> required.  A minimal implementation
        of a security mechanism such as SCRAM <xref target='RFC5802'/>
        is feasible that provides nothing like the API that is the
        GSS-API.</t>

      <t>Similarly, a GS2 <xref target='RFC5801'/> implementation is
        required, but given how simple GS2 is there's no need for a
        full-blown SASL <xref target='RFC4422'/> nor GS2 framework
        implementation.</t>

      <t>The largest obstacle for REST-GSS implementation lies in the
        web browser, in the case of browser-based applications: without
        a native implementation of REST-GSS in the browser (or the
        platform, but accessed via the browser), the only way to
        implement REST-GSS is by implementing a security mechanism
        JavaScript [XXX Add reference. -Nico].  Implementing security
        mechanisms in scripts downloaded as needed from the same origin
        as the page that will use them presents a number of obvious
        security considerations, but as a technology demonstrator, this
        approach will work.</t>

      <t>As for deployment, the availability of security mechanisms and
        federations is critical.  Work is in progress to produce
        federatable security mechanisms for the GSS-API.  In the
        meantime, there are security mechanisms such as Kerberos V5
        <xref target='RFC4121'/> and others, that make deployment in the
        enterprise scale, if not the Internet scale, an immediately
        available option.</t>

      <section title="Desired GSS-API Extensions">

        <t>At least one GSS-API extension is desired, though not required:
          the ability to export (serialize) partially-established security
          contexts.  It is possible to implement REST-GSS on the server
          without this feature, but especially for clustered servers using
          multi-round-trip security mechanisms, it would be much easier to
          implement where this extension is available.</t>

      </section>

    </section>

    <section title="IANA Considerations">

      <t>This document has IANA considerations: new HTTP fields,
        and, possibly, new HTTP status codes.  These need to be
        registered.  Registration information to-be-added.</t>

    </section>

    <section title="Security Considerations">

      <t>The security considerations of HTTP <xref target='RFC2616'/>,
        TLS <xref target='RFC5246'/>, the GSS-API <xref
          target='RFC2743'/>, SASL <xref target='RFC4422'/>, and GS2
        <xref target='RFC5801'/> apply.  When channel binding is used
        the security considerations of <xref target='RFC5056'/> and
        <xref target='RFC5929'/> also apply.  Some of the security
        considerations of HTTP and TLS are addressed by the use of
        mutual authentication and channel binding in REST-GSS.</t>

      <t>REST-GSS provide a number of optional facilities, both by
        itself and because the GSS-API itself provides optional
        facilities.  These facilities can provide excellent security to
        users and service providers, particularly mutual authentication
        and channel binding, which together can significantly strengthen
        the authentication of services otherwise provided only by
        TLS.</t>

      <t>Some GSS-API security mechanisms are not secure against
        eavesdroppers or active attacks.  Therefore REST-GSS
        applications MUST use TLS with confidentiality protection to
        protect all REST-GSS authentication message exchanges, and
        SHOULD require the use of a server certificate <xref
          target='RFC5280'/> unless mutual authentication and channel
        binding are being used.</t>

      <t>REST-GSS applications SHOULD prefer security mechanisms that
        provide for mutual authentication to ones that do not, and
        SHOULD use channel binding to TLS whenever it's available.
        REST-GSS applications SHOULD NOT, by default, use security
        mechanisms that do not support mutual authentication or channel
        binding.  REST-GSS applications that allow the use of security
        mechanisms that do not provide mutual authentication MUST
        require that the server be authenticated by a server certificate
        <xref target='RFC5280'/>.</t>

      <t>REST-GSS applications SHOULD use channel binding to TLS, using
        the channel binding data of the TLS connection that will carry
        the client's initial authentication message.</t>

      <t>REST-GSS does not provide a confidentiality protection option.
        Therefore REST-GSS applications MUST use TLS if confidentiality
        protection is desired.</t>

      <t>REST-GSS applications SHOULD use TLS if integrity protection is
        desired.  Where they do not use TLS then they SHOULD use MIC
        tokens to protect the bodies of the requests and responses, not
        just the HTTP method and URI.</t>

      <t>REST-GSS applications SHOULD use MIC tokens instead of cookies
        to tie requests to sessions.  REST-GSS applications SHOULD use
        channel binding to TLS for session requests.</t>

      <t>REST-GSS applications that are sensitive to replays of requests
        SHOULD use MIC tokens with Request-Date and Request-Nanoseconds
        fields present in the data that the MIC is taken over, unless
        the server supports tls-unique channel bindings, in which case
        the application SHOULD NOT include Request-Date and
        Request-Nanoseconds fields in the MIC data.  But servers that
        have suitable GSS-API per-message token replay detection
        implementations SHOULD NOT request that Request-Date and
        Request-Nanoseconds header fields be used.</t>

      <t>REST-GSS applications SHOULD use the extended GSS mechanism
        inquiry API <xref target='RFC5587'/> to help select mechanisms
        that provide the features required by the application.</t>

      <t>While it is convenient to have servers decide when
        authentication is required on the basis of the URIs being
        accessed by the client, this can leak information.  It is best
        to require authentication, or not, for an entire site.</t>

      <t>...</t>

      <section title="User Interface and Scripting Interface Recommendations">

        <t>User interface (UI) and scripting interfaces are out of scope
          for this document.  However, in the interest of seeding
          works-in-progress, we describe some such UIs and scripting
          APIs here, in broad strokes.</t>

        <t>For browser-based applications we recommend the addition of
          an element to the HTML DOM for rendering a "login" button on a
          web page such that the user may activate it to initiate
          REST-GSS authentication.  Such a DOM element should include a
          URI to POST initial authentication messages to.  For
          non-browser applications we recommend a similar UI.</t>

        <t>For all REST-GSS  applications we also recommend non-DOM
          element by which the client may indicate REST-GSS login status
          to the user, as well as by which the user may initiate a
          logout.  The status displayed to users of logged-in REST-GSS
          sessions should include information such as: what security
          mechanism was used, the authenticated client and server
          principal names, session protection options, etcetera.</t>

        <t>For scripting we recommend extensions to XMLHttpRequest that
          allows the application to request a REST-GSS session URI as an
          output, implying that a session will be logged in.  We also
          recommend inputs to XMLHttpRequest to specify what REST-GSS
          session to use, and/or a REST-GSS login URI.  An extension
          should be provided for inquiring the status of a REST-GSS
          session.</t>

        <t>Cross-site scripting note: browsers MUST apply
          same-origin-like constraints to the REST-GSS target service
          names, if any, specified by scripts downloaded from a
          site.</t>

      </section>

      <section title='Platform Integration'>

        <t>[Add notes about platform integration. -Nico]</t>

      </section>

      <section title='Anti-Phishing'>

        <t>[Add notes about how mutual authentication via federated
          security mechanisms may reduce the scope of phishing attacks
          by effectively adding a service whitelist of sorts. -Nico]</t>

      </section>

    </section>

  </middle>

  <back>
    <references title="Normative References">
      &rfc2119;
      &rfc2616;
      &rfc2743;
      &rfc4422;
      &rfc5056;
      &rfc5234;
      &rfc5246;
      &rfc5587;
      &rfc5801;
      &rfc5929;
    </references>

    <references title="Informative References">
      &rfc2104;
      &rfc4013;
      &rfc4121;
      &rfc4401;
      &rfc5802;
      &rfc5280;
      &rfc5849;
      &gss-openid;
      &gss-saml;
      &gss-eap;
    </references>
  </back>
</rfc>