Open Network Configuration Format

Outline

Objective

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

Background

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 WiFi 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.

Overview

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.

This format neither supports configuring browser settings nor allows setting other types of system policies.

Infrastructure

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.

This file format may be delivered to a user and manually imported into a device.

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

Detailed Design

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.

The JSON consists of a top level dictionary containing a Type field which must have either the value EncryptedConfiguration or UnencryptedConfiguration.

For a description of the EncryptedConfiguration type, see the section on Encrypted Configuration below. The EncryptedConfiguration format encrypts an unencrypted JSON object.

GUIDs and Updating

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.

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.

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.

Implementation-specific fields

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.

Fields and values should follow these general guidelines:

  • 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 CertificatePattern type.
  • Fields should exist in the most-specific object in the hierarchy and should be named CamelCase style.
  • Booleans and integers should be used directly instead of using a stringified version of the type.

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.

Unencrypted Configuration

When the top level Type field is UnencryptedConfiguration, the top level JSON has the UnencryptedConfiguration type. UnencryptedConfiguration type contains the following:

Type
(optional, defaults to UnencryptedConfiguration ) string Must be UnencryptedConfiguration.
NetworkConfigurations
(optional) array of NetworkConfiguration Describes WiFi, Ethernet, VPN, and wireless connections.
Certificates
(optional) array of Certificate Contains certificates stored in X.509 or PKCS#12 format.
At least one actual configuration field (NetworkConfigurations or Certificates) should be present, however it should not be considered an error if no such field is present.

Network Configuration

Field NetworkConfigurations is an array of NetworkConfiguration typed objects. The NetworkConfiguration type contains the following:

Ethernet
(required if Type is Ethernet, otherwise ignored) Ethernet Ethernet settings.
GUID
(required) string A unique identifier for this network connection, which exists to make it possible to update previously imported configurations. Must be a non-empty string.
IPAddressConfigType
(optional if Remove is false, otherwise ignored. Defaults to DHCP if NameServersConfigType is specified) string Allowed values are DHCP and Static. Determines whether the IP Address configuration is statically configured, see StaticIPConfig, or automatically configured using DHCP.
NameServersConfigType
(optional if Remove is false, otherwise ignored. Defaults to DHCP if IPAddressConfigType is specified) string Allowed values are DHCP and Static. Determines whether the NameServers configuration is statically configured, see StaticIPConfig, or automatically configured using DHCP.
IPConfigs
(optional for connected networks, read-only) array of IPConfig Array of IPConfig properties associated with this connection.
StaticIPConfig
(required if IPAddressConfigType or NameServersConfigType is set to Static) IPConfig Each property set in this IPConfig object overrides the respective parameter received over DHCP. If IPAddressConfigType is set to Static, IPAddress and Gateway are required. If NameServersConfigType is set to Static, NameServers is required.
SavedIPConfig
(optional for connected networks, read-only) IPConfig IPConfig property containing the configuration that was received from the DHCP server prior to applying any StaticIPConfig parameters.
Name
(required if Remove is false, otherwise ignored) string 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.
Remove
(optional, defaults to false) boolean If set, remove this network configuration (only GUID should be set).
ProxySettings
(optional if Remove is false, otherwise ignored) ProxySettings Proxy settings for this network
VPN
(required if Type is VPN, otherwise ignored) VPN VPN settings.
WiFi
(required if Type is WiFi, otherwise ignored) WiFi WiFi settings.
WiMAX
(required if Type is WiMAX, otherwise ignored) WiMAX WiMAX settings.
Cellular
(required if Type is Cellular, otherwise ignored) Cellular Cellular settings.
Type
(required if Remove is false, otherwise ignored) string Allowed values are Cellular, Ethernet, WiFi, Cellular and VPN. Indicates which kind of connection this is.
ConnectionState
(optional, read-only) string The current connection state for this network, provided by the system. Allowed values are: Connected, Connecting, NotConnected
RestrictedConnectivity
(optional, defaults to false, read-only) boolean True if a connnected network has limited connectivity to the Internet, e.g. a connection is behind a portal or a cellular network is not activated or requires payment.
Connectable
(optional, read-only) boolean True if the system indicates that the network can be connected to without any additional configuration.
ErrorState
(optional, read-only) string The current error state for this network, if any. Error states are provided by the system and are not explicitly defined here. They may or may not be human-readable. This field will be empty or absent if the network is not in an error state.
MacAddress
(optional, read-only) string The MAC address for the network. Only applies to connected non-virtual networks. The format is 00:11:22:AA:BB:CC.
Source
(optional, read-only) string Indicates whether the network is configured and how it is configured:
  • User: Configured for the active user only, i.e. an unshared configuration.
  • Device: Configured for all users of the device (e.g laptop), i.e. a shared configuration.
  • UserPolicy: Configured by the user policy for the active user.
  • DevicePolicy: Configured by the device policy for the device.
  • None: Not configured, e.g. a visible but unconfigured WiFi network.
