onc/docs/onc_spec.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="onc_spec.css" >
  <script src="onc_spec.js"></script>
  <title>Open Network Configuration Format</title>
</head>
<body>

<section id="root" class="not_in_toc">
  <h1>Open Network Configuration Format</h1>

<section class="not_in_toc">
  <h1>Outline</h1>
  <div id="outline"></div>
</section>

<section>
  <h1>Objective</h1>
  <p>
    We would like to create a simple, open, but complete format to describe
    multiple network configurations for Wi-Fi, Ethernet, Cellular,
    Bluetooth/WiFi-Direct, and VPN connections in a single file format, in order
    to simplify and automate network configuration for users.
  </p>
</section>

<section>
  <h1>Background</h1>
  <p>
    Configuring networks is a painful and error-prone experience for users. It
    is a problem shared across desktop, laptop, tablet, and phone users of all
    operating system types. It is exacerbated in business and schools which
    often have complex network configurations (VPNs and 802.1X networking) that
    change often and have many connected devices. Configuration of Wi-Fi is
    still done manually, often by administrators physically standing next to
    users working on devices. Certificate distribution is particularly painful
    which often results in admins instead using passphrases to protect networks
    or using protocols without client certificates that instead use LDAP
    passwords for authentication. Even after networks are configured, updates to
    the network configuration require another round of manual changes, and
    accidental changes by a user or malicious changes by an attacker can break
    connectivity or make connections less private or secure.
  </p>

<section>
  <h1>Overview</h1>
  <p>
    We propose a single-file format for network configuration that is
    human-readable, can describe all of the common kinds of network
    configurations, supports integrity checking, certificate and key
    provisioning, and updating. The file can be encrypted with a single
    passphrase so that upon entering the passphrase the entire configuration is
    loaded. The format can be described as an open format to enable multiple OS
    vendors to interoperate and share configuration editors.
  </p>

  <p>
    This format neither supports configuring browser settings nor allows setting
    other types of system policies.
  </p>
</section>

<section>
  <h1>Infrastructure</h1>
  <p>
    A standalone configuration editor will be created, downloadable as a Chrome
    app. This editor will allow creating, modifying, and encrypting an open
    network configuration file in a way that is intuitive for a system
    administrator.
  </p>

  <p>
    This file format may be delivered to a user and manually imported into a
    device.
  </p>

  <p>
    This file format may be created by an administrator, stored in a policy
    repository, and automatically pushed to a device.
  </p>
</section>

</section>

<section>
  <h1>Detailed Design</h1>
  <p>
    We use JSON format for the files. The fields in a JSON file are always
    case-sensitive, so the exact case of the fields in this section must be
    matched. In addition, the values that are called out as explicit constants
    must also match the case specified (e.g. WiFi must not be written as wifi,
    etc.). This document describes a minimum set of required fields and optional
    fields. Other fields may be created, however, see the
    implementation-specific fields for guidelines for these fields.
  </p>

  <p>
    The JSON consists of a top level dictionary containing
    a <span class="field">Type</span> field which must have either the
    value <span class="value">EncryptedConfiguration</span>
    or <span class="value">UnencryptedConfiguration</span>.
  </p>

  <p>
    For a description of the <span class="type">EncryptedConfiguration</span>
    type, see the section on Encrypted Configuration
    below. The <span class="type">EncryptedConfiguration</span> format encrypts
    an unencrypted JSON object.
  </p>

<section>
  <h1>GUIDs and Updating</h1>
  <p>
    This format allows for importing updated network configurations and
    certificates by providing GUIDs to each network configuration and
    certificate so they can be modified or even removed in future updates.
  </p>

  <p>
    GUIDs are non-empty strings that are meant to be stable and unique. When
    they refer to the same entity, they should be the same between ONC files. No
    two different networks or certificates should have the same GUID, similarly
    a network and certificate should not have the same GUID. A single ONC file
    should not contain the same entity twice (with the same GUID). Failing any
    of these tests indicates the ONC file is not valid.
  </p>

  <p>
    Any GUID referred to in an ONC file must be present in the same ONC file. In
    particular, it is an error to create a certificate in one ONC file and refer
    to it in a NetworkConfiguration in another ONC file and not define it there,
    even if the previous ONC file has been imported.
  </p>
</section>

<section>
  <h1>Implementation-specific fields</h1>
  <p>
    As there are many different kinds of connections and some that are not yet
    anticipated may require new fields. This format allows arbitrary other
    fields to be added.
  </p>

  <p>
    Fields and values should follow these general guidelines:
  </p>

  <ul>
    <li>
      Certificates (with and without keys) should always be placed in the
      certificate section - specifically certificate contents should not be
      placed in fields directly. Referring to certificates should be done using
      a field whose name ends in Ref and whose value is the GUID of the
      certificate, or if the certificate is not contained in this file, its
      pattern can be described using a field ending in Pattern of
      <span class="type">CertificatePattern</span> type.
    </li>
    <li>
      Fields should exist in the most-specific object in the hierarchy and
      should be named CamelCase style.
    </li>
    <li>
      Booleans and integers should be used directly instead of using a
      stringified version of the type.
    </li>
  </ul>

  <p>
    Any editor of network configuration information should allows the user to
    modify any fields that are implementation-specific. It may not be present
    directly in the UI but it should be able to import files with such settings
    and leave preserve these settings on export.
  </p>
</section>

<section>
  <h1>Unencrypted Configuration</h1>
  <p>
    When the top level <span class="field">Type</span> field
    is <span class="value">UnencryptedConfiguration</span>, the top level JSON
    has the <span class="type">UnencryptedConfiguration</span>
    type. <span class="type">UnencryptedConfiguration</span> type contains the
    following:
  </p>

  <dl class="field_list">
    <dt class="field">Type</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      Must be <span class="value">UnencryptedConfiguration</span>.
    </dd>

    <dt class="field">NetworkConfigurations</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">array of NetworkConfiguration</span>
      </span>
      Describes Wi-Fi, Ethernet, VPN, and wireless connections.
    </dd>

    <dt class="field">Certificates</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">array of Certificate</span>
      </span>
      Contains certificates stored in X.509 or PKCS#12 format.
    </dd>
  </dl>

  <p class="rule">
    <span class="rule_id"></span>
    At least one array (either <span class="field">NetworkConfigurations</span>
    and/or <span class="field">Certificates</span>) must be present.
  </p>

