draft-openconnect.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [

 	<!ENTITY RFC8446 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.8446.xml">

 	<!ENTITY RFC5746 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.5746.xml">

	<!ENTITY RFC2119 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">

	<!ENTITY RFC2743 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.2743.xml">

	<!ENTITY RFC6066 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.6066.xml">

	<!ENTITY RFC7301 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.7301.xml">

	<!ENTITY RFC6347 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.6347.xml">

	<!ENTITY RFC4559 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.4559.xml">

	<!ENTITY RFC2616 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">

	<!ENTITY RFC4519 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.4519.xml">

	<!ENTITY RFC6164 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.6164.xml">

	<!ENTITY RFC3706 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.3706.xml">

	<!ENTITY RFC5056 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.5056.xml">

	<!ENTITY RFC5705 SYSTEM
	"http://xml.resource.org/public/rfc/bibxml/reference.RFC.5705.xml">

	<!ENTITY I-D.ietf-tls-dtls13 SYSTEM
	"http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-tls-dtls13-28.xml">
]>



<?rfc rfcedstyle="yes" ?>
<?rfc subcompact="no" ?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>

<rfc category="info" ipr="trust200902" docName="draft-mavrogiannopoulos-openconnect-02">
   <front>
      <title abbrev="The OpenConnect Version 1.1">The OpenConnect VPN Protocol Version 1.1</title>

      <author initials="N." surname="Mavrogiannopoulos" fullname="Nikos Mavrogiannopoulos">
         <organization>Red Hat</organization>
      <address>
        <email>nmav@redhat.com</email>
      </address>
      </author>

      <date month="October" year="2018"/>
      <area>Security</area>
      <keyword>SSL</keyword>
      <keyword>TLS</keyword>
      <keyword>VPN</keyword>
      <keyword>Secure sockets layer</keyword>
      <keyword>Virtual Private Network</keyword>
      <keyword>Transport layer security</keyword>


      <abstract>
<t>
   This document specifies version 1.1 of the OpenConnect Virtual Private
   Network (VPN) protocol, a secure VPN protocol that provides
   communications privacy over the Internet.  That protocol is believed
   to be compatible with CISCO's AnyConnect VPN protocol. The protocol allows
   the establishment of VPN tunnels in a way that is designed
   to prevent eavesdropping, tampering, or message forgery.
         </t>
      </abstract>

   </front>

<middle>


<section anchor="intro" title="Introduction">
    <t>
   The purpose of this document is to specify the OpenConnect VPN protocol
   in a detail in order to allow for multiple interoperable implementations.
   This is the protocol used by the OpenConnect client and server
   <xref target="OPENCONNECT-CLIENT"/><xref target="OPENCONNECT-SERVER"/>, 
   and is believed to be compatible with CISCO's AnyConnect protocol.
   </t>
   <t>
   This protocol's design follows a minimalistic modular philosophy.
   It delegates several protocol-related elements often considered as core VPN
   features and diversifiers, to standards protocols. That delegation, allows
   a minimalistic core protocol which contains very few security related elements
   and is decoupled from cryptography. That in turn transfers the auditing
   requirements due to cryptographic and negotiation protocols to dedicated
   for that purpose components.
   In particular the Openconnect VPN protocol uses standard protocols such as HTTP,
   TLS <xref target="RFC8446"/> and DTLS <xref target="RFC6347"/> to provide a
   VPN with data security and authenticity.</t>

<section anchor="terminology" title="Requirements Terminology">
<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"/>.
</t>
</section>
<section anchor="goals-document" title="Goals of This Document">
<t>
   The OpenConnect protocol version 1.1 specification is intended primarily
   for readers who will be implementing the protocol and those doing
   cryptographic analysis of it.
</t>
</section>
</section>

<section anchor="oc-protocol" title="The OpenConnect Protocol">
<t>
   The OpenConnect protocol combines the TLS protocol <xref
   target="RFC8446"/>, Datagram TLS protocol <xref
   target="RFC6347"/> and HTTP protocols <xref
   target="RFC2616"/> to provide an Internet-Layer VPN channel.
   The channel is designed to operate using UDP packets, and
   fallback on TCP if that's not possible.
</t>
<t>
   In brief the protocol initiates an HTTP over TLS connection
   on a known port, where client authentication is performed. After
   this step, the client initiates an HTTP CONNECT command to
   establish a VPN channel over TCP. A secondary VPN channel over
   UDP will be established using information provided by the server
   using HTTP headers. At that point the raw IP packets flow, over
   the VPN channels.
</t>

<section anchor="session-establishment" title="VPN Session Establishment">
<t>
   The client and server establish a TLS connection over a known port,
   typically over 443, the port used for HTTPS. The client SHOULD
   negotiate TLS 1.1 or later, and support the following TLS protocol extensions.

       <list style="hanging">
       <t>Server Name Indication <xref target="RFC6066"/>: the client SHOULD provide the DNS name of
       the server in the TLS handshake.</t>
       <t>Application-Layer Protocol Negotiation <xref target="RFC7301"/>: the client MAY provide
       this protocol name. The protocol name to be used is defined in <xref
       target="alpn-name"/>.</t>
       </list>