Allowed values are: User, Device, UserPolicy, DevicePolicy, None
Priority
(optional) integer Provides a suggested priority value for this network. May be used by the system to determine which network to connect to when multiple configured networks are available (or may be ignored).

Ethernet networks

For Ethernet connections, Type must be set to Ethernet and the field Ethernet must be set to an object of type Ethernet containing the following fields:

Authentication
(optional) string Allowed values are None and 8021X.
EAP
(required if Authentication is 8021X, otherwise ignored) EAP EAP settings.

IPConfig

Objects of type IPConfig are used to report the actual IP configuration of a connected network (see IPConfigs), the IP configuration received from DHCP (see SavedIPConfig) and to configure a static IP configuration (see StaticIPConfig).

Type
(required) string Allowed values are IPv4 and IPv6 Describes the type of configuration this is.
IPAddress
(optional) string Describes the IPv4 or IPv6 address of a connection, depending on the value of Type field. It should not contain the routing prefix (i.e. should not end in something like /64).
RoutingPrefix
(required if IPAddress is set. Otherwise ignored.) integer Must be a number in the range [1, 32] for IPv4 and [1, 128] for IPv6 addresses. Describes the routing prefix.
Gateway
(required if IPAddress is set. Otherwise ignored.) string Describes the gateway address to use for the configuration. Must match address type specified in Type field. If not specified, DHCP values will be used.
NameServers
(optional) array of string Array of addresses to use for name servers. Address format must match that specified in the Type field. If not specified, DHCP values will be used.
SearchDomains
(optional) array of string Array of strings to append to names for resolution. Items in this array should not start with a dot. Example: [ "corp.acme.org", "acme.org" ]. If not specified, DHCP values will be used.
WebProxyAutoDiscoveryUrl
(optional if part of IPConfigs, read-only) string The Web Proxy Auto-Discovery URL for this network as reported over DHCP.

WiFi networks

For WiFi connections, Type must be set to WiFi and the field WiFi must be set to an object of type WiFi containing the following fields:

AllowGatewayARPPolling
(optional, defaults to true) boolean Indicaties if ARP polling of default gateway is allowed. When it is allowed, periodic ARP messages will be sent to the default gateway. This is used for monitoring the status of the current connection.
AutoConnect
(optional, defaults to false) boolean Indicating that the network should be connected to automatically when in range.
EAP
(required if Security is WEP-8021X or WPA-EAP, otherwise ignored) EAP EAP settings.
HexSSID
(optional if SSID is set, if so defaults to a hex representation of SSID) string Hex representation of the network's SSID.
HiddenSSID
(optional, defaults to false) boolean Indicating if the SSID will be broadcast.
Passphrase
(required if Security is WEP-PSK or WPA-PSK, otherwise ignored) string Describes the passphrase for WEP/WPA/WPA2 connections. If WEP-PSK is used, the passphrase must be of the format 0x<hex-number>, where <hex-number> is 40, 104, 128, or 232 bits.
RoamThreshold
(optional) integer The roam threshold for this network, which is the signal-to-noise value (in dB) below which we will attempt to roam to a new network. If this value is not set, the default value will be used.
Security
(required) string Allowed values are None, WEP-PSK, WEP-8021X, WPA-PSK, and WPA-EAP.
SSID
(optional if HexSSID is set, otherwise ignored) string Property to access the decoded SSID of a network.
If this field is set, but HexSSID is not, its value will be UTF-8 encoded and the hex representation will be assigned to HexSSID. To configure a non-UTF-8 SSID, field HexSSID must be used.
When reading the configuration of a network, both this field and HexSSID might be set. Then this field is the decoding of HexSSID. If possible the HexSSID is decoded using UTF-8, otherwise an encoding is guessed on a best effort basis.
SignalStrength
(optional, read-only) integer The current signal strength for this network in the range [0, 100], provided by the system. If the network is not in range this field will be set to '0' or not present.
At least one of the fields HexSSID or SSID must be present. If both HexSSID and SSID are set, the values must be consistent.

