| Internet-Draft | The OpenConnect Version 1.2 | July 2023 |
| Mavrogiannopoulos | Expires 24 January 2024 | [Page] |
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.¶
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 (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.¶
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.¶
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].¶
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.¶
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.¶
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.¶
The OpenConnect VPN protocol allows for the following types of client authentication, or combinations of them.¶
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.¶
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.¶
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.¶
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.¶
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.¶
<?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.¶
When a user is authenticated using a certificate, during the initial TLS protocol handshake the server will require a client certificate to be presented.¶
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.¶
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
¶
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.¶
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
¶
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.¶
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.¶
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.¶
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.¶
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.¶
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.¶
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.¶
An overview of the established tunnel and channels is shown in Figure 1.¶
,-.
`-'
/|\
| ,------. ,----------.
/ \ |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|
`-' `------' `----------'
/|\
|
/ \
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.¶
| 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 |
The available payload types are listed in Table 2.¶
| 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. |
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]).¶
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.¶
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.¶
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.¶
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.¶
None yet.¶
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.¶
| Algorithm | Description |
|---|---|
| oc-lz4 | The stateless LZ4 compression algorithm. |
| lzs | The stateless LZS (stacker) compression algorithm. |
<!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)>
¶