diff options
| author | pneubeck@chromium.org <pneubeck@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98> | 2012-12-19 19:22:19 +0000 |
|---|---|---|
| committer | pneubeck@chromium.org <pneubeck@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98> | 2012-12-19 19:22:19 +0000 |
| commit | 268d3cc4d0823ba204651dc7faa2dbdd65394119 (patch) | |
| tree | 403832deb1f046d6b08826de9b18b0e11d49c81b /chromeos/docs | |
| parent | 678a73f30774fadac146517a35d455bd30fb0541 (diff) | |
| download | chromium_src-268d3cc4d0823ba204651dc7faa2dbdd65394119.zip chromium_src-268d3cc4d0823ba204651dc7faa2dbdd65394119.tar.gz chromium_src-268d3cc4d0823ba204651dc7faa2dbdd65394119.tar.bz2 | |
Initial commit of the ONC spec in HTML.
BUG=166413
Review URL: https://chromiumcodereview.appspot.com/11602010
git-svn-id: svn://svn.chromium.org/chrome/trunk/src@173970 0039d316-1c4b-4281-b951-d872f2087c98
Diffstat (limited to 'chromeos/docs')
| -rw-r--r-- | chromeos/docs/OWNERS | 2 | ||||
| -rw-r--r-- | chromeos/docs/onc_spec.css | 46 | ||||
| -rw-r--r-- | chromeos/docs/onc_spec.html | 2020 | ||||
| -rw-r--r-- | chromeos/docs/onc_spec.js | 55 |
4 files changed, 2123 insertions, 0 deletions
diff --git a/chromeos/docs/OWNERS b/chromeos/docs/OWNERS new file mode 100644 index 0000000..5e43217 --- /dev/null +++ b/chromeos/docs/OWNERS @@ -0,0 +1,2 @@ +pneubeck@chromium.org +gspencer@chromium.org diff --git a/chromeos/docs/onc_spec.css b/chromeos/docs/onc_spec.css new file mode 100644 index 0000000..d93cc1c --- /dev/null +++ b/chromeos/docs/onc_spec.css @@ -0,0 +1,46 @@ +/* Copyright (c) 2012 The Chromium Authors. All rights reserved. + * Use of this source code is governed by a BSD-style license that can be + * found in the LICENSE file. */ + +.value { + font-family: monospace; + font-style: italic; +} + +.type { + color: blue; + font-family: monospace; +} + +.field { + font-weight: bold; + font-family: monospace; +} + +.field_meta { + text-align: left; + background: rgb(240,240,240); + display: block; +} + +.field_list { + margin-left: 1em; +} + +.snippet { + font-family: monospace; +} + +body { + text-align: justify; + width:600px; +} + +h1{font-size: 38px} +section h1{font-size: 32px} +section section h1{font-size: 28px} +section section section h1{font-size: 24px} +section section section section h1{font-size: 20px} +section section section section section h1{font-size: 18px} +section section section section section section h1{font-size: 16px} +section section section section section section section h1{font-size: 14px} diff --git a/chromeos/docs/onc_spec.html b/chromeos/docs/onc_spec.html new file mode 100644 index 0000000..40bcb54 --- /dev/null +++ b/chromeos/docs/onc_spec.html @@ -0,0 +1,2020 @@ +<!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 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> + 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>) + <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 + </dd> + + <dt class="field">IPConfigs</dt> + <dd> + <span class="field_meta"> + (optional) + <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>) + <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) <span class="type">ProxySettings</span> + </span> + Proxy settings for this network + </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. If not specified, DHCP 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>. 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 + VPN) + <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 WiFi) + <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>) + <span class="type">string</span> + </span> + Indicates which kind of connection this is. Must be one + of <span class="value">Cellular</span>, <span class="value">Ethernet</span>, + <span class="value">WiFi</span>, or <span class="value">VPN</span>. + If <span class="field">Remove</span> is <span class="value">true</span>, + this field should not be present nor should any that depends on it + (<span class="value">Ethernet</span>, <span class="value">VPN</span>, + <span class="value">WiFi</span>, etc). + </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> + Either <span class="value">None</span> + or <span class="value">8021X</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>) + <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> + Must be either <span class="value">IPv4</span> + or <span class="value">IPv6</span>, describing 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> + Describes the routing prefix. This is a number in the range [1, 32] for + IPv4 and [1, 128] for IPv6 addresses. + </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 network should be connected 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>) + <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>) + <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<hex-number>, where <hex-number> 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> + One of <span class="value">None</span>, <span class="value">WEP-PSK</span>, + <span class="value">WEP-8021X</span>, <span class="value">WPA-PSK</span>, + <span class="value">WPA-EAP</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">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>) + <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 + L2TP-IPsec) + <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 + OpenVPN) + <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> + Type of the VPN, one + of <span class="value">IPsec</span>, <span class="value">L2TP-IPsec</span>, + or <span class="value">OpenVPN</span>. + </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> + Either <span class="value">PSK</span> or <span class="value">Cert</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> + Either <span class="value">Ref</span> + or <span class="value">Pattern</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">ServerCARef</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> + Reference to server certificate authority stored in certificate section. + </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> + <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> + Controls how OpenVPN responds to username/password verification + errors. Allowed values are <span class="value">none</span> (fail with + error on retry), <span class="value">nointeract</span> (retry without + asking for authentication), and <span class="value">interact</span> (ask + again for authentication each time). + </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>) + <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>) + <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> + Either <span class="value">Ref</span>, <span class="value">Pattern</span>, + or <span class="value">None</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. 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> + Require peer certificate signing based on RFC3280 TLS rules. May + be <span class="value">none</span> or <span class="value">server</span>. + </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">ServerCARef</dt> + <dd> + <span class="field_meta"> + (optional) + <span class="type">string</span> + </span> + Reference to a certificate. Certificate authority to use for verifying + connection. + </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 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 IssuerCARef + 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> + 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. 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> + One + of <span class="value">Direct</span>, <span class="value">Manual</span>, + <span class="value">PAC</span>, or <span class="value">WPAD</span>. + <span class="value">PAC</span> indicates Proxy Auto-Configuration. + <span class="value">WPAD</span> indicates Web Proxy Autodiscovery. If + <span class="value">WPAD</span> is specified, all other fields are ignored. + </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>) + <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) + <span class="type">string</span> + </span> + For tunnelling protocols (<span class="value">PEAP</span> + and <span class="value">EAP-TTLS</span>) 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>) + <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>) + <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> + Must be either <span class="value">Ref</span> + or <span class="value">Pattern</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 AnonymousIdentity is used for the EAP identity outside the + tunnel. For non-tunneling outer protocols, this is used for the EAP + identity. This string may include string expansions. See below. + </dd> + + <dt class="field">Inner</dt> + <dd> + <span class="field_meta"> + (optional, defaults to <span class="value">Automatic</span>) + <span class="type">string</span> + </span> + Must be one of <span class="value">Automatic</span>, + <span class="value">MD5</span>, <span class="value">MSCHAPv2</span>, + <span class="value">EAP-MSCHAPv2</span>, <span class="value">PAP</span>. Only + valid for outer protocols that are tunnelling protocols + (<span class="value">EAP-TTLS</span>, <span class="value">PEAP</span> + and <span class="value">EAP-FAST</span>). + </dd> + + <dt class="field">Outer</dt> + <dd> + <span class="field_meta"> + (required) + <span class="type">string</span> + </span> + Must be one of <span class="value">PEAP</span>, + <span class="value">EAP-TLS</span>, <span class="value">EAP-TTLS</span>, + <span class="value">LEAP</span>, <span class="value">EAP-SIM</span>, + <span class="value">EAP-FAST</span> or <span class="value">EAP-AKA</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 Identity and/or Password + when <span class="field">SaveCredentials</span> + is <span class="value">false</span> is not allowed. + </dd> + + <dt class="field">ServerCARef</dt> + <dd> + <span class="field_meta"> + (optional) + <span class="type">string</span> + </span> + Reference to server certificate authority stored in certificate + section. If not specified, client does not check the server certificate is + signed by a specific CA. It will still check the server CA + if <span class="field">UseSystemCAs</span> is set. + </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">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 the given server CA. If <span class="field">UseSystemCAs</span> + is <span class="value">false</span>, and + no <span class="field">ServerCARef</span> is set, then the certificate + must be a self signed certificate, and no CA signature is required. + </dd> + </dl> +</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> + unique identification for certificate + </dd> + + <dt class="field">PKCS12</dt> + <dd> + <span class="field_meta"> + (required when <span class="field">Remove</span> + is <span class="value">false</span> and <span class="field">Type</span> + is Client) + <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">Trust</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> + A array of trust attributes. Trust can + include <span class="value">Web</span>. <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">Trust</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>) + <span class="type">string</span> + </span> + One + of <span class="value">Client</span>, <span class="value">Server</span>, + or <span class="value">Authority</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">Remove</span> + is <span class="value">false</span> and <span class="field">Type</span> + is <span class="value">Server</span> or Authority) + <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> + 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, "HiddenSSID": false, "Security": "WPA-EAP", + "SSID": "MySSID", "EAP": { "Outer": "PEAP", "UseSystemCAs": true } } } ], + "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, "HiddenSSID": false, "Security": + "WPA-EAP", "SSID": "MyTTLSNetwork", "EAP": { "Outer": "EAP-TLS", + "UseSystemCAs": true, "ServerCARef": "{6ed8dce9-64c8-d568-d225d7e467e37828}", + "ClientCertType": "Pattern", "ClientCertPattern": { "IssuerCARef": [ + "{6ed8dce9-64c8-d568-d225d7e467e37828}" ], "EnrollmentURI": [ + "http://fetch-my-certificate.com" ] } } } } ], "Certificates": [ { "Trust": + [], "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": [ { "Trust": [ "Web" ], "GUID": + "{f31f2110-9f5f-61a7-a8bd7c00b94237af}", "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", "IV": + "hcm6OENfqG6C/TVO6p5a8g==", "Iterations": 20000, "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> diff --git a/chromeos/docs/onc_spec.js b/chromeos/docs/onc_spec.js new file mode 100644 index 0000000..ac51a8c --- /dev/null +++ b/chromeos/docs/onc_spec.js @@ -0,0 +1,55 @@ +// Copyright (c) 2012 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +var outline_root = null; +var root = null; +var outline_ptr = null; + +function onEnter(node) { + var li = document.createElement('li'); + outline_ptr.appendChild(li); + + var header = node.querySelector('h1'); + header.id = 'sec_' + header.textContent.replace(/ /g, '_'); + var link = document.createElement('a'); + link.href = '#' + header.id; + link.textContent = header.textContent; + li.appendChild(link); + var ul = document.createElement('ul'); + li.appendChild(ul); + outline_ptr = ul; +} + +function onExit(node) { + outline_ptr = outline_ptr.parentNode.parentNode; +} + +function outline(node) { + var in_toc = !node.classList.contains('not_in_toc'); + if (in_toc) { + onEnter(node); + } + var child = node.firstChild; + while (child) { + if (child.tagName === 'SECTION') { + outline(child); + } + child = child.nextSibling; + } + if (in_toc) { + onExit(node); + } +} + + +window.onload = function () { + outline_root = document.getElementById('outline'); + root = document.getElementById('root'); + + var ul = document.createElement('ul'); + outline_root.appendChild(ul); + outline_ptr = ul; + + outline(root); +};
\ No newline at end of file |