</t>

  <section anchor="server-authentication" title="Server Authentication">
  <t>
  In the OpenConnect VPN protocol, the server is always authenticated using its
  certificate. Once a client establishes a TCP connection to the server's well known
  port, it initiates the TLS protocol. 
  In the first connection to the server, the client SHOULD verify the 
  provided by the server certificate, and SHOULD store its public key for 
  verification of subsequent sessions. Thus, subsequent sessions SHOULD
  check whether the server's key match the initial.
  </t>
  <t>
  The server's identity in the certificate SHOULD be placed in the
  certificate's SubjectAlternativeName field, and unless a special
  profile is assumed, it will be of type DNSName.
  </t>
  </section>

  <section anchor="authentication" title="Client Authentication">
  <t>
  The OpenConnect VPN protocol allows for the following types of
  client authentication, or combinations of them.
	<list style="numbers">
	<t>Password: a user can authenticate itself using a password.</t>
	<t>Certificate: a user can authenticate itself using a PKIX certificate
	it possesses.</t>
	<t>HTTP SPNEGO: a user can authenticate itself using a Kerberos ticket, or any
	other mechanism supported by SPNEGO (i.e., GSSAPI).</t>
    </list>
  The server is authenticated to the client using a PKIX certificate
  presented during the TLS negotiation.
  </t>
  <t>
  It is important to note that during the password and HTTP SPNEGO authentication
  methods, any headers allowed by the HTTP protocol can be present. In fact, 
  there are legacy clients which assume that the server will keep a state using
  cookies, and send their username and password in different TLS and HTTP
  connections. This practice prevents the server from binding the TLS
  channel with the VPN session <xref target="RFC5056"/>, and is discouraged.
  It is RECOMMENDED for clients to complete authentication in the same TLS
  session, and rely on TLS session resumption if reconnections to the server
  are needed.
  </t>

  <t>
  After the TLS session is established the client irrespective of the
  supported authentication methods, should send an HTTP POST request
  on "/" with a config-auth XML structure of type 'init'. An example of its
  contents follow.
  <figure><artwork><![CDATA[
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE config-auth SYSTEM "config-auth.dtd">
    <config-auth client="vpn" type="init">
        <version who="vpn">v5.01</version>
    </config-auth>
  ]]></artwork></figure>
  </t>
  <t>
  The precise DTD declarations for the contents of XML messages defined in
  this document are listed in <xref target="dtd-decl"/>. Also the
  HTTP Content-Type to be used for these XML structures MUST be 'text/xml'.
  </t>

  <section anchor="authentication_cert" title="Authentication using certificates">
  <t>
  During the initial TLS protocol handshake the server may require
  a client certificate to be presented, depending on its configuration.
  </t>
  <t>
  Because the client certificate is sent in the clear during the handshake
  it SHOULD NOT contain other identifying information other than a username,
  or a pseudonymus identifier. It is RECOMMENDED to place the user identifier
  in the DN field of the certificate, using the UID object identifier
  (0.9.2342.19200300.100.1.1) <xref target="RFC4519"/>.
  </t>
  <t>
  After the TLS session is established and the the config-auth XML structure of type 'init'
  is sent, the server should send it reply. If the certificate sent by the
  client was successfully validated, it should reply using
  the HTTP response code 200, and the contents of the reply should be
  a config-auth XML structure of type 'complete', as follows.
  </t>
  <t>
  <figure><artwork><![CDATA[
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE config-auth SYSTEM "config-auth.dtd">
    <config-auth client="vpn" type="complete">
      <version who="sg">0.1(1)</version>
      <auth id="success">
        <title>SSL VPN Service</title>
      </auth>
    </config-auth>
  ]]></artwork></figure>
  </t>
  <t>
  In that case the client should proceed to the
  establishment of the primary channel as in <xref target="primary-channel"/>.
  </t>

  </section>

  <section anchor="authentication_pass" title="Authentication using passwords">
  <t>
  After the TLS session is established and the the config-auth XML structure of type 'init'
  is sent, the server will reply using forms the client software should prompt the
  user to fill in. Its reply utilizes a config-auth XML structure of type
  'auth-request'.
  <figure><artwork><![CDATA[
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE auth SYSTEM "config-auth.dtd">
    <config-auth client="vpn" type="auth-request">
        <auth id="main">
            <message>Please enter your username</message>
            <form action="/auth" method="post">
                <input label="Username:" name="username" type="text" />
            </form>
        </auth>
    </config-auth>
  ]]></artwork></figure>
  </t>
  <t>
  The client may be asked to provide the information in separate forms as
  above, or may be asked combined as below.
  <figure><artwork><![CDATA[
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE auth SYSTEM "config-auth.dtd">
    <config-auth client="vpn" type="auth-request">
      <auth id="main">
        <message>Please enter your username</message>
        <form action="/auth" method="post">
            <input label="Username:" name="username" type="text"/>
            <input label="Password:" name="password" type="password"/>
        </form>
      </auth>
    </config-auth>
  ]]></artwork></figure>
  </t>
  <t>
  The client software will then fill in the provided form and sent it back
  to the server using an HTTP POST on the location specified by the server
  (in the above examples it was "/auth"). The reply would then be of type
  'auth-reply' as in the following example.

  <figure><artwork><![CDATA[
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE config-auth SYSTEM "config-auth.dtd">
    <config-auth client="vpn" type="auth-reply">
        <version who="vpn">v5.01</version>
        <auth><username>test</username>
        </auth>
    </config-auth>  
  ]]></artwork></figure>
  </t>
  <t>
  As mentioned above, the server may ask repeatedly for information until it
  believes the user is authenticated. For example, the server could present
  a second form asking for the password, after the username is provided, or
  ask for a second password if that is necessary. In these cases the server
  should respond with an HTTP 200 OK status code, and proceed sending its
  new request.
  </t>
  <t>
  If client authentication fails, the server MUST respond with an HTTP 401
  unauthorized status code. Otherwise, on successful authentication
  the server should reply with a 200 HTTP code and use the 'complete' config-auth
  XML structure as in <xref target="authentication_cert"/>.
  </t>
  <t>
  Note, that sending the username and password in different messages will
  reveal the length of them to a passive eavesdropper. For that is is
  RECOMMENDED for clients to use the 'X-Pad' HTTP header, which will contain
  arbitrary printable data to make the message length a multiple of 64 bytes.
  </t>
  <t>
  An example session is shown in figure <xref target="example1"/>.</t>
  <t>
  <figure anchor='example1'><artwork><![CDATA[
        ,-.                                                                   
        `-'                                                                   
        /|\                                                                   
         |                                ,------.          ,----------.      
        / \                               |Server|          |ServerDTLS|      
      Client                              `--+---'          `----+-----'      
        |     TLS handshake Client Hello     |                   |            
        | ----------------------------------->                   |            
        |                                    |                   |            
        |       TLS handshake Finished       |                   |            
        | <-----------------------------------                   |            
        |                                    |                   |            
        |     HTTP POST config-auth init     |  ,--------------------!.       
        | ----------------------------------->  |This is an HTTP over|_\      
        |                                    |  |TLS session.          |      
        |                                    |  `----------------------'      
        |      config-auth auth-request      |                   |            
        | <-----------------------------------                   |            
        |                                    |                   |            
        |  HTTP POST config-auth auth-reply  |                   |            
        | ----------------------------------->                   |            
        |                                    |                   |            
        |        config-auth complete        |                   |            
        | <-----------------------------------                   |            
        |                                    |                   |            
        |            HTTP CONNECT            |                   |            
        | ----------------------------------->                   |            
        |                                    |                   |            
        |                                    |                   |            
        |            ===================================         |            
====================== CSTP VPN session is established =======================
        |            ===================================         |            
        |                                    |                   |            
        |                                    |  ,-------------------------!.  
        | TLS record packet with CSTP payload|  |These packets show       |_\ 
        | ----------------------------------->  |that IP traffic can start  | 
        |                                    |  |prior to the DTLS channel  | 
        |                                    |  |establishment.             | 
        |                                    |  `---------------------------' 
        | TLS record packet with CSTP payload|                   |            
        | <-----------------------------------                   |            
        |                                    |                   |            
        |               DTLS handshake Client Hello              |            
        |  - - - - - - - - - - - - - - - - - - - - - - - - - - - >            
        |                                    |                   |            
        |                 DTLS handshake Finished                |            
        | <- - - - - - - - - - - - - - - - - - - - - - - - - - - -            
        |                                    |                   |            
        |                                    |                   |            
        |            ===================================         |            
====================== DTLS VPN channel is established =======================
        |            ===================================         |            
        |                                    |                   |            
        |             DTLS record packet with payload            |            
        |  - - - - - - - - - - - - - - - - - - - - - - - - - - - >            
        |                                    |                   |            
        |             DTLS record packet with payload            |            
        | <- - - - - - - - - - - - - - - - - - - - - - - - - - - -            
      Client                              ,--+---.          ,----+-----.      
        ,-.                               |Server|          |ServerDTLS|      
        `-'                               `------'          `----------'      
        /|\                                                                   
         |                                                                    
        / \                                                                   
  ]]></artwork></figure>
  </t>
  </section>
  
  <section anchor="authentication_gssapi" title="HTTP Authentication using SPNEGO">