<section>
  <h1>Network Configuration</h1>
  <p>
    Field <span class="field">NetworkConfigurations</span> is an array
    of <span class="type">NetworkConfiguration</span> typed
    objects. The <span class="type">NetworkConfiguration</span> type contains
    the following:
  </p>

  <dl class="field_list">
    <dt class="field">Ethernet</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Type</span> is
        <span class="value">Ethernet</span>, otherwise ignored)
        <span class="type">Ethernet</span>
      </span>
      Ethernet settings.
    </dd>

    <dt class="field">GUID</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      A unique identifier for this network connection, which exists to make it
      possible to update previously imported configurations. Must be a non-empty
      string.
    </dd>

    <dt class="field">IPConfigs</dt>
    <dd>
      <span class="field_meta">
        (optional if <span class="field">Remove</span> is
        <span class="value">false</span>, otherwise ignored)
        <span class="type">array of IPConfig</span>
      </span>
      Static IPv4 or IPv6 parameters to associate with this connection.
    </dd>

    <dt class="field">Name</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Remove</span> is
        <span class="value">false</span>, otherwise ignored)
        <span class="type">string</span>
      </span>
      A user-friendly description of this connection. This name will not be used
      for referencing and may not be unique. Instead it may be used for
      describing the network to the user.
    </dd>

    <dt class="field">Remove</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">false</span>)
        <span class="type">boolean</span>
      </span>
      If set, remove this network configuration (only GUID should be set).
    </dd>

    <dt class="field">ProxySettings</dt>
    <dd>
      <span class="field_meta">
        (optional if <span class="field">Remove</span> is
        <span class="value">false</span>, otherwise ignored)
        <span class="type">ProxySettings</span>
      </span>
      Proxy settings for this network
    </dd>

    <dt class="field">NameServers</dt>
    <dd>
      <span class="field_meta">
        (optional if <span class="field">Remove</span> is
        <span class="value">false</span>, otherwise ignored)
        <span class="type">array of string</span>
      </span>
      Array of addresses to use for name servers. If not specified, DHCP values
      will be used.
    </dd>

    <dt class="field">SearchDomains</dt>
    <dd>
      <span class="field_meta">
        (optional if <span class="field">Remove</span> is
        <span class="value">false</span>, otherwise ignored)
        <span class="type">array of string</span>
      </span>
      Array of strings to append to names for resolution. Items in this array
      should not start with a dot. Example:
      <span class="snippet">["corp.acme.org", "acme.org"]</span>. If not
      specified, DHCP values will be used.
    </dd>

    <dt class="field">VPN</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Type</span> is
        <span class="value">VPN</span>, otherwise ignored)
        <span class="type">VPN</span>
      </span>
      VPN settings.
    </dd>

    <dt class="field">WiFi</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Type</span> is
        <span class="value">WiFi</span>, otherwise ignored)
        <span class="type">WiFi</span>
      </span>
      Wi-Fi settings.
    </dd>

    <dt class="field">Type</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Remove</span> is
        <span class="value">false</span>, otherwise ignored)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">Cellular</span>,
        <span class="value">Ethernet</span>, <span class="value">WiFi</span>,
        and <span class="value">VPN</span>.
      </span>
      Indicates which kind of connection this is.
    </dd>
  </dl>

<section>
  <h1>Ethernet networks</h1>
  <p>
    For Ethernet connections, <span class="field">Type</span> must be set to
    <span class="value">Ethernet</span> and the
    field <span class="field">Ethernet</span> must be set to an object of
    type <span class="type">Ethernet</span> containing the following fields:
  </p>

  <dl class="field_list">
    <dt class="field">Authentication</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">None</span> and
        <span class="value">8021X</span>.
      </span>
    </dd>

    <dt class="field">EAP</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Authentication</span> is
        <span class="value">8021X</span>, otherwise ignored)
        <span class="type">EAP</span>
      </span>
      EAP settings.
    </dd>
  </dl>
</section>

<section>
  <h1>IP Config</h1>
  <p>
    Field <span class="field">IPConfigs</span> is an array
    of <span class="type">IPConfig</span>
    objects. Each <span class="type">IPConfig</span> object describes a
    particular static IP configuration and contains the following fields:
  </p>

  <dl class="field_list">
    <dt class="field">Type</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">IPv4</span>
        and <span class="value">IPv6</span>
      </span>
      Describes the type of configuration this is.
    </dd>

    <dt class="field">IPAddress</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      Describes the IPv4 or IPv6 address of a connection, depending on the value
      of <span class="field">Type</span> field. It should not contain the
      routing prefix (i.e. should not end in something like /64).
    </dd>

    <dt class="field">RoutingPrefix</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">integer</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Must be a number in the range [1, 32] for IPv4 and [1, 128] for IPv6
        addresses.
      </span>
      Describes the routing prefix.
    </dd>

    <dt class="field">Gateway</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Describes the gateway address to use for the configuration. Must match
      address type specified in <span class="field">Type</span> field. If not
      specified, DHCP values will be used.
    </dd>

    <dt class="field">NameServers</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">array of string</span>
      </span>
      Array of addresses to use for name servers. Address format must match that
      specified in the <span class="field">Type</span> field. Overrides values
      in the top level NameServers field for this configuration. If not
      specified, top level values will be used.
    </dd>

    <dt class="field">SearchDomains</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">array of string</span>
      </span>
      Array of strings to append to names for resolution. Items in this array
      should not start with a dot. Example: <span class="snippet">[
      "corp.acme.org", "acme.org" ]</span>. Overrides values in the top level
      SearchDomains field for this configuration. If not specified, top level
      values will be used.
    </dd>
  </dl>
</section>

<section>
  <h1>Wi-Fi networks</h1>
  <p>
    For Wi-Fi connections, <span class="field">Type</span> must be set to
    <span class="value">WiFi</span> and the
    field <span class="field">WiFi</span> must be set to an object of
    type <span class="type">WiFi</span> containing the following fields:
  </p>

  <dl class="field_list">
    <dt class="field">AutoConnect</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">false</span>)
        <span class="type">boolean</span>
      </span>
      Indicating that the network should be connected to automatically when in
      range.
    </dd>

    <dt class="field">EAP</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Security</span> is
        <span class="value">WEP-8021X</span> or
        <span class="value">WPA-EAP</span>, otherwise ignored)
        <span class="type">EAP</span>
      </span>
      EAP settings.
    </dd>

    <dt class="field">HiddenSSID</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">false</span>)
        <span class="type">boolean</span>
      </span>
      Indicating if the SSID will be broadcast.
    </dd>

    <dt class="field">Passphrase</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Security</span> is
        <span class="value">WEP-PSK</span> or
        <span class="value">WPA-PSK</span>, otherwise ignored)
        <span class="type">string</span>
      </span>
      Describes the passphrase for WEP/WPA/WPA2
      connections. If <span class="value">WEP-PSK</span> is used, the passphrase
      must be of the format 0x&lt;hex-number&gt;, where &lt;hex-number&gt; is
      40, 104, 128, or 232 bits.
    </dd>

    <dt class="field">Security</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">None</span>,
        <span class="value">WEP-PSK</span>,
        <span class="value">WEP-8021X</span>,
        <span class="value">WPA-PSK</span>, and
        <span class="value">WPA-EAP</span>.
      </span>
    </dd>

    <dt class="field">SSID</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      SSID of the network.
    </dd>
  </dl>
</section>

