Internet DRAFT - draft-mavrogiannopoulos-openconnect
draft-mavrogiannopoulos-openconnect
Network Working Group N. Mavrogiannopoulos
Internet-Draft Independent
Intended status: Informational July 2023
Expires: 24 January 2024
The OpenConnect VPN Protocol Version 1.2
draft-mavrogiannopoulos-openconnect-04
Abstract
This document specifies version 1.2 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.
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 2 January 2024.
Copyright Notice
Copyright (c) 2023 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 (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 Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Mavrogiannopoulos Expires 24 January 2024 [Page 1]
Internet-Draft The OpenConnect Version 1.2 July 2023
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Requirements Terminology . . . . . . . . . . . . . . . . 3
1.2. Goals of This Document . . . . . . . . . . . . . . . . . 3
2. The OpenConnect Protocol . . . . . . . . . . . . . . . . . . 3
2.1. Authentication . . . . . . . . . . . . . . . . . . . . . 3
2.1.1. Server authentication . . . . . . . . . . . . . . . . 3
2.1.2. Client authentication . . . . . . . . . . . . . . . . 3
2.2. VPN tunnel establishment . . . . . . . . . . . . . . . . 4
2.2.1. Tunnel initiation . . . . . . . . . . . . . . . . . . 4
2.2.2. Tunnel authentication using passwords . . . . . . . . 5
2.2.3. Tunnel authentication using certificates . . . . . . 6
2.2.4. Tunnel authentication using SPNEGO . . . . . . . . . 7
2.2.5. Tunnel and channels establishment . . . . . . . . . . 8
2.2.6. The primary CSTP channel - TCP . . . . . . . . . . . 10
2.2.7. The secondary DTLS channel - UDP . . . . . . . . . . 10
2.2.8. Overview of the tunnel establishment . . . . . . . . 11
2.3. The CSTP Channel Protocol . . . . . . . . . . . . . . . . 13
2.4. The DTLS Channel Protocol . . . . . . . . . . . . . . . . 15
2.5. The Channel Re-Key Protocol . . . . . . . . . . . . . . . 15
2.6. The Keepalive and Dead Peer Detection Protocols . . . . . 16
3. Security Considerations . . . . . . . . . . . . . . . . . . . 17
4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17
5. Normative References . . . . . . . . . . . . . . . . . . . . 17
Appendix A. Compression . . . . . . . . . . . . . . . . . . . . 19
Appendix B. DTD declarations . . . . . . . . . . . . . . . . . . 20
B.1. config-auth.dtd . . . . . . . . . . . . . . . . . . . . . 20
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
1. Introduction
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 [OPENCONNECT-CLIENT][OPENCONNECT-SERVER], and is believed
to be compatible with CISCO's AnyConnect protocol.
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 [RFC8446] and DTLS [RFC6347] to provide a VPN with
data security and authenticity.
Mavrogiannopoulos Expires 24 January 2024 [Page 2]
Internet-Draft The OpenConnect Version 1.2 July 2023
1.1. Requirements Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
1.2. Goals of This Document
The OpenConnect protocol version 1.2 specification is intended
primarily for readers who will be implementing the protocol and those
doing cryptographic analysis of it.
2. The OpenConnect Protocol
The OpenConnect protocol combines the TLS protocol [RFC8446],
Datagram TLS protocol [RFC6347] and HTTP protocols [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.
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.
2.1. Authentication
2.1.1. Server authentication
In the OpenConnect VPN protocol, the server is always authenticated
using its certificate for the HTTP over TLS session. The server's
identity in the certificate SHOULD be placed in the X.509
certificate's SubjectAlternativeName field, and be of type DNSName.
This doesn't imply a particular certificate validation model.
Clients also use an internet PKIX trust model, or trust on first use
key validation model.
2.1.2. Client authentication
The OpenConnect VPN protocol allows for the following types of client
authentication, or combinations of them.
1. Password: a user can authenticate itself using a password.
Mavrogiannopoulos Expires 24 January 2024 [Page 3]
Internet-Draft The OpenConnect Version 1.2 July 2023
2. Certificate: a user can authenticate itself using a PKIX
certificate it possesses.
3. HTTP SPNEGO: a user can authenticate itself using a Kerberos
ticket, or any other mechanism supported by SPNEGO (i.e.,
GSSAPI).
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, some legacy clients 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 [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.
2.2. VPN tunnel establishment
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.2 or later.
2.2.1. Tunnel initiation
A client initiates the session by start a TLS connection with the
server. The initial TLS Client Hello will contain a number of
extensions as mandated by the TLS protocol, but the following SHOULD
be included.
Server Name Indication [RFC6066]: the client SHOULD provide the
DNS name of the server in the TLS handshake.
After the TLS session is established the client irrespective of the
supported authentication methods, sends an HTTP POST request on "/"
with a config-auth XML structure of type 'init'. The HTTP Content-
Type to be used for these XML structures MUST be 'text/xml'. An
example of its contents follow.
<?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>
The precise DTD declarations for the contents of XML messages are
defined in this document and are listed in Appendix B.
Mavrogiannopoulos Expires 24 January 2024 [Page 4]
Internet-Draft The OpenConnect Version 1.2 July 2023
2.2.2. Tunnel authentication using passwords
After the TLS session is established and the the config-auth XML
structure of type 'init' is sent, the server requests the username
and password using forms the client software prompts the user to fill
in. The server's reply utilizes a config-auth XML structure of type
'auth-request'.
<?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>
The client can be asked to provide the information in multiple,
separate forms as the above message implies, and any number of
passwords may be requested, e.g., when second factor authentication
is available, a password and a second factor token may be requested.
Alternatively, when the number of inputs are fixed the client may be
provided a combined form as listed below.
<?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>
The client software is expected to respond to the provided form(s)
and send the responses to the server using an HTTP POST on the form
action location as specified in the XML message (in the above
examples it was "/auth"). The reply would then be of type 'auth-
reply' as in the following example.
Mavrogiannopoulos Expires 24 January 2024 [Page 5]
Internet-Draft The OpenConnect Version 1.2 July 2023
<?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>
As mentioned above, the server may ask repeatedly for information
until 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, and may
even use forms to prompt the user to change a password, provide
additional information and so on. When multiple forms are provided
the servers responds with an HTTP 200 OK status code and sends its
new request.
If client authentication fails, the server MUST respond with an HTTP
401 unauthorized status code. On successful authentication the
server replies with a 200 HTTP code and use the 'complete' config-
auth XML structure as follows.
<?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>
Note, that including the username and password in XML messages will
reveal the length of them to a passive eavesdropper. For that is is
RECOMMENDED for clients to use an 'X-Pad' HTTP header, containing
arbitrary printable data to make the message length a multiple of 64
bytes.
2.2.3. Tunnel authentication using certificates
When a user is authenticated using a certificate, during the initial
TLS protocol handshake the server will require a client certificate
to be presented.
Mavrogiannopoulos Expires 24 January 2024 [Page 6]
Internet-Draft The OpenConnect Version 1.2 July 2023
Because under TLS 1.2 the client certificate is sent in the clear
during the handshake, the certificate 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) [RFC4519].
After the TLS session is established and the the config-auth XML
structure of type 'init' is sent, the server responds according to
certificate validation status. If the certificate sent by the client
was successfully validated, the server 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.
<?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>
In that case the client should proceed to the establishment of the
primary CSTP channel as in Section 2.2.6.
2.2.4. Tunnel authentication using SPNEGO
The HTTP SPNEGO protocol [RFC4559] enables among others
authentication using Kerberos tickets. The HTTP SPNEGO method is
available using the Generic Security Service API [RFC2743]. A client
which supports the HTTP SPNEGO protocol, indicates it using the
following header on in its initial request to the server with the
config-auth 'init' XML structure.
X-Support-HTTP-Auth: true
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.
X-Support-HTTP-Auth: fallback
Mavrogiannopoulos Expires 24 January 2024 [Page 7]
Internet-Draft The OpenConnect Version 1.2 July 2023
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
advertising HTTP SPNEGO, meaning the "X-Support-HTTP-Auth: true"
header will not be included.
Otherwise, on successful authentication the server should reply with
a 200 HTTP code and use the 'complete' config-auth XML structure as
in Section 2.2.3.
Once the client is successfully validated, the server 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 with the
certificate authentication.
2.2.5. Tunnel and channels establishment
By the receipt of a 'complete' config-auth XML structure, the client
issues an HTTP CONNECT request to initiate the VPN tunnel. An
example CONNECT request is shown below.
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
2.2.5.1. Client capabilities
As each client supports different capabilities, the following HTTP
headers are used during the CONNECT request to advertise them.
X-CSTP-Address-Type: A comma separated list of the requested
address types.
IPv4: when the client only supports IPv4 addresses.
IPv6: when the client only supports IPv6 addresses.
IPv4,IPv6: when the client supports both types of IP addresses.
X-CSTP-Base-MTU: The MTU of the link as estimated by the client.
X-CSTP-Accept-Encoding: A comma separated list of accepted
compression algorithms for the CSTP channel (optional).
Compression on encrypted streams introduces additional risk, see
Appendix A for more information.
User-Agent: A string identifying the client software. By
Mavrogiannopoulos Expires 24 January 2024 [Page 8]
Internet-Draft The OpenConnect Version 1.2 July 2023
convention OpenConnect clients identify as "Open AnyConnect VPN
Agent". This string is informative to the server and its
operator.
2.2.5.2. Server response and tunnel configuration
After a successful receipt of an HTTP CONNECT request, the server
responds and provides the client with configuration parameters. The
available tunnel configuration options are listed below.
X-CSTP-Address: The IPv4 address of the client, if IPv4 has been
requested.
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.
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 [RFC6164].
X-CSTP-DNS: The IP address of a DNS server that can be used for
that session.
X-CSTP-Default-Domain: The DNS default search domains. Typically
a subset of X-CSTP-Split-DNS. If multiple, the domains are space
separated.
X-CSTP-Split-DNS: A DNS domain the provided DNS servers respond
for. Multiple such headers may be present for different domains.
X-CSTP-Split-Include: The network address of a route which is
provided by this server. Multiple such headers may be present.
X-CSTP-Split-Exclude: The network address of a route that is not
provided by this server. Multiple such headers may be present.
X-CSTP-Base-MTU: The MTU of the link as estimated by this server.
X-CSTP-DynDNS: Set to "true" if the server is operating with a
dynamic DNS address.
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
contains the compression algorithm used in the CSTP channel.
X-DTLS-Content-Encoding: if present is it set to one of the values
Mavrogiannopoulos Expires 24 January 2024 [Page 9]
Internet-Draft The OpenConnect Version 1.2 July 2023
presented by the client in 'X-DTLS-Accept-Encoding' header. It
will be the compression algorithm used in the DTLS channel.
The received options are the client's tunnel networking
configuration. If no "X-CSTP-Split-Include" headers are present, the
client is expected to assign its default route through the VPN.
After the server's response to the CONNECT request, the VPN tunnel is
established. This tunnel consists of two channels, the CSTP channel
and the (optional) DTLS channel that are described in the next
sections.
2.2.6. The primary CSTP channel - TCP
The previous HTTP message is the last HTTP message sent by the
server. After that message, the established TCP connection forms a
channel that is transports IP packets between the client and the
server. We refer to it as the CSTP channel in the rest of this
document. The encoding of the transferred packets is described
further in Section 2.3.
2.2.7. The secondary DTLS channel - UDP
The secondary DTLS based channel over UDP is established optionally
by clients and servers that wish to avoid the drawbacks of tunneling
TCP over TCP. This channel -referred to as the DTLS channel- is
established if the client advertises support for it during the HTTP
CONNECT request (see Section 2.2.5). This is done by the client
including the following headers in the request.
X-DTLS-CipherSuite: Must contain the keyword PSK-NEGOTIATE.
X-DTLS-Accept-Encoding: A comma separated list of accepted
compression algorithms for the DTLS channel (optional). The same
risks as with the primary CSTP channel apply for compression.
An example HTTP CONNECT request that advertises support for the DTLS
channel is shown below.
User-Agent: Open AnyConnect VPN Agent v5.01
X-CSTP-Base-MTU: 1280
X-CSTP-Address-Type: IPv4,IPv6
X-DTLS-CipherSuite: PSK-NEGOTIATE
CONNECT /CSCOSSLC/tunnel HTTP/1.1
The server's response to the HTTP CONNECT request, includes the
following headers, if the server wishes to establish the DTLS
channel.
Mavrogiannopoulos Expires 24 January 2024 [Page 10]
Internet-Draft The OpenConnect Version 1.2 July 2023
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. The identifier (before encoding) can be
from 16 to 32 bytes.
X-DTLS-Port: The port number to which the client should send UDP
packets for DTLS.
X-DTLS-CipherSuite: It must contain the value "PSK-NEGOTIATE"
without any quotes.
X-DTLS-Rekey-Time: The time (in seconds) after which the DTLS
session should rekey, see Section 2.5. Only considered if
applicable to the negotiated DTLS protocol.
X-DTLS-Rekey-Method: The method used in DTLS rekey, see
Section 2.5. Only considered if applicable to the negotiated DTLS
protocol.
2.2.7.1. DTLS session establishment
After the DTLS channel is negotiated over the CSTP channel, it is
established by the client initiating a DTLS session.
The client initiates a UDP connection to the IP address if the server
and port as specified by the X-DTLS-Port value. The new UDP
connection uses the DTLS 1.2 protocol (or any later version) with the
PSK key exchange method. The pre-shared key material for this
channel are generated by both the server and the client independently
and is not exchanged. The pre-shared key is a 256-bit value
generated with an [RFC5705] exporter from the TLS session of the CSTP
channel. The key material exporter uses the label "EXPORTER-
openconnect-psk" without the quotes, and without any context value.
In its DTLS 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 when it
receives the first UDP message to associate the new DTLS protocol
connection with the corresponding CSTP channel.
2.2.8. Overview of the tunnel establishment
An overview of the established tunnel and channels is shown in
Figure 1.
Mavrogiannopoulos Expires 24 January 2024 [Page 11]
Internet-Draft The OpenConnect Version 1.2 July 2023
,-.
`-'
/|\
| ,------. ,----------.
/ \ |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 |
| <- - - - - - - - - - - - - - - - - - - - - - - - - - - -
| | |
Mavrogiannopoulos Expires 24 January 2024 [Page 12]
Internet-Draft The OpenConnect Version 1.2 July 2023
| | |
| =================================== |
====================== DTLS VPN channel is established =======================
| =================================== |
| | |
| DTLS record packet with payload |
| - - - - - - - - - - - - - - - - - - - - - - - - - - - >
| | |
| DTLS record packet with payload |
| <- - - - - - - - - - - - - - - - - - - - - - - - - - - -
Client ,--+---. ,----+-----.
,-. |Server| |ServerDTLS|
`-' `------' `----------'
/|\
|
/ \
Figure 1
2.3. The CSTP Channel Protocol
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 [RFC8446]). The bytes of the header indicate
the type of data that follow, and their contents are explained in
Table 1.
Mavrogiannopoulos Expires 24 January 2024 [Page 13]
Internet-Draft The OpenConnect Version 1.2 July 2023
+======+=======================================+
| byte | value |
+======+=======================================+
| 0 | fixed to 0x53 (S) |
+------+---------------------------------------+
| 1 | fixed to 0x54 (T) |
+------+---------------------------------------+
| 2 | fixed to 0x46 (F) |
+------+---------------------------------------+
| 3 | fixed to 0x01 |
+------+---------------------------------------+
| 4-5 | The length of the packet that follows |
| | this header in big endian order |
+------+---------------------------------------+
| 6 | The type of the payload that follows |
| | (see Table 2 for available types) |
+------+---------------------------------------+
| 7 | fixed to 0x00 |
+------+---------------------------------------+
Table 1
The available payload types are listed in Table 2.
Mavrogiannopoulos Expires 24 January 2024 [Page 14]
Internet-Draft The OpenConnect Version 1.2 July 2023
+=======+=========================================================+
| Value | Description |
+=======+=========================================================+
| 0x00 | DATA: the TLS record packet contains an IPv4 or IPv6 |
| | packet |
+-------+---------------------------------------------------------+
| 0x03 | 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. |
+-------+---------------------------------------------------------+
| 0x04 | DPD-RESP: used as a response to a previously received |
| | DPD-REQ. |
+-------+---------------------------------------------------------+
| 0x05 | DISCONNECT: sent by the client (or server) to terminate |
| | the session. This is followed by one byte indicating |
| | the disconnect reason. When the reason is '0xb0' the |
| | session should be invalidated after the request. |
+-------+---------------------------------------------------------+
| 0x07 | KEEPALIVE: sent by any peer. No data is associated |
| | with this request. |
+-------+---------------------------------------------------------+
| 0x08 | COMPRESSED DATA: a Data packet which is compressed |
| | prior to encryption. |
+-------+---------------------------------------------------------+
| 0x09 | TERMINATE: sent by the server to indicate that the |
| | server is shutting down. No data is associated with |
| | this request. |
+-------+---------------------------------------------------------+
Table 2
2.4. The DTLS Channel Protocol
The format of the packets sent over the DTLS channel consists of an
1-byte header followed by data. The header byte indicates the type
of data that follow as in Table 2. The header and the data are
encapsulated in a DTLS record packet (see [RFC6347]).
2.5. The Channel Re-Key Protocol
During the exchange of session parameters (Section 2.2.5), the server
advertises 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.
1. none: no rekey; the session will go on until 2^48 DTLS records
have been exchanged, or 2^64 TLS records.
Mavrogiannopoulos Expires 24 January 2024 [Page 15]
Internet-Draft The OpenConnect Version 1.2 July 2023
2. ssl: a TLS or DTLS rekey will be performed periodically. Under
TLS/DTLS 1.2 this is performed using a rehandshake, and in later
versions using a rekey.
3. new-tunnel: the session will tear down and the client will
reconnect periodically.
When the value is other than "none" the rekey period is determined 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.
It should be noted that when the "ssl" rekey option is used under
TLS1.2, care must be taken by both the client and the server to
ensure that either safe renegotiation is used ([RFC5746]), or that
the identity of the peer remains the same.
2.6. The Keepalive and Dead Peer Detection Protocols
In OpenConnect there are two packet types that can be used for keep-
alive or dead peer detection, as shown in Table 2. These are the
DPD-REQ and KeepAlive packets.
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 [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.
The server advertises the suggested periods during the tunnel
establishment (Section 2.2.5). The available headers are listed
below.
* X-CSTP-DPD: applicable to CSTP channel; contains a relative time
in seconds.
* X-CSTP-Keepalive: applicable to CSTP channel; contains a relative
time in seconds.
* X-DTLS-DPD: applicable to DTLS channel; contains a relative time
in seconds.
* X-DTLS-Keepalive: applicable to DTLS channel; contains a relative
time in seconds.
Mavrogiannopoulos Expires 24 January 2024 [Page 16]
Internet-Draft The OpenConnect Version 1.2 July 2023
3. Security Considerations
This document provides a description of a protocol to establish a VPN
tunnel over a TLS 1.2 or later channel. All security considerations
of the referenced documents in particular [RFC8446] and [RFC6347] are
applicable, in addition the following considerations.
The protocol is designed to be as compatible as possible with a
legacy VPN protocol. This compatibility is not believed to cause a
degradation of the overall protocol security.
The protocol provides a VPN tunnel split in two channels that carry
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 [COMP-ISSUES][COMP-ISSUES2]. For that we RECOMMEND
that implementations not implement compression or not to enable it by
default.
This protocol could sometimes be used because it resembles the TLS
protocol and thus is not detected by the available VPN blockers.
While an implementation could intentionally masquerade its packets to
resemble a typical HTTPS session, a fully compliant implementation
will be distinct from an average HTTP session due to the DTLS session
establishment, the predictable size of the XML exchanges, and the
transferred packet sizes.
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.
4. Acknowledgements
None yet.
5. Normative References
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
Mavrogiannopoulos Expires 24 January 2024 [Page 17]
Internet-Draft The OpenConnect Version 1.2 July 2023
[RFC5746] Rescorla, E., Ray, M., Dispensa, S., and N. Oskov,
"Transport Layer Security (TLS) Renegotiation Indication
Extension", RFC 5746, DOI 10.17487/RFC5746, February 2010,
<https://www.rfc-editor.org/info/rfc5746>.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <https://www.rfc-editor.org/info/rfc6347>.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616,
DOI 10.17487/RFC2616, June 1999,
<https://www.rfc-editor.org/info/rfc2616>.
[RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based
Kerberos and NTLM HTTP Authentication in Microsoft
Windows", RFC 4559, DOI 10.17487/RFC4559, June 2006,
<https://www.rfc-editor.org/info/rfc4559>.
[RFC2743] Linn, J., "Generic Security Service Application Program
Interface Version 2, Update 1", RFC 2743,
DOI 10.17487/RFC2743, January 2000,
<https://www.rfc-editor.org/info/rfc2743>.
[RFC5056] Williams, N., "On the Use of Channel Bindings to Secure
Channels", RFC 5056, DOI 10.17487/RFC5056, November 2007,
<https://www.rfc-editor.org/info/rfc5056>.
[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>.
[RFC4519] Sciberras, A., Ed., "Lightweight Directory Access Protocol
(LDAP): Schema for User Applications", RFC 4519,
DOI 10.17487/RFC4519, June 2006,
<https://www.rfc-editor.org/info/rfc4519>.
[RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS)
Extensions: Extension Definitions", RFC 6066,
DOI 10.17487/RFC6066, January 2011,
<https://www.rfc-editor.org/info/rfc6066>.
[RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan,
"Transport Layer Security (TLS) Application-Layer Protocol
Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
July 2014, <https://www.rfc-editor.org/info/rfc7301>.
Mavrogiannopoulos Expires 24 January 2024 [Page 18]
Internet-Draft The OpenConnect Version 1.2 July 2023
[RFC6164] Kohno, M., Nitzan, B., Bush, R., Matsuzaki, Y., Colitti,
L., and T. Narten, "Using 127-Bit IPv6 Prefixes on Inter-
Router Links", RFC 6164, DOI 10.17487/RFC6164, April 2011,
<https://www.rfc-editor.org/info/rfc6164>.
[RFC3706] Huang, G., Beaulieu, S., and D. Rochefort, "A Traffic-
Based Method of Detecting Dead Internet Key Exchange (IKE)
Peers", RFC 3706, DOI 10.17487/RFC3706, February 2004,
<https://www.rfc-editor.org/info/rfc3706>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[COMP-ISSUES]
Bhargavan, K., Fournet, C., Kohlweiss, M., Pironti, A.,
and P-Y. Strub, "TLS Compression Fingerprinting and a
Privacy-aware API for TLS", 2012.
[COMP-ISSUES2]
Kelsey, J., "Compression and information leakage of
plaintex", International Workshop on Fast Software
Encryption , 2002.
[OPENCONNECT-CLIENT]
Woodhouse, D., "http://www.infradead.org/openconnect/",
2016.
[OPENCONNECT-SERVER]
Mavrogiannopoulos, N., "http://www.infradead.org/ocserv/",
2016.
Appendix A. Compression
The available compression algorithms for the CSTP and DTLS channels
are shown in Table 3. 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 implementation MUST NOT enable compression by default.
After compression is negotiated each side may choose to compress the
payload and use the 'COMPRESSED DATA' header from Table 2, or may
send uncompressed data with the 'DATA' payload. Each side MUST be
able to process both payloads.
Mavrogiannopoulos Expires 24 January 2024 [Page 19]
Internet-Draft The OpenConnect Version 1.2 July 2023
+===========+====================================================+
| Algorithm | Description |
+===========+====================================================+
| oc-lz4 | The stateless LZ4 compression algorithm. |
+-----------+----------------------------------------------------+
| lzs | The stateless LZS (stacker) compression algorithm. |
+-----------+----------------------------------------------------+
Table 3
Appendix B. DTD declarations
B.1. config-auth.dtd
<!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)>
Author's Address
Nikos Mavrogiannopoulos
Independent
Email: n.mavrogiannopoulos@gmail.com
Mavrogiannopoulos Expires 24 January 2024 [Page 20]
