Improve GTK-DOC coverage.

[gnutls.git] / doc / protocol / draft-housley-tls-authz-extns-00.txt

Internet-Draft                                                  M. Brown
February 2006                                          RedPhone Security
Expires: August 2006                                          R. Housley
                                                          Vigil Security

        Transport Layer Security (TLS) Authorization Extensions
                 <draft-housley-tls-authz-extns-00.txt>


Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   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
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

Copyright Notice

   Copyright (C) The Internet Society (2006).  All Rights Reserved.

Abstract

   This document specifies authorization extensions to the Transport
   Layer Security (TLS) Handshake Protocol.  Extension types are carried
   in the client and server hello messages to confirm that both parties
   support the authorization messages.  The syntax and semantics of the
   authorization messages are described in detail.








Brown & Housley                                                 [Page 1]
\f
Internet-Draft                                             February 2006


1. Introduction

   Transport Layer Security (TLS) protocol [TLS1.0][TLS1.1] is being
   used in an increasing variety of operational environments, including
   ones that were not envisioned when the original design criteria for
   TLS were determined.  The extensions introduced in this document are
   designed to enable TLS to operate in environments where authorization
   information needs to be exchanged between the client and the server
   before any protected data is exchanged.

   This document describes authorization extensions for the TLS
   Handshake Protocol in both TLS 1.0 and TLS 1.1.  These extensions
   observe the conventions defined for TLS Extensions [TLSEXT] that make
   use of the general extension mechanisms for the client hello message
   and the server hello message.  The extensions described in this
   document allow TLS clients to provide to the TLS server authorization
   information, and allow TLS server to provide to the TLS client
   authorization information about the TLS server.

   The authorization extensions may be used in conjunction with TLS 1.0
   and TLS 1.1.  The extensions are designed to be backwards compatible,
   meaning that the Handshake Protocol messages associated with the
   authorization extensions will only be exchanged if the client
   indicates support for them in the client hello message and the server
   indicates support for them in the server hello message.

   Clients typically know the context of the TLS session that is being
   setup, thus the client can request the use of the authorization
   extensions when they are needed.  Servers must accept extended client
   hello messages, even if the server does not "understand" the all of
   the listed extensions.  However, the server will not indicate support
   for these "not understood" extensions.  Then, clients may reject
   communications with servers that do not support the authorization
   extensions.

1.1. Conventions

   The syntax for the authorization messages is defined using the TLS
   Presentation Language, which is specified in Section 4 of [TLS1.0].

   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 RFC 2119 [STDWORDS].








Brown & Housley                                                 [Page 2]
\f
Internet-Draft                                             February 2006


1.2. Overview

   Figure 1 illustrates the placement of the authorization messages in
   the full TLS handshake.  In order to avoid unnecessary disclosure of
   privilege information, the authorization messages appear after the
   Finished message.  This placement ensures that they are encrypted and
   integrity protected.

      Client                                                 Server

      ClientHello               -------->
                                                        ServerHello
                                                       Certificate*
                                                 ServerKeyExchange*
                                                CertificateRequest*
                                <--------           ServerHelloDone
      Certificate*
      ClientKeyExchange
      CertificateVerify*
      [ChangeCipherSpec]
      Finished                  -------->
      ClientAuthorizationData   -------->
                                                 [ChangeCipherSpec]
                                <--------                  Finished
                                <--------   ServerAuthorizationData
      Application Data          <------->          Application Data

       *  Indicates optional or situation-dependent messages that
          are not always sent.

       [] Indicates that ChangeCipherSpec is an independent TLS
          Protocol content type; it is not actually a TLS
          handshake message.

        Figure 1. Authorization data exchange in full TLS handshake

   The ClientHello message includes an indication that the
   ClientAuthorizationData message and ServerAuthorizationData message
   are supported.  The ServerHello message also includes an indication
   that the ClientAuthorizationData message and ServerAuthorizationData
   message are supported.  Both the client and the server MUST indicate
   support for the authorization messages, otherwise they MUST NOT be
   included in the handshake.








Brown & Housley                                                 [Page 3]
\f
Internet-Draft                                             February 2006


2. Authorization Extension Types

   The general extension mechanisms enable clients and servers to
   negotiate whether to use specific extensions, and how to use specific
   extensions.  As specified in [TLSEXT], the extension format used in
   the extended client hello message and extended server hello message
   is:

      struct {
         ExtensionType extension_type;
         opaque extension_data<0..2^16-1>;
      } Extension;

   The extension_type identifies a particular extension type, and the
   extension_data contains information specific to the particular
   extension type.

   As specified in [TLSEXT], for all extension types, the extension type
   MUST NOT appear in the extended server hello message unless the same
   extension type appeared in the corresponding client hello message.
   Clients MUST abort the handshake if they receive an extension type in
   the extended server hello message that they did not request in the
   associated extended client hello message.

   When multiple extensions of different types are present in the
   extended client hello message or the extended server hello message,
   the extensions can appear in any order, but there MUST NOT be more
   than one extension of the same type.

   This document specifies the use of two new extension types:
   client_authz_request and server_authz_request.  These extension types
   are described in Section 2.1 and Section 2.2, respectively.  This
   specification adds two new types to ExtensionType:

      enum {
        client_authz_request(TBD), server_authz_request(TBD),
        (65535)
      } ExtensionType;

   The authorization extensions are relevant when a session is initiated
   and any subsequent session resumption.  However, a client that
   requests resumption of a session does not know whether the server
   will have all of the context necessary to accept this request, and
   therefore the client SHOULD send an extended client hello message
   that includes the extension types associated with the authorization
   extensions.  This way, if the resumption request is denied, then the
   authorization extensions will be negotiated as normal.




