[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                                           O. Friel
Internet-Draft                                                 R. Barnes
Intended status: Standards Track                             M. Pritikin
Expires: May 3, 2018                                               Cisco
                                                        October 30, 2017


                         Application-Layer TLS
                      draft-friel-tls-over-http-00

Abstract

   Many clients need to establish secure connections to application
   services but face challenges establishing these connections due to
   the presence of middleboxes that terminate TLS connections from the
   client and restablish new TLS connections to the service.  This
   document defines a mechanism for transporting TLS records in HTTP
   message bodies between clients and services.  This enables clients
   and services to establish secure connections using TLS at the
   application layer, and treat any middleboxes that are intercepting
   traffic at the network layer as untrusted transport.  In short, this
   mechanism moves the TLS handshake up the OSI stack to the application
   layer.

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

   This Internet-Draft will expire on May 3, 2018.

Copyright Notice

   Copyright (c) 2017 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



Friel, et al.              Expires May 3, 2018                  [Page 1]


Internet-Draft                    ATLS                      October 2017


   (https://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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  ATLS Transport Goals  . . . . . . . . . . . . . . . . . . . .   3
   4.  Architecture Overview . . . . . . . . . . . . . . . . . . . .   4
     4.1.  Network Architecture  . . . . . . . . . . . . . . . . . .   4
     4.2.  Application Architecture  . . . . . . . . . . . . . . . .   5
     4.3.  Application Arthiecture Benefits  . . . . . . . . . . . .   6
     4.4.  Implementation  . . . . . . . . . . . . . . . . . . . . .   6
   5.  ATLS Overview . . . . . . . . . . . . . . . . . . . . . . . .   6
     5.1.  TLS Connections . . . . . . . . . . . . . . . . . . . . .   7
     5.2.  Protocol Introduction . . . . . . . . . . . . . . . . . .   7
     5.3.  TLS Session Tracking  . . . . . . . . . . . . . . . . . .   8
     5.4.  Upgrade to Websocket  . . . . . . . . . . . . . . . . . .   8
     5.5.  Service Container Affinity  . . . . . . . . . . . . . . .   8
     5.6.  Keying Material Exporting . . . . . . . . . . . . . . . .   8
   6.  Protocol Details  . . . . . . . . . . . . . . . . . . . . . .   9
     6.1.  Message Body  . . . . . . . . . . . . . . . . . . . . . .   9
     6.2.  HTTP Content-Type . . . . . . . . . . . . . . . . . . . .   9
     6.3.  Client Requests . . . . . . . . . . . . . . . . . . . . .   9
     6.4.  Server Responses  . . . . . . . . . . . . . . . . . . . .  10
   7.  ATLS Session Establishment  . . . . . . . . . . . . . . . . .  10
     7.1.  ATLS Handshake Message Sequence Flow  . . . . . . . . . .  11
     7.2.  Detailed ATLS Handshake . . . . . . . . . . . . . . . . .  12
     7.3.  Application Data Exchange . . . . . . . . . . . . . . . .  14
   8.  RTT Considerations  . . . . . . . . . . . . . . . . . . . . .  15
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  15
   10. Security Considerations . . . . . . . . . . . . . . . . . . .  15
   11. Appendix A. TLS Software Stack Configuration  . . . . . . . .  15
   12. Appendix B. Pseudo Code . . . . . . . . . . . . . . . . . . .  15
     12.1.  B.1 OpenSSL  . . . . . . . . . . . . . . . . . . . . . .  15
     12.2.  B.2 Java JSSE  . . . . . . . . . . . . . . . . . . . . .  17
   13. Appendix C. Example ATLS Handshake  . . . . . . . . . . . . .  19
   14. Informative References  . . . . . . . . . . . . . . . . . . .  19
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  19







Friel, et al.              Expires May 3, 2018                  [Page 2]


Internet-Draft                    ATLS                      October 2017


1.  Introduction

   There are far more classes of clients being deployed on today's
   networks than at any time previously.  This poses challenges for
   network administators who need to mange their network and the clients
   connecting to their network, and poses challenges for client vendors
   and client software developers who must ensure that their clients can
   connect to all required services.

   One common example is where a client is deployed on a local domain
   network that protects its perimeter using a TLS terminating
   middlebox, and the client needs to establish a secure connection to a
   service in a different network via the middlebox.  Traditionally,
   this has been enabled by the network administrator deploying the
   necessary certificate authority trusted roots on the client.  This
   can be achieved at scale using standard tools that enable the
   administrator to automatically push trusted roots out to all client
   machines in the network from a centralised domain controller.  This
   works for for personal computers, laptops and servers running
   standard Operating Systems that can be centrally managed.  This
   client management process breaks for multilpe classes of clients that
   are being deployed today, there is no standard mechanism for
   configuring trusted roots on these clients, and there is no standard
   mechaism for these clients to securely traverse middleboxes.

   The TLS over HTTP mechanism defined in this document enables clients
   to traverse middleboxes that restrict communications to HTTP traffic
   they have inserted themselves into, and establish secure connections
   to services across network domain boundaries.

2.  Terminology

   TLS over HTTP is referred to as ATLS throughout this document i.e.
   "Application Layer TLS".

3.  ATLS Transport Goals

   The high level goals driving the design of this mechanism are:

   o  reuse existing TLS specifications [RFC5246] [I-D.ietf-tls-tls13]
      as is without requiring any protocol changes

   o  work with all versions of TLS

   o  do not require any changes to current TLS software stacks

   o  do not mandate constraints on how the TLS stack is configured or
      used



Friel, et al.              Expires May 3, 2018                  [Page 3]


Internet-Draft                    ATLS                      October 2017


   o  be forward compatible with future TLS versions

   o  work with both HTTP and HTTPS transport

   o  avoid introducing TLS protocol handling logic or semantics into
      the HTTP application layer i.e. TLS protocol knowledge and logic
      is handled by the TLS stack, HTTP is just a dumb transport

   o  ensure the client and server software implementations are as
      simple as possible

4.  Architecture Overview

4.1.  Network Architecture

   A typical network deployment is illustrated in Figure 1.  It shows a
   client connecting to a service via a middlebox.  It also shows a TLS
   terminator deployed in front of the service.  The client establishes
   a transport layer TLS connection with the middlebox (C->M TLS), the
   middlebox in turn opens a transport layer TLS connection with the TLS
   terminator deployed in front of the service (M->T TLS).  The client
   can ignore any certificate validation errors when it connects to the
   middlebox.  HTTP messages are transported over this layer between the
   client and the service.  Finally, application layer TLS messages are
   exchanged inside the HTTP message bodies in order to establish an
   end-to-end TLS session between the client and the service (C->S TLS).

          +----------+        +----------+
          | App Data |        | App Data |
          +----------+        +----------+         +----------+
          | C->S TLS |        | C->S TLS |         | App Data |
          +----------+        +----------+         +----------+
          |   HTTP   |        |   HTTP   |         | C->S TLS |
          +----------+        +----------+         +----------+
          | C->M TLS |        | M->T TLS |         |   HTTP   |
          +----------+        +----------+         +----------+
          |   TCP    |        |   TCP    |         |   TCP    |
          +----------+        +----------+         +----------+

   +--------+      +-----------+      +----------------+     +---------+
   | Client |----->| Middlebox |----->| TLS Terminator |---->| Service |
   +--------+      +-----------+      +----------------+     +---------+
      ^                                                           ^
      |                                                           |
      +--------------Client to Service TLS Connection-------------+

                      Figure 1: Network Architecture




Friel, et al.              Expires May 3, 2018                  [Page 4]


Internet-Draft                    ATLS                      October 2017


4.2.  Application Architecture

   TLS software stacks allow application developers to 'unplug' the
   default network socket transport layer and read and write TLS records
   directly from byte buffers.  This enables application developers to
   create application layer TLS sessions, extract the raw TLS record
   bytes from the bottom of the TLS stack, and transport these bytes
   over any suitable transport.  The TLS software stacks can generate
   byte streams of full TLS flights which may include multiple TLS
   records.  This is illustrated in Figure 2 below.

                       +------------+                    +---------+
    Handshake Records  |            | Handshake Records  |         |
   ------------------->|    TLS     |------------------->|         |
                       |            |                    |  Byte   |
    Unencrypted Data   |  Software  | Encrypted Data     |         |
   ------------------->|            |------------------->| Buffers |
                       |   Stack    |                    |         |
    Encrypted Data     |            | Unencrypted Data   |         |
   ------------------->|            |------------------->|         |
                       + -----------+                    +---------+

                      Figure 2: TLS Stack Interfaces

   These TLS software stack APIs enable application developers to build
   the software architecture illustrated in Figure 3.  The application
   creates and interacts with an application layer TLS session in order
   to generate and consume raw TLS records.  The application transports
   these raw TLS records inside HTTP message bodies using a standard
   HTTP stack.  The HTTP stack may in turn use either TLS or TCP
   transport to comunicate with the peer.  The application layer TLS
   session and network layer TLS session can both leverage a shared,
   common TLS software stack.  This high level architecture is
   applicable to both clients and services.

















Friel, et al.              Expires May 3, 2018                  [Page 5]


Internet-Draft                    ATLS                      October 2017


   +-------------+
   |             |  App
   |             |  Data   +---------+
   | Application |<------->|   App   |    +---------+
   |             |  TLS    |   TLS   |--->|   TLS   |
   |             | Records | Session |    |  Stack  |
   |        +--->|<------->|         |    +---------+
   |        |    |         +---------+         ^
   |        |    |                             |
   |        |    |  JSON   +-------+    +-------------+    +-----------+
   |        |    | Payload | HTTP  |    |  Transport  |    |  TCP/IP   |
   |        +--->|<------->| Stack |--->| TLS Session |--->| Transport |
   +-------------+         +-------+    +-------------+    +-----------+

                    Figure 3: Application Architecture

4.3.  Application Arthiecture Benefits

   There are several benefits to using a standard TLS software stack to
   establish an application layer secure communications channel between
   a client and a service.  These include:

   o  no need to define a new cryptographic negotiation and exchange
      protocol beween client and service

   o  automatically benefit from new cipher suites by simply upgrading
      the TLS software stack

   o  automaticaly benefit from new features, bugfixes, etc. in TLS
      software stack upgrades

4.4.  Implementation

   Pseudo code illustrating how to read and write TLS records directly
   from byte buffers using both OpenSSL and Java JSSE is given in the
   appendices.

5.  ATLS Overview

   The assumption is that the client will establish a transport layer
   connection to the server for exchange of HTTP messages.  The
   underlying transport layer connection could be over TCP or TLS.  The
   client will then establish an application layer TLS connection with
   the server by exchanging TLS records with the server inside HTTP
   message requests and responses.






Friel, et al.              Expires May 3, 2018                  [Page 6]


Internet-Draft                    ATLS                      October 2017


5.1.  TLS Connections

   If the underlying transport layer connection is TLS, this means that
   the client will establish two independent TLS connections:

   o  one at the transport layer which could be directly with the
      service or could be with a middlebox

   o  one at the application layer which will be with the service

   As an optimisation, clients may choose to only use ATLS as a fallback
   mechanism if certificate validation fails on the transport layer TLS
   connection to the service.  For the purposes of establishing a secure
   connection with the service, the client does not need to perform any
   certificate checks or validation on the transport layer TLS
   connection.

   Similarly, the service may also establish two independent TLS
   connections:

   o  one at the transport layer which could be directly with the client
      or could be with a middlebox

   o  one at the application layer which will be with the client

   Once the application layer TLS connection is estabilshed, the client
   may report to the service the TLS certificates that where presented
   by the network layer TLS connection but this is application specific
   behaviour and outside the scope of this specification.

5.2.  Protocol Introduction

   All application TLS records are transported as base64 encoded
   payloads inside JSON message bodies over HTTP transport.  Each
   payload contains a full TLS flight made up of one or more TLS
   records.

   The client sends all application TLS records to the server in JSON
   message bodies in POST requests.

   The server sends all TLS records to the client in JSON message bodies
   in 200 OK responses to the POST requests.

   No constraints are placed on the ContentType contained within the
   transported TLS records.  The TLS records may contain handshake,
   application_data, alert or change_cipher_spec messages.  If new
   ContentType messages are defined in future TLS versions, these may
   also be transported using this protocol.



Friel, et al.              Expires May 3, 2018                  [Page 7]


Internet-Draft                    ATLS                      October 2017


   If the server is able to handle the application layer TLS records
   included in the request, the server always responds with a 200 OK and
   includes any application TLS records in the message body.  The server
   does not, for example, parse the TLS records generated by its TLS
   software stack for an AlertDescription and attempt to map this to a
   suitable HTTP error response code.

   The server only responds with a non-200 OK message if a server error
   occurrs and it is not capable of handling the application layer TLS
   message received from the client.

5.3.  TLS Session Tracking

   The service needs to track multiple client application layer TLS
   sessions so that it can collerate TLS records received in HTTP
   message bodies with the appropriate TLS session.  It does this by
   inclusion of an explicit session identifier in the JSON message body.

5.4.  Upgrade to Websocket

   The HTTP connection between the client and the service may be
   upgraded to a websocket if required.  This would allow a server to
   send a TLS close request, or any application data, asynchronously to
   the client.  Note that for the majority of use cases, there will be
   no need to open a websocket between the client and service.

5.5.  Service Container Affinity

   Application services are typically distributed across multiple
   containers and virtual machines.  As TLS is stateful, it must be
   ensured that sequences of TLS messages are handled appropriately by
   the service deployment and the service execution engine has access to
   all necessary state information.  This is explicilty outside the
   scope of this specification as there are multiple well defined
   mechanisms for enabling this.

5.6.  Keying Material Exporting

   This specification does not require, or preclude, the use of
   [RFC5705].  When the client and service applications detect that the
   ATLS session is established, the application may use the key exporter
   functions of the TLS stack to derive shared keys between client and
   service.  The client and service may then use these shared keys to
   establish an independent cryptographic context and exchange data
   using any suitable mechanism such as JSON Web Encryption [RFC7516] or
   Encrypted Content-Encoding for HTTP [RFC8188].





Friel, et al.              Expires May 3, 2018                  [Page 8]


Internet-Draft                    ATLS                      October 2017


6.  Protocol Details

6.1.  Message Body

   All message bodies are JSON bodies containing one or two parameters:

   {
     "session": "<session-string>",
     "records": "<base64 encoded TLS records>"
   }

   The following two parameters are defined:

   session: This is set by the service and is used to correlate requests
   across multiple client sessions.  This parameter is included in all
   messages apart from the first first message sent from the client to
   the service.  When a client sends the first request to establish an
   ATLS session with a service, it MUST omit this parameter.  When a
   service handles the first request from a client (and that request
   will include the ClientHello), and the service creates an internal
   TLS session object, it MUST return a server-generated "<session-
   string>" to the client.  The client MUST include that "<session-
   string>" in all subsequent messages to the server.  If the service is
   unable to find a TLS session that correlates with the "<session-
   string>" that a client specifies, the server MUST return 422
   Unprocessable Entity.

   records: This parameter is used to transport the base64 encoded TLS
   records that the client and service applications retrieve from their
   TLS stack.  This parameter is sent in all requests from the client to
   the service.  This parameter may not necessarily be sent in all
   response messages from the service to the client if the service has
   no TLS records to send.  This can happen with a TLS1.3 handshake.

6.2.  HTTP Content-Type

   A new HTTP Content-Type is defined:

   Content-Type: application/atls+json

6.3.  Client Requests

   When a client has base64 encoded TLS records to send to a service, it
   will include the previously received "<session-string>" in the
   request, or else omit this field for the very first handshake
   message, and send the following request to the service:





Friel, et al.              Expires May 3, 2018                  [Page 9]


Internet-Draft                    ATLS                      October 2017


   POST /atls
   Content-Type: application/atls+json

   {
     "session": "<session-string>",
     "records": "<base64 encoded TLS records>"
   }

6.4.  Server Responses

   When a service has processed the TLS records received from a client
   and has generated TLS records to reply with, it will send the
   following reply to the client:

   200 OK
   Content-Type: application/atls+json

   {
     "session": "<session-string>",
     "records": "<base64 encoded TLS records>"
   }

   The server MUST respond with one of the following status codes:

   200 OK:  The server was able to successfully parse the request and
      process the TLS records using its TLS software stack.

   400 Bad Request:  The client's request did not contain a JSON object
      of the form specified above.

   422 Unprocessable Entity:  The client presented a "<session-string>"
      that the service is unable to correlate that to an existing TLS
      session.

   Note that a status code of 200 OK does not indicate that the TLS
   connection being negotiated is error-free.  Alerts produced by TLS
   will be returned in the encoded TLS records.  A 200 OK response
   simply indicates that the client should provide the records encoded
   in the response to its TLS stack.

7.  ATLS Session Establishment

   This section describes a typical ATLS session establishment flow.








Friel, et al.              Expires May 3, 2018                 [Page 10]


Internet-Draft                    ATLS                      October 2017


7.1.  ATLS Handshake Message Sequence Flow

   The following flow chart shows an illustrative message sequence flow
   for the first TLS handshake flight between a client and a service.

   +-------------------------------+  +-------------------------------+
   |             Client            |  |           ATLS Server         |
   +---------+---+-----+---+-------+  +-------+---+-----+---+---------+
   |   TLS   |   | App |   | HTTP  |  | HTTP  |   | App |   |   TLS   |
   | Session |   +-----+   | Stack |  | Stack |   +-----+   | Session |
   +---------+       |     +-------+  +-------+       |     +---------+
        |            |         |           |          |          |
        |            |         |  HTTP(S)  |          |          |
        |            |         | Transport |          |          |
        |   Create   |         |<--------->|          |          |
        |   Session  |         |           |          |          |
        |<-----------|         |           |          |          |
        |    Start   |         |           |          |          |
        |  Handshake |         |           |          |          |
        |<-----------|         |           |          |          |
        |    TLS     |         |           |          |          |
        |  Records   | Package |           |          |          |
        |----------->|  JSON   |           |          |          |
        |            |-------->|   POST    | Unwrap   |          |
        |            |         |---------->|  JSON    | Create   |
        |            |         |           |--------->| Session  |
        |            |         |           |          |--------->|
        |            |         |           |          |   TLS    |
        |            |         |           |          | Records  |
        |            |         |           |          |--------->|
        |            |         |           |          |   TLS    |
        |            |         |           | Package  | Records  |
        |            |         |           |  JSON    |<---------|
        |            | Unwrap  |  200 OK   |<---------|          |
        |    TLS     |  JSON   |<----------|          |          |
        |  Records   |<--------|           |          |          |
        |<-----------|         |           |          |          |
        |    TLS     |         |           |          |          |
        |  Records   |         |           |          |          |
        |----------->|         |           |          |          |

   This process repeats until the handshake completes.  Once the
   application-layer TLS connection is ready to carry application data,
   the ATLS server relays it to the application server that is
   ultimately serving the rqeuest.  That is, a given ATLS server is
   assumed to be connected to a single application endpoint.





Friel, et al.              Expires May 3, 2018                 [Page 11]


Internet-Draft                    ATLS                      October 2017


                       +--------+           +--------+
   +--------+          |  ATLS  |           |  App   |
   | Client |          | Server |           | Server |
   +--------+          +--------+           +--------+
       |                   |                    |
       |   TLS Handshake   |                    |
       |    (POST/200)     |                    |
       |<----------------->|                    |
       |                   |                    |
       | Application Data  |                    |
       |    (POST/200)     |  Application Data  |
       |<----------------->|<------------------>|

7.2.  Detailed ATLS Handshake

   o  Client establishes transport layer connection with service

   This transport layer session can be established over TCP or TLS.  If
   over TLS, the client does not need to perform certificate validation
   on the TLS connection, and may ignore any certificate validation
   errors if it does perform certificate validation.

   o  Client creates an application TLS session object

   The client application creates a TLS session object that is not bound
   to any network socket.  The client initiates a TLS handshake on the
   session.  This will result in the TLS session generating the TLS
   record bytes for a full TLS handshake first flight.  This will be a
   ClientHello message.  Note that the client application does not
   explicitly know what the contents of the TLS record bytes are.

   o  The client base64 encodes the TLS flight 1 records and sends them
      in a HTTP POST to the service

   POST /atls
   Content-Type: application/atls

   {
     "records": "<base64 encoded flight 1>"
   }

   o  The service creates a TLS session for handling the request

   The service notes that there is no "session" in the request and
   creates an application TLS session object and a suitable "<session-
   string>" for correlation.  The service decodes the received base64
   encoded "records" and passes them to the TLS session.  The session
   handles the TLS handshake message and generates a full TLS handshake



Friel, et al.              Expires May 3, 2018                 [Page 12]


Internet-Draft                    ATLS                      October 2017


   response flight.  Typically, this will be a ServerHello and
   additional handshake messages that are TLS version dependent.  For
   TLS1.3, this may include a Finished message.  Note that the service
   application does not explicitly know what the contents of the TLS
   record bytes are.

   o  The service base64 encodes the TLS flight 1 response records and
      sends them in the response to the client

   The service MUST include its generated "session".

   200 OK
   Content-Type: application/atls

   {
     "session": "<session-string>",
     "records": "<base64 encoded flight 1 response>"
   }

   o  The client passes the service response to its TLS session

   The client decodes the received base64 encoded "records" and passes
   them to the TLS session.  The session handles the TLS handshake
   message and generates a full TLS handshake second flight.  This will
   be a Finished message, Certificate and CertificateVerify messages if
   required, and additional handshake messages that are TLS version
   dependent.

   o  The client base64 encodes the TLS flight 2 records and sends them
      in a HTTP POST to the service

   The client MUST include the "<session-string>" it received from the
   service.

   POST /atls
   Content-Type: application/atls

   {
     "session": "<session-string>",
     "records": "<base64 encoded flight 2>"
   }

   o  The service passes the client response to the respective TLS
      session

   The service extracts the "<session-string>" from the request and
   finds the respective application TLS session object.  The service
   decodes the received base64 encoded "records" and passes them to the



Friel, et al.              Expires May 3, 2018                 [Page 13]


Internet-Draft                    ATLS                      October 2017


   TLS session.  The session handles the TLS handshake message and will
   generates a full TLS handshake response flight where appropriate.
   For TLS1.2, this will include a Finished and ChangeCipherSpec
   message.  For TLS1.3, there are not TLS records generated.

   o  The service base64 encodes the TLS flight 2 response records and
      sends them in the response to the client

   For TLS 1.2:

   200 OK
   Content-Type: application/atls

   {
     "session": "<session-string>",
     "records": "<base64 encoded flight 2 response>"
   }

   For TLS1.3:

   200 OK
   Content-Type: application/atls

   {
     "session": "<session-string>"
   }

   o  The client passes the service response to its TLS session

   If there are TLS records included in the response from the service,
   the client decodes the received base64 encoded "records" and passes
   them to its TLS session.

7.3.  Application Data Exchange

   Application data is exchanged between the client and service inside
   the TLS tunnel using exactly the same JSON transport payload.  When
   the client has data to send to the service, it encrypts the data
   using the standard TLS stack methods (e.g.  OpenSSL SSL_write() or
   Java SSLEngine.wrap()), extracts the encrypted TLS records from the
   bottom of the TLS stack, and sends them as in the JSON "records"
   parameter to the service.  The service injects the TLS records into
   its stack and reads the decrypted data from the top of its stack.








Friel, et al.              Expires May 3, 2018                 [Page 14]


Internet-Draft                    ATLS                      October 2017


8.  RTT Considerations

   The number of RTTs that take place when establishing a TLS session
   depends on the version of TLS and what capabilities are enabled on
   the TLS software stack.  For example, a 0-RTT exchange is possible
   with TLS1.3.

   If applications wish to ensure a predictable number of RTTs when
   establishing an application layer TLS connection, this may be
   achieved by configuring the TLS softwrae stack appropriately.
   Relevant configuration parameters for OpenSSL and Java SunJSSE stacks
   are outlined in the appendix.

9.  IANA Considerations

   [[ TODO - New Content-Type must be registered. ]]

10.  Security Considerations

   [[ TODO ]]

11.  Appendix A.  TLS Software Stack Configuration

   [[ EDITOR'S NOTE: We could include details here on how TLS stack
   configuration items control the number of round trips between the
   client and server.
   And just give two examples: OpenSSL and Java SunJSSE]]

12.  Appendix B.  Pseudo Code

   This appendix gives both C and Java pseudo code illustrating how to
   inject and extract raw TLS records from a TLS software stack.  Please
   not that this is illustrative, non-functional pseudo code that does
   not compile.  Functioning proof-of-concept code is available on the
   following public respository [[ EDITOR'S NOTE: Add the URL here ]].

12.1.  B.1 OpenSSL

   OpenSSL provides a set of Basic Input/Output (BIO) APIs that can be
   used to build a custom transport layer for TLS connections.  This
   appendix gives pseudo code on how BIO APIs could be used to build a
   client application that completes a TLS handshake and exchanges
   application data with a service.








Friel, et al.              Expires May 3, 2018                 [Page 15]


Internet-Draft                    ATLS                      October 2017


   char inbound[MAX];
   char outbound[MAX];
   int rx_bytes;
   SSL_CTX *ctx = SSL_CTX_new();
   SSL *ssl = SSL_new(ctx);

   // Create in-memory BIOs and plug in to the SSL session
   BOI* bio_in = BIO_new(BIO_s_mem());
   BOI* bio_out = BIO_new(BIO_s_mem());
   SSL_set_bio(ssl, bio_in, bio_out);

   // We are a client
   SSL_set_connect_state(ssl);

   // Loop through TLS flights until we are done
   do {
     // Calling SSL_do_handshake() will result in a full
     // TLS flight being written to the BIO buffer
     SSL_do_handshake(ssl);

     // Read the client flight that the TLS session
     // has written to memory
     BIO_read(bio_out, outbound, MAX);

     // POST the outbound bytes to the server using a suitable
     // function. Lets assume that the server response will be
     // written to the 'inbound' buffer
     num_bytes = postTlsRecords(outbound, inbound);

     // Write the server flight to the memory BIO so the TLS session
     // can read it. The next call to SSL_do_handshake() will handle
     // this received server flight
     BIO_write(bio_in, inbound, num_bytes);

   } while (!SSL_is_init_finished(ssl));

   // Send a message to the server. Calling SSL_write() will run the
   // plaintext through the TLS session and write the encrypted TLS
   // records to the BIO buffer
   SSL_write(ssl, "Hello World", strlen("Hello World"));

   // Read the TLS records from the BIO buffer and
   // POST them to the server
   BIO_read(bio_out, outbound, MAX);
   num_bytes = postTlsRecords(outbound, inbound);






Friel, et al.              Expires May 3, 2018                 [Page 16]


Internet-Draft                    ATLS                      October 2017


12.2.  B.2 Java JSSE

   The Java SSLEngine class "enables secure communications using
   protocols such as the Secure Sockets Layer (SSL) or IETF RFC 2246
   "Transport Layer Security" (TLS) protocols, but is transport
   independent".  This pseudo code illustrates how a server could use
   the SSLEngine class to handle an inbound client TLS flight and
   generate an outbound server TLS flight response.











































Friel, et al.              Expires May 3, 2018                 [Page 17]


Internet-Draft                    ATLS                      October 2017


   SSLEngine sslEngine = SSLContext.getDefault().createSSLEngine();
   sslEngine.setUseClientMode(false);
   sslEngine.beginHandshake();

   // Lets assume 'inbound' has been populated with
   // the Client 1st Flight
   ByteBuffer inbound;

   // 'outbound' will be populated with the
   // Server 1st Flight response
   ByteBuffer outbound;

   // SSLEngine handles one TLS Record per call to unwrap().
   // Loop until the engine is finished unwrapping.
   while (sslEngine.getHandshakeStatus() ==
          HandshakeStatus.NEED_UNWRAP) {
     SSLEngineResult res = sslEngine.unwrap(inbound, outbound);

     // SSLEngine may need additional tasks run
     if (res.getHandshakeStatus() == NEED_TASK) {
       Runnable run = sslEngine.getDelegatedTask();
       run.run();
     }
   }

   // The SSLEngine has now finished handling all inbound TLS Records.
   // Check if it wants to generate outbound TLS Records. SSLEngine
   // generates one TLS Record per call to wrap().
   // Loop until the engine is finished wrapping.
   while (sslEngine.getHandshakeStatus() ==
          HandshakeStatus.NEED_WRAP) {
     SSLEngineResult res = sslEngine.wrap(inbound, outbound);

     // SSLEngine may need additional tasks run
     if (res.getHandshakeStatus() == NEED_TASK) {
       Runnable run = sslEngine.getDelegatedTask();
       run.run();
     }
   }

   // outbound ByteBuffer now contains a complete server flight
   // containing multiple TLS Records
   // Rinse and repeat!








Friel, et al.              Expires May 3, 2018                 [Page 18]


Internet-Draft                    ATLS                      October 2017


13.  Appendix C.  Example ATLS Handshake

   [[ EDITOR'S NOTE: For completeness, include a simple full TLS
   handshake showing the B64 encoded flights in JSON, along with the
   HTTP request/response/headers.  And also the raw hex TLS records
   showing protocol bits ]]

14.  Informative References

   [I-D.ietf-tls-tls13]
              Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", draft-ietf-tls-tls13-21 (work in progress),
              July 2017.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246,
              DOI 10.17487/RFC5246, August 2008,
              <https://www.rfc-editor.org/info/rfc5246>.

   [RFC5705]  Rescorla, E., "Keying Material Exporters for Transport
              Layer Security (TLS)", RFC 5705, DOI 10.17487/RFC5705,
              March 2010, <https://www.rfc-editor.org/info/rfc5705>.

   [RFC7516]  Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
              RFC 7516, DOI 10.17487/RFC7516, May 2015,
              <https://www.rfc-editor.org/info/rfc7516>.

   [RFC8188]  Thomson, M., "Encrypted Content-Encoding for HTTP",
              RFC 8188, DOI 10.17487/RFC8188, June 2017,
              <https://www.rfc-editor.org/info/rfc8188>.

Authors' Addresses

   Owen Friel
   Cisco

   Email: ofriel@cisco.com


   Richard Barnes
   Cisco

   Email: rlb@ipv.sx








Friel, et al.              Expires May 3, 2018                 [Page 19]


Internet-Draft                    ATLS                      October 2017


   Max Pritikin
   Cisco

   Email: pritikin@cisco.com















































Friel, et al.              Expires May 3, 2018                 [Page 20]


Html markup produced by rfcmarkup 1.124, available from https://tools.ietf.org/tools/rfcmarkup/