VPN networks

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.

For VPN connections, Type must be set to VPN and the field VPN must be set to an object of type VPN containing the following fields:

AutoConnect
(optional, defaults to false) boolean Indicating that the network should be connected to automatically.
Host
(optional) string 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 Host field is required.
IPsec
(required if Type is IPsec or L2TP-IPsec, otherwise ignored) IPsec IPsec layer settings.
L2TP
(required if Type is L2TP-IPsec, otherwise ignored) L2TP L2TP layer settings.
OpenVPN
(required if Type is OpenVPN, otherwise ignored) OpenVPN OpenVPN settings.
ThirdPartyVPN
(required if Type is ThirdPartyVPN, otherwise ignored) ThirdPartyVPN Third-party VPN provider settings.
Type
(required) string Allowed values are IPsec, L2TP-IPsec, OpenVPN, and ThirdPartyVPN. Type of the VPN.

IPsec-based VPN types

The IPsec type contains the following:

AuthenticationType
(required) string Allowed values are PSK and Cert. If Cert is used, ClientCertType and ServerCARefs (or the deprecated ServerCARef) must be set.
ClientCertPattern
(required if ClientCertType is Pattern, otherwise ignored) CertificatePattern Pattern describing the client certificate.
ClientCertRef
(required if ClientCertType is Ref, otherwise ignored) string Reference to client certificate stored in certificate section.
ClientCertType
(required if AuthenticationType is Cert, otherwise ignored) string Allowed values are Ref and Pattern
EAP
(optional if IKEVersion is 2, otherwise ignored) EAP Indicating that EAP authentication should be used with the provided parameters.
Group
(optional if IKEVersion is 1, otherwise ignored) string Group name used for machine authentication.
IKEVersion
(required) integer Version of IKE protocol to use.
PSK
(optional if AuthenticationType is PSK, otherwise ignored) string Pre-Shared Key. If not specified, user is prompted at time of connection.
SaveCredentials
(optional if AuthenticationType is PSK, otherwise ignored, defaults to false) boolean If false, require user to enter credentials (PSK) each time they connect.
ServerCARefs
(optional if AuthenticationType is Cert, otherwise rejected) array of string Non-empty list of references to CA certificates in Certificates to be used for verifying the host's certificate chain. At least one of the CA certificates must match. If this field is set, ServerCARef must be unset.
ServerCARef
(optional if AuthenticationType is Cert, otherwise rejected) string DEPRECATED, use ServerCARefs instead.
Reference to a CA certificate in Certificates. Certificate authority to use for verifying connection. If this field is set, ServerCARefs must be unset.
XAUTH
(optional if IKEVersion is 1, otherwise ignored) XAUTH Describing XAUTH credentials. XAUTH is not used if this object is not present.

If AuthenticationType is set to Cert, ServerCARefs or ServerCARef must be set.

At most one of ServerCARefs and ServerCARef can be set.

L2TP type contains the following:

LcpEchoDisabled
(optional, defaults to false) boolean Disable L2TP connection monitoring via PPP LCP frames. This allows the VPN client to work around server implementations that do not support the LCP echo feature.
Password
(optional) string User authentication password. If not specified, user is prompted at time of connection.
SaveCredentials
(optional, defaults to false) boolean If false, require user to enter credentials each time they connect.
Username
(optional) string User identity. This value is subject to string expansions. If not specified, user is prompted at time of connection.

XAUTH type contains the following:

Password
(optional) string XAUTH password. If not specified, user is prompted at time of connection.
SaveCredentials
(optional, defaults to false) boolean If false, require user to enter credentials each time they connect.
Username
(optional) string XAUTH user name. This value is subject to string expansions. If not specified, user is prompted at time of connection.

IPsec IKE v1 VPN connections

VPN.Type must be IPsec, IKEVersion 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 IPsec type described below.

IPsec IKE v2 VPN connections

VPN.Type must be IPsec, IKEVersion must be 2. This may be used with EAP-based user authentication.

L2TP over IPsec VPN connections