<section>
  <h1>VPN networks</h1>
  <p>
    There are many kinds of VPNs with widely varying configuration options. We
    offer standard configuration options for a few common configurations at this
    time, and may add more later. For all others, implementation specific fields
    should be used.
  </p>

  <p>
    For VPN connections, <span class="field">Type</span> must be set
    to <span class="value">VPN</span> and the
    field <span class="field">VPN</span> must be set to an object of
    type <span class="type">VPN</span> containing the following fields:
  </p>

  <dl class="field_list">
    <dt class="field">AutoConnect</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">false</span>)
        <span class="type">boolean</span>
      </span>
      Indicating that the network should be connected to automatically.
    </dd>

    <dt class="field">Host</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Host name or IP address of server to connect to. The only scenario that
      does not require a host is a VPN that encrypts but does not tunnel
      traffic. Standalone IPsec (v1 or v2, cert or PSK based -- this is not the
      same as L2TP over IPsec) is one such setup. For all other types of VPN,
      the <span class="field">Host</span> field is required.
    </dd>

    <dt class="field">IPsec</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Type</span> is
        <span class="value">IPsec</span> or
        <span class="value">L2TP-IPsec</span>, otherwise ignored)
        <span class="type">IPsec</span>
      </span>
      IPsec layer settings.
    </dd>

    <dt class="field">L2TP</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Type</span> is
        <span class="value">L2TP-IPsec</span>, otherwise ignored)
        <span class="type">L2TP</span>
      </span>
      L2TP layer settings.
    </dd>

    <dt class="field">OpenVPN</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Type</span> is
        <span class="value">OpenVPN</span>, otherwise ignored)
        <span class="type">OpenVPN</span>
      </span>
      OpenVPN settings.
    </dd>

    <dt class="field">Type</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">IPsec</span>,
        <span class="value">L2TP-IPsec</span>, and
        <span class="value">OpenVPN</span>.
      </span>
      Type of the VPN.
    </dd>
  </dl>

  <section>
    <h1>IPsec-based VPN types</h1>
    <p>
      The <span class="type">IPsec</span> type contains the following:
    </p>

    <dl class="field_list">
      <dt class="field">AuthenticationType</dt>
      <dd>
        <span class="field_meta">
          (required)
          <span class="type">string</span>
        </span>
        <span class="rule">
          <span class="rule_id"></span>
          Allowed values are <span class="value">PSK</span> and
          <span class="value">Cert</span>. If <span class="value">Cert</span> is used, <span class="field">ClientCertType</span> and <span class="field">ServerCARefs</span> (or the deprecated <span class="field">ServerCARef</span>) must be set.
        </span>
      </dd>

      <dt class="field">ClientCertPattern</dt>
      <dd>
        <span class="field_meta">
          (required if <span class="field">ClientCertType</span>
          is <span class="value">Pattern</span>, otherwise ignored)
          <span class="type">CertificatePattern</span>
        </span>
        Pattern describing the client certificate.
      </dd>

      <dt class="field">ClientCertRef</dt>
      <dd>
        <span class="field_meta">
          (required if <span class="field">ClientCertType</span>
          is <span class="value">Ref</span>, otherwise ignored)
          <span class="type">string</span>
        </span>
        Reference to client certificate stored in certificate section.
      </dd>

      <dt class="field">ClientCertType</dt>
      <dd>
        <span class="field_meta">
          (required if <span class="field">AuthenticationType</span>
          is <span class="value">Cert</span>, otherwise ignored)
          <span class="type">string</span>
        </span>
        <span class="rule">
          <span class="rule_id"></span>
          Allowed values are <span class="value">Ref</span> and
          <span class="value">Pattern</span>
        </span>
      </dd>

      <dt class="field">EAP</dt>
      <dd>
        <span class="field_meta">
          (optional if <span class="field">IKEVersion</span> is 2, otherwise
          ignored)
          <span class="type">EAP</span>
        </span>
        Indicating that EAP authentication should be used with the provided
        parameters.
      </dd>

      <dt class="field">Group</dt>
      <dd>
        <span class="field_meta">
          (optional if <span class="field">IKEVersion</span> is 1, otherwise
          ignored)
          <span class="type">string</span>
        </span>
        Group name used for machine authentication.
      </dd>

      <dt class="field">IKEVersion</dt>
      <dd>
        <span class="field_meta">
          (required)
          <span class="type">integer</span>
        </span>
        Version of IKE protocol to use.
      </dd>

      <dt class="field">PSK</dt>
      <dd>
        <span class="field_meta">
          (optional if <span class="field">AuthenticationType</span>
          is <span class="value">PSK</span>, otherwise ignored)
          <span class="type">string</span>
        </span>
        Pre-Shared Key. If not specified, user is prompted at time of
        connection.
      </dd>

      <dt class="field">SaveCredentials</dt>
      <dd>
        <span class="field_meta">
          (optional if <span class="field">AuthenticationType</span>
          is <span class="value">PSK</span>, otherwise ignored, defaults
          to <span class="value">false</span>)
          <span class="type">boolean</span>
        </span>
        If <span class="value">false</span>, require user to enter credentials
        (PSK) each time they connect.
      </dd>

      <dt class="field">ServerCARefs</dt>
      <dd>
        <span class="field_meta">
          (optional if <span class="field">AuthenticationType</span>
          is <span class="value">Cert</span>, otherwise rejected)
          <span class="type">array of string</span>
        </span>
        Non-empty list of references to CA certificates in <span class="field">Certificates</span> to be used for verifying the host's certificate chain. At least one of the CA certificates must match. If this field is set, <span class="field">ServerCARef</span> must be unset.
      </dd>

      <dt class="field">ServerCARef</dt>
      <dd>
        <span class="field_meta">
          (optional if <span class="field">AuthenticationType</span>
          is <span class="value">Cert</span>, otherwise rejected)
          <span class="type">string</span>
        </span>
        DEPRECATED, use <span class="field">ServerCARefs</span> instead.<br/>
        Reference to a CA certificate in <span class="field">Certificates</span>. Certificate authority to use for verifying connection. If this field is set, <span class="field">ServerCARefs</span> must be unset.
      </dd>

      <dt class="field">XAUTH</dt>
      <dd>
        <span class="field_meta">
          (optional if <span class="field">IKEVersion</span> is 1, otherwise
          ignored)
          <span class="type">XAUTH</span>
        </span>
        Describing XAUTH credentials. XAUTH is not used if this object is not
        present.
      </dd>
    </dl>

    <p class="rule">
      <span class="rule_id"></span>
      If <span class="field">AuthenticationType</span> is set to <span class="value">Cert</span>, <span class="field">ServerCARefs</span> or <span class="field">ServerCARef</span> must be set.
    </p>

    <p class="rule">
      <span class="rule_id"></span>
      At most one of <span class="field">ServerCARefs</span> and <span class="field">ServerCARef</span> can be set.
    </p>

    <p>
      <span class="type">L2TP</span> type contains the following:
    </p>

    <dl class="field_list">
      <dt class="field">Password</dt>
      <dd>
        <span class="field_meta">
          (optional)
          <span class="type">string</span>
        </span>
        User authentication password. If not specified, user is prompted at time
        of connection.
      </dd>

      <dt class="field">SaveCredentials</dt>
      <dd>
        <span class="field_meta">
          (optional, defaults to <span class="value">false</span>)
          <span class="type">boolean</span>
        </span>
        If <span class="value">false</span>, require user to enter credentials
        each time they connect.
      </dd>

      <dt class="field">Username</dt>
      <dd>
        <span class="field_meta">
          (optional)
          <span class="type">string</span>
        </span>
        User identity. This value is subject to string expansions. If not
        specified, user is prompted at time of connection.
      </dd>
    </dl>

    <p>
      <span class="type">XAUTH</span> type contains the following:
    </p>

    <dl class="field_list">
      <dt class="field">Password</dt>
      <dd>
        <span class="field_meta">
          (optional)
          <span class="type">string</span>
        </span>
        XAUTH password. If not specified, user is prompted at time of
        connection.
      </dd>

      <dt class="field">SaveCredentials</dt>
      <dd>
        <span class="field_meta">
          (optional, defaults to <span class="value">false</span>)
          <span class="type">boolean</span>
        </span>
        If <span class="value">false</span>, require user to enter credentials
        each time they connect.
      </dd>

      <dt class="field">Username</dt>
      <dd>
        <span class="field_meta">
          (optional)
          <span class="type">string</span>
        </span>
        XAUTH user name. This value is subject to string expansions. If not
        specified, user is prompted at time of connection.
      </dd>
    </dl>

<section>
  <h1>IPsec IKE v1 VPN connections</h1>
  <p>
    <span class="field">VPN.Type</span> must
    be <span class="value">IPsec</span>, <span class="field">IKEVersion</span>
    must be 1. Do not use this for L2TP over IPsec. This may be used for
    machine-authentication-only IKEv1 or for IKEv1 with XAUTH. See
    the <span class="type">IPsec</span> type described below.
  </p>
</section>

<section>
  <h1>IPsec IKE v2 VPN connections</h1>
  <p>
    <span class="field">VPN.Type</span> must
    be <span class="value">IPsec</span>, <span class="field">IKEVersion</span>
    must be 2. This may be used with EAP-based user authentication.
  </p>
</section>

