openvpn-wire-protocol.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
    There has to be one entity for each item to be referenced.
    An alternate method (rfc include) is described in the references. -->

<!ENTITY RFC2104 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2104.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY RFC5226 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml">
<!ENTITY RFC5246 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml">
<!ENTITY RFC5280 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5280.xml">
<!ENTITY RFC5705 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5705.xml">
<!ENTITY RFC8452 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8452.xml">
]>
<!-- give errors regarding ID-nits and DTD validation -->
<?rfc strict="yes" ?>
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<?rfc tocdepth="2"?>
<!-- control references -->
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc symrefs="yes"?>
<!-- sort the reference entries alphabetically -->
<?rfc sortrefs="yes" ?>
<!-- control vertical white space
    (using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- keep one blank line between list items -->
<?rfc subcompact="no" ?>
<!-- end of list of popular I-D processing instructions -->

<rfc category="info" docName="draft-openvpntech-openvpn-wire-protocol-01" ipr="trust200902">
 <!-- category values: std, bcp, info, exp, and historic
    ipr values: trust200902, noModificationTrust200902, noDerivativesTrust200902,
       or pre5378Trust200902
    you can add the attributes updates="NNNN" and obsoletes="NNNN"
    they will automatically be output with "(if approved)" -->

 <front>
   <title abbrev="OpenVPN Wire Protocol">OpenVPN Wire Protocol (work in progress)</title>
   <author fullname="Arne Schwabe" initials="A.S." surname="Schwabe">
     <organization>OpenVPN, Inc</organization>
     <address>
       <email>david.sommerseth@openvpn.net</email>
     </address>
   </author>
   <author fullname="David Sommerseth" initials="D.S." surname="Sommerseth">
      <organization>OpenVPN, Inc</organization>
      <address>
        <email>david.sommerseth@openvpn.net</email>
      </address>
   </author>

    <author fullname="Steffan Karger" initials="S.K." surname="Karger">
      <organization>Fox-IT</organization>
      <address>
        <email>steffan.karger@fox-it.com</email>
      </address>
    </author>

    <date year="2038" day="19" month="Jan"/> <!-- Can add day="XX" month="YYY" later on -->

    <keyword>OpenVPN</keyword>
    <keyword>protocol</keyword>
    <keyword>VPN</keyword>

    <abstract>
      <t>
        OpenVPN is an open source SSL/TLS based VPN solution which had
        its first release in May 2001.  This document describes the wire
        protocol OpenVPN makes use of for establishing end-to-end-
        connections.  Even though OpenVPN bases its communication on
        SSL/TLS, it is not a traditional SSL/TLS protocol which utilizes
        only TCP.  OpenVPN supports some enhanced security features as
        well as providing SSL/TLS connections both over TCP as well as
        UDP.

        This document focuses on the modern/current variant of the OpenVPN
        protocol. Some of the features used in older variants of the protocol
        are not documented.
      </t>
    </abstract>
  </front>

  <middle>
    <section title="WORK IN PROGRESS">
      <t>
        Please not that this document is work in progress and should not considered a
        complete or correct documentation of the OpenVPN protocol yet.  Please check
        the current implementations.
      </t>
    </section>
    <section title="Introduction">
      <t>
        OpenVPN is an open source SSL/TLS based VPN solution which was
        first released in 2001.  The communication between OpenVPN
        instances are based on SSL/TLS but it has added several
        additional features on top of the standard SSL/TLS protocol.
        The wire protocol this document describes will go into the
        depths of how OpenVPN processes communicates with each other.
      </t>
      <t>
        The wire protocol is dynamic, which means it will be slightly
        different depending on which features the OpenVPN processes have
        been configured to use.  New implementations SHOULD implement all
        features.
      </t>

      <section title="Requirements Language">
        <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">RFC 2119</xref>.</t>
      </section>

    </section>

    <section title="The OpenVPN Wire Protocol">
      <t>
        Since OpenVPN can work both in a traditional server-client setup
        as well as a peer-to-peer setup, this document tries to avoid the
        concept of server and clients.  It will refer to these as
        either the local or remote sites.  In a peer-to-peer setup only
        a single tunnel can be established, while in a server-client setup
        several clients can connect to a single server at the same time.

        If the terms server and client are used these are almost always
        synonymous with the peer's role as either TLS server or TLS client.
      </t>

      <section title="TCP and UDP transport modes">
        <t>
          OpenVPN is capable of using both UDP and TCP for transporting
          SSL/TLS traffic.  The SSL/TLS protocol is strictly written for
          TCP but OpenVPN makes that possible through encapsulating the
          SSL/TLS packets and adding a reliability layer to avoid issues
          when packets get resent.
        </t>
      </section>
      <section title="Static-key mode and TLS operational modes">
        <section title="Static-key mode">
        <t>
          The OpenVPN protocol has a mode where it does not use
          dynamic key derivation but instead uses static keys.
          The mode does not make use of any TLS features, so
          it is called static key mode.  In this mode there is no control
          channel and all the data on the wire is plain encrypted packets
          transported over a standard UDP or TCP connection.
        </t>
        <t>
          Peer-to-peer mode also depends on a shared secret key between
          both ends of the VPN tunnel.  Again, as there are no SSL/TLS
          handshakes between either side, this method does not have any
          possibilities to enable Perfect Forward Secrecy (PFS).  The
          data channel is encrypted solely by the shared static secret.
          This mode does not negotiate any ephemeral session keys for the
          tunneled data.

          Using pre-shared secrets also significantly weakens the guarantees for
          no IV reuse, so modern ciphers like AES in GCM mode are not
          available in this mode.

          This mode is deprecated and this document does not provide
          documentation for it.
        </t>
        </section>

        <section title="TLS mode">
        <t>
          With TLS mode the control channel gets activated and this
          requires both sides to make use of private keys and
          <xref target="RFC5280">X.509</xref> Certificates.  These requirements are due to this
          operational mode utilizing the <xref target="RFC5246">TLS/SSL</xref> protocol.
          This mode is also the only operational mode which uses the
          client-server terminology in OpenVPN.
        </t>
        <t>
          The use of X.509 certificates on the client side is OPTIONAL
          and is REQUIRED on the server side.  It is highly
          RECOMMENDED to always enable user/password authentication when X.509
          client certificates are not used.
        </t>
        <t>
          It is highly RECOMMENDED to enforce certificate authentication
          against a locally controlled Certificate Authority (CA) certificate.
          The use of public Certification Authorities will reduce the security
          of the tunnel dramatically, as it can easily enable man-in-the-middle
          attacks where the client cannot verify the true identity of a server,
          or a server cannot verify the true identity of a client.
        </t>
        <t>
          [FIXME/syzzer: explain more what happens on the wire during the
                  SSL/TLS handshake and certificate authentication]
        </t>
        <t>
          The TLS mode will use the same communication channel for
          both TLS handshakes and the tunnel data.  The TLS handshakes
          are referred to as the control channel and tunnel data is
          referred to as the data channel.  Each packet in TLS mode
          contains an OPCODE which defines if the following payload is
          a control channel or data channel packet.
        </t>
        </section>
      </section>
    </section>

      <section title="OpenVPN wire packet format">
        <t>
          OpenVPN uses a single UDP or TCP connection between two
          peers. Over this connection all packets for the VPN
          connection are multiplexed.  In UDP one packet is is the same
          as one UDP payload. When TCP is used, each packet with started
          by a 16 bit length indicator in network byte order, followed
          by the packet.
        </t>
        <t>
          Each packet starts with an opcode that determines the packet
          type.  OpenVPN packets fall can be differentiated into two
          types of packets: control channel packets and data channel
          apckets. They share the same header but serve different
          purposes.  The data channel packets transport the VPN
          payload, typically IP packets.  The control channel packets
          are used to setup and control the VPN connection.
        </t>
        <t>
          The key_id specifies a key generation that allow to
          multiplex different key generations. 
        </t>
        <t>
          <figure>
            <sourcecode>
struct tcp_packet {
   uint16 len;
   int opcode:5;
   int keyid:3;
   uint8 data[];
   }

struct udp_packet {
   int opcode:5;
   int keyid:3;
   uint8 data[];
}
            </sourcecode>
          </figure>
        </t>
        <t>
          The following sections will often only show the UDP format for brievity.  The
          TCP format can be infered by prepending the 16 bit length field.
        </t>
        <t>
          The <xref target="datachannel">data channel section</xref>
          and <xref target="controlchannel">control channel</xref>
          sections describe the formats of the packets in details.
        </t>
      </section>


      <section title="General Control channel format">
        <t>
        There are three different variants of the control channel format.  The
        format depends on the variant of control channel authentication and
        encryption.
        </t>

        <section title="Unauthenticated control channel packets">
          <t>
          <figure>
            <sourcecode>
struct control_packet {
    int opcode:5;
    int keyid:3;
    uint64_t own_session_id;
    uint8_t acked_pktid_len;
    uint8_t[n*8] acked_pktid_list; [only if acked_id_len > 0]
    uint64_t peer_session_id; [only if acked_id_len > 0]
    uint32_t packet_id;
    uint8_t control_channel_payload[];
}
            </sourcecode>
          </figure>
          The basic form of control channe ldoes not involve any additional authentication or
          encryption of control channel packets.
          </t>
          <t>
            The <tt>own_session_id</tt> is an opaque id that identifies the session id
            from the perspective of the peer.  The peer MUST NOT make any assumption about the
            format of this id.  It is RECOMMEND to use 64 bit of randomness.
          </t>
        </section>
        <section title="OpenVPN mixed timestamp/packet counter format" anchor="longpkt">
          <t>
            The <tt>replay_packet_id</tt>  64 bit counter that is used by both tls-crypt and tls-auth has internally
            the following format
          <figure>
            <sourcecode>
struct replay_packet_id_packet {
    uint32_t packet_id;
    uint32_t timestamp;
}
            </sourcecode>
          </figure>
          This format is a legacy from old static key mode from OpenVPN to avoid IV reuse and provide a stable packet counter.
          While OpenVPN largely abondoned this format and static key format, this packet counter format still survived in the
          replay protection for tls-auth and tls-crypt protocol. Unfortunately, in this format the format the order of the fields
          does not represent their significance and when interpreting this as a 64bit counter, the timestamp value represents the
          more significant bytes. To turn this structure into a 64bit counter, the timestamp represent the upper 32 bit while the
          packet_id represents the lower 32 bits.

          (timestamp &lt;&lt; 32) | packet_id

          </t>
        </section>
        <section title="HMAC authentication of control channel packets" anchor="tlsauth">
        <t>
          <figure>
            <sourcecode>
struct tlsauth_control {
    int opcode:5;
    int keyid:3;
    uint64_t own session_id;
    uint8[8-32] hmac;
    uint64_t replay_packet_id;

    uint8_t acked_pktid_len;
    uint8_t[n*8] acked_pktid_list; [only if acked_id_len > 0]
    uint64_t peer_session_id; [only if acked_id_len > 0]
    uint32_t packet_id;

    uint8_t payload[];
}
            </sourcecode>
          </figure>
        </t>
        <t>
          In this mode, which is also called tls-auth in existing implementations,
          control channel packets are authenticated by the
          use of an <xref target="RFC2104">HMAC</xref> signature using a pre-shared key.
        </t>
        <t>
          This authentication can strengthen the overall security on
          both client and server side as OpenVPN will validate the HMAC
          signature before any other processing on the packet is done.
          This can protect server and client from triggering problems in
          other parts of implementation such as TLS protocol implementations.
        </t>
        <t>
          The keys used for the HMAC signatures are static and pre-shared between
          server and all clients.  The default hashing algorithm is HMAC-SHA1
          but any hashing algorithms supported by the SSL/TLS protocol can
          be used as long as the clients and server are configured to use the
          same algorithm.  The choice of hashing algorithms defines the length
          of the HMAC field in the control packet.  HMAC-SHA1 uses 160 bits (20 bytes),
          HMAC-SHA512 uses 512 bits (64 bytes).
        </t>
        <t>
          The key used for the HMAC signatures has the same length as the
          HAMC signature.  A different key is used for each direction
          between two peers.  The keys can be identical but it is recomended
          that they are different.

          The appendix <xref target="ovpnkeyfile">OpenVPN static key format</xref>
          will provide the file format that is used in existing implementations
          to provide these keys.
        </t>

        <t>
          The HMAC is calculated over the following pseudo packet, which moves the
          replay_packet_id to the beginning and drops the hmac field. 
        </t>
        <figure>
          <sourcecode>
struct tlsauth_control {
    uint64_t replay_packet_id;
    int opcode:5;
    int keyid:3;
    uint64_t own session_id;
    uint8_t acked_pktid_len;
    uint8_t[n*8] acked_pktid_list; [only if acked_id_len > 0]
    uint64_t peer_session_id; [only if acked_id_len > 0]
    uint32_t packet_id;
    uint8_t payload[];
}
          </sourcecode>
        </figure>
        <t>
          When sending or resending a packet, an implementation must increase the replay_packet_id
          counter, calculate the HMAC and send the packet with the HMAC.
        </t>
        <t>
          On recieving, the receiver MUST check if the replay_packet_id is not an already received
          replay_packet_id or is lower by 32 or more than the highest replay_packet_id in an
          authenticated packet from a peer and otherwise discard it. The value 32 MAY be
          configurable.  If the packet passes this test, the HMAC of the packet using the
          outlined procedure MUST be calculated and verfied.  If the HMAC does not match,
          the implementation MUST discard the packet.
        </t>

      </section>

      <section title="Encrypting control channel packets (tls-crypt)" anchor="tlscrypt">
      <t>
        When using this format of control packets, OpenVPN peers will encrypt the control
        packet channel payload using pre-shared static keys.  The encryption scheme uses
        a pair of encryption key <tt>Ke</tt> (256 bite) and HMAC authentication key <tt>Ka</tt>
        (256 bits) per direction, four private keys or 1024 bits in total. 
        In existing impelmentation this feature is usually referred to as "tls-crypt".
      </t>
      <t>
        Encrypting control channel packets has three main advantages:

        <ul>
          <li> It provides more privacy by hiding the certificate used
          for the TLS connection. </li>
          <li> It is harder to identify OpenVPN traffic as such. </li>
          <li> It provides "poor-man's" post-quantum security, against
          attackers who will never know the pre-shared key
          (i.e. no forward secrecy provided by the pre-shared private key). </li>
        </ul>
      </t>

      <section title="Control channel packet encryption">

        <t>
          The encryption method is based on the SIV construction
          <xref target="rogaway2006provable" format="default" sectionFormat="of" derivedContent="rogaway2006provable"/>,
          to achieve nonce misuse-resistant authenticated encryption. 
          
          Note that this is is using AES256-CTR and HMAC-SHA256 and is not the
          <xref target="RFC8452">RFC8452 AES-GCM-SIV</xref>.
        </t>
        <t>
          TODO: Check if our scheme is one that is described in RFC 5297
        </t>
        <t>
          The use of a nonce misuse-resistant authenticated encryption scheme
          allows minimising the risks of nonce collisions.  This is
          important, because in contrast to other encryption as TLS, it is impractical
           to rotate the pre-shared keys often or fully guarantee nonce
          uniqueness.  For non misuse-resistant modes such as GCM
          (<xref target="ferguson2005authentication" format="default" sectionFormat="of" derivedContent="ferguson2005authentication"/>,
          <xref target="joux2006authentication" format="default" sectionFormat="of" derivedContent="joux2006authentication"/>),
          the TLS (or OpenVPN's own data channel) only has to ensure that the packet counter
          never rolls over, while the encryption of control packages would have to
          provide nonce uniqueness  over all control channel packets sent by all clients,
          for the lifetime of the pre-shared key.
        </t>

        <t>
          This control channel packet format uses fixed encryption and authentication
          algorithms. This encryption intention is to primarely provide  privacy as well
          as DoS protection, these MUST not be made negotiable.
        </t>

        <t>
          The format of a tls-crypt control packet looks are the following:
          <figure>
            <artwork>
struct tlscrypt_control {
  int opcode:5;
  int keyid:3;
  uint64_t own session_id;
  uint64_t replay_packet_id;
  uint8 auth_tag[32];
  uint8[] enc_control_payload;
  }
            </artwork>
          </figure>
        </t>

        <t>
          The encrypted payload enc_control_payload consits of encrypting
          the following structure:

          <figure>
            <artwork>
struct clear_control_payload {
   uint8_t acked_pktid_len;
   uint8_t[n*8] acked_pktid_list; [only if acked_id_len > 0]
   uint64_t peer_session_id; [only if acked_id_len > 0]
   uint32_t packet_id;
   uint8_t control_channel_payload[];
}
            </artwork>
          </figure>
        </t>
        <t>
          The auth tag is generated by generating a HMAC-SHA256 with the pre-shared HMAC key over the
          the cleartext of the tls_auth_control structure and the clear_control_payload struct,
          omitting the auth_tagfand enc_control_payload fields:
        </t>

        <t>
          <tt>auth_tag = HMAC-SHA256(Ka, opcode || keyid || own_session_id || replay_packet_id || clear_control_payload)</tt>
        </t>
        <t> Using the auth_tag, we create the IV from it.
        </t>
        <t>
          <tt>IV = 128 most-significant bits of auth_tag</tt>
        </t>
        <t>
          And finally the <tt>enc_control_payload</tt> is encrypted using AES-CTR with <tt>Ke</tt>
          as key and the constructed IV:
        </t>
        <t>
          <tt>enc_control_payload = AES256-CTR(Ke, IV, clear_control_payload)</tt>
        </t>
      </section>
      <section title="Security considerations">
        <t>
          This encryption scheme is a best-effort mechanism aiming to provide as much
          privacy and security as possible, while staying as simple as possible.
          The following are some security considerations for this scheme.
        </t>
        <t>
          The same set of pre-shared key is potentially shared by a lot of peers, so it
          is quite likely to get compromised.  Once an attacker acquires the
          tls-crypt key, this mechanism no longer provides any security against
          the attacker.
        </t>

        <t>
          Since many peers potentially use the same set of keys for a long time, a
          lot of data might be encrypted under the encryption keys.  This leads
          to two potential problems:
          <ul>
            <li>
              <t>
                The <tt>opcode || session id || packet id</tt> combination might collide.
                This might happen in larger setups, because the session id contains
                just 64 bits of randomess.  Using the uniqueness requirement from the
                GCM spec <xref target="nistgcm" format="default" sectionFormat="of"
                derivedContent="nistgcm"/>
                (a collision probability of less than 2^(-32)),
                uniqueness is achieved when using the tls-crypt key for at most
                2^16 (65536) connections per process start.  (The packet id
                includes the daemon start time in the packet ID, which should be
                different after stopping and (re)starting OpenVPN.)
              </t>
              <t>
                And if a collision happens, an attacker can *only* learn whether
                colliding packets contain the same plaintext.  Attackers will not
                be able to learn anything else about the plaintext (unless the
                attacker knows the plaintext of one of these packets, of course).
                Since the impact is limited, this is considered an acceptable
                remaining risk.
              </t>
            </li>

            <li>
              The IVs used in encryption might collide.  When two IVs collide, an
              attacker can learn the xor of the two plaintexts by xor-ing the
              ciphertexts.  This is a serious loss of confidentiality.  The IVs
              are 128-bit, so when HMAC-SHA256 is a secure PRF (an assumption
              that must also hold for TLS), and we use the same uniqueness
              requirement from <xref target="nistgcm" format="default" 
              sectionFormat="of" derivedContent="nistgcm"/>,
              this limits the total amount of control
              channel messages for all peers in the setup to 2^48.  Assuming a
              large setup of 2^16 (65536) clients, and a (conservative) number of
              2^16 control channel packets per connection on average, this means
              that clients may set up 2^16 connections on average.  
            </li>
          </ul>
        </t>
        <t>
          Typical OpenVPN implementations will use the same key format as for the authentication
          of control channel to distribute the pre-shared keys.  See Appendix
          <xref target="ovpnkeyfile">OpenVPN static key format</xref>
          for a description of the format.
        </t>
      </section>
      <section anchor="tlscryptv2" title="Client-specific encryption keys">
        <t>
          This section describes configuring OpenVPN to use client-specific tls-crypt keys. This feature is
          referred to as tls-crypt-v2 in existing implementations.
        </t>


        <section title="Rationale">
          <t>
            ``--tls-auth`` and ``tls-crypt`` use a pre-shared group key,
            which is shared among all clients and servers in an OpenVPN
            deployment.  If any client or server is compromised, the
            attacker will have access to this shared key, and it
            will no longer provide any security.  To reduce the risk of
            losing pre-shared keys, ``tls-crypt-v2`` adds the ability to
            supply each client with a unique tls-crypt key.  This allows
            large organizations and VPN providers to profit from the same
            DoS and TLS stack protection that small deployments can already
            achieve using ``tls-auth`` or ``tls-crypt``.
          </t>

          <t>
            Also, for ``tls-crypt``, even if all these peers succeed in
            keeping the key secret, the key lifetime is limited to roughly
            8000 years, divided by the number of clients (see the
            ``--tls-crypt`` section of the man page).
            [FIXME/flichtenheld: either include or remove reference]
            Using client-specific keys, we lift this lifetime requirement to roughly 8000 years
            for each client key (which "Should Be Enough For Everybody (tm)").
          </t>
        </section>

        <section title="Introduction">
          <t>
            The per client encryption key schema uses an encrypted cookie mechanism to introduce
            client-specific tls-crypt keys without introducing a lot of server-side state.
            The client-specific key is encrypted using a server key.  The server key is the
            same for all servers in a group.  When a client connects, it first sends the
            encrypted key to the server, such that the server can decrypt the key and all
            messages can thereafter be encrypted using the client-specific key.
          </t>

          <t>
            A wrapped (encrypted and authenticated) client-specific key can also contain
            metadata.  The metadata is wrapped together with the key, and can be used to
            allow servers to identify clients and/or key validity.  This allows the server
            to abort the connection immediately after receiving the first packet, rather
            than performing an entire TLS handshake.  Aborting the connection this early
            greatly improves the DoS resilience and reduces attack surface against
            malicious clients that have the ``tls-crypt`` or ``tls-auth`` key.  This is
            particularly relevant for large deployments (think lost key or disgruntled
            employee) and VPN providers (clients are not trusted).
          </t>

          <t>
            To allow for a smooth transition, this feature is designed such that a
            server can enable both the per client encryption and either ``tls-crypt`` or
            ``tls-auth``.  This is achieved by introducing a CONTROL_HARD_RESET_CLIENT_V3
            opcode, that indicates that the client wants to use ``tls-crypt-v2`` for the
            current connection.
          </t>
        </section>
        <section title="Implementation">
          <t>
            This implementation here assumes that all server share the same pre-shared key. Since the
            server implementation is transparent to the client, another schema can be potentially used.
          </t>
          <t>
            <ol>
              <li>
                The server key cosists of 2 512-bit keys, of which we use:

                <ul>
                  <li> the first 256 bits of key 1 as AES-256-CTR encryption key ``Ke``</li>
                  <li> the first 256 bits of key 2 as HMAC-SHA-256 authentication key ``Ka`` </li>
                </ul>
              </li>
              <li>
                This server key is shared by all OpenVPN servers that clients should be considere as equivalent. For different
                servers, different sets of keys SHOULD be supported.
              </li>
            </ol>
          </t>

          <t>
            The client key consists of two parts. The client-specific key ``Kc`` and a wrapped key ``WKc`` that is opaque to the
            client.
          </t>
          <t>
            The 2048 bits client-specific key ``Kc`` is identical to the key for the control channel encryption.
          </t>
          <t>
            The standard format used by OpenVPN for the  wrapped key has the foloowing components:
            <ol>
              <li>The 2048 bits client-specific key ``Kc`` is identical to the key for the control channel encryption. </li>
              <li>
                <t> Optional Metadata

                 The first byte of the metadata determines the type.  The initial
              implementation supports the following types:

              <ul>
                <li> 0x00 (USER): User-defined free-form data. </li>
                <li> 0x01 (TIMESTAMP): 64-bit network order unix timestamp of key generation. </li>
              </ul>
                </t>
              <t>
                The timestamp can be used to reject too-old tls-crypt-v2 client keys.
              </t>
              <t>
                User metadata could for example contain the users certificate serial, such
                that the incoming connection can be verified against a CRL.
              </t>

              <t>
                If no metadata is supplied during key generation, an implementation SHOULD default to the
                TIMESTAMP metadata type.
              </t>
              </li>

              <li> Create a wrapped client key ``WKc``, using the same nonce-misuse-resistant
              SIV construction we use for tls-crypt:

              <figure>
                <sourcecode>
len = len(WKc) (16 bit, network byte order)

T = HMAC-SHA256(Ka, len || Kc || metadata)

IV = 128 most significant bits of T

WKc = T || AES-256-CTR(Ke, IV, Kc || metadata) || len
                </sourcecode>
              </figure>

              Note that the length of ``WKc`` can be computed before composing ``WKc``,
              because the length of each component is known (and AES-256-CTR does not add
              any padding).
              </li>

              <li> Create a tls-crypt-v2 client key: PEM-encode ``Kc || WKc`` and store in a
              file, using the header <tt>-----BEGIN OpenVPN tls-crypt-v2 client key-----</tt>
              and the footer <tt>-----END OpenVPN tls-crypt-v2 client key-----</tt>.  (The PEM
              format is simple, and following PEM allows us to use the crypto library functions
              for en/decoding.)
              </li>

              <li> Add the tls-crypt-v2 client key to the client config
              (``tls-crypt-v2 /path/to/client-specific.key``)</li>
              

            </ol>
          </t>
            
          <t> Note, since the Wkc format is opaque to the client, a server can decide to use
          a different format. For example when using a large infrastructure, e.g. a Cloud service,
          it is desirable to allow using multiple different server keys to be able to replace a
          compromised key or to be able to do key rotation. </t>
          
          <t> In this scenario a cleartext key id should be added to allow the server to select
          the key that should be used to decrypt the wrapped key.</t>
          
          <t> As example how to implement this wrapping, assume the server keys are using a 32 bit
          index. The server key (Ke, Ka) with the index i is named Kai and Kei.
          <figure>
            <sourcecode>
K_id = key id of server key Kai, Kei  (32 bit, network order)

len = len(WKc) (16 bit, network byte order)

T = HMAC-SHA256(Kai, len || K_id || Kc || metadata)

IV = 128 most significant bits of T

WKc = T || AES-256-CTR(Ke, IV, Kc || metadata) || K_id || len
                </sourcecode>
              </figure>
          </t>



          <t>
            When setting up the OpenVPN connection:

            <ol>

              <li> The client reads the tls-crypt-v2 key from its config, and:
              <ol>
                <li> loads ``Kc`` as its tls-crypt key, </li>
                <li> stores ``WKc`` in memory for sending to the server. </li>
              </ol>
              </li>

              <li> To start the connection, the client creates a P_CONTROL_HARD_RESET_CLIENT_V3
              message, wraps it with tls-crypt using ``Kc`` as the key, and appends
              ``WKc``.  (``WKc`` must not be encrypted, to prevent a chicken-and-egg
              problem.)</li>

              <li> The server receives the P_CONTROL_HARD_RESET_CLIENT_V3 message, and

              <ol>
                <li> reads the WKc length field from the end of the message, and extracts WKc
                from the message </li>
                <li> unwraps ``WKc`` </li>
                <li> uses unwrapped ``Kc`` to verify the remaining
                P_CONTROL_HARD_RESET_CLIENT_V3 message's (encryption and) authentication. </li>
              </ol>

              The message is dropped and no error response is sent when any of these steps fails (DoS protection).
              </li>

              <li> Server optionally checks metadata using a --tls-crypt-v2-verify script

              This allows early abort of connection, *before* we expose any of the
              notoriously dangerous TLS, X.509 and ASN.1 parsers and thereby reduces the
              attack surface of the server.

              The metadata is checked *after* the OpenVPN three-way handshake has
              completed, to prevent DoS attacks.  (That is, once the client has proved to
              the server that it possesses Kc, by authenticating a packet that contains the
              session ID picked by the server.)

              A server should not send back any error messages if metadata verification
              fails, to reduce attack surface and maximize DoS resilience.
              </li>
              <li> Client and server use ``Kc`` for (un)wrapping any following control channel
              messages.</li>
            </ol>
          </t>
          <t>
            Setting up connection with cookie support

            To avoid exhaustion attack and keeping state for connections that fail to
            complete the three way handshake, the OpenVPN server will use its own session
            id as challenge that the client must repeat in the third packet of the
            handshake. This introduces a problem. If the server does not keep the wrapped
            client key from the initial packet, the server cannot decode the third packet.
            Therefore, tls-crypt-v2 allows resending the wrapped key in the third
            packet of the handshake with the P_CONTROL_WKC_V1 message. The modified
            handshake is as follows (the rest of the handshake is unmodified):

            <ol>
              <li> The client creates the P_CONTROL_HARD_RESET_CLIENT_V3 message as before
              but to indicate that it supports resending the wrapped key by setting the
              packet id of the replay id to 0x0f000000 where the first byte indicates the
              early negotiation support and the next byte the flags. All tls-crypt-v2
              implementations that support early negotiation, MUST
              also support resending the wrapped key. The flags byte is therefore empty.
              </li>
              <li>The server responds with a P_CONTROL_HARD_RESET_V2 message. Instead of having
              an empty payload like normally, the payload consists of TLV (type (uint16),
              length (uint16), value) packets. TLV was chosen
              to allow extensibility in the future. Currently only the following TLV is
              defined:

              flags - type 0x01, length 2.

              Bit 1 indicates that the client needs to resend the WKC in the third packet.
              </li>

              <li>Instead of normal P_ACK_V1 or P_CONTROL_V1 packet, the client will send a
              P_CONTROL_WKC_V1 packet. The P_CONTROL_WKC_V1 is identical to a normal
              P_CONTROL_V1 packet but with the WKc appended.

              Normally the first message of the client is either P_ACK_V1, directly
              followed by a P_CONTROL_V1 message that contains the TLS Client Hello or
              just a P_CONTROL_V1 message. Instead of a P_ACK_V1 message the client should
              send a P_CONTROL_WKC_V1 message with an empty payload. This message must
              also include an ACK for the P_CONTROL_HARD_RESET_V2 message.

              When directly sending the TLS Client Hello message in the P_CONTROL_WKC_V1
              message, the client must ensure that the resulting P_CONTROL_WKC_V1 message
              with the appended WKc does not extend the control message length.
              </li>
            </ol>
          </t>
        </section>

        <section title="Considerations">
          <t>
            To allow for a smooth transition, the server implementation allows
            ``tls-crypt`` or ``tls-auth`` to be used simultaneously with ``tls-crypt-v2``.
            This specification does not allow simultaneously using ``tls-crypt-v2`` and
            connections without any control channel wrapping, because that would break DoS
            resilience.
          </t>
          <t>
            WKc includes a length field, so we leave the option for future extension of the
            P_CONTROL_HEAD_RESET_CLIENT_V3 message open.  (E.g. add payload to the reset to
            indicate low-level protocol features.)
          </t>
          <t>
            ``tls-crypt-v2`` uses fixed crypto algorithms, because:

            <ul>
              <li>The crypto is used before we can do any negotiation, so the algorithms have
              to be predefined.</li>
              <li>The crypto primitives are chosen conservatively, making problems with these
              primitives unlikely.</li>
              <li>Making anything configurable adds complexity, both in implementation and
              usage.  We should not add any more complexity than is absolutely necessary.</li>
            </ul>
          </t>
          <t>
            Potential ``tls-crypt-v2`` risks:
            <ul>
              <li>Slightly more work on first connection (``WKc`` unwrap + hard reset unwrap)
              than with ``tls-crypt`` (hard reset unwrap) or ``tls-auth`` (hard reset auth).</li>
              <li>Flexible metadata allow mistakes
              (So we should make it easy to do it right.  Provide tooling to create client
              keys based on cert serial + CA fingerprint, provide script that uses CRL (if
available) to drop revoked keys.)</li>
            </ul>
          </t>
        </section>

      </section>
    </section>


   </section>
    <section anchor="controlchannel" title="Control channel">
      <t>
        OpenVPN communicates over two channels which are multiplexed over the
        same connection; control channel and data channel.  The control
        channel is used for passing configuration and environment data between
        each side of the tunnel, including encryption session keys.  The data
        channel carries the encrypted tunnel data.  The OPCODE determines which
        channel the packet belongs to.
      </t>

      <section title="Overview of OPCODEs">
        <t>
          Each packet MUST contain an OPCODE.  This is located within the first
          byte in each UDP packet and the third byte in TCP packets.  The high 5
          bits contains the OPCODE and the lower 3 bits defines a key-id.  The
          OPCODE defines the contents of the following payload. The op codes
          DATA_V1 and DATA_V2 are NOT control channel op coes and will NOT be discussed
          in this chapter. They are included for completeness.
          
        </t>
        <texttable>
          <ttcol>OPCODE</ttcol>
          <ttcol>Channel</ttcol>
          <ttcol>Short name</ttcol>
          <ttcol>Payload</ttcol>
          <ttcol>Status</ttcol>

          <c>1</c>
          <c>Control</c>
          <c>CONTROL_HARD_RESET_CLIENT_V1</c>
          <c/>
          <c>Obsolete</c>

          <c>2</c>
          <c>Control</c>
          <c>CONTROL_HARD_RESET_SERVER_V1</c>
          <c/>
          <c>Obsolete</c>

          <c>3</c>
          <c>Control</c>
          <c>CONTROL_SOFT_RESET_V1</c>
          <c>-</c>
          <c>Obsolete</c>

          <c>4</c>
          <c>Control</c>
          <c>CONTROL_V1</c>
          <c>X</c>
          <c>Current</c>

          <c>5</c>
          <c>Control</c>
          <c>ACK_V1</c>
          <c>X</c>
          <c>Current</c>

          <c>6</c>
          <c>Data</c>
          <c>DATA_V1</c>
          <c>X</c>
          <c>Current</c>

          <c>7</c>
          <c>Control</c>
          <c>CONTROL_HARD_RESET_CLIENT_V2</c>
          <c>-</c>
          <c>Current</c>

          <c>8</c>
          <c>Control</c>
          <c>CONTROL_HARD_RESET_SERVER_V2</c>
          <c>-</c> <!-- FIXME: VERIFY -->
          <c>Current</c>

          <c>9</c>
          <c>Data</c>
          <c>DATA_V2</c>
          <c>X</c>
          <c>Current</c>

          <c>10</c>
          <c>Control</c>
          <c>CONTROL_HARD_RESET_CLIENT_V3</c>
          <c>X</c>

          <c>Current</c>
          <c>11</c>
          <c>Control</c>
          <c>CONTROL_WKC_V1</c>
          <c>X</c>
          <c>Current</c>
        </texttable>
      </section>

      <section title="The Control Channel">
        <t>
          The control channel is used to pass configuration and environment
          information in addition to handle the SSL/TLS handshake process
          between the server and client.
        </t>

        <section title="Control channel wire packet structure">
          <t>
            The following table lists all fields found in control channel
            packets.  The fields arrive in the order they are listed in the
            table.
          </t>
          <t>
            The TLS auth column indicates fields used when additional
            HMAC authentication data is added to the control channel packets.
          </t>
          <texttable>
            <ttcol>Field name</ttcol>
            <ttcol align="right">Length (bits)</ttcol>
            <ttcol align="center">TLS auth</ttcol>
            <ttcol>Comment</ttcol>

            <c>pkt_len</c>
            <c>16</c>
            <c></c>
            <c>Packet length (TCP only)</c>

            <c>OPCODE</c>
            <c>5</c>
            <c></c>
            <c></c>

            <c>key_id</c>
            <c>3</c>
            <c>X</c>
            <c></c>

            <c>own session_id</c>
            <c>64</c>
            <c>X</c>
            <c></c>

            <c>HMAC</c>
            <c>128-512</c>
            <c>X</c>
            <c>Algorithm defines length</c>

            <c>replay_packet_id</c>
            <c>64</c>
            <c>X</c>
            <c>ID used for replay protection.</c>

            <c>acked_pktid_len</c>
            <c>8</c>
            <c>X</c>
            <c></c>

            <c>acked_pktid_list</c>
            <c>32 * n</c>
            <c>X</c>
            <c>List length defined by acked_pktid_len.</c>

            <c>peer session id</c>
            <c>64</c>
            <c>X</c>
            <c>Session ID of the remote peer. Present if acked_pktid_len >= 1</c>

            <c>packet_id</c>
            <c>32</c>
            <c>X</c>
            <c>ID of the control channel packet. ACK packets lack a packet_id</c>

            <c>payload</c>
            <c>(var)</c>
            <c>X</c>
            <c>Can be empty</c>
          </texttable>

          <section title="Field: pkt_len">
            <t>
              This field is only present when TCP is used as the transport
              protocol.  This value should be the number of bytes being
              transported in this packet, excluding the pkt_len field.
            </t>
          </section>

          <section title="Field: OPCODE">
            <t>
              The OPCODE field is described in detail in the
              <xref target="opcodes">Control Channel OPCODEs</xref> section.
            </t>
          </section>

          <section title="Field: key_id">
            <t>
              This is used to indicate which keys to use when
              processing the payload.  This has a range from 0 to
              7. All new sessions starts with key_id 0. After a key
              renegotiation the key_id will increase by one. After
              key_id 7, the key_id wraps to 1.
            </t>
          </section>

          <section title="Field: session_id">
            <t>
              This is a unique random value for a particular connected
              session.  If an established session needs a full reconnect,
              the session ID MUST be changed.  Client and server have
              their own independent session ID.
            </t>
          </section>

          <section title="Field: HMAC">
            <t>
              Contains the HMAC signature for this packet if the HMAC
              authentication has been enabled.  The length of this
              field will vary according to the requirements of the
              hashing algorithm.
            </t>
          </section>

          <section title="Field: replay_packet_id">
            <t>
              This is an incremental ID for each packet which helps
              discovering packet replay attacks. Usually consists of
              a 32 bit time + 32 bit counter but can be any monotonically
              increasing sequence. For both fields the value is
              transferred using network byte order.
            </t>
            <t>
              For CFB/OFB based ciphers, the long packet_id format MUST be
              used, as the packet_id is part of the cipher's IV.
              [FIXME/syzzer: Elaborate more]
              [FIXME/schwabe: move to data channel]
            </t>
          </section>

          <section title="Field: acked_pktid_len">
            <t>
              Defines the number of acked packet IDs being reported in this
              packet.  If set to 0, no acked packet ID elements will be found,
              otherwise the following 4 bytes * acked_pktid_len of data
              will contain the list of acked packet IDs.
            </t>
          </section>

          <section title="Field: acked_pktid_list">
            <t>
              This field contains the packet ID which the remote side have
              received and processed.  This field will appear up to
              acked_pktid_len number of times, each with an individual packet
              ID.  These packet IDs should be found in a local cache of sent
              packet IDs.  If not found, the communication may have been
              manipulated.
            </t>
          </section>
          <section title="Field: peer_session_id">
            <t>
              If acked_pktid_len is 1 or greater this field MUST be present and
              specify the remote session id. If acked_pktid_len is 0 the field MUST
              be absent.
            </t>
          </section>

          <section title="Field: packet_id">
            <t>
              The ID of the control channel packet. The packet IDs
              are used to ensure a TCP-like connection even if UDP is
              used as protocol. The ID MUST start at 0 and MUST be
              sequential without gaps. Retransmission must have the same
              packet_id as the original message but can have a different
              replay_packet_id. ACK packages MUST NOT have a packet_id.
            </t>
          </section>

          <section title="Field: payload">
            <t>
              The payload to be processed.  This is most commonly an
              encrypted blob which is expected to be passed on to
              the SSL/TLS library for further processing.
              [FIXME: Elaborate more]
            </t>
          </section>
        </section>

        <section anchor="opcodes" title="Control Channel OPCODEs">
          <section title="[OPCODE ID 1] CONTROL_HARD_RESET_CLIENT_V1">
            <t>
              <em>OBSOLETE:</em> This OPCODE is not in use any more.
            </t>
            <t>
              This MAY be reused in the future once all other OPCODE
              slots are in use.
            </t>
          </section>

          <section title="[OPCODE ID 2] CONTROL_HARD_RESET_SERVER_V1">
            <t>
              <em>OBSOLETE:</em> This OPCODE is not in use any more.
            </t>
            <t>
              This MAY be reused in the future once all other OPCODE
              slots are in use.
            </t>
          </section>

          <section title="[OPCODE ID 3] CONTROL_SOFT_RESET_V1">
            <t>
              Start new TLS session to generate a new data channel key
              to allow a graceful transition from old to new key.
            </t>
            <t>
              This is used to rotate session keys.  It allows both
              a new key and the old ones to be valid for a limited
              transition window.  The transition window size is
              decided by the server.  This window SHOULD NOT
              exceed the expected renegotiation cycle.
            </t>
            <t>
              Either client or server MAY send a CONTROL_SOFT_RESET_V1
              packet to the remote side.  The remote side MUST respond
              with a CONTROL_SOFT_RESET_V1 message to acknowledge that
              a renegotiation of the session keys will start.  Then
              the side receiving the last CONTROL_SOFT_RESET_V1 packet
              replies with an ACK_V1 message.  At this point the
              renegotiation can start using the CONTROL_V1 OPCODE.
            </t>
            <t>
              When the ACK_V1 packet is being sent, the key_id field
              MUST be incremented to ensure the connection can still
              use the old keys for a shorter time until the transition
              has completed.  Any following packets need to use the new
              key-id until the old key has been removed and the new
              key-id replaces it completely. [FIXME/schwabe:THIS IS WRONG)
            </t>
            <t>
              [FIXME: Elaborate more on how re-keying happens]
            </t>
          </section>

          <section title="[OPCODE ID 4] CONTROL_V1">
            <t>
              Control channel packet, usually TLS protocol data.
            </t>
            <t>
              CONTROL_V1 is used to encapsulate the SSL/TLS protocol into the
              OpenVPN wire packet, primarily used for the SSL/TLS handshake
              process.  The payload of CONTROL_V1 packets are expected to be
              processed by an SSL/TLS library.  Once the SSL/TLS handshake
              has completed and the ephemeral session key has been
              negotiated, encrypted tunnel data will use either DATA_V1 or
              DATA_V2 for the transport of those packets.
            </t>
          </section>

          <section title="[OPCODE ID 5] ACK_V1">
            <t>
              Acknowledgment for received control channel packets.
            </t>
            <t>
              When control channel packets have been received an ACK_V1
              packet is sent back to confirm its arrival.  An ACK_V1
              message SHOULD NOT be sent upon receiving an ACK_V1 message.
            </t>
            <t>See also <xref target="acks">Acknowledgments</xref>.</t>
          </section>

          <section title="[OPCODE ID 7] CONTROL_HARD_RESET_CLIENT_V2">
            <t>
             Used to start a VPN connection from client, first packet of the three-way handshake.
            </t>
            <t>
              The client starts with a fresh new session key.  This tells the server
              to initiate a new TLS handshake and establish a new session key for
              data channel going from client to server.
            </t>
            <t>
              Note that the payload of this packet MUST be ignored but might
              be used to implement early protocol negotiation in the future.
            </t>
          </section>

          <section title="[OPCODE ID 8] CONTROL_HARD_RESET_SERVER_V2">
            <t>
              Initial packet from server, reply to a CONTROL_HARD_RESET_CLIENT_V2 packet.
              Second packet in the three-way handshake.
            </t>
            <t>
              In the P2P mode for TLS.  Similar to CONTROL_HARD_RESET_CLIENT_V2, but initiated from
              the server side.
            </t>
            <t>
              Note that the payload of this packet MUST be ignored but might
              be later used to implement early protocol negotiation in the future.
            </t>
          </section>
          <section title="[OPCODE ID 10] CONTROL_HARD_RESET_CLIENT_V3">
            <t>
              Initial key packet from the client in the three-way handshake from the client
              when tls-crypt-v2 is in use. See <xref target="tlscryptv2">TLS crypt v2</xref> for more details.
            </t>
            <t>
              Note that the payload of this packet is interpreted by OpenVPN 2.x to be already
              part of the TLS session. The payload of this packet SHOULD be empty.
            </t>
            <t>
              The tls-crypt packet id of this packet is used to indicate
              early protocol negotiation. Without early protocol negotiation the first four octets
              are normally an uint32 in network byte order starting at 0 and increase linearly
              with later packets. When early protocol negotiation is supported the value is
              instead 0x0f 00 00 00. The most significant byte of 0x0f indicates that the
              second highest byte contains flags of supported features (see below). The third byte SHOULD also be
              0x00. The fourth byte is expected to be used for retransmission and will linearly
              increase with retransmissions of the control packet. For packets other than the reset
              packet, the packet id is just a normal replay counter.
            </t>
            <t>
              Currently no flags are defined for the second byte, yet. But indicating support for early protocol negotiation implies that the client
              supports sending <xref target="CONTROL_WKC_V1">CONTROL_WKC_V1</xref> packets.
            </t>
          </section>
          <section anchor="CONTROL_WKC_V1" title="[OPCODE ID 11] CONTROL_WKC_V1">
            <t>
              Identical to the CONTROL_V1 message but with a wrapped
              client append to the message similar to the CONTROL_HARD_RESET_CLIENT_V3
              message. See <xref target="tlscryptv2">TLS crypt v2</xref> for details.
            </t>
          </section>

          <section title="[OPCODE ID 9] DATA_V2">
          <t>
            Data channel packet with 4-byte header.  This is
            similar to DATA_V1 with an additional field of 24 bits
            for Peer-ID.
          </t>
          <t>
            For details about this opcode see sections about <xref target="dataaead">AEAD</xref>
            and <xref target="datacbc">CBC/OFB/CTR</xref> packet format.
          </t>
          </section>
          <section title="[OPCODE ID 6] DATA_V1">
          <t>
            The DATA_V1 packet is identical to the DATA_V2 packet apart from
            op_code being 6 and the peer_id absent from the packet format
            (all followings fields are shifted by 3 bytes to the left).
          </t>
          <t>
            The DATA_V1 packet are <em>deprecated</em> and should only used for
            interoperability with old clients.
          </t>
        </section>

      </section>

        <section title="PUSH messages">
        </section>

        <section title="Peer-Info">
        </section>
      </section>
      <section title="Message Packet IDs">
        <t>
          Control channel packets have a message id that orders them and identifies them for ack messages.
          The message ids are independent for both direction and MUST start at 0. If the message id reaches
          MAX_UINT32, the implementation MAY implement a rollover to 0 again. However, since such a
          huge number of control message is unrealistic, an implementation MAY refuse new packets if
          the message packet id rolls over.
        </t>
      </section>
      <section anchor="acks" title="Acknowledgements">
        <t>
          OpenVPN has dedicated acknowledgment messages and also allows adding
          acknowledgments to other control messages. A P_ACK_V1 message usually
          carries up to 8 acknowledgments while other messages only carry 4
          acknowledgments. Unlike other protocols like TCP, OpenVPN does not
          have cumulative ACKs and each ACK only allows acknowledging a
          single packet.
        </t>
        <t>
          To avoid retransmissions it is recommended to keep an LRU cache of the
          most recently seen packets from the peer and always put ACKs for these
          packets in messages (4 for non P_ACK_V1 and 8 for P_ACK_V1).
        </t>
        <t>
          To ensure compatibility to with the existing OpenVPN implementation the
          number of ACKs in a single packet (acked_pktid_list) should be limited
          to 8.
        </t>
      </section>
      <section title="Control message framing">
        <t>
        The current implementation expects control to be 1250 or smaller. Apart from the early protocol
        negotiation, all payloads of control packets are TLS data.
        </t>

        <t>
        For the plaintext messages, OpenVPN considers a control message to correspond to a single TLS
        record. Splitting a plaintext message into two TLS records, will result it to be treated as
        two separate messages. To send a control message with a larger plaintext, a single TLS record
        must be split over multiple control messages.
        </t>
        <t>
          Control message should be also separated by a NUL byte. The current implementation might not
          enforce this behaviour but future implementation that no longer rely on TLS framing might enforce
          this behaviour. When sending an implementation MUST send each control message in its own TLS
          record terminated by a NUL byte.
        </t>
      </section>
      <section title="Key exchange message">
        <t>
          <figure>
            <sourcecode>
struct key_exchange {
    uint32 null;
    uint8 method = 2;
    uint8 key_random[48];
    uint8_t random1[32];
    uint8_t random2[32];
    uint16   occ_string_len;
    uint8_t* occ_string;
    uint16   username_len;
    uint8_t* username;
    uint16   password_len;
    uint8_t* password;
    uint16   peerinfo_len;
    uint8_t* peerinfo;
}
            </sourcecode>
          </figure>
        </t>

        <t>
          All the strings in these packets are expected to be valid UTF8 null-terminated strings. If they are not
          used (e.g. password and username), they are just a single zero byte.
          The string length MUST include the trailing null byte.
        </t>

        <t>
          The packets always starts with 4 bytes of zero, followed by one byte of 0x02. After that comes
          random data that is used with legacy clients to derive the <xref target="openvpnkey">data channel keys</xref>
          using a TLS1.0/TLS1.1 style PRF function. These fields are not used in the modern protocol anymore
          since the data channel key derivation is using TLS export key feature but SHOULD be set to random
          values.
        </t>

        <t>
          The OCC string is a string that contains a number of parameters that are used to check if client
          and server are using compatible configuration and warn on mismatches. With more and more dynamic
          configuration in the OpenVPN protocol, its usefulness is highly diminished.
        </t>
        <t>
          During the handshake, the client will have username and password if username and password authentication
          is used. <xref target="peerinfo">Peerinfo</xref> is also present. The server replies with a key_exchange
          packet on its own with occ_string, username, password and empty peerinfo.
        </t>
        <t>
          The <tt>key_random</tt>, <tt>random1</tt>, and <tt>random2</tt> only used for older clients that do
          not support key derivation via RFC 5705 keying material exporter support. This value should contain
          random bytes.
        </t>

      </section>
      <section anchor="peerinfo" title="Peerinfo">
        <t>
          The peerinfo is an UTF8 encoded string that contains newline separated (<tt>\n</tt>) variables
          in the form of VAR=VALUE. The following variables are specified:
          <ul>
            <li> IV_PROTO: A positive decimal number which is being interpreted as a bit field containing supported protocol extensions by the peer. </li>
            <li> IV_CIPHERS: A list of colon (<tt>:</tt>) separated allowed data channel ciphers. </li>
            <li> IV_HWADDR: A MAC address or UUID address that uniquely identifies the client </li>
            <li> IV_GUI_VER: name and version number of the UI of the OpenVPN client </li>
            <li> IV_VER: version of the OpenVPN library/program</li>
            <li> IV_PLAT: operating system the peer uses</li>
            <li> IV_NCP: if equal to 2 the client supports AES-128-GCM and AES-256-GCM, IV_NCP is
            <em>deprecated</em> in favor of IV_CIPHERS </li>
            <li> IV_SSO: out of band (auth pending) methods the client supports</li>
            <li> IV_MTU: The client is capable of dynamically set the MTU as part of imported options up to the size
            specified by IV_MTU</li>
            <li> IV_ACC: App control channel. This announces support for the OpenVPN implementation to transport a custom payloads
            for use in a sideband channel for a custom communication between server and client. </li>
            <li> variables starting with UV_. This are variables set by the user by a
            configuration file or similar means. These do not have any fixed meaning.</li>
          </ul>

          Most of the variables are considered optional. Only IV_CIPHERS, IV_PROTO and IV_SSO (if
          auth pending is supported) MUST be implemented.
        </t>
        <t>
          For IV_PROTO, the bits have the following meaning:
          <ul>
            <li>bit 0: Reserved. SHOULD be 0.</li>
            <li>bit 1: The peer supports peer-id floating mechanism</li>
            <li>bit 2: The client expects a <xref target="pushreply">PUSH_REPLY</xref> and the server MAY
            send this reply without waiting for a <xref target="pushrequest">PUSH_REQUEST</xref> first. </li>
            <li>bit 3: The client is capable of doing key derivation using
            <xref target="RFC5705">RFC5705 key material exporter</xref>. </li>
            <li>bit 4: The client is capable of accepting additional arguments
            to the <xref target="authpending">AUTH_PENDING</xref> message.</li>
            <li>bit 5: The client supports doing feature negotiation in P2P mode.</li>
            <li>bit 6: The client is capable of parsing and receiving the <xref target="dnsproto">dns</xref> messages pushed option. DEPRECATED. Do not use.</li>
            <li>bit 7: The client is capable of sending exit notification via control channel using <xref target="exitcc">EXIT</xref> message. The client is accpting the protocol-flags pushed option for the EKM capability</li>
            <li>bit 8: The client is capable of accepting <xref target="authfailed">AUTH_FAILED,TEMP</xref> messages.</li>
            <li>bit 9: The client is capable of dynamic tls-crypt</li>
            <li>bit 10: The client is capable of AEAD tag at the end of a data channel packet and capable of using 64bit packet counters for AEAD ciphers.</li>
            <li>bit 11: The client is capable of parsing and receiving the <xref target="dnsproto">dns</xref> messages pushed option.</li>
            <li>bit 12: The client is capable of receiving <xref target="pushupdate">PUSH_UPDATE</xref> message.</li>
          </ul>
        </t>
        <t>
          If the IV_ACC variable is present, this indicates that the library implements the <xref target="ACC_MSG">ACC control message</xref>. The IV_ACC
          variable indicates the capabilities of the client.  IV_ACC has the following format

          <figure>
            <sourcecode>
              IV_ACC=&lt;maxlen>,&lt;protocol flags>,&lt;custom protocols>
            </sourcecode>
          </figure>
        </t>
        <t>
           maxlen: the maximum length of message this implementation can receive in one message. This is encoded
           message and depends on the general size of control frame the implementation can handle.
        </t>
        <t>
          The protocol flags are a colon seperated list of flags. Currently defined are:
          <ul>
            <li> 6 - supports transfer of base64 encoded messages to transport binary messages </li>
            <li> B - supports transfer of binary message without any encoding </li>
            <li> A - supports transfer of text messages without control characters </li>
          </ul>
          
        </t>
        <t>
          custom protocols is a colon separated list of custom app protocols that are supported. This list should be kept
            short and the protocol names itself should be short as well as they will repeated with every message that is
            sent for the protocol.
        </t>
        <t>
          An example would of an IV_ACC message would be for a client that supports base64 and text messages and supports
          the flower and fortune protocol would be
          <figure>
            <sourcecode>
              IV_ACC=1400,6:B:m=1400,flower:fortune
            </sourcecode>
          </figure>
        </t>
      </section>

    </section>

  <section title="Data channel" anchor="datachannel">
    <section anchor="openvpnkey" title="OpenVPN Key">
      <t>
        OpenVPN uses 256 byte of key material for encryption/decryption of the data
        channel. The format of this key material is the following:

        <figure>
          <sourcecode>
struct datakeys {
    uint8_t key_c2s[64];
    uint8_t auth_c2s[64];
    uint8_t key_s2c[64];
    uint8_t auth_s2c[64];
}
          </sourcecode>
        </figure>
      </t>
      <t>
        All these keys provide more than enough material to provide encryption keys
        for all encryption and authentication algorithms. E.g. when 128 bit are required
        for an encryption cipher, only the first 16 bytes are used.

        key_c2s and auth_c2s are used to encrypt/authenticate data from client to server
        and key_s2c and auth_s2c are used to encrypt/authenticate from server to client.
      </t>
      <t>
        This key structure is normally generated by using <xref target="RFC5705">RFC 5705 key material exporter</xref>
        from the Control Channel session with the label <tt>EXPORTER-OpenVPN-datakeys</tt>
        and using the 256 bytes length of the structure.

        Older clients use the mechanism described in the section OpenVPN data channel
        PRF.
      </t>
    </section>
    <section title="Peer-ID">
      <t>
        The purpose of this feature is to allow a client to float between various client
        IP addresses and UDP ports.  When a client floats it means that the established
        encryption and session keys will be reused when the client's source IP
        address or source port changes.  Reasons for such changes can be NAT
        firewalls interrupting longer lasting established connections, mobile
        devices moving from WLAN to a mobile data carrier (such as GPRS, 3G,
        LTE, etc) and similar scenarios.
      </t>
      <section title="Requirements">
        <t>
          Each client implementing Peer-ID support MUST indicate its support
          with the IV_PROTO=2 <xref target="peerinfo">peerinfo</xref> variable.
          By sending IV_PROTO=2 to the server, it means
          the client will be able to use the DATA_V2 packet format.  When
          the server acknowledges that the client supports IV_PROTO=2/DATA_V2
          it SHOULD assign an unique Peer-ID to the client.  The server is
          responsible of keeping track of which Peer-ID is related to which
          active session and MUST ensure no active clients share the same
          Peer-ID.
        </t>
        <t>
          Clients MUST accept the peer-id option being passed to it via a
          PUSH_REPLY message and MUST use this value as the Peer-ID in all
          DATA_V2 packets.  Clients MUST provide a valid Peer-ID in all
          DATA_V2 packets, but it can be the ID used to indicate Peer-ID being
          disabled.
        </t>
        <t>
          Server implementations MUST support the IV_PROTO=2 and the DATA_V2
          packet format and MUST evaluate the response from the client before
          assigning and pushing a peer-id option to the client.  The server
          SHOULD use the DATA_V2 packet formats when communicating
          with the clients.
        </t>
        <t>
          The client is not expected to parse the Peer-ID in DATA_V2 packets.
          The server should send the same Peer-ID provided in packets from the
          server to client.
        </t>
        <t>
          The Peer-ID is included protected in the HMAC signature/AEAD tag
          of DATA_V2 packets.
        </t>
      </section>
      <section title="Allowing floating clients">
        <t>
          The server MUST ensure the packet integrity is intact, through
          checking HMAC or GCM authentication tags, replay protection, etc
          of the DATA_V2 packet.
        </t>
        <t>
          In addition the server MUST ensure the float does not clobber
          a pre-existing client, such as a client floating to a source
          IP address used by a different client unless it can be verified
          that the pre-existing client is a previous instance of the
          floating client.
        </t>
      </section>
      <section title="Replay protection">
	<t>
	  The replay protection in OpenVPN uses a fairly standard approach
	  with a sliding window with a number of packets n and a timeout t

	  <ol>
	    <li>If a packet arrives that has a higher sequence number than the highest packet sequence seen so far, it is accepted</li>
	    <li>If a packet arrives out of order, it will only be accepted if the difference between its sequence number and the highest sequence number received so far is less than n. </li>
	    <li>If a packet arrives out of order, it will only be accepted if it arrives no later than t seconds after any packet containing a higher sequence number.</li>
	    <li> A packet will be rejected if it is a replay</li>
	  </ol>
        </t>

        <t>
	  This means that a client needs to keep track of the highest received
	  sequence number and the n sequence ids lower than the highest received
	  sequence number.
        </t>
        <t>
	  Old OpenVPN peers before 2.4 will enforce a strict packet ordering
	  when using TCP that does not allow reordering.
	</t>
      </section>
    </section>
    <section anchor="dataaead" title="AEAD encrypted data channel packet">

      <t>
        AEAD format with tag at the start:
        
          <figure>
            <sourcecode>
struct aead_packet {
    int opcode:5;
    int key_id:3;
    int peer_id:24;
    uint32_t/uint_64_t packet_id;
    uint8_t[16] authentication_tag;
    uint8_t* encrypted_payload;
}
            </sourcecode>
          </figure>
        </t>

        <t>
          AEAD format with tag at the end:
          
          <figure>
            <sourcecode>
struct aead_packet {
    int opcode:5;
    int key_id:3;
    int peer_id:24;
    uint32_t/uint64_t packet_id;
    uint8_t* encrypted_payload;
    uint8_t[16] authentication_tag;    
}
            </sourcecode>
          </figure>
        </t>
        
        <t>
          The packet_id together with the implicit IV forms the IV for
	  decryption. The packet_id is also used for the replay protection.

          When 64 bit packet ids are enabled, the size becomes 64 bit.
        </t>

        <t>
          <sourcecode>IV = packet_id | implicit_iv;</sourcecode>
        </t>

        <t>
          The implicit part of IV is filled by first bytes of the
	  auth_c2s/auth_s2c of
          the data channel key. For the current implemented AEAD ciphers
          Chacha20-Poly1305 and AES-GCM the IV length is 96 bits, 32 bits are
          from packet_id and the remaining 64 bits (the implicit IV part) are
          taken from the data channel key.

          With 64 bit packet id counters the implicit IV part becomes 32 bit.
        </t>

        <t>
          For DATA_V2 packets the authenticated data <em>includes</em> opcode,
          key_id and peer_id. For DATA_V1 packets the authenticated data starts
          on the first byte of packet_id, not including opcode and key_id.
        </t>

        <t>
          <sourcecode>
authenticated_data_v1 = packet_id | payload
authenticated_data_v2 = opcode| key_id | peer_id | packet_id | payload
          </sourcecode>
        </t>

        <t>
          The tag size is always 128 bit (16 bytes). (Same size as in TLS). If the
          protocol flag for AEAD tag at the end is in effect, the AEAD tag is at the end
          of the packet rather than at the start.
        </t>
      </section>
      <section anchor="datacbc" title="CBC/OFB/CTR encrypted packet">
        <t>
          <figure>
            <sourcecode>
struct data_packet_cbc {
    int opcode:5;
    int key_id:3;
    int peer_id:24;
    uint8_t[HMAC_LEN] hmac;
    uint8_t[IV_LEN] iv;
    uint32_t encrypted_packet_id;
    uint8_t* encrypted_payload
}
            </sourcecode>
          </figure>
          <figure>
            <sourcecode>
struct data_packet_xfb {
    int opcode:5;
    int key_id:3;
    int peer_id:24;
    uint8_t[HMAC_LEN] hmac;
    uint8_t[IV_LEN] iv;
    uint8_t* encrypted_payload
}
            </sourcecode>
          </figure>

          <t>HMAC_LEN depends on the length of the HMAC being used, e.g. 20 bytes for
          SHA1, 32 for SHA256. If no authentication is used (DEPRECATED) then the
          length of the field is 0.</t>

          <t>The HMAC is computed over the complete remainder of the packet. opcode,
          key_id, and peer_id are NOT included in the HMAC calculation. If HMAC verification
          fails decryption of the packet MUST NOT be attempted. OpenVPN implements the
          encrypt-then-MAC approach.</t>

          <t>IV_LEN depends on the IV of used cipher. For AES in CBC, CFB and OFB this
          is 128 bits (IV_LEN=8), for Blowfish in CBC mode (DEPRECATED) 64 bits (IV_LEN=4). For generating
          the IV use best practices. OpenVPN generates the CBC IV as random bytes
          with an PRNG. For OFB and CFB the IV has the following format:</t>

          <sourcecode>IV = 64 bit packet ID | IV_remainder</sourcecode>

          <t>The IV_remainder SHOULD be random bytes. OpenVPN 2.x uses all zeros instead.</t>

          <t>The packet ID in CBC mode is encrypted and included before the payload. In contrast
          to that, the packet ID in OFB and CFB mode are the first 64 bit of the IV.</t>

          <t>For unencrypted data packets the same format as CBC without IV is used.</t>
        </t>
      </section>
      <section title="OpenVPN data channel PRF">
        <t>
        This is a deprecated way of deriving the data channel keys. It should be only implemented if
        compatibility with older OpenVPN versions is required that do not support key derivation via
        the RFC5705 key material exporter. It also requires the MD5 algorithm which often
        modern crypto libraries do not readily support anymore.</t>

        <t>This uses the <tt>key_random</tt>, <tt>random1</tt>, and <tt>random2</tt> from the key
        exchange messages. These will be prefixed with client and server here to indicate from which
        packet these field are coming. Also the session id of the control channel will be used here</t>

        <t>
        Here TLS_PRF(seed, secret) is the TLS PRF function according to RFC 2246 with
        MD5 and SHA1 as used in TLS 1.0/1.1.

        <figure>
          <sourcecode>
seed = "OpenVPN master secret" | client.random1 | server.random1
secret = client.key_random
master_secret - TLS_PRF(seed, secret)

key_seed = "OpenVPN key expansion " | client.random2 | server.random2
datakeys = TLS_PRF(key_seed, key_seed)
          </sourcecode>
        </figure>
      </t>
      </section>
    </section>
    <section title="Control channel messages">
      <section title="Message format">
        <t>
          After the control channel has been established the format switch from the binary format of
          the key exchange message to a text based format. The message are sent in plain text. The
          current implementation does not allow a message to span more than one TLS record.
        </t>
      </section>
      <section anchor="pushrequest" title="PUSH_REQUEST">
        <t>
          Format: <sourcecode>PUSH_REQUEST</sourcecode>
        </t>
        <t>
          This message is sent from the client to the server and instructs the server that the
          client is ready to receive a <tt>PUSH_REPLY</tt> message. The message is periodically repeated
          until the <tt>PUSH_REPLY</tt> is received for compatibility with old OpenVPN servers and to act as
          a keepalive.
        </t>
      </section>
      <section anchor="pushreply" title="PUSH_REPLY">
        <t>
          Format: <sourcecode>PUSH_REPLY [comma separated options]</sourcecode>
        </t>
        <t>
          This message is sent from the server to the client and has dynamic configuration for the client.
          See the section "dynamic configuration option" for a detailed description of the options. [FIXME/flichtenheld: proper reference]
        </t>
        <t>If the client has set the IV_PROTO_REQUEST_PUSH bit in the IV_PROTO
        <xref target="peerinfo">peerinfo</xref> client variable the server MAY send a <tt>PUSH_REPLY</tt>
        without waiting for the <tt>PUSH_REQUEST</tt> from the client.
        </t>
      </section>
      <section anchor="pushupdate" title="PUSH_UPDATE">
      <t>
        Format: <sourcecode>PUSH_UPDATE [comma separated options]</sourcecode>
      </t>
      <t>
        This message includes dynamic configuration options that can be pushed from the server to the client without reconnecting.
        These options augment existing options. Options with the same name are replaced. To remove an option, it should be prefixed
        with <tt>-</tt>. For example, the following code replaces all routes (if there were any) with the provided one and removes the <tt>dns</tt> option:
        <sourcecode>
          PUSH_UPDATE,route 10.10.10.0 255.255.255.0,-dns
        </sourcecode>
        The client SHOULD support updating all pushed options; otherwise, it SHOULD reconnect. This also applies to removal.
        <t>
        Options prefixed with <tt>?</tt> are considered optional. The client MAY support them. If the client cannot support some optional options,
        they can be ignored, and the client does not have to reconnect. This also applies to removal. Example syntax:
        <sourcecode>
          PUSH_UPDATE,-?block-ipv6
        </sourcecode>
        Here client should remove <tt>block-ipv6</tt> option. However, if client does not support updating it, it does not need to reconnect.
        </t>
      </t>
      <t>
        This message is only sent if the client has set the IV_PROTO_PUSH_UPDATE bit in the IV_PROTO
        <xref target="peerinfo">peerinfo</xref> client variable.
      </t>
    </section>
      <section anchor="authpending" title="AUTH_PENDING">
        <t>
          Format:
          <sourcecode>AUTH_PENDING</sourcecode>

          or

          <sourcecode>AUTH_PENDING,flags</sourcecode>
        </t>
        <t>
          This message is sent from the server to the client to indicate that a multi factor authentication is in use
          and the authentication is not completed. The authentication can continue inband or out-of-band.
        </t>
        <t>
          <tt>flags</tt> is a comma separate key-value list. Currently <tt>timeout time</tt> is defined and defines the maximum time the server
          expects the client to stay in the pending auth state.
        </t>
        <t>
          The client indicates if the extended format with flags is supported by setting
          the IV_PROTO_AUTH_PENDING_KW bit in the IV_PROTO
          <xref target="peerinfo">peerinfo</xref> client variable. All new clients MUST support the extended format.
        </t>
      </section>
      <section title="RESTART and HALT">
        <t>
          Format:

          <sourcecode>
RESTART[,message]
HALT[,message]
          </sourcecode>

          and

          <sourcecode>RESTART,[[flags]]message</sourcecode>
        </t>
        <t>
          These message are sent from the server to the client and the client to
          terminate a session. With <tt>HALT</tt> the client is expected to also not try to
          try reconnect. With <tt>RESTART</tt> the client is expected to reconnect. <tt>flags</tt> is
          a list of characters that must follow directly after the comma and is
          enclosed in <tt>[</tt> and <tt>]</tt>. The client SHOULD purge username and password before
          reconnecting if flags contains <tt>P</tt> and reconnect to the next server unless
          <tt>N</tt> is in flags in which case it should reconnect to the same server. E.g.
          when the client receives a <tt>RESTART[PN]</tt> message it should reconnect to same
          server with the same username and password.
        </t>
        <t>
          The optional <tt>message</tt> indicates a message that can relayed to the user.
        </t>
      </section>
      <section anchor="authfailed" title="AUTH_FAILED">
        <t>
          Format:

          <sourcecode>
AUTH_FAILED[,message]

AUTH_FAILED,SESSION:message

AUTH_FAILED,TEMP[keywords]:message
AUTH_FAILED,TEMP:message
          </sourcecode>
        </t>
        <t>
          This message indicates to a client that an authentication attempt was unsuccessful.
          This message is mostly send in response to a <tt>PULL_REQUEST</tt> or when a client attempts to
          renegotiates a TLS session.
        </t>
        <t>
          The optional message can be relayed to the user. If the message starts with <tt>SESSION</tt>, this
          indicates that current credentials are longer valid. This is mostly used to indicate that
          the temporary session credentials that were pushed with "auth-token" and "auth-token-user"
          should be purged and the client should reconnect in the same way as a new connection.
        </t>
        <t>
          The <tt>AUTH_FAILED,TEMP</tt> message indicates that the authentication temporarily failed and should
          the client continue to retry to connect. The server can optionally give a user readable message
          and hint the client a behavior how to proceed. The keywords of <tt>AUTH_FAILED,TEMP</tt> are comma separated
          keys/values. Currently defined are:

          <ul>
            <li> <tt>backoff s</tt> - instructs the client to wait at least s seconds before the next connection attempt. If
            the client has already a higher delay before reconnecting, the delay should NOT be shortened. </li>
            <li> <tt>advance addr</tt> - Instructs the client to reconnect to the (IP) address of the current server. </li>
            <li> <tt>advance remote</tt> - Instructs the client to skip the remaining IP addresses of the current server and instead
            connect to the next server specified in the configuration file </li>
            <li> <tt>advance no</tt> - Instructs the client to retry connecting to the same server again. </li>
          </ul>
          For example a server that might send <tt>AUTH_FAILED,TEMP[backoff 42,advance no]: No free IP addresses</tt> to indicate
          that the VPN connection can currently not succeed and instructs the client to retry in 42 seconds again.
        </t>
        <t>
          The client will announce the capability of understanding <tt>AUTH_FAILED,TEMP</tt> message by setting the
          IV_PROTO_AUTH_FAILED_TEMP bit in the IV_PROTO <xref target="peerinfo">peerinfo</xref> client variable. A client that does not understand the <tt>AUTH_FAILED,TEMP</tt> message
          will treat this recoverable error as a non-recoverable error.
        </t>
      </section>
      <section anchor="exitcc" title="EXIT">
        <t>
          Format:

          <sourcecode>
            EXIT
          </sourcecode>
        </t>
        <t>
          This message indicates that the peer has terminated and the connection can be torn down.
        </t>
      </section>
      <section title="CR_RESPONSE">
        <t>
          Format: <sourcecode>CR_RESPONSE,base64reply</sourcecode>
        </t>
        <t>
          This message indicates a reply to prior challenge/response request. The response is specific to the
          challenge response and is encoded with base64.
        </t>
      </section>
      <section title="INFO_PRE and INFO">
        <t>
          Format:

          <sourcecode>
INFO_PRE,EXTRA

INFO,EXTRA
          </sourcecode>
        </t>
        <t>
          This message is used to send pending auth parameters. See the section on pending auth for more details
          on the format of the <tt>EXTRA</tt> parameter. [FIXME/flichtenheld: proper reference]
        </t>
      </section>
      <section title="ACC" anchor="ACC_MSG">
      <t>
        Format: <sourcecode>ACC,&lt;proto>,&lt;encoding>,&lt;len>,&lt;payload></sourcecode>
        This message is the same in both directions.
      </t>
      <t>
        <ul>
          <li> proto -- this repeats of the protocols that are listed in the IV_ACC message. </li>
          <li> len -- length of the payload. If the payload is encoded (e.g. base64) this length represented
          the length of encoding. </li>
          <li> encoding -- This is one encoding letters and an optional 'F' to indicate that this is message
          is fragmented with following messages until the first without an 'F' in the flags field is received. Then the
          message fragment should be combined and delievered as one message. </li>
          <li> payload -- the payload itself. According to the encoding, the message is just unecoded ('T' or 'B') or is encoded
          with base64 </li>
        </ul>
      </t>
      </section>
      <section title="Pushing configuration options and OCC">
          <section anchor="dnsproto" title="dns">
            <t>
              The dns option is used to configure the DNS server the client should use. The option is follow by a space seperated list of feature
              flags.
            </t>
          </section>
          <section title="protocol-flags">
            <t> The <sourcecode>protocol-flags</sourcecode> directive tells a client what OpenVPN protocol features to use.
            <ul>
              <li> <sourcecode>cc-exit</sourcecode> explicit exit notifies should be sent via the control channel instead of using an OCC message. </li>
              <li> <sourcecode>tls-ekm</sourcecode> The <xref target="openvpnkey">OpenVPN key</xref> for the
              data channel enryption should be derived using TLS key material exporter </li>
              <li> <sourcecode>dyn-tls-crypt</sourcecode> Renegotion control channel use dynamic TLS crypt </li>
              <li> <sourcecode>aead-tag-end</sourcecode> The AEAD tag is at the end of the data channel packets </li>
              <li> <sourcecode>pkt-id-64-bit</sourcecode> Use 64 bit packet counter for AEAD data channel ciphers </li>
            </ul>
            </t>
          </section>
      </section>
    </section>

    <section title="Cryptography">
      <section title="OpenVPN and the SSL/TLS protocol">
        <t>TBD</t>
      </section>

      <section title="Cipher negotiation">
        <t>TBD</t>
      </section>

      <section title="TLS mode and PKI">
        <t>TBD</t>
      </section>
    </section>

    <section title="User authentication">
      <section title="User/password authentication">
        <t>TBD</t>
      </section>

      <section title="Challenge-Response authentication">
        <t>TBD</t>
      </section>
    </section>
    <section title="Appendix">
      <section anchor="ovpnkeyfile" title="OpenVPN Static key file format">
      <t>
        The <xref target="tlsauth">HMAC packet authentication</xref> and
        <xref target="tlscrypt">Control packet encryption</xref> use pre-shared keys.
        The pre-shared key format is based on the internal <xref target="openvpnkey">OpenVPN key</xref>
        data structure.
      </t>
      <t>
        The file contains header line "-----BEGIN OpenVPN Static key V1-----", followed by each
        of the 256 bytes of the structure encodes as hexacdecimal ascii. After 16 bytes
        (32 characters in the output), a new line is started. Finally, an footer line
        "-----END OpenVPN Static key V1-----" ends the encoding of the block.
      </t>

      <figure>
        <sourcecode>
# 2048 bit encoded as a key
-----BEGIN OpenVPN Static key V1-----
112233445566778899a0b0ccd0efa1a2
[ 14 lines skipped ]
998877aaffe1838139aabbff88a2a3a6
-----END OpenVPN Static key V1-----
        </sourcecode>
        Example of a static key file.
      </figure>
      <t>
        Anything outside the header line and footer line MUST be ignored when parsing a static key
        file. Implementations SHOULD be able to handle different number of bytes per line when
        parsing the file.
      </t>
      </section>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <reference anchor="rogaway2006provable">
        <front><title>A provable-security treatment of the key-wrap problem</title><author surname="Rogaway" fullname="Phillip Rogaway" /><author surname="Shrimpton" fullname="Thomas Shrimpton" /><date year="2006" />
      </front></reference>
      <reference anchor="ferguson2005authentication"><front><title>Authentication weaknesses in GCM</title><author surname="Ferguson" fullname="Niels Ferguson" /><date year="2005" /></front></reference>
      <reference anchor="joux2006authentication"><front><title>Authentication failures in NIST version of GCM (2006)</title><author surname="Joux" fullname="Antoine Joux" /><date year="2006" /></front></reference>

      <reference anchor="nistgcm"><front><title>Sp 800-38d. recommendation for block cipher modes of operation: Galois/counter mode (gcm) and gmac</title><author surname="Dworkin" fullname="Morris J Dworkin" /><date year="2007" /></front></reference>

     <!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2104.xml"?-->
     &RFC2104;

     <!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"?-->
     &RFC2119;

     <!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml"?-->
     &RFC5246;

     <!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.5280.xml"?-->
     &RFC5280;

     <!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.5705.xml"?-->
     &RFC5705;

     <!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.8452.xml"?-->
     &RFC8452;
    </references>
  </back>
</rfc>