<t>
That type of authentication is performed using the HTTP SPNEGO protocol <xref
target="RFC4559"/>, a method which is available using the Generic Security
Service API <xref target="RFC2743"/>. The following approach is used
to advertise the availability of the HTTP SPNEGO protocol by the client.
A client which supports the HTTP SPNEGO protocol, SHOULD indicate it using the
following header on in its initial request to the server with the
config-auth 'init' XML structure.
</t>
<t>
<figure>
<artwork><![CDATA[
    X-Support-HTTP-Auth: true
]]></artwork>
</figure></t>

<t>
After that the server would report a "401 Unauthorized" status code
and authentication would proceed as specified in the HTTP SPNEGO protocol.
The server may utilize the following header, to indicate that alternative
authentication methods are available (e.g., with plain password), if
authentication fails.
</t>
<t>
<figure><artwork><![CDATA[
    X-Support-HTTP-Auth: fallback
]]></artwork></figure>
</t>
  <t>
  If client authentication fails, the server MUST respond with an HTTP 401
  unauthorized status code. In that case, a client which received the previous
  header should retry authenticating to the
  server without sending the "X-Support-HTTP-Auth: true" header.
  </t>
  <t>
  Otherwise, on successful authentication
  the server should reply with a 200 HTTP code and use the 'complete' config-auth
  XML structure as in <xref target="authentication_cert"/>.
  </t>
  </section>

  </section>
  <section anchor="params-exchange" title="Exchange of Session Parameters">
  <t>
  By the receipt of a success XML structure, the client SHOULD issue an HTTP
  CONNECT request. In addition it may provide the following headers.
  
       <list style="hanging">
       <t>X-CSTP-Address-Type: A comma separated list of the requested address types.
	       <list style="hanging">
	       <t>IPv4: when the client only supports IPv4 addresses.</t>
	       <t>IPv6: when the client only supports IPv6 addresses.</t>
	       <t>IPv4,IPv6: when the client supports both types of IP addresses.</t>
	       </list>
	       </t>
       <t>X-CSTP-Base-MTU: The MTU of the link as estimated by the
	       client.
       </t>
       <t>X-CSTP-Accept-Encoding: A comma separated list of accepted
       compression algorithms for the CSTP channel.
       </t>
       <t>User-Agent: A string identifying the client software.</t>
       </list>
       </t>
  <t>
  For the options related to compression see <xref target="compression"/> for more information.  </t>
  <t>
  An example CONNECT request is shown below.
  </t>
  <t>
  <figure><artwork><![CDATA[
    User-Agent: Open AnyConnect VPN Agent v5.01
    X-CSTP-Base-MTU: 1280
    X-CSTP-Address-Type: IPv4,IPv6
    CONNECT /CSCOSSLC/tunnel HTTP/1.1
  ]]></artwork></figure>
  </t>
  <t>
  After a successful receipt of an HTTP CONNECT request, the server should
  reply and provide the client with configuration parameters. The available
  options follow.

       <list style="hanging">
       <t>X-CSTP-Address: The IPv4 address of the client, if IPv4 has been
       requested.</t>
       <t>X-CSTP-Netmask: An IPv4 netmask to be pushed to the client, if IPv4 has been
       requested. This should contain the mask on the P-t-P link and is
       RECOMMENDED the server address to be the first in defined network.
       </t>
       <t>X-CSTP-Address-IP6: The IPv6 address of the client in CIDR
       notation, if IPv6 has been requested. The prefix length is
       RECOMMENDED to be set to 127-bits according to <xref target="RFC6164"/>.</t>
       <t>X-CSTP-DNS: The IP address of a DNS server that can be used for
       that session.</t>
       <t>X-CSTP-Default-Domain: The DNS domains the provided DNS servers
       respond for.</t>
       <t>X-CSTP-Split-Include: The network address of a route which is
       provided by this server.</t>
       <t>X-CSTP-Split-Exclude: The network address of a route that is not
       provided by this server.</t>
       <t>X-CSTP-Base-MTU: The MTU of the link as estimated by this
       server.</t>
       <t>X-CSTP-DynDNS: Set to "true" if the server is operating with a
       dynamic DNS address.</t>
       <t>X-CSTP-Content-Encoding: if present is it set to one of the values
       presented by the client in 'X-CSTP-Accept-Encoding' header. It will
       be the compression algorithm used in the CSTP channel.</t>
       <t>X-DTLS-Content-Encoding: if present is it set to one of the values
       presented by the client in 'X-DTLS-Accept-Encoding' header. It will
       be the compression algorithm used in the DTLS channel.</t>
       </list>
  </t>
  <t>