<section>
  <h1>L2TP over IPsec VPN connections</h1>
  <p>
    There are two major configurations L2TP over IPsec which depend on how IPsec
    is authenticated. In either case <span class="field">Type</span> must be
    <span class="value">L2TP-IPsec</span>. They are described below.
  </p>

  <p>
    L2TP over IPsec with pre-shared key:
  </p>

  <ul>
    <li>The field <span class="field">IPsec</span> must be present and have the
    following settings:
      <ul>
        <li><span class="field">IKEVersion</span> must be 1.</li>
        <li><span class="field">AuthenticationType</span> must be PSK.</li>
        <li><span class="field">XAUTH</span> must not be set.</li>
      </ul>
    </li>
    <li>The field <span class="field">L2TP</span> must be present.</li>
  </ul>
</section>

</section>

<section>
  <h1>OpenVPN connections and types</h1>
  <p>
    <span class="field">VPN.Type</span> must be
    <span class="value">OpenVPN</span>.
  </p>

  <p>
    <span class="type">OpenVPN</span> type contains the following:
  </p>

  <dl class="field_list">
    <dt class="field">Auth</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">SHA1</span>)
        <span class="type">string</span>
      </span>
    </dd>

    <dt class="field">AuthRetry</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">none</span>)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">none</span>,
        <span class="value">nointeract</span>, and
        <span class="value">interact</span>.
      </span>
      Controls how OpenVPN responds to username/password verification
      errors:<br> Either fail with error on retry
      (<span class="value">none</span>), retry without asking for authentication
      (<span class="value">nointeract</span>), or ask again for authentication
      each time (<span class="value">interact</span>).
    </dd>

    <dt class="field">AuthNoCache</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">false</span>)
        <span class="type">boolean</span>
      </span>
      Disable caching of credentials in memory.
    </dd>

    <dt class="field">Cipher</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">BF-CBC</span>)
        <span class="type">string</span>
      </span>
      Cipher to use.
    </dd>

    <dt class="field">ClientCertRef</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">ClientCertType</span> is
        <span class="value">Ref</span>, otherwise ignored)
        <span class="type">string</span>
      </span>
      Reference to client certificate stored in certificate section.
    </dd>

    <dt class="field">ClientCertPattern</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">ClientCertType</span> is
        <span class="value">Pattern</span>, otherwise ignored)
        <span class="type">CertificatePattern</span>
      </span>
      Pattern to use to find the client certificate.
    </dd>

    <dt class="field">ClientCertType</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">Ref</span>,
        <span class="value">Pattern</span>, and <span class="value">None</span>.
      </span>
      <span class="value">None</span> implies that the server is configured to
      not require client certificates.
    </dd>

    <dt class="field">CompLZO</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">adaptive</span>)
        <span class="type">string</span>
      </span>
      Decides to fast LZO compression with <span class="value">true</span>
      and <span class="value">false</span> as other values.
    </dd>

    <dt class="field">CompNoAdapt</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">false</span>)
        <span class="type">boolean</span>
      </span>
      Disables adaptive compression.
    </dd>

    <dt class="field">KeyDirection</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Passed as --key-direction.
    </dd>

    <dt class="field">NsCertType</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      If set, checks peer certificate type. Should only be set
      to <span class="value">server</span> if set.
    </dd>

    <dt class="field">Password</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      XAUTH password. If not specified, user is prompted at time of connection.
    </dd>

    <dt class="field">Port</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">1194</span>)
        <span class="type">integer</span>
      </span>
      Port for connecting to server.
    </dd>

    <dt class="field">Proto</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">udp</span>)
        <span class="type">string</span>
      </span>
      Protocol for communicating with server.
    </dd>

    <dt class="field">PushPeerInfo</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">false</span>)
        <span class="type">boolean</span>
      </span>
    </dd>

    <dt class="field">RemoteCertEKU</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Require that the peer certificate was signed with this explicit extended
      key usage in oid notation.
    </dd>

    <dt class="field">RemoteCertKU</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to [])
        <span class="type">array of string</span>
      </span>
      Require the given array of key usage numbers. These are strings that are
      hex encoded numbers.
    </dd>

    <dt class="field">RemoteCertTLS</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">server</span>)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">none</span> and
        <span class="value">server</span>.
      </span>
      Require peer certificate signing based on RFC3280 TLS rules.
    </dd>

    <dt class="field">RenegSec</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">3600</span>)
        <span class="type">integer</span>
      </span>
      Renegotiate data channel key after this number of seconds.
    </dd>

    <dt class="field">SaveCredentials</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">false</span>)
        <span class="type">boolean</span>
      </span>
      If <span class="value">false</span>, require user to enter credentials
      each time they connect.
    </dd>

    <dt class="field">ServerCARefs</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">array of string</span>
      </span>
      Non-empty list of references to CA certificates in <span class="field">Certificates</span> to be used for verifying the host's certificate chain. At least one of the CA certificates must match. See also OpenVPN's command line option "--ca". If this field is set, <span class="field">ServerCARef</span> must be unset.
    </dd>

    <dt class="field">ServerCARef</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      DEPRECATED, use <span class="field">ServerCARefs</span> instead.<br/>
      Reference to a CA certificate in <span class="field">Certificates</span>. Certificate authority to use for verifying connection. If this field is set, <span class="field">ServerCARefs</span> must be unset.
    </dd>

    <dt class="field">ServerCertRef</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Reference to a certificate. Peer's signed certificate.
    </dd>

    <dt class="field">ServerPollTimeout</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">integer</span>
      </span>
      Spend no more than this number of seconds before trying the next server.
    </dd>

    <dt class="field">Shaper</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">integer</span>
      </span>
      If not specified no bandwidth limiting, otherwise limit bandwidth of
      outgoing tunnel data to this number of bytes per second.
    </dd>

    <dt class="field">StaticChallenge</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      String is used in static challenge response. Note that echoing is always
      done.
    </dd>

    <dt class="field">TLSAuthContents</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      If not set, tls auth is not used. If set, this is the TLS Auth key
      contents (usually starts with "-----BEGIN OpenVPN Static Key..."
    </dd>

    <dt class="field">TLSRemote</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      If set, only allow connections to server hosts with X509 name or common
      name equal to this string.
    </dd>

    <dt class="field">Username</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      OpenVPN user name. This value is subject to string expansions. If not
      specified, user is prompted at time of connection.
    </dd>

    <dt class="field">Verb</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Verbosity level, defaults to OpenVpn's default if not specified.
    </dd>

    <dt class="field">VerifyHash</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      If set, this value is passed as the "--verify-hash" argument to OpenVPN,
      which specifies the SHA1 fingerprint for the level-1 certificate.
    </dd>

    <dt class="field">VerifyX509</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">VerifyX509</span>
      </span>
       If set, the "--verify-x509-name" argument is passed to OpenVPN with the values of this object and only connections will be accepted if a host's X.509 name is equal to the given name.
    </dd>
  </dl>

  <p class="rule">
    <span class="rule_id"></span>
    At most one of <span class="field">ServerCARefs</span> and <span class="field">ServerCARef</span> can be set.
  </p>

  <p>
    <span class="type">VerifyX509</span> type contains the following:
  </p>
  <dl class="field_list">
    <dt class="field">Name</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      The name that the host's X.509 name is compared to. Which host name is compared depends on the value of <span class="field">Type</span>.
    </dd>

    <dt class="field">Type</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Determines which of the host's X.509 names will be verified. Allowed values are <span class="value">name</span>, <span class="value">name-prefix</span> and <span class="value">subject</span>. See OpenVPN's documentation for "--verify-x509-name" for the meaning of each value. Defaults to OpenVPN's default if not specified.
    </dd>
  </dl>

</section>

</section>

<section>
  <h1>Client certificate patterns</h1>
  <p>
    In order to allow clients to securely key their private keys and request
    certificates through PKCS#10 format or through a web flow, we provide
    alternative CertificatePattern types. The
    <span class="type">CertificatePattern</span> type contains the following:
  </p>

  <dl class="field_list">
    <dt class="field">IssuerCARef</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">array of string</span>
      </span>
      Array of references to certificates. At least one must have signed the
      client certificate.
    </dd>

    <dt class="field">Issuer</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">IssuerSubjectPattern</span>
      </span>
      Pattern to match the issuer X.509 settings against. If not specified, the
      only checks done will be a signature check against
      the <span class="field">IssuerCARef</span> field. Issuer of the
      certificate must match this field exactly to match the pattern.
    </dd>

    <dt class="field">Subject</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">IssuerSubjectPattern</span>
      </span>
      Pattern to match the subject X.509 settings against. If not specified, the
      subject settings are not checked and any certificate matches. Subject of
      the certificate must match this field exactly to match the pattern.
    </dd>

    <dt class="field">EnrollmentURI</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">array of string</span>
      </span>
      If no certificate matches this CertificatePattern, the first URI from this
      array with a recognized scheme is navigated to, with the intention this
      informs the user how to either get the certificate or gets the certificate
      for the user. For instance, the array may be [
      "chrome-extension://asakgksjssjwwkeielsjs/fetch-client-cert.html",
      "http://intra/connecting-to-wireless.html" ] so that for Chrome browsers a
      Chrome app or extension is shown to the user, but for other browsers, a
      web URL is shown.
    </dd>
  </dl>

  <p>
    The <span class="type">IssuerSubjectPattern</span> type contains the
    following:
  </p>

  <dl class="field_list">
    <dt class="field">CommonName</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Certificate subject's commonName must match this string if present.
    </dd>

    <dt class="field">Locality</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Certificate subject's location must match this string if present.
    </dd>

    <dt class="field">Organization</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      At least one of certificate subject's organizations must match this string
      if present.
    </dd>

    <dt class="field">OrganizationalUnit</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      At least one of certificate subject's organizational units must match this
      string if present.
    </dd>
  </dl>

  <p class="rule">
    <span class="rule_id"></span>
    One field in <span class="field">Subject</span>,
    <span class="field">Issuer</span>, or <span class="field">IssuerCARef</span>
    must be given for a <span class="type">CertificatePattern</span> typed field
    to be valid.
  </p>

  <p>
    For a certificate to be considered matching, it must match all
    the fields in the certificate pattern. If multiple certificates match, the
    certificate with the latest issue date that is still in the past, and hence
    valid, will be used.
  </p>

  <p>
    If <span class="field">EnrollmentURI</span> is not given and no match is
    found to this pattern, the importing tool may show an error to the user.
  </p>
</section>

<section>
  <h1>Proxy settings</h1>
  <p>
    Every network can be configured to use a
    proxy. The <span class="type">ProxySettings</span> type contains the
    following:
  </p>

  <dl class="field_list">
    <dt class="field">Type</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">Direct</span>,
        <span class="value">Manual</span>, <span class="value">PAC</span>, and
        <span class="value">WPAD</span>.
      </span>
      <span class="value">PAC</span> indicates Proxy Auto-Configuration.
      <span class="value">WPAD</span> indicates Web Proxy Autodiscovery.
    </dd>

    <dt class="field">Manual</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Type</span>
        is <span class="value">Manual</span>, otherwise ignored)
        <span class="type">ManualProxySettings</span>
      </span>
      Manual proxy settings.
    </dd>

    <dt class="field">ExcludeDomains</dt>
    <dd>
      <span class="field_meta">
        (optional if <span class="field">Type</span>
        is <span class="value">Manual</span>, otherwise ignored)
        <span class="type">array of string</span>
      </span>
      Domains and hosts for which to exclude proxy settings.
    </dd>

    <dt class="field">PAC</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Type</span> is
        <span class="value">PAC</span>, otherwise ignored)
        <span class="type">string</span>
      </span>
      URL of proxy auto-config file.
    </dd>
  </dl>

  <p>
    The <span class="type">ManualProxySettings</span> type contains the
    following:
  </p>

  <dl class="field_list">
    <dt class="field">HTTPProxy</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">ProxyLocation</span>
      </span>
      settings for HTTP proxy.
    </dd>

    <dt class="field">SecureHTTPProxy</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">ProxyLocation</span>
      </span>
      settings for secure HTTP proxy.
    </dd>

    <dt class="field">FTPProxy</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">ProxyLocation</span>
      </span>
      settings for FTP proxy
    </dd>

    <dt class="field">SOCKS</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">ProxyLocation</span>
      </span>
      settings for SOCKS proxy.
    </dd>
  </dl>

  <p>
    The <span class="type">ProxyLocation</span> type contains the following:
  </p>

  <dl class="field_list">
    <dt class="field">Host</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      Host (or IP address) to use for proxy
    </dd>

    <dt class="field">Port</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">integer</span>
      </span>
      Port to use for proxy
    </dd>
  </dl>