Brown & Housley                                                 [Page 4]
\f
Internet-Draft                                             February 2006


2.1. The client_authz_request Extension Type

   Clients MUST include the client_authz_request extension type in the
   extended client hello message to indicate their desire to send
   authorization data to the server.  The extension_data field indicates
   the format of the authorization data that will be sent.  The format
   is indicated with the AuthzDataFormat type defined in Section 2.3.

   Servers that receive an extended client hello message containing the
   client_authz_request extension MUST respond with the same
   client_authz_request extension in the extended server hello message
   if the server is willing to receive authorization data in the
   indicated format.  The client_authz_request extension MUST be omitted
   from the extended server hello message if the server is not willing
   to receive authorization data in the indicated format.

2.2. The server_authz_request Extension Type

   Clients MUST include the server_authz_request extension type in the
   extended client hello message to indicate their desire to receive
   authorization data from the server.  The extension_data field
   indicates the format of the authorization data that is desired.  The
   format is indicated with the AuthzDataFormat type defined in Section
   2.3.

   Servers that receive an extended client hello message containing the
   server_authz_request extension MUST respond with the same
   server_authz_request extension in the extended server hello message
   if the server is willing to provide authorization data in the
   requested format.  The server_authz_request extension MUST be omitted
   from the extended server hello message if the server is not able to
   provide authorization data in the requested format.

2.3. AuthzDataFormat Type

   The AuthzDataFormat type is used in both the client_authz_request and
   the server_authz_request extensions.  It indicates the format of the
   authorization data that will be transferred.  The AuthzDataFormat
   type definition is:

      enum{
         x509_attr_cert(0), saml_assertion(1), (255)
      } AuthzDataFormat;

   When the x509_attr_cert value is present, the authorization data is
   an X.509 Attribute Certificate that conforms to the profile in RFC
   3281 [ATTRCERT].




Brown & Housley                                                 [Page 5]
\f
Internet-Draft                                             February 2006


   When the saml_assertion value is present, the authorization data is
   an assertion composed using the Security Assertion Markup Language
   (SAML) [SAML].

3. Handshake Messages

   This document specifies the use of two new handshake messages: the
   ClientAuthorizationData message and ServerAuthorizationData message.
   These messages are described in Section 3.1 and Section 3.2,
   respectively.  The updated handshake message structure becomes:

      enum {
          hello_request(0), client_hello(1), server_hello(2),
          certificate(11), server_key_exchange (12),
          certificate_request(13), server_hello_done(14),
          certificate_verify(15), client_key_exchange(16),
          finished(20), certificate_url(21), certificate_status(22),
          client_authz_data(TBD), server_authz_data(TBD), (255)
      } HandshakeType;

      struct {
          HandshakeType msg_type;    /* handshake type */
          uint24 length;             /* octets in message */
          select (HandshakeType) {
              case hello_request:       HelloRequest;
              case client_hello:        ClientHello;
              case server_hello:        ServerHello;
              case certificate:         Certificate;
              case server_key_exchange: ServerKeyExchange;
              case certificate_request: CertificateRequest;
              case server_hello_done:   ServerHelloDone;
              case certificate_verify:  CertificateVerify;
              case client_key_exchange: ClientKeyExchange;
              case finished:            Finished;
              case certificate_url:     CertificateURL;
              case certificate_status:  CertificateStatus;
              case client_authz_data:   ClientAuthorizationData;
              case server_authz_data:   ServerAuthorizationData;
          } body;
      } Handshake;











Brown & Housley                                                 [Page 6]
\f
Internet-Draft                                             February 2006


3.1. ClientAuthorizationData Message

   The ClientAuthorizationData message contains authorization data
   associated with the TLS client.  The format of the authentication
   data depends on the format negotiated in the client_authz_request
   hello message extensions.

      struct {
         client_authz_data AuthorizationData;
      } ClientAuthorizationData;

   The AuthorizationData structure is described in Section 3.3.

3.2. ServerAuthorizationData Message

   The ServerAuthorizationData message contains authorization data
   associated with the TLS server.  The format of the authorization data
   depends on the format negotiated in the server_authz_request hello
   message extensions.

      struct {
         server_authz_data AuthorizationData;
      } ServerAuthorizationData;

   The AuthorizationData structure is described in Section 3.3.

