Open Network Configuration
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
Type
- (optional, defaults to UnencryptedConfiguration) - string
- Must be UnencryptedConfiguration.
NetworkConfigurations
Certificates
- 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.
Global Network Configuration
Field GlobaNetworkConfiguration has the [GlobalNetworkConfiguration] (#GlobalNetworkConfiguration-type) type.
GlobalNetworkConfiguration type
The GlobalNetworkConfiguration contains settings which apply to all of the networks that the device may connect to. The client supports this only in device-level policy; the client-side ONC validator fails if it appears in user policy. To avoid bricking devices, these policies will only be enforced in user sessions. The login screen ignores these policies and may still be used for fetching new policy or logging in. A Help Center article warns admins of the implications of mis-using this policy for Chrome OS.
AllowCellularHotspot
- (optional, defaults to true) - boolean
- When this field is present and set to true, chromebook users will be allowed to turn on hotspot on their devices. If there is an active hotspot and this field is set to false, hotspot will be turned off and a notification will be displayed to the user.
AllowCellularSimLock
- (optional, defaults to true) - boolean
- When this field is present and set to false, a SIM cannot be PIM Locked on a managed device. If the currently active SIM is already PIN Locked when this field turns false, the managed user will be guided to PIN unlock the SIM.
AllowOnlyPolicyCellularNetworks
- (optional, defaults to false) - boolean
- When this field is present and set to true, only cellular networks present in policy may be connected to. No new cellular networks may be added or configured. This allows admins to ensure that only policy configured cellular networks are accessible.
AllowOnlyPolicyNetworksToAutoconnect
- (optional, defaults to false) - boolean
- When this field is present and set to true, on startup the device will only auto connect to those networks that are present in its policy. This is necessary for devices that are used as kiosks, for example, so that they can’t be hijacked by some other user on startup.
AllowOnlyPolicyNetworksToConnect
- (optional, defaults to false) - boolean
- When this field is present and set to true, only networks present in policy may be connected to. This allows schools to enforce that only known-good networks (e.g., filtered student networks) may be used. Existing connections to unmanaged networks will be disconnected on policy fetch.
AllowOnlyPolicyNetworksToConnectIfAvailable
- (optional, defaults to false) - boolean
- When this field is present, set to true and a policy network is in range, only policy networks may be connected to. If no managed network is in range (e.g. user’s home), the device may connect to any network. If enabled and a network scan shows a new policy managed network, the device will automatically switch to the managed network.
AllowAPNModification
- (optional, defaults to true) - boolean
- Only relevant when the admin does not specify APNs for a SIM. Note that users cannot modify any admin assigned APNs. When this field is present and set to false, users won't have the capabilities to add, modify, and use their own custom APNs for cellular networks that do not have an APN specified by the admin. When this field is unset or set to true, users will have the aforementioned capabilities for an eSIM with no AdminAssignedAPNIds, and for any pSIM if there are no PSIMAssignedAPNIds.
AllowTextMessages
- (optional, defaults to Unset) - string
- When this field is present and set to Allow text message notifications will be shown. When this field is set to Suppress, no text message notifications will be shown and text messages will be dropped forever. When this field is Unset, text messages notifications will be shown by default and will allow user configuration for suppressing text messages.
- Allowed values are:
BlacklistedHexSSIDs
- DEPRECATED, use BlockedHexSSIDs instead.
- (optional) - array of string
- List of strings containing blocked hex SSIDs. Networks included in this list will not be connectable. Existing connections to networks contained in this list will be disconnected on policy fetch.
BlockedHexSSIDs
- (optional) - array of string
- List of strings containing blocked hex SSIDs. Networks included in this list will not be connectable. Existing connections to networks contained in this list will be disconnected on policy fetch.
DisableNetworkTypes
- (optional) - array of string
- Allowed values are:
- Cellular
- Ethernet
- WiFi
- Tether
- VPN
- List of strings containing disabled network interfaces.
- Adding VPN to the list will disable all VPN types. Android VPN connections may still be established successfully but will be closed shortly after that by the Chrome OS connection manager.
PSIMAdminAssignedAPNs
- (optional) - array of APN
- Setting this field directly will have no effect, as it will be automatically constructed from the provided PSIMAdminAssignedAPNIds, each mapping to a unique APN in the the top-level AdminAPNList. For all pSIMs, CustomAPNList will set to PSIMAdminAssignedAPNs.
PSIMAdminAssignedAPNIds
- (optional) - array of string
- List of custom APN configuration IDs added by the admin that map to APNs that will be applied to all available pSIMs. PSIMAdminAssignedAPNs will be automatically constructed from the provided PSIMAdminAssignedAPNIds, each mapping to a unique APN in the the top-level AdminAPNList.
RecommendedValuesAreEphemeral
- (optional, defaults to false) - boolean
- When this field is set to true, settings of device-wide policy-provided network configurations marked as “Recommended” will be regarded as ephemeral. These settings will be reverted to the policy-recommended (or default) value on reboot (startup), logout, and when the device has been idle.
UserCreatedNetworkConfigurationsAreEphemeral
- (optional, defaults to false) - boolean
- When this field is set to true, device-wide network configurations created by the user will be regarded as ephemeral. These network configurations will be deleted on reboot (startup), logout, and when the device has been idle.
Network Configuration
Field NetworkConfigurations is an array of NetworkConfiguration typed objects.
NetworkConfiguration type
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:
- Determines whether the IP Address configuration is statically configured, see StaticIPConfig, or automatically configured. Note that DHCP here includes the case of configuring through other dynamic IP allocating protocols (e.g. SLAAC) as well.
Metered
- (optional, defaults to “false”) - boolean
- Whether the network should be considered metered. This may affect auto update frequency, and may be used as a hint for apps to conserve data. When not specified, the system will set this to the detected value.
TrafficCounterResetTime
- (optional, defaults to “0”) - double
- A UTC timestamp, in milliseconds, representing when the traffic counters for a Service were last reset. The timestamp's value equals the number of milli- seconds since the Windows epoch (1601-01-01 00:00:00 UTC).
NameServersConfigType
- (optional if Remove is false, otherwise ignored. Defaults to DHCP if IPAddressConfigType is specified) - string
- Allowed values are:
- Determines whether the NameServers configuration is statically configured, see StaticIPConfig, or automatically configured. Note that DHCP here includes the case of configuration through other dynamic nameserver configuring protocols (e.g. IPv6 RDNSS option) as well.
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, Gateway and RoutingPrefix 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.
Cellular
- (required if Type is Cellular, otherwise ignored) - Cellular
- Cellular settings.
Tether
- (required if Type is Tether, otherwise ignored) - Tether
- Tether settings.
Type
- (required if Remove is false, otherwise ignored) - string
- Allowed values are:
- 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).
CheckCaptivePortal
- (optional, defaults to False) - string
- Indicates whether captive portal detection is configured for this
- network. The configurations are:
- False: Captive portal detection is disabled
- True: Captive portal detection is enabled
- HTTPOnly: Captive portal detection is enabled and the portal detector will only use HTTP web probes.
- Allowed values are:
Ethernet networks
For Ethernet connections, Type must be set to Ethernet and the field Ethernet must be set to an object of type Ethernet.
Ethernet type
Authentication
- (optional) - string
- Allowed values are:
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).
IPConfig type
Type
- (optional, defaults to IPv4) - string
- Allowed values are:
- 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. 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.
IncludedRoutes
- (optional) - array of string
- An array of strings, each of which is an IP block in CIDR notation, whose traffic should be handled by the network. Example:
["10.0.0.0/8", "192.168.5.0/24"]. These routes will supplement the existing routes for this network; physical networks (Type Cellular, Ethernet, or WiFi) and L2TP-IPsec VPN networks will by default route all traffic sent to them. ARCVPN and ThirdPartyVPN VPN networks have routes configured by the corresponding VPN app, and OpenVPN VPN networks have routes configured by the OpenVPN server.
ExcludedRoutes
- (optional) - array of string
- An array of strings, each of which is an IP block in CIDR notation, whose traffic should not be handled by the network. Example:
["10.0.0.0/8", "192.168.5.0/24"]. These excluded IP blocks will always take priority over the included blocks in IncludedRoutes.
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.
WiFi type
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.
BSSIDAllowlist
- (optional) - array of string
- Array of BSSIDs that control what APs can be connected to. BSSIDs should be formatted as colon-separated octets (e.g.
"00:01:02:03:04:05"). - Values are:
- Empty list: The WiFi network can associate with any AP.
- Non-empty list: The Wifi network will only associate with the specified BSSes.
- [“00:00:00:00:00:00”]: Special value indicating the network shouldn‘t associate with any AP.
"00:00:00:00:00:00" shouldn’t be a part of any other list of values, otherwise it may cause an error.
BSSIDRequested
- (optional) - string
- BSSID that the AP should connect to. BSSIDs should be formatted as colon-separated octets (e.g.
"00:01:02:03:04:05"). - If the AP cannot connect to the requested BSSID, then it will not fallback to another BSSID and will remain unconnected.
- If BSSIDRequested is empty and BSSIDAllowlist is not, then the WiFi network will follow the values in BSSIDAllowlist
- If BSSIDAllowlist is empty and BSSIDRequested is not, then the WiFi network will follow the value in BSSIDRequested
- If BSSIDRequested and BSSIDAllowlist have a disjoint set of values, then the WiFi network will not connect.
- If BSSIDRequested is also in BSSIDAllowlist, then the network will follow the value in BSSIDRequested
EAP
- (required if Security is: WEP-8021X, WPA-EAP or any value with -Enterprise suffix; otherwise ignored)
- EAP settings - EAP.
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 neither None nor any value indicating that EAP is used for key derivation: WEP-8021X, WPA-EAP, or any value with -Enterprise suffix; otherwise ignored)
- Describes the passphrase for WEP/WPA/WPA2/WPA3 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.
Security
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.
TetheringState
- 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.
VPN type
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:
- ARCVPN
- IPsec
- L2TP-IPsec
- OpenVPN
- ThirdPartyVPN
- Type of the VPN.
IPsec-based VPN types
IPsec type
- If AuthenticationType is set to Cert, ServerCARefs or ServerCARef must be set.
- At most one of ServerCARefs and ServerCARef can be set
L2TP type
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
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:
OpenVPN connections and types
VPN.Type must be OpenVPN.
OpenVPN type
- At most one of ServerCARefs and ServerCARef can be set.
VerifyX509 type
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
- subject See OpenVPN‘s documentation for “--verify-x509-name” for the meaning of each value. Defaults to OpenVPN’s default if not specified.
WireGuard connections and types
VPN.Type must be WireGuard.
WireGuard type
IPAddresses
- (required) - array of string
- Array of IP addresses in string representation (case-insensitive for IPv6) to be configured on the local WireGuard interface.
PrivateKey
- (optional) - string
- The base64 private key of the wireguard client peer. If not set, a random one will be generated.
Peers
WireGuardPeer type
PublicKey
- (required) - string
- The base64 public key of the remote peer.
PresharedKey
- (optional) - string
- A base64 preshared key between client and remote peer for an additional layer of symmetric-key cryptography.
AllowedIPs
- (required) - string
- A comma-separated list of IPv4 prefixes which controls the allowed incoming traffic and set outgoing route for this peer.
Endpoint
- (required) - string
- The physical IP or hostname and port of the peer, separated by a colon.
PersistentKeepalive
- (optional, default to 0) - integer
- A second interval between 1 and 65535 inclusive, of how often an authenticated empty packet will be sent to the peer for the purpose of keeping a stateful firewall or NAT mapping valid persistently. Set to 0 will disable this feature.
Third-party VPN provider based connections and types
VPN.Type must be ThirdPartyVPN.
ThirdPartyVPN type
- ExtensionID
- (required) - string
- The extension ID of the third-party VPN provider used by this network.
- ProviderName
- (optional, read-only) - string
- The name 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
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.
IssuerSubjectPattern type
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.
ProxySettings type
Type
- (required) - string
- Allowed values are:
- PAC indicates Proxy Auto-Configuration. WPAD indicates Web Proxy Autodiscovery.
Manual
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.
ManualProxySettings type
HTTPProxy
SecureHTTPProxy
FTPProxy (Unsupported)
SOCKS
ProxyLocation type
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.
EAP type
- At most one of ServerCARefs and ServerCARef can be set.
AlternativeSubjectName type
- Type
- (required) - string
- Type of the alternative subject name.
- Allowed values are:
- Value
- (required) - string
- Value of the alternative subject name.
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.
Cellular type
FoundNetwork type
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
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
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
LockType
- (required) - string
- Specifies the type of lock in effect, or an empty string if unlocked.
- Allowed values are:
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).
Tether Networks
For Tether connections, Type must be set to Tether and the field Tether must be set to an object of type Tether.
Used for representing a tether hotspot provided by an external device, e.g. a phone.
Tether type
BatteryPercentage
- (optional, read-only) - integer
- The battery percentage of the device providing the tether hotspot in the range [0, 100].
Carrier
- (optional, read-only) - string
- The name of the cellular carrier when the hotspot is provided by a cellular connection.
HasConnectedToHost
- (read-only) - boolean
- If true, the current device has already connected to a Tether network created by the same external device which is providing this Tether network.
SignalStrength
- (optional, read-only) - integer
- The current signal strength for the hotspot's connection in the range [0, 100]. Note that this value refers to the strength of the signal between the external device and its data provider, not the strength of the signal between the current device and the external device.
Bluetooth / WiFi Direct Networks
This format will eventually also cover configuration of Bluetooth and WiFi Direct network technologies, however they are currently not supported.
APNs
Each of the following is an array of APN type objects:
The APN,LastConnectedAttachApnProperty, LastConnectedDefaultApnProperty, and LastGoodAPN fields of Cellular are APN types.
Note that each APN contained in the top-level field AdminAPNList may be referenced by its Id. For example, PSIMAdminAssignedAPNIds and AdminAssignedAPNIds are each an array of APN Ids that reference APNs contained in AdminAPNList.
APN type
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.
Authentication
- (optional) - string
- Type of authentication protocol for sending username and password. Possible values are "", “PAP”, or “CHAP”.
Language
- (optional, required if LocalizedName is provided) - string
- Two letter language code for Localizedname if provided.
Id
- (optional) - string
- A unique identifier for this APN. Must be a non-empty string.
IpType
- (optional) - string
- The IP type of the APN. Possible values are "", “IPv4”, “IPv6”, or “IPv4orIPv6”. If none is provided or the provided string is empty, the IP type is automatic.
ApnTypes
- (optional) - array of string
- The type(s) of the APN. Possible values are “Default” and or “Attach”.
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.
Certificate type
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 a PKCS#12 file.
Remove
- (optional, defaults to false) - boolean
- If true, remove this certificate (only GUID should be set).
Scope
- (optional, default Scope if missing) - Scope
- If this is given, it specifies the scope in which the certificate should be applied.
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 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.
Scope type
- Id
- (required if Type is Extension, otherwise ignored) - string
- If Type is Extension, this is the ID of the chrome extension for which the certificate should be applied.
- Type
- (required) - string
- Allowed values are:
- Extension indicates that the certificate should only be applied in the scope of a chrome extension. Default indicates that the scope the certificate applies in should not be restricted.
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
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.
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:
Placeholders that will only be replaced in user-specific ONC:
- ${LOGIN_ID} - expands to the email address of the user, but before the ‘@’.
- ${LOGIN_EMAIL} - expands to the email address of the user.
Placeholders that will only be replaced in device-wide ONC:
- ${DEVICE_SERIAL_NUMBER} - expands to the serial number of the device.
- ${DEVICE_ASSET_ID} - expands to the administrator-set asset ID of the device.
Placeholders that will only be replaced when a client certificate has been matched by a CertificatePattern:
- ${CERT_SAN_EMAIL} - expands to the first RFC822 SubjectAlternativeName extracted from the client certificate.
- ${CERT_SAN_UPN} - expands to the first OtherName SubjectAlternativeName with OID 1.3.6.1.4.1.311.20.2.3 (UserPrincipalName) extracted from the client certificate.
- ${CERT_SUBJECT_COMMON_NAME} - expands to the ASCII value of the Subject CommonName extracted from the client certificate.
The following SED would properly handle resolution.
Example expansions, assuming the user was bobquail@example.com:
String Substitutions
The values of WiFi.EAP.Password and VPN.L2TP.Password are subject to string substitution. These differ from the String Expansions section above in that an exact match of the substitution variable is required in order to substitute the real value.
Example expansions, assuming the user password was helloworld:
Recommended Values
When a policy is providing ONC configurations, the assumption is that all values are mandatory and immutable. To specify values that can be overridden by a user (e.g. proxy or username), use the Recommended property.
- Recommended
- (optional) - array of string
- The field(s) with the names in the strings in this array are to be treated as recommended settings. Any fields not mentioned in this array remain mandatory. This also means that fields that are not mentioned in the array and also not mentioned in the objects are mandatory and have the default value of the field. If not present, all fields are mandatory. Fields that are objects or arrays of objects included in Recommended will be ignored. In those cases, the nested objects should have their own Recommended fields. A special case is if the string “.” is included in the list. When this is present, it means that the entire certificate or network can be forgotten or deleted by the user. Including the “.” has no implications on the rest of the settings. For instance, a network may have Recommended set to [ “.” ], in which case its settings may not be changed by the user, but the whole network can be forgotten by the user. The “.” is valid in a Certificate object and the NetworkConfiguration object, it is ignored elsewhere.
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.
Examples
GlobalNetworkConfiguration Example
In this example, we only allow managed networks to auto connect and disallow any other networks if a managed network is available. We also block the “Guest” network (hex(“Guest”)=4775657374) and disable Cellular services.
{
"Type": "UnencryptedConfiguration",
"GlobalNetworkConfiguration": {
"AllowOnlyPolicyNetworksToAutoconnect": true,
“AllowOnlyPolicyNetworksToConnect”: false,
“AllowOnlyPolicyNetworksToConnectIfAvailable”: true,
“BlockedHexSSIDs”: [“4775657374”],
"DisableNetworkTypes": ["Cellular"]
}
}
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"
}
Recommended values example
In this example, the EAP Identity and Password are marked as recommended, i.e. they can be edited by the user. All other values are mandatory.
{
"Type": "UnencryptedConfiguration",
"GlobalNetworkConfiguration": {},
"NetworkConfigurations": [
{
"GUID": "{485e6176-dd34-6b6d-1234}",
"Name": "wifi_test",
"Type": "WiFi",
"WiFi": {
"SSID": "wifi_test",
"Security": "WPA-EAP",
"AutoConnect": true,
"EAP": {
"Inner": "MSCHAPv2",
"Outer": "PEAP",
"SaveCredentials": true,
"UseSystemCAs": false,
"Identity": "john-doe",
"Password": "secret-password-123",
"Recommended": ["Identity", "Password"]
}
}
}
}
]
}
Chrome internal format
Internally, Chrome uses a base::Value dictionary format to represent ONC configurations. We refer to two types of dictionaries within the code:
ONC Dictionary A dictionary of key-value pairs similar to the dictionaries under “NetworkConfigurations” described above.
Managed ONC Dictionary A dictionary of key-value pairs where the values are dictionaries containing values from policies and settings described below.
Configurations may combine policy and settings configurations.
Merge rules
If a policy configuration exists, the following rules apply:
- Enforced (default): The policy value is always the effective value.
- Note: User policy supersedes Device policy.
- Note: If a property is not provided by policy it is treated as enforced and the default value is applied.
- Recommended: If a property appears in the Recommended section, it is considered ‘Recommended’. If a UserSetting or SharedSetting value exists, it can be selected as the Effective value.
Managed ONC Dictionary format (“augmented”)
Managed ONC dictionaries contain the keys described under Network Configuration, however the values are dictionaries that may include the following properties:
- Active: For properties that are translated from the configuration manager (e.g. Shill), the ‘active’ value currently in use by the configuration manager.
- Effective: The effective source for the property: UserPolicy, DevicePolicy, UserSetting or SharedSetting.
- UserPolicy: The value provided by the user policy if any.
- DevicePolicy: The value provided by the device policy if any.
- UserSetting: The value set by the logged in user. Only provided if UserEditable is true (i.e. no policy affects the property or the policy provided value is recommended only).
- SharedSetting: The value set for all users of the device. Only provided if DeviceEditiable is true (i.e. no policy affects the property or the policy provided value is recommended only).
- UserEditable: True if a UserPolicy exists and allows the property to be edited (i.e. is a recommended value). Defaults to False.
- DeviceEditable: True if a DevicePolicy exists and allows the property to be edited (i.e. is a recommended value). Defaults to False.
Examples
Property with User policy enforced value.
"Priority": {
"Active": 3,
"Effective": "UserPolicy",
"UserEditable": false,
"UserPolicy": 3,
},
Property with Device policy recommended value and no setting value.
"Priority": {
"Active": 2,
"DeviceEditable": true,
"DevicePolicy": 2,
"Effective": "DevicePolicy",
},
Property with Device policy recommended value and a shared setting value.
"Priority": {
"Active": 1,
"DeviceEditable": true,
"DevicePolicy": 2,
"Effective": "SharedSetting",
"SharedSetting": 1,
},
Property with Device policy and User policy recommended values and a user setting selected as the effective setting.
"Priority": {
"Active": 1
"DeviceEditable": true,
"DevicePolicy": 2,
"Effective": "UserSetting",
"UserEditable": true,
"UserPolicy": 3,
"UserSetting": 1
},
Mojo format
Chrome provides a mojo API for ONC properties: https://source.chromium.org/chromium/chromium/src/+/main:chromeos/services/network_config/public/mojom/cros_network_config.mojom
The mojo API uses a simplified structure for managed properties based on the following assumptions:
- Settings UI and other clients are only interested in the active value and the source of the active / effective value.
- Preserving non policy settings is only interesting if they are the active value. i.e. if a policy value is enforced or a recommended value is used, it is not necessary to preserve any other settings values.
In this simplified format, a descriptive enum is used to describe the effective policy source and whether it is enforced or recommended.
The conversion code can be found in cros_network_config.cc:GetManagedDictionary https://source.chromium.org/chromium/chromium/src/+/main:chromeos/ash/services/network_config/cros_network_config.cc
enum PolicySource {
// The property is not controlled by policy.
kNone,
// The property value came from a user policy and is enforced.
kUserPolicyEnforced,
// The property value came from a device policy and is enforced.
kDevicePolicyEnforced,
// The property value came from a user policy and is recommended.
kUserPolicyRecommended,
// The property value came from a device policy and is recommended.
kDevicePolicyRecommended,
// The property value came from an extension.
kActiveExtension,
};
struct ManagedString {
string active_value;
PolicySource policy_source = kNone;
string? policy_value;
};
Examples
Property with User policy enforced value.
Priority: {
activeValue: 3,
policySource: kUserPolicyEnforced,
policyValue: 3
},
Property with Device policy recommended value and no setting value.
Priority: {
activeValue: 2,
policySource: kDevicePolicyRecommended,
policyValue: 2
},
Property with Device policy recommended value and a setting value.
Priority: {
activeValue: 1,
policySource: DevicePolicyRecommended,
policyValue: 2
},
Property with Device policy and User policy recommended values and a user setting selected as the effective setting. Note: The User policy overrides the Device policy and is all that is represented here. The device configuration is persisted in the device policy itself.
Priority: {
activeValue: 1,
policySource: kUserPolicyRecommended,
policyValue: 3
},
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.