The client is expected to treat the received parameters as his networking
settings. If no "X-CSTP-Split-Include" headers are present, the client is
expected to assign its default route through the VPN.
  </t>
  </section>

  <section anchor="primary-channel" title="Establishment of Primary TCP Channel (CSTP)">
  <t>The previous HTTP message is the last HTTP message sent by the server.
  After that message, the established TCP channel is used to transport IP
  packets between the client and the server. The transferred packets
  encoding is discussed in <xref target="primary-channel-protocol"/>. This
  channel will be referred as CSTP in the rest of this document.
  </t>
  </section>

  <section anchor="secondary-channel-establishment" title="Establishment of Secondary UDP Channel (DTLS)">

  <t>To establish the secondary UDP-based channel, which will be referred to as the DTLS channel,
  the client must advertise support for it during the issue of the HTTP CONNECT request
  (see <xref target="params-exchange"/>). This is done by appending the following headers
  to the request.
       <list style="hanging">
        <t>X-DTLS-Accept-Encoding: A comma separated list of accepted
        compression algorithms for the DTLS channel.
        </t>
	<t>X-DTLS-CipherSuite: Must contain the keyword PSK-NEGOTIATE.</t>
       </list>
  </t>
  <t>
  The DTLS channel utilizes the PSK key exchange method.
  The key material for this session is a 256-bit value generated with an <xref
 target="RFC5705"/> exporter. The key material exporter uses the label
  "EXPORTER-openconnect-psk" without the quotes, and without any context
  value.
  </t>
  <t>In its client hello message the client must copy the value received in the
  'X-DTLS-App-ID' header (after hex decoding it), to the session ID field of
  the DTLS client hello.  That identifier, is not used for session resumption,
  and is used by the server to associate the DTLS channel with the CSTP channel.
  The following headers are used by the server's response to CONNECT, and are
  related to the DTLS channel establishment.
       <list style="hanging">
	<t>X-DTLS-App-ID: A hex encoded value to be used as a DTLS application-specific
	identifier by the client. It serves as an identifier for the server to associate the
	incoming DTLS session with the TLS session.</t>
	<t>X-DTLS-Port: The port number to which the client should send UDP
	packets for DTLS.</t>
	<t>X-DTLS-CipherSuite: It must contain the value "PSK-NEGOTIATE" without any quotes.</t>
	<t>X-DTLS-Rekey-Time: The time (in seconds) after which the DTLS
	session should rekey, see <xref target="rekey-protocol"/>. Only considered if
	applicable to the negotiated DTLS protocol.</t>
	<t>X-DTLS-Rekey-Method: The method used in DTLS rekey, see <xref target="rekey-protocol"/>.
	Only considered if applicable to the negotiated DTLS protocol.</t>
       </list>
  </t>
  <t>
  Note that in future versions of the Datagram TLS protocol (see <xref target="I-D.ietf-tls-dtls13"/>),
  clients should supply the value in 'X-DTLS-App-ID' header as a PSK identity after hex decoding it.
  </t>

  <section anchor="legacy-secondary-channel-establishment" title="Legacy Establishment of Secondary UDP Channel (DTLS)">
  <t>Previous versions of this protocol utilized a special DTLS protocol negotiation,
  based on an unpublished description of the DTLS protocol.
  This section attempts to summarize this negotiation, but may not be entirely accurate.
  </t>
  <t>
  To establish the legacy UDP-based channel, the client must advertise support for it 
  during the issue of the HTTP CONNECT request (see <xref target="params-exchange"/>). This is
  done by appending the following headers to the request.
       <list style="hanging">
        <t>X-DTLS-Accept-Encoding: A comma separated list of accepted
        compression algorithms for the DTLS channel.
        </t>
	<t>X-DTLS-Master-Secret: A hex encoded pre-master secret to be used
	in the legacy DTLS session negotiation.</t>
	<t>X-DTLS-CipherSuite: A colon-separated list of ciphers (e.g., the
	string PSK-NEGOTIATE:AES256-SHA:AES128-SHA:DES-CBC3-SHA).</t>
       </list>
  </t>
  <t>
  The DTLS channel utilizes session resumption as a method
  for preshared-key authentication. That is the value presented in
  X-DTLS-Master-Secret is set as a master secret to be resumed. The session
  ID value is sent by the server on the response to CONNECT using the
  'X-DTLS-Session-ID' header. That header provides a hex-encoded value of
  the DTLS session ID to be used by the client. The following headers
  are used by the server's response to CONNECT, and are related to the DTLS
  channel establishment.
       <list style="hanging">
	<t>X-DTLS-Session-ID: A hex encoded value to be used as a DTLS
	session ID by the client. It also serves as an identifier for the server to associate the
	incoming DTLS session with the TLS session.</t>
	<t>X-DTLS-Port: The port number to which the client should send UDP
	packets for DTLS.</t>
	<t>X-DTLS-CipherSuite: The ciphersuite selected by the server. It
	should be one of the options present in the client's
	X-DTLS-CipherSuite header.</t>
	<t>X-DTLS-Rekey-Time: The time (in seconds) after which the DTLS
	session should rekey, see <xref target="rekey-protocol"/>.</t>
	<t>X-DTLS-Rekey-Method: The method used in DTLS rekey, see <xref target="rekey-protocol"/>.</t>
       </list>
  </t>
  <t>
  The following table lists the ciphers negotiated via the
  X-DTLS-CipherSuite header, and the corresponding DTLS ciphersuite.
  	</t>
	<texttable anchor='cipher_table'>
		<preamble></preamble>
		<ttcol width="30%" align='center'>OpenConnect cipher</ttcol>
		<ttcol width="50%" align='center'>DTLS ciphersuite</ttcol>
		<ttcol width="20%" align='center'>DTLS version</ttcol>