There are two major configurations L2TP over IPsec which depend on how IPsec is authenticated. In either case Type must be L2TP-IPsec. They are described below.

L2TP over IPsec with pre-shared key:

  • The field IPsec must be present and have the following settings:
    • IKEVersion must be 1.
    • AuthenticationType must be PSK.
    • XAUTH must not be set.
  • The field L2TP must be present.

OpenVPN connections and types

VPN.Type must be OpenVPN.

OpenVPN type contains the following:

Auth
(optional, defaults to SHA1) string
AuthRetry
(optional, defaults to none) string Allowed values are none, nointeract, and interact. Controls how OpenVPN responds to username/password verification errors:
Either fail with error on retry (none), retry without asking for authentication (nointeract), or ask again for authentication each time (interact).
AuthNoCache
(optional, defaults to false) boolean Disable caching of credentials in memory.
Cipher
(optional, defaults to BF-CBC) string Cipher to use.
ClientCertRef
(required if ClientCertType is Ref, otherwise ignored) string Reference to client certificate stored in certificate section.
ClientCertPattern
(required if ClientCertType is Pattern, otherwise ignored) CertificatePattern Pattern to use to find the client certificate.
ClientCertType
(required) string Allowed values are Ref, Pattern, and None. None implies that the server is configured to not require client certificates.
CompLZO
(optional, defaults to adaptive) string Decides to fast LZO compression with true and false as other values.
CompNoAdapt
(optional, defaults to false) boolean Disables adaptive compression.
IgnoreDefaultRoute
(optional, defaults to false) bool Omits a default route to the VPN gateway while the connection is active. By default, the client creates a default route to the gateway address advertised by the VPN server. Setting this value to true will allow split tunnelling for configurations where the VPN server omits explicit default routes. This is roughly equivalent to omitting "redirect-gateway" OpenVPN client configuration option. If the server pushes a "redirect-gateway" configuration flag to the client, this option is ignored.
KeyDirection
(optional) string Passed as --key-direction.
NsCertType
(optional) string If set, checks peer certificate type. Should only be set to server if set.
OTP
(optional if UserAuthenticationType is OTP, PasswordAndOTP or unset, otherwise ignored, defaults to empty string) string If UserAuthenticationType is OTP or PasswordAndOTP and this field is not set, the user will be asked for an OTP. The OTP is never persisted and must be provided on every connection attempt.
Password
(optional if UserAuthenticationType is Password, PasswordAndOTP or unset, otherwise ignored, defaults to empty string) string If UserAuthenticationType is Password or PasswordAndOTP and this field is not set, the user will be asked for a password. If SaveCredentials is true, the password is persisted for future connection attempts. Otherwise it is not persisted but might still be reused for consecutive connection attempts (opposed to an OTP, which will never be reused).
Port
(optional, defaults to 1194) integer Port for connecting to server.
Proto
(optional, defaults to udp) string Protocol for communicating with server.
PushPeerInfo
(optional, defaults to false) boolean
RemoteCertEKU
(optional) string Require that the peer certificate was signed with this explicit extended key usage in oid notation.
RemoteCertKU
(optional, defaults to []) array of string Require the given array of key usage numbers. These are strings that are hex encoded numbers.
RemoteCertTLS
(optional, defaults to server) string Allowed values are none and server. Require peer certificate signing based on RFC3280 TLS rules.
RenegSec
(optional, defaults to 3600) integer Renegotiate data channel key after this number of seconds.
SaveCredentials
(optional, defaults to false) boolean If false, require user to enter credentials each time they connect.
ServerCARefs
(optional) array of string Non-empty list of references to CA certificates in Certificates to be used for verifying the host's certificate chain. At least one of the CA certificates must match. See also OpenVPN's command line option "--ca". If this field is set, ServerCARef must be unset.
ServerCARef
(optional) string DEPRECATED, use ServerCARefs instead.
Reference to a CA certificate in Certificates. Certificate authority to use for verifying connection. If this field is set, ServerCARefs must be unset.
ServerCertRef
(optional) string Reference to a certificate. Peer's signed certificate.
ServerPollTimeout
(optional) integer Spend no more than this number of seconds before trying the next server.
Shaper
(optional) integer If not specified no bandwidth limiting, otherwise limit bandwidth of outgoing tunnel data to this number of bytes per second.
StaticChallenge
(optional) string String is used in static challenge response. Note that echoing is always done.
TLSAuthContents
(optional) string If not set, tls auth is not used. If set, this is the TLS Auth key contents (usually starts with "-----BEGIN OpenVPN Static Key..."
TLSRemote
(optional) string If set, only allow connections to server hosts with X509 name or common name equal to this string.
UserAuthenticationType
(optional, defaults to None) string Allowed values are None, Password, PasswordAndOTP and OTP. Determines the required form of user authentication:
  • PasswordAndOTP: This VPN requires a password and an OTP (possibly empty). Both will be send to the server in the 'password' response using the SCRv1 encoding.
  • Password: This VPN requires only a password, which will be send without modification to the server in the 'password' response (no CRv1 or SCRv1 encoding).
  • OTP: This VPN requires only an OTP, which will be send without modification to the server in the 'password' response (no CRv1 or SCRv1 encoding).
  • None: Neither password nor OTP are required. No password request from the server is expected.
If not set, the user can provide a password and an OTP (both not mandatory) and the network manager will send both in the SCRv1 encoding, when the server sends a static-challenge. If the server does not send a static-challenge, the client will reply with only the password (without any encoding). This behavior is deprecated and new configurations should explicitly set one of the above values. See the fields Password and OTP for configuring the password and OTP.
Username
(optional) string OpenVPN user name. This value is subject to string expansions. If not specified, user is prompted at time of connection.
Verb
(optional) string Verbosity level, defaults to OpenVpn's default if not specified.
VerifyHash
(optional) string If set, this value is passed as the "--verify-hash" argument to OpenVPN, which specifies the SHA1 fingerprint for the level-1 certificate.
VerifyX509
(optional) VerifyX509 If set, the "--verify-x509-name" argument is passed to OpenVPN with the values of this object and only connections will be accepted if a host's X.509 name is equal to the given name.

At most one of ServerCARefs and ServerCARef can be set.

VerifyX509 type contains the following:

Name
(required) string The name that the host's X.509 name is compared to. Which host name is compared depends on the value of Type.
Type
(optional) string Determines which of the host's X.509 names will be verified. Allowed values are name, name-prefix and subject. See OpenVPN's documentation for "--verify-x509-name" for the meaning of each value. Defaults to OpenVPN's default if not specified.

Third-party VPN provider based connections and types

VPN.Type must be ThirdPartyVPN.

ThirdPartyVPN type contains the following:

ExtensionID
(required) string The extension ID of the third-party VPN provider used by this network.

Client certificate patterns

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 CertificatePattern type contains the following:

IssuerCARef
(optional) array of string Array of references to certificates. At least one must have signed the client certificate.
Issuer
(optional) IssuerSubjectPattern 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.
Subject
(optional) IssuerSubjectPattern 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.
EnrollmentURI
(optional) array of string 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.

The IssuerSubjectPattern type contains the following:

CommonName
(optional) string Certificate subject's commonName must match this string if present.
Locality
(optional) string Certificate subject's location must match this string if present.
Organization
(optional) string At least one of certificate subject's organizations must match this string if present.
OrganizationalUnit
(optional) string At least one of certificate subject's organizational units must match this string if present.

One field in Subject, Issuer, or IssuerCARef must be given for a CertificatePattern 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.

If EnrollmentURI is not given and no match is found to this pattern, the importing tool may show an error to the user.

Proxy settings

Every network can be configured to use a proxy. The ProxySettings type contains the following:

Type
(required) string Allowed values are Direct, Manual, PAC, and WPAD. PAC indicates Proxy Auto-Configuration. WPAD indicates Web Proxy Autodiscovery.
Manual
(required if Type is Manual, otherwise ignored) ManualProxySettings Manual proxy settings.
ExcludeDomains
(optional if Type is Manual, otherwise ignored) array of string Domains and hosts for which to exclude proxy settings.
PAC
(required if Type is PAC, otherwise ignored) string URL of proxy auto-config file.

The ManualProxySettings type contains the following:

HTTPProxy
(optional) ProxyLocation settings for HTTP proxy.
SecureHTTPProxy
(optional) ProxyLocation settings for secure HTTP proxy.
FTPProxy
(optional) ProxyLocation settings for FTP proxy
SOCKS
(optional) ProxyLocation settings for SOCKS proxy.

The ProxyLocation type contains the following:

Host
(required) string Host (or IP address) to use for proxy
Port
(required) integer Port to use for proxy

EAP configurations

For networks with 802.1X authentication, an EAP type exists to configure the authentication. The EAP type contains the following:

AnonymousIdentity
(optional if Outer is PEAP or EAP-TTLS, otherwise ignored) string 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.
ClientCertPattern
(required if ClientCertType is Pattern, otherwise ignored) CertificatePattern Pattern to use to find the client certificate.
ClientCertRef
(required if ClientCertType is Ref, otherwise ignored) string Reference to client certificate stored in certificate section.
ClientCertType
(optional) string Allowed values are Ref, and Pattern.
Identity
(optional) string Identity of user. For tunneling outer protocols (PEAP, EAP-TTLS, and EAP-FAST), 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 value is subject to string expansions.
Inner
(optional if Outer is EAP-FAST, EAP-TTLS or PEAP, otherwise ignored, defaults to Automatic) string Allowed values are Automatic, MD5, MSCHAPv2, EAP-MSCHAPv2, PAP, and GTC. For tunneling outer protocols.
Outer
(required) string Allowed values are LEAP, EAP-AKA, EAP-FAST, EAP-TLS, EAP-TTLS, EAP-SIM and PEAP.
Password
(optional) string Password of user. If not specified, defaults to prompting the user.
SaveCredentials
(optional, defaults to false) boolean If false, require user to enter credentials each time they connect. Specifying Identity and/or Password when SaveCredentials is false is not allowed.
ServerCARefs
(optional) array of string Non-empty list of references to CA certificates in Certificates to be used for verifying the host's certificate chain. At least one of the CA certificates must match. If this field is set, ServerCARef must be unset. If neither ServerCARefs nor ServerCARef is set, the client does not check that the server certificate is signed by a specific CA. A verification using the system's CA certificates may still apply. See UseSystemCAs for this.
ServerCARef
(optional) string DEPRECATED, use ServerCARefs instead.
Reference to a CA certificate in Certificates. If this field is set, ServerCARefs must be unset. If neither ServerCARefs nor ServerCARef is set, the client does not check that the server certificate is signed by a specific CA. A verification using the system's CA certificates may still apply. See UseSystemCAs for this.
UseSystemCAs
(optional, defaults to true) boolean Required server certificate to be signed by "system default certificate authorities". If both ServerCARefs (or ServerCARef) and UseSystemCAs are supplied, a server certificate will be allowed if it either has a chain of trust to a system CA or to one of the given CA certificates. If UseSystemCAs is false, and no ServerCARef is set, the certificate must be a self signed certificate, and no CA signature is required.
UseProactiveKeyCaching
(optional, defaults to false) boolean Indicates whether Proactive Key Caching (also known as Opportunistic Key Caching) should be used on a per-service basis.

At most one of ServerCARefs and ServerCARef can be set.

WiMAX Networks

For WiMAX connections, Type must be set to WiMAX and the field WiMAX must be set to an object of type WiMAX. Currently only used for representing an existing configuration; ONC configuration of of WiMAX networks is not yet fully supported. Contains the following fields:

AutoConnect
(optional, defaults to false) boolean Indicating that the network should be connected to automatically when possible.
EAP
(required) EAP EAP settings.
SignalStrength
(optional, read-only) integer The current signal strength for this network in the range [0, 100], provided by the system. If the network is not in range this field will be set to '0' or not present.

Cellular Networks

For Cellular connections, Type must be set to Cellular and the field Cellular must be set to an object of type Cellular. Currently only used for representing an existing configuration; ONC configuration of of Cellular networks is not yet supported. Contains the following fields:

AutoConnect
(optional, defaults to false) boolean Indicating that the network should be connected to automatically when possible. Note, that disabled AllowRoaming takes precedence over autoconnect.
APN
(optional) APN Currently active APN object to be used with a GSM carrier for making data connections.
APNList
(optional, read-only) array of APN List of available APN configurations.
ActivationType
(optional) string Activation type.
ActivationState
(optional, read-only) string Carrier account activation state. Allowed values are Activated, Activating, NotActivated, PartiallyActivated
AllowRoaming
(optional) boolean Whether cellular data connections are allowed when the device is roaming.
Carrier
(optional, read-only) string The name of the carrier for which the device is configured.
ESN
(optional, read-only) string The Electronic Serial Number of the cellular modem.
Family
(optional, read-only) string Technology family. Allowed values are CDMA, GSM
FirmwareRevision
(optional, read-only) string The revision of firmware that is loaded in the modem.
FoundNetworks
(optional, read-only, provided only if Family is GSM) array of FoundNetwork The list of cellular netwoks found in the most recent scan operation.
HardwareRevision
(optional, read-only) string The hardware revision of the cellular modem.
HomeProvider
(optional, read-only) array of CellularProvider Description of the operator that issued the SIM card currently installed in the modem.
ICCID
(optional, read-only, provided only if Family is GSM or NetworkTechnology is LTE) string For GSM / LTE modems, the Integrated Circuit Card Identifer of the SIM card installed in the device.
IMEI
(optional, read-only) string The International Mobile Equipment Identity of the cellular modem.
IMSI
(optional, read-only, provided only if Family is GSM) string For GSM modems, the International Mobile Subscriber Identity of the SIM card installed in the device.
LastGoodAPN
(optional, read-only) APN The APN information used in the last successful connection attempt.
Manufacturer
(optional, read-only) string The manufacturer of the cellular modem.
MDN
(optional) string The Mobile Directory Number (i.e., phone number) of the device.
MEID
(optional, read-only, provided only if Family is CDMA) string For CDMA modems, the Mobile Equipment Identifer of the cellular modem.
MIN
(optional, read-only) string The Mobile Identification Number of the device.
ModelID
(optional, read-only) string The hardware model of the cellular modem.
NetworkTechnology
(optional, read-only) string If the modem is registered on a network, then this is set to the network technology currently in use. Allowed values are CDMA1XRTT, EDGE, EVDO, GPRS, GSM, HSPA, HSPAPlus, LTE, LTEAdvanced UMTS,
PaymentPortal
(optional, read-only) PaymentPortal Properties describing the online payment portal (OLP) at which a user can sign up for or modify a mobile data plan.
PRLVersion
(optional, read-only) integer The revision of the Preferred Roaming List that is loaded in the modem.
RoamingState
(optional, read-only) string The roaming status of the cellular modem on the current network. Allowed values are Home, Roaming, or if the provider has no home network, Required.
ServingOperator
(optional, read-only, provided only if Family is GSM) CellularProvider Description of the operator on whose network the modem is currently registered
SIMLockStatus
(optional, read-only, provided only if Family is GSM) SIMLockStatus For GSM modems, a dictionary containing two properties describing the state of the SIM card lock.
SIMPresent
(optional, read-only, provided only if Family is GSM or NetworkTechnology is LTE) boolean For GSM or LTE modems, indicates whether a SIM card is present or not.
SupportNetworkScan
(optional, read-only) boolean True if the cellular network supports scanning.
SupportedCarriers
(optional, read-only) array of string A list of supported carriers.

APN type contains the following:

AccessPointName
(required) string The access point name used when making connections.
Name
(optional) string Description of the APN.
LocalizedName
(optional) string Localized description of the APN.
Username
(optional) string Username for making connections if required.
Password
(optional) string Password for making connections if required.
Language
(optional, rquired if LocalizedName is provided) string Two letter language code for Localizedname if provided.

FoundNetwork type contains the following:

Status
(required) string The availability of the network.
NetworkId
(required) string The network id in the form MCC/MNC (without the '/').
Technology
(required) string Access technology used by the network, e.g. "GSM", "UMTS", "EDGE", "HSPA", etc.
ShortName
(optional) string Short-format name of the network operator.
LongName
(optional) string Long-format name of the network operator.

PaymentPortal type contains the following:

Method
(required) string The HTTP method to use, "GET" or "POST"
PostData
(required if Method is POST, otherwise ignored) string The postdata to send.
Url
(required) string The URL for the portal.

CellularProvider type contains the following:

Name
(required) string The operator name.
Code
(required) string The network id in the form MCC/MNC (without the '/').
Country
(optional) string The two-letter country code.

SIMLockStatus type contains the following:

LockType
(required) string Specifies the type of lock in effect, or an empty string if unlocked. Allowed values are sim-pin, sim-puk
LockEnabled
(required) boolean Indicates whether SIM locking is enabled
RetriesLeft
(optional) integer If LockType is empty or sim-pin, then this property represents the number of attempts remaining to supply a correct PIN before the PIN becomes blocked, at which point a PUK provided by the carrier would be necessary to unlock the SIM (and LockType changes to sim-puk).

Bluetooth / WiFi Direct Networks

This format will eventually also cover configuration of Bluetooth and WiFi Direct network technologies, however they are currently not supported.

Certificates

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.

The top-level field Certificates is an array of objects of Certificate type.

The Certificate type contains the following:

GUID
(required) string A unique identifier for this certificate. Must be a non-empty string.
PKCS12
(required if Type is Client, otherwise ignored) string For certificates with private keys, this is the base64 encoding of the a PKCS#12 file.
Remove
(optional, defaults to false) boolean If true, remove this certificate (only GUID should be set).
TrustBits
(optional if Type is Server or Authority, otherwise ignored, defaults to []) array of string An array of trust flags. Clients should ignore unknown flags. For backwards compatibility, each flag should only increase the trust and never restrict. The trust flag Web implies that the certificate is to be trusted for HTTPS SSL identification. A typical web certificate authority would have Type set to Authority and TrustBits set to ["Web"].
Type
(required if Remove is false, otherwise ignored) string Allowed values are Client, Server, and Authority. Client indicates the certificate is for identifying the user or device over HTTPS or for VPN/802.1X. Server indicates the certificate identifies an HTTPS or VPN/802.1X peer. Authority indicates the certificate is a certificate authority and any certificates it issues should be trusted. Note that if Type disagrees with the x509 v3 basic constraints or key usage attributes, the Type field should be honored.
X509
(required if Type is Server or Authority, otherwise ignored) string For certificate without private keys, this is the X509 certificate in PEM format.

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.

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.

Encrypted Configuration

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.

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.

An encrypted ONC file's top level object will have the EncryptedConfiguration type. EncryptedConfiguration type contains the following:

Cipher
(required) string The type of cipher used. Currently only AES256 is supported.
Ciphertext
(required) string The raw ciphertext of the encrypted ONC file, base64 encoded.
HMAC
(required) string The HMAC for the ciphertext, base64 encoded.
HMACMethod
(required) string The method used to compute the Hash-based Message Authentication Code (HMAC). Currently only SHA1 is supported.
Salt
(required) string The salt value used during key stretching.
Stretch
(required) string The key stretching algorithm used. Currently only PBKDF2 is supported.
Iterations
(required) integer The number of iterations to use during key stretching.
IV
(required) string The initial vector (IV) used for Cyclic Block Cipher (CBC) mode, base64 encoded.
Type
(required) string The type of the ONC file, which must be set to EncryptedConfiguration.

When decrypted, the ciphertext must contain a JSON object of type UnencryptedConfiguration.

String Expansions

The values of some fields, such as WiFi.EAP.Identity and VPN.*.Username, are subject to string expansions. These allow one ONC to have basic user-specific variations.

The expansions are:

  • ${LOGIN_ID} - expands to the email address of the user, but before the '@'.
  • ${LOGIN_EMAIL} - expands to the email address of the user.

The following SED would properly handle resolution.

  • s/\$\{LOGIN_ID\}/bobquail$1/g
  • s/\$\{LOGIN_EMAIL\}/bobquail@example.com$1/g

Example expansions, assuming the user was bobquail@example.com:

  • "${LOGIN_ID}" -> "bobquail"
  • "${LOGIN_ID}@corp.example.com" -> "bobquail@corp.example.com"
  • "${LOGIN_EMAIL}" -> "bobquail@example.com"
  • "${LOGIN_ID}X" -> "bobquailX"
  • "${LOGIN_IDX}" -> "${LOGIN_IDX}"
  • "X${LOGIN_ID}" -> "Xbobquail"

Detection

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.

Alternatives considered

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.

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.

Detection

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.

Mocks

Simple format example: PEAP/MSCHAPv2 network (per device)

{
  "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": []
}

Notice that in this case, we do not provide a username and password - we set SaveCredentials to false so we are prompted every time. We could have passed in username and password - but such a file should be encrypted.

Complex format example: TLS network with client certs (per device)

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

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.

Simple format example: HTTPS Certificate Authority

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

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

Encrypted format example

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

{
  "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"
}

Standalone editor

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

Internationalization and Localization

UIs will need to have internationalization and localizations - the file format will remain in English.

Security Considerations

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.

Privacy Considerations

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.