</section>

<section>
  <h1>EAP configurations</h1>
  <p>
    For networks with 802.1X authentication, an <span class="type">EAP</span>
    type exists to configure the
    authentication. The <span class="type">EAP</span> type contains the
    following:
  </p>

  <dl class="field_list">
    <dt class="field">AnonymousIdentity</dt>
    <dd>
      <span class="field_meta">
        (optional if <span class="field">Outer</span> is
        <span class="value">PEAP</span> or <span class="value">EAP-TTLS</span>,
        otherwise ignored)
        <span class="type">string</span>
      </span>
      For tunnelling protocols only, this indicates the identity of the user
      presented to the outer protocol. This value is subject to string
      expansions. If not specified, use empty string.
    </dd>

    <dt class="field">ClientCertPattern</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">ClientCertType</span> is
        <span class="value">Pattern</span>, otherwise ignored)
        <span class="type">CertificatePattern</span>
      </span>
      Pattern to use to find the client certificate.
    </dd>

    <dt class="field">ClientCertRef</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">ClientCertType</span> is
        <span class="value">Ref</span>, otherwise ignored)
        <span class="type">string</span>
      </span>
      Reference to client certificate stored in certificate section.
    </dd>

    <dt class="field">ClientCertType</dt>
    <dd>
      <span class="field_meta">
        (optional) <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">Ref</span>, and
        <span class="value">Pattern</span>.
      </span>
    </dd>

    <dt class="field">Identity</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Identity of user. For tunneling outer protocols
      (<span class="value">PEAP</span>, <span class="value">EAP-TTLS</span>, and
      <span class="value">EAP-FAST</span>), this is used to authenticate inside
      the tunnel, and <span class="field">AnonymousIdentity</span> is used for
      the EAP identity outside the tunnel. For non-tunneling outer protocols,
      this is used for the EAP identity. This value is subject to string
      expansions.
    </dd>

    <dt class="field">Inner</dt>
    <dd>
      <span class="field_meta">
        (optional if <span class="field">Outer</span> is
        <span class="value">EAP-FAST</span>, <span class="value">EAP-TTLS</span>
        or <span class="value">PEAP</span>, otherwise ignored, defaults to
        <span class="value">Automatic</span>)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">Automatic</span>,
        <span class="value">MD5</span>, <span class="value">MSCHAPv2</span>,
        <span class="value">EAP-MSCHAPv2</span>, and
        <span class="value">PAP</span>.
      </span>
      For tunneling outer protocols.
    </dd>

    <dt class="field">Outer</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">LEAP</span>,
        <span class="value">EAP-AKA</span>, <span class="value">EAP-FAST</span>,
        <span class="value">EAP-TLS</span>, <span class="value">EAP-TTLS</span>,
        <span class="value">EAP-SIM</span> and <span class="value">PEAP</span>.
      </span>
    </dd>

    <dt class="field">Password</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      Password of user. If not specified, defaults to prompting the user.
    </dd>

    <dt class="field">SaveCredentials</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">false</span>)
        <span class="type">boolean</span>
      </span>
      If <span class="value">false</span>, require user to enter credentials
      each time they connect. Specifying <span class="field">Identity</span>
      and/or <span class="field">Password</span> when
      <span class="field">SaveCredentials</span> is
      <span class="value">false</span> is not allowed.
    </dd>

    <dt class="field">ServerCARefs</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">array of string</span>
      </span>
      Non-empty list of references to CA certificates in <span class="field">Certificates</span> to be used for verifying the host's certificate chain. At least one of the CA certificates must match. If this field is set, <span class="field">ServerCARef</span> must be unset. If neither <span class="field">ServerCARefs</span> nor <span class="field">ServerCARef</span> is set, the client does not check that the server certificate is signed by a specific CA. A verification using the system's CA certificates may still apply. See <span class="field">UseSystemCAs</span> for this.
    </dd>

    <dt class="field">ServerCARef</dt>
    <dd>
      <span class="field_meta">
        (optional)
        <span class="type">string</span>
      </span>
      DEPRECATED, use <span class="field">ServerCARefs</span> instead.<br/>
      Reference to a CA certificate in <span class="field">Certificates</span>. If this field is set, <span class="field">ServerCARefs</span> must be unset. If neither <span class="field">ServerCARefs</span> nor <span class="field">ServerCARef</span> is set, the client does not check that the server certificate is signed by a specific CA. A verification using the system's CA certificates may still apply. See <span class="field">UseSystemCAs</span> for this.
    </dd>

    <dt class="field">UseSystemCAs</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">true</span>)
        <span class="type">boolean</span>
      </span>
      Required server certificate to be signed by "system default certificate
      authorities". If both <span class="field">ServerCARefs</span> (or <span class="field">ServerCARef</span>)
      and <span class="field">UseSystemCAs</span> are supplied, a server
      certificate will be allowed if it either has a chain of trust to a system
      CA or to one of the given CA certificates. If <span class="field">UseSystemCAs</span>
      is <span class="value">false</span>, and no <span class="field">ServerCARef</span> is set, the certificate
      must be a self signed certificate, and no CA signature is required.
    </dd>
  </dl>

  <p class="rule">
    <span class="rule_id"></span>
    At most one of <span class="field">ServerCARefs</span> and <span class="field">ServerCARef</span> can be set.
  </p>