3.3. AuthorizationData Type

   The AuthorizationData structure is defined as follows.  For
   readability, the definition of AuthzDataFormat is repeated from
   section 2.3.

   All of the entries in the authz_data_list MUST contain the same
   authz_format value, and this value MUST match the one advertised by
   the client in the extended hello message extension.

      struct{
         AuthorizationDataEntry authz_data_list<1..2^16-1>;
      } AuthorizationData;

      struct {
         AuthzDataFormat authz_format;
         select (authz_format) {
            case x509_attr_cert: X509AttrCert;
            case saml_assertion: SAMLAssertion;
         } authz_data_entry;
      } AuthorizationDataEntry;




Brown & Housley                                                 [Page 7]
\f
Internet-Draft                                             February 2006


      enum{
         x509_attr_cert(0), saml_assertion(1), (255)
      } AuthzDataFormat;

      opaque X509AttrCert<1..2^16-1>;

      opaque SAMLAssertion<1..2^16-1>;

   When X509AttrCert is used, the field contains an ASN.1 DER-encoded
   X.509 Attribute Certificate (AC) that follows the profile in RFC 3281
   [ATTRCERT].  An AC is a structure similar to a public key certificate
   (PKC); the main difference being that the AC contains no public key.
   An AC may contain attributes that specify group membership, role,
   security clearance, or other authorization information associated
   with the AC holder.

   When SAMLAssertion is used, the field contains XML constructs with a
   nested structure defined in [SAML].  SAML is an XML-based framework
   for exchanging security information.  This security information is
   expressed in the form of assertions about subjects, where a subject
   is either human or computer with an identity.  In this context, the
   assertions are most likely to convey authorization decisions about
   whether subjects are allowed to access certain resources.  Assertions
   are issued by SAML authorities, namely, authentication authorities,
   attribute authorities, and policy decision points.

4. IANA Considerations

   IANA needs to assign two TLS Extension Types: client_authz_request,
   and server_authz_request.

   IANA needs to assign two TLS Handshake Message Types:
   client_authz_data, and server_authz_data.

   IANA needs to establish a registry for TLS Authorization Data
   Formats.  The first two entries in the registry are x509_attr_cert(0)
   and saml_assertion(1).  TLS Authorization Data Format identifiers
   with values in the inclusive range 0-63 (decimal) are assigned via
   RFC 2434 [IANA] Standards Action.  Values from the inclusive range
   64-223 (decimal) are assigned via RFC 2434 Specification Required.
   Values from the inclusive range 224-255 (decimal) are reserved for
   RFC 2434 Private Use.









Brown & Housley                                                 [Page 8]
\f
Internet-Draft                                             February 2006


5. Security Considerations

   A TLS server can support more than one application, and each
   application may include several features, each of which requires
   separate authorization checks.  This is the reason that more than one
   piece of authorization information can be provided.

   A TLS server that requires different authorization information for
   different applications or different application features may find
   that a client has provided sufficient authorization information to
   grant access to a subset of these offerings.  In this situation the
   TLS Handshake protocol will complete successfully; however, the
   server must ensure that the client will only be able to use the
   appropriate applications and application features.  That is, the TLS
   server must deny access to the applications and application features
   for which authorization has not been confirmed.

6. Normative References

   [ATTRCERT]   Farrell, S., and R. Housley, "An Internet Attribute
                Certificate Profile for Authorization", RFC 3281,
                April 2002.

   [IANA]       Narten, T., and H. Alvestrand, "Guidelines for Writing
                an IANA Considerations Section in RFCs", RFC 3434,
                October 1998.

   [TLS1.0]     Dierks, T., and C. Allen, "The TLS Protocol, Version 1.0",
                RFC 2246, January 1999.

   [TLS1.1]     Dierks, T., and E. Rescorla, "The Transport Layer Security
                (TLS) Protocol, Version 1.1", RFC 4346, February 2006.

   [TLSEXT]     Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J.,
                and T. Wright, "Transport Layer Security (TLS) Extensions",
                RFC 3546, June 2003.

   [SAML]       Organization for the Advancement of Structured Information
                Standards, "Security Assertion Markup Language (SAML),
                version 1.1", September 2003.  [Version 2.0 is out for
                public comment; it will replace this reference if approved.]

   [STDWORDS]   Bradner, S., "Key words for use in RFCs to Indicate
                Requirement Levels", BCP 14, RFC 2119, March 1997.







Brown & Housley                                                 [Page 9]
\f
Internet-Draft                                             February 2006


Author's Address

   Mark Brown
   RedPhone Security
   2019 Palace Avenue
   Saint Paul, MN  55105
   USA
   mark <at> redphonesecurity <dot> com

   Russell Housley
   Vigil Security, LLC
   918 Spring Knoll Drive
   Herndon, VA 20170
   USA
   housley <at> vigilsec <dot> com

Full Copyright Statement

   Copyright (C) The Internet Society (2006). This document is subject
   to the rights, licenses and restrictions contained in BCP 78, and
   except as set forth therein, the authors retain all their rights.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works. However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.








Brown & Housley                                                [Page 10]