5f31b9b4c1
Also clarifying some of the field descriptions. BUG=None Review URL: https://chromiumcodereview.appspot.com/12255005 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@182568 0039d316-1c4b-4281-b951-d872f2087c98
2156 lines
69 KiB
HTML
2156 lines
69 KiB
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<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>
|
|
<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>
|
|
</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">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>
|
|
<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">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 <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">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>
|
|
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">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>, 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}",
|
|
"Trust": [],
|
|
"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}",
|
|
"Trust": [ "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>
|