<c>   DES-CBC3-SHA</c><c>TLS_RSA_WITH_3DES_EDE_CBC_SHA1</c><c>DTLS 0.9 (pre-draft version)</c>
<c>   AES128-SHA</c><c>TLS_RSA_WITH_AES_128_CBC_SHA1</c><c>DTLS 0.9 (pre-draft version)</c>
<c>   AES256-SHA</c><c>TLS_RSA_WITH_AES_256_CBC_SHA1</c><c>DTLS 0.9 (pre-draft version)</c>
<c>   OC-DTLS1_2-AES128-GCM</c><c>TLS_RSA_WITH_AES_128_GCM_SHA256</c><c>DTLS 1.2</c>
<c>   OC-DTLS1_2-AES256-GCM</c><c>TLS_RSA_WITH_AES_256_GCM_SHA256</c><c>DTLS 1.2</c>
		<postamble></postamble>
	</texttable>
  <t>
  The legacy DTLS protocol negotiation described in this section, is similar to DTLS 1.0 except for the following deviations:
       <list style="hanging">
	<t>The negotiated protocol version for the handshake and record headers is 1.0 instead of 254.255.</t>
	<t>The Hello Verify and Hello verify request messages are included in the handshake hashes.</t>
	<t>The handshake header is not included as part of the handshake hashes.</t>
	<t>The ChangeCipherSpec message is 3 byte long instead of 1, and contains the handshake
	   sequence number (2-bytes long) appended to the message id.</t>
       </list>
  </t>
  </section>

  </section>