</section>

<section>
  <h1>Cellular Networks</h1>
  <p>
    This format will eventually also cover configuration of cellular network
    technologies, however they are currently not supported.
  </p>
</section>

<section>
  <h1>Bluetooth / WiFi Direct Networks</h1>
  <p>
    This format will eventually also cover configuration of Bluetooth and Wi-Fi
    Direct network technologies, however they are currently not supported.
  </p>
</section>

</section>

<section>
  <h1>Certificates</h1>
  <p>
    Certificate data is stored in a separate section. Each certificate may be
    referenced from within the NetworkConfigurations array using a certificate
    reference. A certificate reference is its GUID.
  </p>

  <p>
    The top-level field <span class="field">Certificates</span> is an array of
    objects of <span class="type">Certificate</span> type.
  </p>

  <p>
    The <span class="type">Certificate</span> type contains the following:
  </p>

  <dl class="field_list">
    <dt class="field">GUID</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      A unique identifier for this certificate. Must be a non-empty string.
    </dd>

    <dt class="field">PKCS12</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Type</span> is
        <span class="value">Client</span>, otherwise ignored)
        <span class="type">string</span>
      </span> For certificates with
      private keys, this is the base64 encoding of the a PKCS#12 file.
    </dd>

    <dt class="field">Remove</dt>
    <dd>
      <span class="field_meta">
        (optional, defaults to <span class="value">false</span>)
        <span class="type">boolean</span>
      </span>
      If <span class="value">true</span>, remove this certificate (only GUID
      should be set).
    </dd>

    <dt class="field">TrustBits</dt>
    <dd>
      <span class="field_meta">
        (optional if <span class="field">Type</span>
        is <span class="value">Server</span>
        or <span class="value">Authority</span>, otherwise ignored, defaults to
        [])
        <span class="type">array of string</span>
      </span>
      An array of trust flags. Clients should ignore unknown flags. For
      backwards compatibility, each flag should only increase the trust and
      never restrict. The trust flag <span class="value">Web</span> implies that
      the certificate is to be trusted for HTTPS SSL identification. A typical
      web certificate authority would have <span class="field">Type</span> set
      to <span class="value">Authority</span> and
      <span class="field">TrustBits</span> set to
      <span class="snippet">["Web"]</span>.
    </dd>

    <dt class="field">Type</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Remove</span> is
        <span class="value">false</span>, otherwise ignored)
        <span class="type">string</span>
      </span>
      <span class="rule">
        <span class="rule_id"></span>
        Allowed values are <span class="value">Client</span>,
        <span class="value">Server</span>, and
        <span class="value">Authority</span>.
      </span>
      <span class="value">Client</span> indicates the certificate is for
      identifying the user or device over HTTPS or for
      VPN/802.1X. <span class="value">Server</span> indicates the certificate
      identifies an HTTPS or VPN/802.1X peer.
      <span class="value">Authority</span> indicates the certificate is a
      certificate authority and any certificates it issues should be
      trusted. Note that if <span class="field">Type</span> disagrees with the
      x509 v3 basic constraints or key usage attributes, the
      <span class="field">Type</span> field should be honored.
    </dd>

    <dt class="field">X509</dt>
    <dd>
      <span class="field_meta">
        (required if <span class="field">Type</span> is
        <span class="value">Server</span> or
        <span class="value">Authority</span>, otherwise ignored)
        <span class="type">string</span>
      </span> For certificate
      without private keys, this is the X509 certificate in PEM format.
    </dd>
  </dl>

  <p>
    The passphrase of the PKCS#12 encoding must be empty. Encryption of key data
    should be handled at the level of the entire file, or the transport of the
    file.
  </p>

  <p>
    If a global-scoped network connection refers to a user-scoped certificate,
    results are undefined, so this configuration should be prohibited by the
    configuration editor.
  </p>
</section>

</section>

<section>
  <h1>Encrypted Configuration</h1>
  <p>
    We assume that when this format is imported as part of policy that
    file-level encryption will not be necessary because the policy transport is
    already encrypted, but when it is imported as a standalone file, it is
    desirable to encrypt it. Since this file has private information (user
    names) and secrets (passphrases and private keys) in it, and we want it to
    be usable as a manual way to distribute network configuration, we must
    support encryption.
  </p>

  <p>
    For this standalone export, the entire file will be encrypted in a symmetric
    fashion with a passphrase stretched using salted PBKDF2 using at least 20000
    iterations, and encrypted using an AES-256 CBC mode cipher with an SHA-1
    HMAC on the ciphertext.
  </p>

  <p>
    An encrypted ONC file's top level object will have the
    <span class="type">EncryptedConfiguration</span>
    type. <span class="type">EncryptedConfiguration</span> type contains the
    following:
  </p>

  <dl class="field_list">
    <dt class="field">Cipher</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      The type of cipher used. Currently only <span class="value">AES256</span>
      is supported.
    </dd>

    <dt class="field">Ciphertext</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      The raw ciphertext of the encrypted ONC file, base64 encoded.
    </dd>

    <dt class="field">HMAC</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      The HMAC for the ciphertext, base64 encoded.
    </dd>

    <dt class="field">HMACMethod</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      The method used to compute the Hash-based Message Authentication Code
      (HMAC). Currently only <span class="value">SHA1</span> is supported.
    </dd>

    <dt class="field">Salt</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      The salt value used during key stretching.
    </dd>

    <dt class="field">Stretch</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      The key stretching algorithm used. Currently
      only <span class="value">PBKDF2</span> is supported.
    </dd>

    <dt class="field">Iterations</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">integer</span>
      </span>
      The number of iterations to use during key stretching.
    </dd>

    <dt class="field">IV</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      The initial vector (IV) used for Cyclic Block Cipher (CBC) mode, base64
      encoded.
    </dd>

    <dt class="field">Type</dt>
    <dd>
      <span class="field_meta">
        (required)
        <span class="type">string</span>
      </span>
      The type of the ONC file, which must be set
      to <span class="value">EncryptedConfiguration</span>.
    </dd>
  </dl>

  <p class="rule">
    <span class="rule_id"></span>
    When decrypted, the ciphertext must contain a JSON object of
    type <span class="type">UnencryptedConfiguration</span>.
  </p>