</section>

<section anchor="primary-channel-protocol" title="The CSTP Channel Protocol">
<t>
The format of the packets sent over the primary channel consists of an
8-bytes header followed by data. The whole packet
in encapsulated in a TLS record (see <xref
 target="RFC8446"/>). The bytes of the header indicate the type of data
that follow, and their contents are explained in <xref target="cstp_table"/>.
</t>

	<texttable anchor='cstp_table'>
		<preamble></preamble>
		<ttcol width="30%" align='center'>byte</ttcol>
		<ttcol width="30%" align='left'>value</ttcol>
<c>0</c><c>fixed to 0x53 (S)</c>
<c>1</c><c>fixed to 0x54 (T)</c>
<c>2</c><c>fixed to 0x46 (F)</c>
<c>3</c><c>fixed to 0x01</c>
<c>4-5</c><c>The length of the packet that follows this header in big endian order</c>
<c>6</c><c>The type of the payload that follows (see <xref target="packet_table"/> for available types)</c>
<c>7</c><c>fixed to 0x00</c>
		<postamble></postamble>
	</texttable>

<t>
The available payload types are listed in <xref target="packet_table"/>.
</t>
	<texttable anchor='packet_table'>
		<preamble></preamble>
		<ttcol width="30%" align='center'>Value</ttcol>
		<ttcol width="50%" align='left'>Description</ttcol>
<c>0x00</c><c>DATA: the TLS record packet contains an IPv4 or IPv6 packet</c>
<c>0x03</c><c>DPD-REQ: used for dead peer detection. Once sent the peer
should reply with a DPD-RESP packet, that has the same contents as the
original request.</c>
<c>0x04</c><c>DPD-RESP: used as a response to a previously received DPD-REQ.</c>
<c>0x05</c><c>DISCONNECT: sent by the client (or server) to terminate the session.
No data is associated with this request. The session will be invalidated
after such request.</c>
<c>0x07</c><c>KEEPALIVE: sent by any peer. No data is associated with this
request.</c>
<c>0x08</c><c>COMPRESSED DATA: a Data packet which is compressed prior to encryption.</c>
<c>0x09</c><c>TERMINATE: sent by the server to indicate that the server is shutting down. No data is associated with this
request.</c>
		<postamble></postamble>
	</texttable>
</section>

<section anchor="secondary-channel-protocol" title="The DTLS Channel Protocol">
<t>
The format of the packets sent over the UDP channel consists of an
1-byte header followed by data. The header byte 
indicates the type of data that follow as in <xref target="packet_table"/>.
The header and the data are encapsulated in a DTLS record packet
(see <xref target="RFC6347"/>).
</t>
</section>

<section anchor="rekey-protocol" title="The Channel Re-Key Protocol">
<t>
During the exchange of session parameters (<xref
target="params-exchange"/>), the server advertizes the methods available
for session rekey using the "X-CSTP-Rekey-Method" and "X-DTLS-Rekey-Method"
HTTP headers. The available options for both the server and client are
listed below.
</t>
<t>
	<list style="numbers">
	<t>none: no rekey; the session will go on until 2^48 DTLS records
	have been exchanged, or 2^64 TLS records.</t>
	<t>ssl: a TLS or DTLS rehandshake will be performed
	periodically.</t>
	<t>new-tunnel: the session will tear down and the client will
	reconnect periodically.</t>
    </list>