</section>

<section>
  <h1>String Expansions</h1>
  <p>
    The values of some fields, such
    as <span class="field">WiFi.EAP.Identity</span>
    and <span class="field">VPN.*.Username</span>, are subject to string
    expansions. These allow one ONC to have basic user-specific variations.
  </p>

  <p>
    The expansions are:
  </p>

  <ul>
    <li>
      ${LOGIN_ID} - expands to the email address of the user, but before the
      '@'.
    </li>
    <li>
      ${LOGIN_EMAIL} - expands to the email address of the user.
    </li>
  </ul>

  <p>
    The following SED would properly handle resolution.
  </p>

  <ul>
    <li>
      s/\$\{LOGIN_ID\}/bobquail$1/g
    </li>
    <li>
      s/\$\{LOGIN_EMAIL\}/bobquail@example.com$1/g
    </li>
  </ul>

  <p>
    Example expansions, assuming the user was bobquail@example.com:
  </p>

  <ul>
    <li>
      "${LOGIN_ID}" -> "bobquail"
    </li>
    <li>
      "${LOGIN_ID}@corp.example.com" -> "bobquail@corp.example.com"
    </li>
    <li>
      "${LOGIN_EMAIL}" -> "bobquail@example.com"
    </li>
    <li>
      "${LOGIN_ID}X" -> "bobquailX"
    </li>
    <li>
      "${LOGIN_IDX}" -> "${LOGIN_IDX}"
    </li>
    <li>
      "X${LOGIN_ID}" -> "Xbobquail"
    </li>
  </ul>
</section>

<section>
  <h1>Detection</h1>
  <p>
    This format should be sent in files ending in the .onc extension. When
    transmitted with a MIME type, the MIME type should be
    application/x-onc. These two methods make detection of data to be handled in
    this format, especially when encryption is used and the payload itself is
    not detectable.
  </p>
</section>

</section>

<section>
  <h1>Alternatives considered</h1>
  <p>
    For the overall format, we considered XML, ASN.1, and protobufs. JSON and
    ASN.1 seem more widely known than protobufs. Since administrators are
    likely to want to tweak settings that will not exist in common UIs, we
    should provide a format that is well known and human modifiable. ASN.1 is
    not human modifiable. Protobufs formats are known by open source developers
    but seem less likely to be known by administrators. JSON serialization
    seems to have good support across languages.
  </p>

  <p>
    We considered sending the exact connection manager configuration format of
    an open source connection manager like connman. There are a few issues
    here, for instance, referencing certificates by identifiers not tied to a
    particular PKCS#11 token, and tying to one OS's connection manager.
  </p>
</section>

<section>
  <h1>Detection</h1>
  <p>
    This format should be sent in files ending in the .onc extension. When
    transmitted with a MIME type, the MIME type should be
    application/x-onc. These two methods make detection of data to be handled in
    this format, especially when encryption is used and the payload itself is
    not detectable.
  </p>
</section>

<section>
  <h1>Mocks</h1>

<section>
  <h1>Simple format example: PEAP/MSCHAPv2 network (per device)</h1>

  <pre>
{
  "Type": "UnencryptedConfiguration",
  "NetworkConfigurations": [
    {
      "GUID": "{f2c17903-b0e1-8593-b3ca74f977236bd7}",
      "Name": "MySSID",
      "Type": "WiFi",
      "WiFi": {
        "AutoConnect": true,
        "EAP": {
          "Outer": "PEAP",
          "UseSystemCAs": true
        },
        "HiddenSSID": false,
        "SSID": "MySSID",
        "Security": "WPA-EAP"
      }
    }
  ],
  "Certificates": []
}
  </pre>

  <p>
    Notice that in this case, we do not provide a username and password - we set
    SaveCredentials to <span class="value">false</span> so we are prompted every
    time. We could have passed in username and password - but such a file should
    be encrypted.
  </p>
</section>

<section>
  <h1>Complex format example: TLS network with client certs (per device)</h1>

  <pre>
{
  "Type": "UnencryptedConfiguration",
  "NetworkConfigurations": [
    {
      "GUID": "{00f79111-51e0-e6e0-76b3b55450d80a1b}",
      "Name": "MyTTLSNetwork",
      "Type": "WiFi",
      "WiFi": {
        "AutoConnect": false,
        "EAP": {
          "ClientCertPattern": {
            "EnrollmentURI": [
              "http://fetch-my-certificate.com"
            ],
            "IssuerCARef": [
              "{6ed8dce9-64c8-d568-d225d7e467e37828}"
            ]
          },
          "ClientCertType": "Pattern",
          "Outer": "EAP-TLS",
          "ServerCARef": "{6ed8dce9-64c8-d568-d225d7e467e37828}",
          "UseSystemCAs": true
        },
        "HiddenSSID": false,
        "SSID": "MyTTLSNetwork",
        "Security": "WPA-EAP"
      }
    }
  ],
  "Certificates": [
    {
      "GUID": "{6ed8dce9-64c8-d568-d225d7e467e37828}",
      "Type": "Authority",
      "X509": "MIIEpzCCA4+gAwIBAgIJAMueiWq5WEIAMA0GCSqGSIb3DQEBBQUAMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTExMDEyODA2MjA0MFoXDTEyMDEyODA2MjA0MFowgZMxCzAJBgNVBAYTAkZSMQ8wDQYDVQQIEwZSYWRpdXMxEjAQBgNVBAcTCVNvbWV3aGVyZTEVMBMGA1UEChMMRXhhbXBsZSBJbmMuMSAwHgYJKoZIhvcNAQkBFhFhZG1pbkBleGFtcGxlLmNvbTEmMCQGA1UEAxMdRXhhbXBsZSBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9EDplhyrVNJIoy1OsVqvD/K67B5PW2bDKKxGznodrzCu8jHsP1Ne3mgrK20vbzQUUBdmxTCWO6x3a3//r4ZuPOuZd1ViycWjt6mRfRbBzNrHzP7NiyFuXjdlz74beHQQLcHwvZ3qFAWZK37uweiLiDPaMaEQlka2Bztqx4PsogmSdoVPSCxi5Cl1XlJmITA03LlKpO79+0rEPRamWO/DMCwvffn2/UUjJLog4/lYe16HQ6iq/6bjhffm2rLXDFKOGZmBVbLNMCfANRMtdFWHYdBXERoUo2zpM9tduOOUNLy7E7kRKVm/wy38s51ChFPlpORrhimN2j1caar+KAv2tAgMBAAGjgfswgfgwHQYDVR0OBBYEFBTIImiXp+57jjgn2N5wq93GgAAtMIHIBgNVHSMEgcAwgb2AFBTIImiXp+57jjgn2N5wq93GgAAtoYGZpIGWMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5ggkAy56JarlYQgAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAnNd0YY7s2YVYPsgEgDS+rBNjcQloTFWgc9Hv4RWBjwcdJdSPIrpBp7LSjC96wH5U4eWpQjlWbOYQ9RBq9Z/RpuAPEjzRV78rIrQrCWQ3lxwywWEb5Th1EVJSN68eNv7Ke5BlZ2l9kfLRKFm5MEBXX9YoHMX0U8I8dPIXfTyevmKOT1PuEta5cQOM6/zH86XWn6WYx3EXkyjpeIbVOw49AqaEY8u70yBmut4MO03zz/pwLjV1BWyIkXhsrtuJyA+ZImvgLK2oAMZtGGFo7b0GW/sWY/P3R6Un3RFy35k6U3kXCDYYhgZEcS36lIqcj5y6vYUUVM732/etCsuOLz6ppw=="
    }
  ]
}
  </pre>

  <p>
    In this example, the client certificate is not sent in the ONC format, but
    rather we send a certificate authority which we know will have signed the
    client certificate that is needed, along with an enrollment URI to navigate
    to if the required certificate is not yet available on the client.
  </p>