</t>
<t>
When the value is other than "none" the rekey period is determinated by the
"X-CSTP-Rekey-Time" and "X-DTLS-Rekey-Time" headers. These headers contain
the time in seconds after which a session should rekey.
</t>
<t>
It should be noted that when the "ssl" rekey option is used, care must be
taken by both the client and the server to ensure that either safe
renegotiation is used (<xref target="RFC5746"/>), or that the identity of
the peer remained the same.
</t>
</section>

<section anchor="dead-peer-detection" title="The Keepalive and Dead Peer Detection
Protocols">
<t>
In OpenConnect there are two packet types that can be used for keep-alive or
dead peer detection, as shown in <xref target="packet_table"/>. These are
the DPD-REQ and KeepAlive packets.
</t>
<t>
The timings of the transmission of these packets are set by the server, and
they for the DPD are advisory to a client. However, any peer receiving these packets
MUST response with the appropriate packet. For DPD-REQ packets, the response
MUST be DPD-RESP, and for KeepAlive packets the response must be another
KeepAlive packet. The main difference between these two types of packets,
is that the DPD packets similarly to <xref target="RFC3706"/> are sent when
there is no traffic or when the other party requests them, and allow for arbitrary
data to be attached, making them suitable for Path MTU detection.
</t>
<t>
The server advertizes the suggested periods during the exchange of session parameters (<xref
target="params-exchange"/>). The available headers are listed below.
</t>
<t>
	<list style="items">
	<t>X-CSTP-DPD: applicable to CSTP channel; contains a relative time in seconds.</t>
	<t>X-CSTP-Keepalive: applicable to CSTP channel; contains a relative time in seconds.</t>
	<t>X-DTLS-DPD: applicable to DTLS channel; contains a relative time in seconds.</t>
	<t>X-DTLS-Keepalive: applicable to DTLS channel; contains a relative time in seconds.</t>
    </list>
</t>
</section>

</section>

<section anchor="security-analysis" title="Security Considerations">
	<t>
This document provides a description of a protocol to establish
a VPN over a TLS channel. All security
considerations of the referenced documents in particular
<xref target="RFC8446"/> and <xref target="RFC6347"/> are applicable,
in addition the following considerations.
</t>
       <t>The protocol is designed to be as compatible as possible with
       a legacy VPN protocol and as such it carries cruft, such as
       partial dependence on a non-standard DTLS version, and utilization
       of an awkward method to establish a DTLS session which relies
       on session resumption. Nevertheless, these particularities are not
       believed to cause a degradation of the overall protocol security,
       and could be addressed with a backwards compatible protocol upgrade.</t>

       <t>The protocol provides a VPN channel which carries payload
       hidden from eavesdroppers. However, the payload's length remain
       visible and in certain scenarios that may be sufficient to
       determine the transferred payload. Furthermore, there are scenarios
       where compressed payload lengths may reveal more information than
       the uncompressed data <xref target="COMP-ISSUES"/><xref
       target="COMP-ISSUES2"/>.
       For that we RECOMMEND that implementations
       don't enable compression by default, and only allow it after
       notifying the users and administrators about the consequences.
       </t>

       <t>This protocol could sometimes be used because of the fact that it
       ressembles the TLS protocol and thus is not detected by the available
       VPN blockers. While an implementation could intentionally masquerade
       its packets to ressemble a typical HTTPS session, a fully compliant
       implementation will be distinct from an average HTTP session due to the
       DTLS session establishment, and the transferred packet sizes.
       </t>
       <t>
       For certificate authentication OpenConnect relies on the
       TLS protocol. However, as mentioned in the text, TLS version 1.2 and earlier
       do not protect the client's (or the server's) certificate from
       eavesdroppers. For that it is RECOMMENDED that certificates to be
       used with this protocol contain the minimum possible identifying
       information.
       </t>
       <t>
       This document defines a protocol name for Application-Layer Protocol
       Negotiation. That, if used by a client would indicate to any
       eavesdropping parties that the client wishes to use VPN, thus
       compromising its intention privacy. On the other hand, providing
       that information would help a server that re-uses the same port
       for different protocols under TLS, to forward to the appropriate handler
       of the connection. That is, it would allow hosting a plain HTTPS server
       serving content, and a VPN server using openconnect at the same port.
       It is left to the client to decide the balance between privacy and
       usability with such servers.
       </t>
</section>

<section title="Acknowledgements">
<t>
None yet.
</t>
</section>

  </middle>

  <back>


    <references title="Normative References">
	&RFC8446;

	&RFC5746;

	&RFC6347;

	&RFC2616;

	&RFC4559;

	&RFC2743;
	
	&RFC5056;

	&RFC5705;

	&RFC4519;

	&RFC6066;

	&RFC7301;

	&RFC6164;

	&RFC3706;

	&RFC2119;

	&I-D.ietf-tls-dtls13;

      <reference anchor="COMP-ISSUES">
	<front>
	  <title>TLS Compression Fingerprinting and
	  a Privacy-aware API for TLS</title>
	  <author initials="K." surname="Bhargavan"
		  fullname="Karthikeyan Bhargavan"/>
	  <author initials="C." surname="Fournet"
		  fullname="Cedric Fournet"/>
	  <author initials="M." surname="Kohlweiss"
		  fullname="Markulf Kohlweiss"/>
	  <author initials="A." surname="Pironti"
		  fullname="Alfredo Pironti"/>
	  <author initials="P-Y." surname="Strub"
		  fullname="Pierre-Yves Strub"/>
	  <date year="2012" />
	</front>
      </reference>

      <reference anchor="COMP-ISSUES2">
	<front>
	  <title>Compression  and  information  leakage  of
	  plaintex</title>
	  <author initials="J." surname="Kelsey"
		  fullname="Kelsey"/>
	  <date year="2002" />
	</front>
	<seriesInfo name="International Workshop on Fast Software Encryption" value=""/>
      </reference>

      <reference anchor="OPENCONNECT-CLIENT">
	<front>
	  <title>http://www.infradead.org/openconnect/</title>
	  <author initials="D." surname="Woodhouse"
		  fullname="David Woodhouse"/>
	  <date year="2016" />
	</front>
      </reference>
      <reference anchor="OPENCONNECT-SERVER">
	<front>
	  <title>http://www.infradead.org/ocserv/</title>
	  <author initials="N." surname="Mavrogiannopoulos"
		  fullname="Nikos Mavrogiannopoulos"/>
	  <date year="2016" />
	</front>
      </reference>

    </references>

<section anchor="alpn-name" title="Name for Application-Layer Protocol Negotiation">
<t>

<figure>
<artwork><![CDATA[
   Protocol:  openconnect-vpn/1.1
   Identification Sequence:
           0x6f 0x70 0x65 0x6e 0x63 0x6f 0x6e 0x6e 0x65 0x63
           0x74 0x2d 0x76 0x70 0x6e 0x2f 0x31 0x2e 0x31
]]></artwork>
</figure></t>
</section>
<section anchor="compression" title="Compression">
<t>
The available compression algorithms for the CSTP and DTLS channels are
shown in <xref target="compression_table"/>. Note, that all algorithms are
intentionally stateless to prevent the influence of independent packets 
(e.g., from different sources) on each others compression. That does not
eliminate all known attacks on compression before encryption, and for
that reason an implentation MUST NOT enable compression by default.
</t>
<t>
After compression is negotiated each side may choose to compress the
payload and use the 'COMPRESSED DATA' header from <xref
target="packet_table"/>, or may send uncompressed data with the 'DATA'
payload. Each side MUST be able to process both payloads.
</t>
	<texttable anchor='compression_table'>
		<preamble></preamble>
		<ttcol width="30%" align='center'>Algorithm</ttcol>
		<ttcol width="50%" align='center'>Description</ttcol>
<c>   oc-lz4</c><c>The stateless LZ4 compression algorithm.</c>
<c>   lzs</c><c>The stateless LZS (stacker) compression algorithm.</c>
		<postamble></postamble>
	</texttable>

</section>

<section anchor="dtd-decl" title="DTD declarations">

<section anchor="dtd-decl1" title="config-auth.dtd">
<t>

<figure>
<artwork><![CDATA[
<!ELEMENT config-auth (version*,auth*)>
  <!ATTLIST config-auth client CDATA #FIXED "vpn">
  <!ATTLIST config-auth type (init|auth-reply|auth-request|complete) "init">
<!ELEMENT version (#PCDATA)>
  <!ATTLIST version who (sg|vpn) "sg">
<!ELEMENT auth (title*,username*,password*,message*,form*)>
  <!ATTLIST auth id (success|main|failure) "failure">
  <!ELEMENT title (#PCDATA)>
  <!ELEMENT username (#PCDATA)>
  <!ELEMENT password (#PCDATA)>
  <!ELEMENT message (#PCDATA)>
  <!ELEMENT form (input)>
    <!ATTLIST form action CDATA #FIXED "/auth">
    <!ATTLIST form method CDATA #FIXED "post">
    <!ELEMENT input (EMPTY)>
       <!ATTLIST input label CDATA "">
       <!ATTLIST input name (username|password) "username">
       <!ATTLIST input type (text|password) "text">
    <!ELEMENT select (option)>
       <!ATTLIST select label CDATA "">
       <!ATTLIST select name (group_list) "group_list">
    <!ELEMENT option (#PCDATA)>
]]></artwork>
</figure></t>
</section>

</section>
  </back>
</rfc>