</section>

<section>
  <h1>Simple format example: HTTPS Certificate Authority</h1>

  <p>
    In this example a new certificate authority is added to be trusted for HTTPS
    server authentication.
  </p>

  <pre>
{
  "Type": "UnencryptedConfiguration",
  "NetworkConfigurations": [],
  "Certificates": [
    {
      "GUID": "{f31f2110-9f5f-61a7-a8bd7c00b94237af}",
      "TrustBits": [ "Web" ],
      "Type": "Authority",
      "X509": "MIIEpzCCA4+gAwIBAgIJAMueiWq5WEIAMA0GCSqGSIb3DQEBBQUAMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTExMDEyODA2MjA0MFoXDTEyMDEyODA2MjA0MFowgZMxCzAJBgNVBAYTAkZSMQ8wDQYDVQQIEwZSYWRpdXMxEjAQBgNVBAcTCVNvbWV3aGVyZTEVMBMGA1UEChMMRXhhbXBsZSBJbmMuMSAwHgYJKoZIhvcNAQkBFhFhZG1pbkBleGFtcGxlLmNvbTEmMCQGA1UEAxMdRXhhbXBsZSBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9EDplhyrVNJIoy1OsVqvD/K67B5PW2bDKKxGznodrzCu8jHsP1Ne3mgrK20vbzQUUBdmxTCWO6x3a3//r4ZuPOuZd1ViycWjt6mRfRbBzNrHzP7NiyFuXjdlz74beHQQLcHwvZ3qFAWZK37uweiLiDPaMaEQlka2Bztqx4PsogmSdoVPSCxi5Cl1XlJmITA03LlKpO79+0rEPRamWO/DMCwvffn2/UUjJLog4/lYe16HQ6iq/6bjhffm2rLXDFKOGZmBVbLNMCfANRMtdFWHYdBXERoUo2zpM9tduOOUNLy7E7kRKVm/wy38s51ChFPlpORrhimN2j1caar+KAv2tAgMBAAGjgfswgfgwHQYDVR0OBBYEFBTIImiXp+57jjgn2N5wq93GgAAtMIHIBgNVHSMEgcAwgb2AFBTIImiXp+57jjgn2N5wq93GgAAtoYGZpIGWMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5ggkAy56JarlYQgAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAnNd0YY7s2YVYPsgEgDS+rBNjcQloTFWgc9Hv4RWBjwcdJdSPIrpBp7LSjC96wH5U4eWpQjlWbOYQ9RBq9Z/RpuAPEjzRV78rIrQrCWQ3lxwywWEb5Th1EVJSN68eNv7Ke5BlZ2l9kfLRKFm5MEBXX9YoHMX0U8I8dPIXfTyevmKOT1PuEta5cQOM6/zH86XWn6WYx3EXkyjpeIbVOw49AqaEY8u70yBmut4MO03zz/pwLjV1BWyIkXhsrtuJyA+ZImvgLK2oAMZtGGFo7b0GW/sWY/P3R6Un3RFy35k6U3kXCDYYhgZEcS36lIqcj5y6vYUUVM732/etCsuOLz6ppw=="
    }
  ]
}
  </pre>
</section>

<section>
  <h1>Encrypted format example</h1>

  <p>
In this example a simple wireless network is added, but the file is encrypted
with the passphrase "test0000".
  </p>

  <pre>
{
  "Cipher": "AES256",
  "Ciphertext": "eQ9/r6v29/83M745aa0JllEj4lklt3Nfy4kPPvXgjBt1eTByxXB+FnsdvL6Uca5JBU5aROxfiol2+ZZOkxPmUNNIFZj70pkdqOGVe09ncf0aVBDsAa27veGIG8rG/VQTTbAo7d8QaxdNNbZvwQVkdsAXawzPCu7zSh4NF/hDnDbYjbN/JEm1NzvWgEjeOfqnnw3PnGUYCArIaRsKq9uD0a1NccU+16ZSzyDhX724JNrJjsuxohotk5YXsCK0lP7ZXuXj+nSR0aRIETSQ+eqGhrew2octLXq8cXK05s6ZuVAc0mFKPkntSI/fzBACuPi4ZaGd3YEYiKzNOgKJ+qEwgoE39xp0EXMZOZyjMOAtA6e1ZZDQGWG7vKdTLmLKNztHGrXvlZkyEf1RDs10YgkwwLgUhm0yBJ+eqbxO/RiBXz7O2/UVOkkkVcmeI6yh3BdL6HIYsMMygnZa5WRkd/2/EudoqEnjcqUyGsL+YUqV6KRTC0PH+z7zSwvFs2KygrSM7SIAZM2yiQHTQACkA/YCJDwACkkQOBFnRWTWiX0xmN55WMbgrs/wqJ4zGC9LgdAInOBlc3P+76+i7QLaNjMovQ==",
  "HMAC": "3ylRy5InlhVzFGakJ/9lvGSyVH0=",
  "HMACMethod": "SHA1",
  "Iterations": 20000,
  "IV": "hcm6OENfqG6C/TVO6p5a8g==",
  "Salt": "/3O73QadCzA=",
  "Stretch": "PBKDF2",
  "Type": "EncryptedConfiguration"
}
  </pre>
</section>

</section>

<section>
  <h1>Standalone editor</h1>

  <p>
    The source code for a Chrome packaged app to generate ONC configuration can
    be found here:
    <a href="https://gerrit.chromium.org/gitweb/?p=chromiumos/platform/spigots.git;a=tree">"https://gerrit.chromium.org/gitweb/?p=chromiumos/platform/spigots.git;a=tree"</a>
  </p>
</section>

<section>
  <h1>Internationalization and Localization</h1>

  <p>
    UIs will need to have internationalization and localizations - the file
    format will remain in English.
  </p>
</section>

<section>
  <h1>Security Considerations</h1>

  <p>
    Data stored inside of open network configuration files is highly sensitive
    to users and enterprises. The file format itself provides adequate
    encryption options to allow standalone use-cases to be secure. For automatic
    updates sent by policy, the policy transport should be made secure. The file
    should not be stored unencrypted on disk as part of policy fetching and
    should be cleared from memory after use.
  </p>
</section>

<section>
  <h1>Privacy Considerations</h1>

  <p>
    Similarly to the security considerations, user names will be present in
    these files for certain kinds of connections, so any places where the file
    is transmitted or saved to disk should be secure. On client device, when
    user names for connections that are user-specific are persisted to disk,
    they should be stored in a location that is encrypted. Users can also opt in
    these cases to not save their user credentials in the config file and will
    instead be prompted when they are needed.
  </p>
</section>
</section>
</body>
</html>