1# Open Network Configuration 2 3[TOC] 4 5## Objective 6 7We would like to create a simple, open, but complete format to describe 8multiple network configurations for WiFi, Ethernet, Cellular, 9Bluetooth/WiFi-Direct, and VPN connections in a single file format, in order 10to simplify and automate network configuration for users. 11 12## Background 13 14Configuring networks is a painful and error-prone experience for users. It 15is a problem shared across desktop, laptop, tablet, and phone users of all 16operating system types. It is exacerbated in business and schools which 17often have complex network configurations (VPNs and 802.1X networking) that 18change often and have many connected devices. Configuration of WiFi is 19still done manually, often by administrators physically standing next to 20users working on devices. Certificate distribution is particularly painful 21which often results in admins instead using passphrases to protect networks 22or using protocols without client certificates that instead use LDAP 23passwords for authentication. Even after networks are configured, updates to 24the network configuration require another round of manual changes, and 25accidental changes by a user or malicious changes by an attacker can break 26connectivity or make connections less private or secure. 27 28## Overview 29 30We propose a single-file format for network configuration that is 31human-readable, can describe all of the common kinds of network 32configurations, supports integrity checking, certificate and key 33provisioning, and updating. The file can be encrypted with a single 34passphrase so that upon entering the passphrase the entire configuration is 35loaded. The format can be described as an open format to enable multiple OS 36vendors to interoperate and share configuration editors. 37 38This format neither supports configuring browser settings nor allows setting 39other types of system policies. 40 41## Infrastructure 42 43A standalone configuration editor will be created, downloadable as a Chrome 44app. This editor will allow creating, modifying, and encrypting an open 45network configuration file in a way that is intuitive for a system 46administrator. 47 48This file format may be delivered to a user and manually imported into a 49device. 50 51This file format may be created by an administrator, stored in a policy 52repository, and automatically pushed to a device. 53 54## Detailed Design 55 56We use JSON format for the files. The fields in a JSON file are always 57case-sensitive, so the exact case of the fields in this section must be 58matched. In addition, the values that are called out as explicit constants 59must also match the case specified (e.g. WiFi must not be written as wifi, 60etc.). This document describes a minimum set of required fields and optional 61fields. Other fields may be created, however, see the 62implementation-specific fields for guidelines for these fields. 63 64The JSON consists of a top level dictionary containing 65a `Type` field which must have either the value 66[EncryptedConfiguration](#EncryptedConfiguration-type) or 67[UnencryptedConfiguration](#UnencryptedConfiguration-type). 68 69For a description of the [EncryptedConfiguration](#EncryptedConfiguration-type) 70type, see the section on [Encrypted Configuration](#Encrypted-Configuration) 71below. 72The [EncryptedConfiguration](#Encrypted-Configuration) format encrypts 73an unencrypted JSON object. 74 75## GUIDs and Updating 76 77This format allows for importing updated network configurations and 78certificates by providing GUIDs to each network configuration and 79certificate so they can be modified or even removed in future updates. 80 81GUIDs are non-empty strings that are meant to be stable and unique. When 82they refer to the same entity, they should be the same between ONC files. No 83two different networks or certificates should have the same GUID, similarly 84a network and certificate should not have the same GUID. A single ONC file 85should not contain the same entity twice (with the same GUID). Failing any 86of these tests indicates the ONC file is not valid. 87 88Any GUID referred to in an ONC file must be present in the same ONC file. In 89particular, it is an error to create a certificate in one ONC file and refer 90to it in a NetworkConfiguration in another ONC file and not define it there, 91even if the previous ONC file has been imported. 92 93## Implementation-specific fields 94 95As there are many different kinds of connections and some that are not yet 96anticipated may require new fields. This format allows arbitrary other 97fields to be added. 98 99Fields and values should follow these general guidelines: 100 101* Certificates (with and without keys) should always be placed in the 102 certificate section - specifically certificate contents should not be 103 placed in fields directly. Referring to certificates should be done using 104 a field whose name ends in Ref and whose value is the GUID of the 105 certificate, or if the certificate is not contained in this file, its 106 pattern can be described using a field ending in Pattern of 107 [CertificatePattern](#CertificatePattern-type) type. 108* Fields should exist in the most-specific object in the hierarchy and 109 should be named CamelCase style. 110* Booleans and integers should be used directly instead of using a 111 stringified version of the type. 112 113Any editor of network configuration information should allows the user to 114modify any fields that are implementation-specific. It may not be present 115directly in the UI but it should be able to import files with such settings 116and leave preserve these settings on export. 117 118## Unencrypted Configuration 119 120When the top level **Type** field 121is *UnencryptedConfiguration*, the top level JSON 122has the [UnencryptedConfiguration](#UnencryptedConfiguration-type) type. 123 124### UnencryptedConfiguration type 125 126* **Type** 127 * (optional, defaults to *UnencryptedConfiguration*) - **string** 128 * Must be *UnencryptedConfiguration*. 129 130* **NetworkConfigurations** 131 * (optional) - [array of NetworkConfiguration](#Network-Configuration) 132 * Describes WiFi, Ethernet, VPN, and wireless connections. 133 134* **Certificates** 135 * (optional) - [array of Certificate](#Certificate-type) 136 * Contains certificates stored in X.509 or PKCS#12 format. 137 138--- 139 * At least one actual configuration field 140 (**NetworkConfigurations** or **Certificates**) should be present, 141 however it should not be considered an error if no such field is present. 142--- 143 144## Global Network Configuration 145 146Field **GlobaNetworkConfiguration** has the [GlobalNetworkConfiguration] 147(#GlobalNetworkConfiguration-type) type. 148 149### GlobalNetworkConfiguration type 150 151The [GlobalNetworkConfiguration](#GlobalNetworkConfiguration-type) contains 152settings which apply to all of the networks that the device may connect to. The 153client supports this only in device-level policy; the client-side ONC validator 154fails if it appears in user policy. 155To avoid bricking devices, these policies will only be enforced in user 156sessions. The login screen ignores these policies and may still be used for 157fetching new policy or logging in. 158A [Help Center article](https://support.google.com/chrome/a/answer/6326250) 159warns admins of the implications of mis-using this policy for Chrome OS. 160 161 162* **AllowOnlyPolicyNetworksToAutoconnect** 163 * (optional, defaults to false) - **boolean** 164 * When this field is present and set to true, on startup the device will 165 only auto connect to those networks that are present in its policy. This 166 is necessary for devices that are used as kiosks, for example, so that 167 they can’t be hijacked by some other user on startup. 168 169* **AllowOnlyPolicyNetworksToConnect** 170 * (optional, defaults to false) - **boolean** 171 * When this field is present and set to true, only networks present in 172 policy may be connected to. This allows schools to enforce that only 173 known-good networks (e.g., filtered student networks) may be used. 174 Existing connections to unmanaged networks will be disconnected on policy 175 fetch. 176 177* **AllowOnlyPolicyNetworksToConnectIfAvailable** 178 * (optional, defaults to false) - **boolean** 179 * When this field is present, set to true and a policy network is in range, 180 only policy networks may be connected to. If no managed network is in 181 range (e.g. user’s home), the device may connect to any network. If 182 enabled and a network scan shows a new policy managed network, the device 183 will automatically switch to the managed network. 184 185* **BlacklistedHexSSIDs** 186 * (optional) - **array of string** 187 * List of strings containing blacklisted hex SSIDs. Networks included in 188 this list will not be connectable. Existing connections to networks 189 contained in this list will be disconnected on policy fetch. 190 191* **DisableNetworkTypes** 192 * (optional) - **array of string** 193 * Allowed values are: 194 * Cellular 195 * Ethernet 196 * WiFi 197 * Tether 198 * List of strings containing disabled network interfaces. 199 200## Network Configuration 201 202Field **NetworkConfigurations** is an array of 203[NetworkConfiguration](#NetworkConfiguration-type) typed objects. 204 205### NetworkConfiguration type 206 207* **Ethernet** 208 * (required if **Type** is *Ethernet*, otherwise ignored) - 209 [Ethernet](#Ethernet-type) 210 * Ethernet settings. 211 212* **GUID** 213 * (required) - **string** 214 * A unique identifier for this network connection, which exists to make it 215 possible to update previously imported configurations. Must be a non-empty 216 string. 217 218* **IPAddressConfigType** 219 * (optional if **Remove** is *false*, otherwise ignored. Defaults to *DHCP* 220 if **NameServersConfigType** is specified) - **string** 221 * Allowed values are: 222 * *DHCP* 223 * *Static* 224 * Determines whether the IP Address configuration is statically configured, 225 see **StaticIPConfig**, or automatically configured 226 using DHCP. 227 228* **NameServersConfigType** 229 * (optional if **Remove** is *false*, otherwise ignored. Defaults to *DHCP* 230 if **IPAddressConfigType** is specified) - **string** 231 * Allowed values are: 232 * *DHCP* 233 * *Static* 234 * Determines whether the NameServers configuration is statically configured, 235 see **StaticIPConfig**, or automatically configured 236 using DHCP. 237 238* **IPConfigs** 239 * (optional for connected networks, read-only) - 240 [array of IPConfig](#IPConfig-type) 241 * Array of IPConfig properties associated with this connection. 242 243* **StaticIPConfig** 244 * (required if **IPAddressConfigType** or **NameServersConfigType** is set 245 to *Static*) - [IPConfig](#IPConfig-type) 246 * Each property set in this IPConfig object overrides the respective 247 parameter received over DHCP. If **IPAddressConfigType** is set to 248 *Static*, **IPAddress**, **Gateway** and **RoutingPrefix** are required. 249 If **NameServersConfigType** is set to *Static*, **NameServers** is 250 required. 251 252* **SavedIPConfig** 253 * (optional for connected networks, read-only) - [IPConfig](#IPConfig-type) 254 * IPConfig property containing the configuration that was received from the 255 DHCP server prior to applying any StaticIPConfig parameters. 256 257* **Name** 258 * (required if **Remove** is *false*, otherwise ignored) - **string** 259 * A user-friendly description of this connection. This name will not be used 260 for referencing and may not be unique. Instead it may be used for 261 describing the network to the user. 262 263* **Remove** 264 * (optional, defaults to *false*) - **boolean** 265 * If set, remove this network configuration (only GUID should be set). 266 267* **ProxySettings** 268 * (optional if **Remove** is *false*, otherwise ignored) - 269 [ProxySettings](#ProxySettings-type) 270 * Proxy settings for this network 271 272* **VPN** 273 * (required if **Type** is *VPN*, otherwise ignored) - [VPN](#VPN-type) 274 * VPN settings. 275 276* **WiFi** 277 * (required if **Type** is *WiFi*, otherwise ignored) - [WiFi](#WiFi-type) 278 * WiFi settings. 279 280* **Cellular** 281 * (required if **Type** is *Cellular*, otherwise ignored) - 282 [Cellular](#Cellular-type) 283 * Cellular settings. 284 285* **Tether** 286 * (required if **Type** is *Tether*, otherwise ignored) - 287 [Tether](#Tether-type) 288 * Tether settings. 289 290* **Type** 291 * (required if **Remove** is *false*, otherwise ignored) - **string** 292 * Allowed values are: 293 * *Cellular* 294 * *Ethernet* 295 * *WiFi* 296 * *VPN* 297 * Indicates which kind of connection this is. 298 299* **ConnectionState** 300 * (optional, read-only) - **string** 301 * The current connection state for this network, provided by the system. 302 Allowed values are: 303 * *Connected* 304 * *Connecting* 305 * *NotConnected* 306 307* **RestrictedConnectivity** 308 * (optional, defaults to *false*, read-only) - **boolean** 309 * True if a connnected network has limited connectivity to the Internet, 310 e.g. a connection is behind a portal or a cellular network is not 311 activated or requires payment. 312 313* **Connectable** 314 * (optional, read-only) - **boolean** 315 * True if the system indicates that the network can be connected to without 316 any additional configuration. 317 318* **ErrorState** 319 * (optional, read-only) - **string** 320 * The current error state for this network, if any. Error states are 321 provided by the system and are not explicitly defined here. They may or 322 may not be human-readable. This field will be empty or absent if the 323 network is not in an error state. 324 325* **MacAddress** 326 * (optional, read-only) - **string** 327 * The MAC address for the network. Only applies to connected non-virtual 328 networks. The format is 00:11:22:AA:BB:CC. 329 330* **Source** 331 * (optional, read-only) - **string** 332 * Indicates whether the network is configured and how it is configured: 333 * *User*: Configured for the active 334 user only, i.e. an unshared configuration. 335 * *Device*: Configured for all users of the 336 device (e.g laptop), i.e. a shared configuration. 337 * *UserPolicy*: Configured by the user 338 policy for the active user. 339 * *DevicePolicy*: Configured by the device 340 policy for the device. 341 * *None*: Not configured, e.g. a visible 342 but unconfigured WiFi network. 343 * Allowed values are: 344 * *User*, 345 * *Device*, 346 * *UserPolicy*, 347 * *DevicePolicy*, 348 * *None* 349 350* **Priority** 351 * (optional) - **integer** 352 * Provides a suggested priority value for this network. May be used by the 353 system to determine which network to connect to when multiple configured 354 networks are available (or may be ignored). 355 356 357## Ethernet networks 358 359For Ethernet connections, **Type** must be set to 360*Ethernet* and the field **Ethernet** must be set to an object of 361type [Ethernet](#Ethernet-type). 362 363### Ethernet type 364 365* **Authentication** 366 * (optional) - **string** 367 * Allowed values are: 368 * *None* 369 * *8021X* 370 371* **EAP** 372 * (required if **Authentication** is *8021X*, otherwise ignored) - 373 [EAP](#EAP-type) 374 * EAP settings. 375 376## IPConfig 377 378Objects of type [IPConfig](#IPConfig-type) are used to report the 379actual IP configuration of a connected network (see 380**IPConfigs**), the IP configuration received from 381DHCP (see **SavedIPConfig**) and to configure a 382static IP configuration (see **StaticIPConfig**). 383 384### IPConfig type 385 386* **Type** 387 * (optional, defaults to *IPv4*) - **string** 388 * Allowed values are: 389 * *IPv4* 390 * *IPv6* 391 * Describes the type of configuration this is. 392 393* **IPAddress** 394 * (optional) - **string** 395 * Describes the IPv4 or IPv6 address of a connection, depending on the value 396 of **Type** field. It should not contain the routing prefix (i.e. should 397 not end in something like /64). 398 399* **RoutingPrefix** 400 * (required if **IPAddress** is set. Otherwise ignored.) - **integer** 401 * `Must be a number in the range [1, 32] for IPv4 and [1, 128] for 402 IPv6 addresses.` 403 * Describes the routing prefix. 404 405* **Gateway** 406 * (required if **IPAddress** is set. Otherwise ignored.) - **string** 407 * Describes the gateway address to use for the configuration. Must match 408 address type specified in **Type** field. If not 409 specified, DHCP values will be used. 410 411* **NameServers** 412 * (optional) - **array of string** 413 * Array of addresses to use for name servers. If not specified, DHCP values 414 will be used. 415 416* **SearchDomains** 417 * (optional) - **array of string** 418 * Array of strings to append to names for resolution. Items in this array 419 should not start with a dot. Example: `["corp.acme.org", "acme.org" ]`. 420 If not specified, DHCP values will be used. 421 422* **IncludedRoutes** 423 * (optional) - **array of string** 424 * An array of strings, each of which is an IP block in CIDR notation, 425 whose traffic should be handled by the network. Example: 426 `["10.0.0.0/8", "192.168.5.0/24"]`. These routes will supplement the 427 existing routes for this network; physical networks (**Type** *Cellular*, 428 *Ethernet*, or *WiFi*) and *L2TP-IPsec* VPN networks will by default route 429 all traffic sent to them. *ARCVPN* and *ThirdPartyVPN* VPN networks have 430 routes configured by the corresponding VPN app, and *OpenVPN* VPN networks 431 have routes configured by the OpenVPN server. 432 433* **ExcludedRoutes** 434 * (optional) - **array of string** 435 * An array of strings, each of which is an IP block in CIDR notation, 436 whose traffic should **not** be handled by the network. Example: 437 `["10.0.0.0/8", "192.168.5.0/24"]`. 438 439* **WebProxyAutoDiscoveryUrl** 440 * (optional if part of **IPConfigs**, read-only) - **string** 441 * The Web Proxy Auto-Discovery URL for this network as reported over DHCP. 442 443 444## WiFi networks 445 446For WiFi connections, **Type** must be set to *WiFi* and the 447field **WiFi** must be set to an object of type [WiFi](#WiFi-type). 448 449### WiFi type 450 451* **AllowGatewayARPPolling** 452 * (optional, defaults to *true*) - **boolean** 453 * Indicaties if ARP polling of default gateway is allowed. 454 When it is allowed, periodic ARP messages will be sent to 455 the default gateway. This is used for monitoring the status 456 of the current connection. 457 458* **AutoConnect** 459 * (optional, defaults to *false*) - **boolean** 460 * Indicating that the network should be connected to automatically when in 461 range. 462 463* **EAP** 464 * (required if **Security** is 465 *WEP-8021X* or *WPA-EAP*, otherwise ignored) - [EAP](#EAP-type) 466 * EAP settings. 467 468* **FTEnabled** 469 * (optional, defaults to *false*) - **boolean** 470 * Indicating if the client should attempt to use Fast Transition with the 471 * network. 472 473* **HexSSID** 474 * (optional if **SSID** is set, if so defaults to a hex representation of 475 **SSID**) - **string** 476 * Hex representation of the network's SSID. 477 478* **HiddenSSID** 479 * (optional, defaults to *false*) - **boolean** 480 * Indicating if the SSID will be broadcast. 481 482* **Passphrase** 483 * (required if **Security** is 484 *WEP-PSK* or *WPA-PSK*, otherwise ignored) - **string** 485 * Describes the passphrase for WEP/WPA/WPA2 486 connections. If *WEP-PSK* is used, the passphrase 487 must be of the format 0x<hex-number>, where <hex-number> is 488 40, 104, 128, or 232 bits. 489 490* **Security** 491 * (required) - **string** 492 * Allowed values are: 493 * *None* 494 * *WEP-PSK* 495 * *WEP-8021X* 496 * *WPA-PSK* 497 * *WPA-EAP* 498 499* **SSID** 500 * (optional if **HexSSID** is set, otherwise ignored) - **string** 501 * Property to access the decoded SSID of a network.<br/> 502 If this field is set, but **HexSSID** is not, 503 its value will be UTF-8 encoded and the hex representation will be 504 assigned to **HexSSID**. To configure a non-UTF-8 505 SSID, field **HexSSID** must be used.<br/> 506 When reading the configuration of a network, both this field and 507 **HexSSID** might be set. Then this field is the 508 decoding of **HexSSID**. If possible the HexSSID is 509 decoded using UTF-8, otherwise an encoding is guessed on a best effort 510 basis. 511 512* **SignalStrength** 513 * (optional, read-only) - **integer** 514 * The current signal strength for this network in the range [0, 100], 515 provided by the system. If the network is not in range this field will 516 be set to '0' or not present. 517 518* **TetheringState** 519 * (optional, read-only, defaults to "NotDetected") - **string** 520 * The tethering state of the WiFi connection. If the connection is 521 tethered the value is "Confirmed". If the connection is suspected to be 522 tethered the value is "Suspected". In all other cases it's 523 "NotDetected". 524 525--- 526 * At least one of the fields **HexSSID** or **SSID** must be present. 527 * If both **HexSSID** and **SSID** are set, the values must be consistent. 528--- 529 530## VPN networks 531 532There are many kinds of VPNs with widely varying configuration options. We 533offer standard configuration options for a few common configurations at this 534time, and may add more later. For all others, implementation specific fields 535should be used. 536 537For VPN connections, **Type** must be set to *VPN* and the 538field **VPN** must be set to an object of type [VPN](#VPN-type). 539 540### VPN type 541 542* **AutoConnect** 543 * (optional, defaults to *false*) - **boolean** 544 * Indicating that the network should be connected to automatically. 545 546* **Host** 547 * (optional) - **string** 548 * Host name or IP address of server to connect to. The only scenario that 549 does not require a host is a VPN that encrypts but does not tunnel 550 traffic. Standalone IPsec (v1 or v2, cert or PSK based -- this is not the 551 same as L2TP over IPsec) is one such setup. For all other types of VPN, 552 the **Host** field is required. 553 554* **IPsec** 555 * (required if **Type** is 556 *IPsec* or *L2TP-IPsec*, otherwise ignored) - [IPsec](#IPsec-type) 557 * IPsec layer settings. 558 559* **L2TP** 560 * (required if **Type** is *L2TP-IPsec*, otherwise ignored) - 561 [L2TP](#L2TP-type) 562 * L2TP layer settings. 563 564* **OpenVPN** 565 * (required if **Type** is *OpenVPN*, otherwise ignored) - 566 [OpenVPN](#OpenVPN-type) 567 * OpenVPN settings. 568 569* **ThirdPartyVPN** 570 * (required if **Type** is *ThirdPartyVPN*, otherwise ignored) - 571 [ThirdPartyVPN](#ThirdPartyVPN-type) 572 * Third-party VPN provider settings. 573 574* **Type** 575 * (required) - **string** 576 * Allowed values are: 577 * *ARCVPN* 578 * *L2TP-IPsec* 579 * *OpenVPN* 580 * *ThirdPartyVPN* 581 * Type of the VPN. 582 583## IPsec-based VPN types 584 585### IPsec type 586 587* **AuthenticationType** 588 * (required) - **string** 589 * Allowed values are: 590 * *Cert* 591 * *PSK* 592 * If *Cert* is used, **ClientCertType** and *ServerCARefs* (or the 593 deprecated *ServerCARef*) must be set. 594 595* **ClientCertPKCS11Id** 596 * (required if **ClientCertType** is *PKCS11Id*, otherwise ignored) - 597 * PKCS#11 identifier in the format slot:key_id. 598 599* **ClientCertPattern** 600 * (required if **ClientCertType** is *Pattern*, otherwise ignored) - 601 [CertificatePattern](#CertificatePattern-type) 602 * Pattern describing the client certificate. 603 604* **ClientCertRef** 605 * (required if **ClientCertType** is *Ref*, otherwise ignored) - **string** 606 * Reference to client certificate stored in certificate section. 607 608* **ClientCertType** 609 * (required if **AuthenticationType** is *Cert*, otherwise ignored) - 610 **string** 611 * Allowed values are 612 * *PKCS11Id* 613 * *Pattern* 614 * *Ref* 615 * *Ref* and *Pattern* indicate that the associated property should be used 616 to identify the client certificate. 617 * *PKCS11Id* is used when representing a certificate in a local store and is 618 only valid when describing a local configuration. 619 620* **EAP** 621 * (optional if **IKEVersion** is 2, otherwise ignored) - [EAP](#EAP-type) 622 * Indicating that EAP authentication should be used with the provided 623 parameters. 624 625* **Group** 626 * (optional if **IKEVersion** is 1, otherwise ignored) - **string** 627 * Group name used for machine authentication. 628 629* **IKEVersion** 630 * (required) - **integer** 631 * Version of IKE protocol to use. 632 633* **PSK** 634 * (optional if **AuthenticationType** is *PSK*, otherwise ignored) 635 - **string** 636 * Pre-Shared Key. If not specified, the user is prompted when connecting. 637 If the value is saved but not known, this may be set to an empty value, 638 indicating that the UI does not need to provide it. 639 640* **SaveCredentials** 641 * (optional if **AuthenticationType** 642 is *PSK*, otherwise ignored, defaults to *false*) - **boolean** 643 * If *false*, require user to enter credentials 644 (PSK) each time they connect. 645 646* **ServerCARefs** 647 * (optional if **AuthenticationType** is *Cert*, otherwise rejected) 648 - **array of string** 649 * Non-empty list of references to CA certificates in **Certificates** to be 650 used for verifying the host's certificate chain. At least one of the CA 651 certificates must match. If this field is set, **ServerCARef** must be 652 unset. 653 654* **ServerCARef** 655 * (optional if **AuthenticationType** is *Cert*, otherwise rejected) - 656 **string** 657 * DEPRECATED, use **ServerCARefs** instead.<br/> 658 Reference to a CA certificate in **Certificates**. Certificate authority 659 to use for verifying connection. If this field is set, **ServerCARefs** 660 must be unset. 661 662* **XAUTH** 663 * (optional if **IKEVersion** is 1, otherwise ignored) - 664 [XAUTH](#XAUTH-type) 665 * Describing XAUTH credentials. XAUTH is not used if this object is not 666 present. 667 668--- 669 * If **AuthenticationType** is set to *Cert*, *ServerCARefs* or *ServerCARef* 670 must be set. 671 * At most one of **ServerCARefs** and **ServerCARef** can be set 672--- 673 674### L2TP type 675 676* **LcpEchoDisabled** 677 * (optional, defaults to *false*) - **boolean** 678 * Disable L2TP connection monitoring via PPP LCP frames. This 679 allows the VPN client to work around server implementations 680 that do not support the LCP echo feature. 681 682* **Password** 683 * (optional) - **string** 684 * User authentication password. If not specified, user is prompted at time 685 of connection. 686 687* **SaveCredentials** 688 * (optional, defaults to *false*) - **boolean** 689 * If *false*, require user to enter credentials 690 each time they connect. 691 692* **Username** 693 * (optional) - **string** 694 * User identity. This value is subject to string expansions. If not 695 specified, user is prompted at time of connection. 696 697### XAUTH type 698 699* **Password** 700 * (optional) - **string** 701 * XAUTH password. If not specified, user is prompted at time of 702 connection. 703 704* **SaveCredentials** 705 * (optional, defaults to *false*) - **boolean** 706 * If *false*, require user to enter credentials 707 each time they connect. 708 709* **Username** 710 * (optional) - **string** 711 * XAUTH user name. This value is subject to string expansions. If not 712 specified, user is prompted at time of connection. 713 714## IPsec IKE v1 VPN connections 715 716**VPN.Type** must 717be *IPsec*, **IKEVersion** 718must be 1. Do not use this for L2TP over IPsec. This may be used for 719machine-authentication-only IKEv1 or for IKEv1 with XAUTH. See 720the [IPsec](#IPsec-type) type described below. 721 722## IPsec IKE v2 VPN connections 723 724**VPN.Type** must 725be *IPsec*, **IKEVersion** 726must be 2. This may be used with EAP-based user authentication. 727 728## L2TP over IPsec VPN connections 729 730There are two major configurations L2TP over IPsec which depend on how IPsec 731is authenticated. In either case **Type** must be *L2TP-IPsec*. 732They are described below. 733 734L2TP over IPsec with pre-shared key: 735 736* The field **IPsec** must be present and have the following settings: 737 * **IKEVersion** must be 1. 738 * **AuthenticationType** must be PSK. 739 * **XAUTH** must not be set. 740 741* The field **L2TP** must be present. 742 743 744## OpenVPN connections and types 745 746**VPN.Type** must be *OpenVPN*. 747 748### OpenVPN type 749 750* **Auth** 751 * (optional, defaults to *SHA1*) - **string** 752 753* **AuthRetry** 754 * (optional, defaults to *none*) - **string** 755 * Allowed values are: 756 * *none* = Fail with error on retry 757 * *nointeract* = retry without asking for authentication 758 * *interact* = ask again for authentication each time 759 * Controls how OpenVPN responds to username/password verification failure. 760 761* **AuthNoCache** 762 * (optional, defaults to *false*) - **boolean** 763 * Disable caching of credentials in memory. 764 765* **Cipher** 766 * (optional, defaults to *BF-CBC*) - **string** 767 * Cipher to use. 768 769* **ClientCertPKCS11Id** 770 * (required if **ClientCertType** is *PKCS11Id*, otherwise ignored) - 771 * PKCS#11 identifier in the format slot:key_id. 772 773* **ClientCertPattern** 774 * (required if **ClientCertType** is *Pattern*, otherwise ignored) - 775 [CertificatePattern](#CertificatePattern-type) 776 * Pattern to use to find the client certificate. 777 778* **ClientCertRef** 779 * (required if **ClientCertType** is *Ref*, otherwise ignored) - **string** 780 * Reference to client certificate stored in certificate section. 781 782* **ClientCertType** 783 * (required) - **string** 784 * Allowed values are 785 * *PKCS11Id* 786 * *Pattern* 787 * *Ref* 788 * *None* 789 * *Ref* and *Pattern* indicate that the associated property should be used 790 to identify the client certificate. 791 * *PKCS11Id* is used when representing a certificate in a local store and is 792 only valid when describing a local configuration. 793 * *None* indicates that the server is configured to not require client 794 certificates. 795 796* **CompLZO** 797 * (optional, defaults to *adaptive*) - **string** 798 * DEPRECATED, use **Compress** with *lzo* option instead. 799 * Decides to fast LZO compression with *true* 800 and *false* as other values. 801 802* **CompNoAdapt** 803 * (optional, defaults to *false*) - **boolean** 804 * DEPRECATED, do not use. 805 * Disables adaptive compression. 806 807* **Compress** 808 * (optional, defaults to *None*) - **string** 809 * Specifies the compression algorithm to be used. 810 * Allowed values are: 811 * *None* 812 * *FramingOnly* 813 * *LZ4* 814 * *LZ4-V2* 815 * *LZO* 816 817* **ExtraHosts** 818 * (optional) - **array of string** 819 * List of hosts to try in order if client is unable to connect to the 820 * primary host. 821 822* **IgnoreDefaultRoute** 823 * (optional, defaults to *false*) - **boolean** 824 * Omits a default route to the VPN gateway while the connection is active. 825 The client will create a default route through the VPN **only** if the 826 OpenVPN server pushes a "redirect-gateway" option. Setting this value to 827 *true* will cause the client to ignore any "redirect-gateway" option 828 provided by the server, ensuring that no default route is available for 829 the VPN. 830 831* **KeyDirection** 832 * (optional) - **string** 833 * Passed as --key-direction. 834 835* **NsCertType** 836 * (optional) - **string** 837 * If set, checks peer certificate type. Should only be set 838 to *server* if set. 839 840* **OTP** 841 * (optional if **UserAuthenticationType** is *OTP*, *PasswordAndOTP* or 842 unset, otherwise ignored, defaults to empty string) - **string** 843 * If **UserAuthenticationType** is 844 *OTP* or *PasswordAndOTP* 845 and this field is not set, the user will be asked for an OTP. 846 The OTP is never persisted and must be provided on every connection 847 attempt. 848 849* **Password** 850 * (optional if **UserAuthenticationType** is *Password*, *PasswordAndOTP* 851 or unset, otherwise ignored, defaults to empty string) - **string** 852 * If **UserAuthenticationType** is 853 *Password* or 854 *PasswordAndOTP* and this field is not set, the user 855 will be asked for a password. 856 If **SaveCredentials** is 857 *true*, the password is persisted for future 858 connection attempts. Otherwise it is not persisted but might still be 859 reused for consecutive connection attempts (opposed to an OTP, which will 860 never be reused). 861 862* **Port** 863 * (optional, defaults to *1194*) - **integer** 864 * Port for connecting to server. 865 866* **Proto** 867 * (optional, defaults to *udp*) - **string** 868 * Protocol for communicating with server. 869 870* **PushPeerInfo** 871 * (optional, defaults to *false*) - **boolean** 872 873* **RemoteCertEKU** 874 * (optional) - **string** 875 * Require that the peer certificate was signed with this explicit extended 876 key usage in oid notation. 877 878* **RemoteCertKU** 879 * (optional, defaults to []) - **array of string** 880 * Require the given array of key usage numbers. These are strings that are 881 hex encoded numbers. 882 883* **RemoteCertTLS** 884 * (optional, defaults to *server*) - **string** 885 * Allowed values are: 886 * *none* 887 * *server* 888 * Require peer certificate signing based on RFC3280 TLS rules. 889 890* **RenegSec** 891 * (optional, defaults to *3600*) - **integer** 892 * Renegotiate data channel key after this number of seconds. 893 894* **SaveCredentials** 895 * (optional, defaults to *false*) - **boolean** 896 * If *false*, require user to enter credentials 897 each time they connect. 898 899* **ServerCAPEMs** 900 * (optional) - **array of string** 901 * Non-empty list of CA certificates in PEM format, If this field is set, 902 **ServerCARef** and **ServerCARefs** must be unset. 903 904* **ServerCARefs** 905 * (optional) - **array of string** 906 * Non-empty list of references to CA certificates in **Certificates** to be 907 used for verifying the host's certificate chain. At least one of the CA 908 certificates must match. See also OpenVPN's command line option "--ca". 909 If this field is set, **ServerCARef** must be unset. 910 911* **ServerCARef** 912 * (optional) - **string** 913 * DEPRECATED, use **ServerCARefs** instead.<br/> 914 Reference to a CA certificate in **Certificates**. Certificate authority 915 to use for verifying connection. If this field is set, **ServerCARefs** 916 must be unset. 917 918* **ServerCertRef** 919 * (optional) - **string** 920 * Reference to a certificate. Peer's signed certificate. 921 922* **ServerPollTimeout** 923 * (optional) - **integer** 924 * Spend no more than this number of seconds before trying the next server. 925 926* **Shaper** 927 * (optional) - **integer** 928 * If not specified no bandwidth limiting, otherwise limit bandwidth of 929 outgoing tunnel data to this number of bytes per second. 930 931* **StaticChallenge** 932 * (optional) - **string** 933 * String is used in static challenge response. Note that echoing is always 934 done. 935 936* **TLSAuthContents** 937 * (optional) - **string** 938 * If not set, tls auth is not used. If set, this is the TLS Auth key 939 contents (usually starts with "-----BEGIN OpenVPN Static Key..." 940 941* **TLSRemote** 942 * (optional) - **string** 943 * If set, only allow connections to server hosts with X509 name or common 944 name equal to this string. 945 946* **TLSVersionMin** 947 * (optional) - **string** 948 * If set, specifies the minimum TLS protocol version used by OpenVPN. 949 950* **UserAuthenticationType** 951 * (optional, defaults to *None*) - **string** 952 * Allowed values are: 953 * *None* 954 * *Password* 955 * *PasswordAndOTP* 956 * *OTP* 957 * Determines the required form of user authentication: 958 * *PasswordAndOTP*: This VPN requires a password 959 and an OTP (possibly empty). Both will be send to the server in the 960 'password' response using the SCRv1 encoding. 961 * *Password*: This VPN requires only a password, 962 which will be send without modification to the server in the 'password' 963 response (no CRv1 or SCRv1 encoding). 964 * *OTP*: This VPN requires only an OTP, which 965 will be send without modification to the server in the 'password' 966 response (no CRv1 or SCRv1 encoding). 967 * *None*: Neither password nor OTP are required. 968 No password request from the server is expected. 969 If not set, the user can provide a password and an OTP (both not 970 mandatory) and the network manager will send both in the SCRv1 encoding, 971 when the server sends a static-challenge. If the server does not send a 972 static-challenge, the client will reply with only the password (without 973 any encoding). This behavior is deprecated and new configurations should 974 explicitly set one of the above values. 975 976 See the fields **Password** and 977 **OTP** for configuring the password and OTP. 978 979* **Username** 980 * (optional) - **string** 981 * OpenVPN user name. This value is subject to string expansions. If not 982 specified, user is prompted at time of connection. 983 984* **Verb** 985 * (optional) - **string** 986 * Verbosity level, defaults to OpenVpn's default if not specified. 987 988* **VerifyHash** 989 * (optional) - **string** 990 * If set, this value is passed as the "--verify-hash" argument to OpenVPN, 991 which specifies the SHA1 fingerprint for the level-1 certificate. 992 993* **VerifyX509** 994 * (optional) - [VerifyX509](#VerifyX509-type) 995 * If set, the "--verify-x509-name" argument is passed to OpenVPN with the 996 values of this object and only connections will be accepted if a host's 997 X.509 name is equal to the given name. 998 999--- 1000 * At most one of **ServerCARefs** and **ServerCARef** can be set. 1001--- 1002 1003### VerifyX509 type 1004 1005* **Name** 1006 * (required) - **string** 1007 * The name that the host's X.509 name is compared to. Which host name is 1008 compared depends on the value of **Type**. 1009 1010* **Type** 1011 * (optional) - **string** 1012 * Determines which of the host's X.509 names will be verified. 1013 * Allowed values are: 1014 * *name* 1015 * *name-prefix* 1016 * *subject* 1017 See OpenVPN's documentation for "--verify-x509-name" for the meaning of 1018 each value. Defaults to OpenVPN's default if not specified. 1019 1020## Third-party VPN provider based connections and types 1021 1022**VPN.Type** must be *ThirdPartyVPN*. 1023 1024### ThirdPartyVPN type 1025 1026* **ExtensionID** 1027 * (required) - **string** 1028 * The extension ID of the third-party VPN provider used by this network. 1029* **ProviderName** 1030 * (optional, read-only) - **string** 1031 * The name of the third-party VPN provider used by this network. 1032 1033 1034## Client certificate patterns 1035 1036In order to allow clients to securely key their private keys and request 1037certificates through PKCS#10 format or through a web flow, we provide 1038alternative CertificatePattern types. The 1039 1040### CertificatePattern type 1041 1042* **IssuerCARef** 1043 * (optional) - **array of string** 1044 * Array of references to certificates. At least one must have signed the 1045 client certificate. 1046 1047* **Issuer** 1048 * (optional) - [IssuerSubjectPattern](#IssuerSubjectPattern-type) 1049 * Pattern to match the issuer X.509 settings against. If not specified, the 1050 only checks done will be a signature check against 1051 the **IssuerCARef** field. Issuer of the 1052 certificate must match this field exactly to match the pattern. 1053 1054* **Subject** 1055 * (optional) - [IssuerSubjectPattern](#IssuerSubjectPattern-type) 1056 * Pattern to match the subject X.509 settings against. If not specified, the 1057 subject settings are not checked and any certificate matches. Subject of 1058 the certificate must match this field exactly to match the pattern. 1059 1060* **EnrollmentURI** 1061 * (optional) - **array of string** 1062 * If no certificate matches this CertificatePattern, the first URI from this 1063 array with a recognized scheme is navigated to, with the intention this 1064 informs the user how to either get the certificate or gets the certificate 1065 for the user. For instance, the array may be [ 1066 "chrome-extension://asakgksjssjwwkeielsjs/fetch-client-cert.html", 1067 "http://intra/connecting-to-wireless.html" ] so that for Chrome browsers a 1068 Chrome app or extension is shown to the user, but for other browsers, a 1069 web URL is shown. 1070 1071### IssuerSubjectPattern type 1072 1073* **CommonName** 1074 * (optional) - **string** 1075 * Certificate subject's commonName must match this string if present. 1076 1077* **Locality** 1078 * (optional) - **string** 1079 * Certificate subject's location must match this string if present. 1080 1081* **Organization** 1082 * (optional) - **string** 1083 * At least one of certificate subject's organizations must match this string 1084 if present. 1085 1086* **OrganizationalUnit** 1087 * (optional) - **string** 1088 * At least one of certificate subject's organizational units must match this 1089 string if present. 1090 1091--- 1092 * One field in **Subject**, **Issuer**, or **IssuerCARef** 1093 must be given for a [CertificatePattern](#CertificatePattern-type) typed 1094 field to be valid. 1095 * For a certificate to be considered matching, it must match all 1096 the fields in the certificate pattern. If multiple certificates match, the 1097 certificate with the latest issue date that is still in the past, and 1098 hence valid, will be used. 1099 * If **EnrollmentURI** is not given and no match is 1100 found to this pattern, the importing tool may show an error to the user. 1101--- 1102 1103## Proxy settings 1104 1105Every network can be configured to use a proxy. 1106 1107### ProxySettings type 1108 1109* **Type** 1110 * (required) - **string** 1111 * Allowed values are: 1112 * *Direct*, 1113 * *Manual* 1114 * *PAC* 1115 * *WPAD* 1116 * *PAC* indicates Proxy Auto-Configuration. 1117 *WPAD* indicates Web Proxy Autodiscovery. 1118 1119* **Manual** 1120 * (required if **Type** is *Manual*, otherwise ignored) - 1121 [ManualProxySettings](#ManualProxySettings-type) 1122 * Manual proxy settings. 1123 1124* **ExcludeDomains** 1125 * (optional if **Type** is *Manual*, otherwise ignored) - 1126 **array of string** 1127 * Domains and hosts for which to exclude proxy settings. 1128 1129* **PAC** 1130 * (required if **Type** is *PAC*, otherwise ignored) - **string** 1131 * URL of proxy auto-config file. 1132 1133### ManualProxySettings type 1134 1135* **HTTPProxy** 1136 * (optional) - [ProxyLocation](#ProxyLocation-type) 1137 * settings for HTTP proxy. 1138 1139* **SecureHTTPProxy** 1140 * (optional) - [ProxyLocation](#ProxyLocation-type) 1141 * settings for secure HTTP proxy. 1142 1143* **FTPProxy (Unsupported)** 1144 * (optional) - [ProxyLocation](#ProxyLocation-type) 1145 * settings for FTP proxy 1146 1147* **SOCKS** 1148 * (optional) - [ProxyLocation](#ProxyLocation-type) 1149 * settings for SOCKS proxy. 1150 1151### ProxyLocation type 1152 1153* **Host** 1154 * (required) - **string** 1155 * Host (or IP address) to use for proxy 1156 1157* **Port** 1158 * (required) - **integer** 1159 * Port to use for proxy 1160 1161## EAP configurations 1162 1163For networks with 802.1X authentication, an [EAP](#EAP-type) 1164type exists to configure the authentication. 1165 1166### EAP type 1167 1168* **AnonymousIdentity** 1169 * (optional if **Outer** is 1170 *PEAP* or *EAP-TTLS*, otherwise ignored) - **string** 1171 * For tunnelling protocols only, this indicates the identity of the user 1172 presented to the outer protocol. This value is subject to string 1173 expansions. If not specified, use empty string. 1174 1175* **ClientCertPKCS11Id** 1176 * (required if **ClientCertType** is *PKCS11Id*, otherwise ignored) - 1177 * PKCS#11 identifier in the format slot:key_id. 1178 1179* **ClientCertPattern** 1180 * (required if **ClientCertType** is *Pattern*, otherwise ignored) - 1181 [CertificatePattern](#CertificatePattern-type) 1182 * Pattern to use to find the client certificate. 1183 1184* **ClientCertRef** 1185 * (required if **ClientCertType** is *Ref*, otherwise ignored) - **string** 1186 * Reference to client certificate stored in certificate section. 1187 1188* **ClientCertType** 1189 * (optional) - **string** 1190 * Allowed values are: 1191 * *PKCS11Id* 1192 * *Pattern* 1193 * *Ref* 1194 * *None* 1195 * *Ref* and *Pattern* indicate that the associated property should be used 1196 to identify the client certificate. 1197 * *PKCS11Id* is used when representing a certificate in a local store and is 1198 only valid when describing a local configuration. 1199 * *None* indicates that the server is configured to not require client 1200 certificates. 1201 1202* **Identity** 1203 * (optional) - **string** 1204 * Identity of user. For tunneling outer protocols 1205 (*PEAP*, *EAP-TTLS*, and 1206 *EAP-FAST*), this is used to authenticate inside 1207 the tunnel, and **AnonymousIdentity** is used for 1208 the EAP identity outside the tunnel. For non-tunneling outer protocols, 1209 this is used for the EAP identity. This value is subject to string 1210 expansions. 1211 1212* **Inner** 1213 * (optional if **Outer** is *EAP-FAST*, *EAP-TTLS* or *PEAP*, otherwise 1214 ignored, defaults to *Automatic*) - **string** 1215 * Allowed values are: 1216 * *Automatic* 1217 * *MD5* 1218 * *MSCHAP* 1219 * *MSCHAPv2* 1220 * *PAP* 1221 * *CHAP* 1222 * *GTC* 1223 * For tunneling outer protocols. 1224 1225* **Outer** 1226 * (required) - **string** 1227 * Allowed values are: 1228 * *LEAP* 1229 * *EAP-AKA* 1230 * *EAP-FAST* 1231 * *EAP-TLS* 1232 * *EAP-TTLS* 1233 * *EAP-SIM* 1234 * *PEAP* 1235 1236* **Password** 1237 * (optional) - **string** 1238 * Password of user. If not specified, defaults to prompting the user. 1239 1240* **SaveCredentials** 1241 * (optional, defaults to *false*) - **boolean** 1242 * If *false*, require user to enter credentials each time they connect. 1243 Specifying **Identity** and/or **Password** when **SaveCredentials** 1244 is *false* is not allowed. 1245 1246* **ServerCAPEMs** 1247 * (optional) - **array of string** 1248 * Non-empty list of CA certificates in PEM format, If this field is set, 1249 **ServerCARef** and **ServerCARefs** must be unset. 1250 1251* **ServerCARefs** 1252 * (optional) - **array of string** 1253 * Non-empty list of references to CA certificates in **Certificates** to be 1254 used for verifying the host's certificate chain. At least one of the CA 1255 certificates must match. If this field is set, **ServerCARef** must be 1256 unset. If neither **ServerCARefs** nor **ServerCARef** is set, the client 1257 does not check that the server certificate is signed by a specific CA. 1258 A verification using the system's CA certificates may still apply. 1259 See **UseSystemCAs** for this. 1260 1261* **ServerCARef** 1262 * (optional) - **string** 1263 * DEPRECATED, use **ServerCARefs** instead.<br/> 1264 Reference to a CA certificate in **Certificates**. 1265 * If this field is set, **ServerCARefs** must be unset. 1266 If neither **ServerCARefs** nor **ServerCARef** is set, the client does 1267 not check that the server certificate is signed by a specific CA. 1268 A verification using the system's CA certificates may still apply. 1269 See **UseSystemCAs** for this. 1270 1271* **SubjectMatch** 1272 * (optional) - **string** 1273 * WiFi only. A substring which a remote RADIUS service certificate subject 1274 name must contain in order to connect. 1275 1276* **SubjectAlternativeNameMatch** 1277 * (optional) - [array of AlternativeSubjectName](#AlternativeSubjectName-type) 1278 * WiFi only. A list of alternative subject names to be matched against the 1279 alternative subject name of an authentication server certificate. 1280 1281* **TLSVersionMax** 1282 * (optional) - **string** 1283 * Sets the maximum TLS protocol version used by the OS for EAP. 1284 This is only needed when connecting to an AP with a buggy TLS 1285 implementation, as the protocol will normally auto-negotiate. 1286 * Allowed values are: 1287 * *1.0* 1288 * *1.1* 1289 * *1.2* 1290 1291* **UseSystemCAs** 1292 * (optional, defaults to *true*) - **boolean** 1293 * Required server certificate to be signed by "system default certificate 1294 authorities". If both **ServerCARefs** (or **ServerCARef**) 1295 and **UseSystemCAs** are supplied, a server 1296 certificate will be allowed if it either has a chain of trust to a system 1297 CA or to one of the given CA certificates. If **UseSystemCAs** 1298 is *false*, and no **ServerCARef** is set, the certificate 1299 must be a self signed certificate, and no CA signature is required. 1300 1301* **UseProactiveKeyCaching** 1302 * (optional, defaults to *false*) - **boolean** 1303 * Indicates whether Proactive Key Caching (also known as Opportunistic 1304 Key Caching) should be used on a per-service basis. 1305 1306--- 1307 * At most one of **ServerCARefs** and **ServerCARef** 1308 can be set. 1309--- 1310 1311### AlternativeSubjectName type 1312 1313* **Type** 1314 * (required) - **string** 1315 * Type of the alternative subject name. 1316 * Allowed values are: 1317 * *EMAIL* 1318 * *DNS* 1319 * *URI* 1320* **Value** 1321 * (required) - **string** 1322 * Value of the alternative subject name. 1323 1324## Cellular Networks 1325 1326For Cellular connections, **Type** must be set to *Cellular* and the 1327field **Cellular** must be set to an object of type [Cellular](#Cellular-type). 1328 1329Currently only used for representing an existing configuration; 1330ONC configuration of of **Cellular** networks is not yet supported. 1331 1332### Cellular type 1333 1334* **AutoConnect** 1335 * (optional, defaults to *false*) - **boolean** 1336 * Indicating that the network should be connected to automatically when 1337 possible. Note, that disabled **AllowRoaming** 1338 takes precedence over autoconnect. 1339 1340* **APN** 1341 * (optional) - [APN](#APN-type) 1342 * Currently active [APN](#APN-type) object to be used with a 1343 GSM carrier for making data connections. 1344 1345* **APNList** 1346 * (optional) - [array of APN](#APN-type) 1347 * List of available APN configurations. 1348 1349* **ActivationType** 1350 * (optional) - **string** 1351 * Activation type. 1352 1353* **ActivationState** 1354 * (optional, read-only) - **string** 1355 * Carrier account activation state. 1356 * Allowed values are: 1357 * *Activated* 1358 * *Activating* 1359 * *NotActivated* 1360 * *PartiallyActivated* 1361 1362* **AllowRoaming** 1363 * (optional) - **boolean** 1364 * Whether cellular data connections are allowed when the device is roaming. 1365 1366* **Carrier** 1367 * (optional, read-only) - **string** 1368 * The name of the carrier for which the device is configured. 1369 1370* **ESN** 1371 * (optional, read-only) - **string** 1372 * The Electronic Serial Number of the cellular modem. 1373 1374* **Family** 1375 * (optional, read-only) - **string** 1376 * Technology family. 1377 * Allowed values are: 1378 * *CDMA* 1379 ** GSM* 1380 1381* **FirmwareRevision** 1382 * (optional, read-only) - **string** 1383 * The revision of firmware that is loaded in the modem. 1384 1385* **FoundNetworks** 1386 * (optional, read-only, provided only if **Family** is *GSM*) - 1387 [array of FoundNetwork](#FoundNetwork-type) 1388 * The list of cellular netwoks found in the most recent scan operation. 1389 1390* **HardwareRevision** 1391 * (optional, read-only) - **string** 1392 * The hardware revision of the cellular modem. 1393 1394* **HomeProvider** 1395 * (optional, read-only) - [CellularProvider](#CellularProvider-type) 1396 * Description of the operator that issued the SIM card currently installed 1397 in the modem. 1398 1399* **ICCID** 1400 * (optional, read-only, provided only if **Family** is *GSM* 1401 or **NetworkTechnology** 1402 is *LTE*) - **string** 1403 * For GSM / LTE modems, the Integrated Circuit Card Identifer of the SIM 1404 card installed in the device. 1405 1406* **IMEI** 1407 * (optional, read-only) - **string** 1408 * The International Mobile Equipment Identity of the cellular modem. 1409 1410* **IMSI** 1411 * (optional, read-only, provided only if **Family** is *GSM*) - **string** 1412 * For GSM modems, the International Mobile Subscriber Identity of the SIM 1413 card installed in the device. 1414 1415* **LastGoodAPN** 1416 * (optional, read-only) - [APN](#APN-type) 1417 * The APN information used in the last successful connection attempt. 1418 1419* **Manufacturer** 1420 * (optional, read-only) - **string** 1421 * The manufacturer of the cellular modem. 1422 1423* **MDN** 1424 * (optional) - **string** 1425 * The Mobile Directory Number (i.e., phone number) of the device. 1426 1427* **MEID** 1428 * (optional, read-only, provided only if **Family** is *CDMA*) - **string** 1429 * For CDMA modems, the Mobile Equipment Identifer of the cellular modem. 1430 1431* **MIN** 1432 * (optional, read-only) - **string** 1433 * The Mobile Identification Number of the device. 1434 1435* **ModelID** 1436 * (optional, read-only) - **string** 1437 * The hardware model of the cellular modem. 1438 1439* **NetworkTechnology** 1440 * (optional, read-only) - **string** 1441 * If the modem is registered on a network, then this is set to the 1442 network technology currently in use. 1443 * Allowed values are: 1444 * *CDMA1XRTT* 1445 * *EDGE* 1446 * *EVDO* 1447 * *GPRS* 1448 * *GSM* 1449 * *HSPA* 1450 * *HSPAPlus* 1451 * *LTE* 1452 * *LTEAdvanced* 1453 * *UMTS* 1454 1455* **PaymentPortal** 1456 * (optional, read-only) - [PaymentPortal](#PaymentPortal-type) 1457 * Properties describing the online payment portal (OLP) at which a user can 1458 sign up for or modify a mobile data plan. 1459 1460* **RoamingState** 1461 * (optional, read-only) - **string** 1462 * The roaming status of the cellular modem on the current network. 1463 * Allowed values are: 1464 * *Home*, 1465 * *Roaming* 1466 * *Required* - the provider has no home network 1467 1468* **Scanning** 1469 * (optional, read-only) - **boolean** 1470 * True when a cellular network scan is in progress. 1471 1472* **ServingOperator** 1473 * (optional, read-only, provided only if **Family** is *GSM*) - 1474 [CellularProvider](#CellularProvider-type) 1475 * Description of the operator on whose network the modem is currently 1476 registered 1477 1478* **SignalStrength** 1479 * (optional, read-only) - **integer** 1480 * The current signal strength for this network in the range [0, 100], 1481 provided by the system. If the network is not in range this field will 1482 be set to '0' or not present. 1483 1484* **SIMLockStatus** 1485 * (optional, read-only, provided only if **Family** is *GSM*) - 1486 [SIMLockStatus](#SIMLockStatus-type) 1487 * For GSM modems, a dictionary containing two properties describing the 1488 state of the SIM card lock. 1489 1490* **SIMPresent** 1491 * (optional, read-only, provided only if **Family** is *GSM* 1492 or **NetworkTechnology** 1493 is *LTE*) - **boolean** 1494 * For GSM or LTE modems, indicates whether a SIM card is present or not. 1495 1496* **SupportNetworkScan** 1497 * (optional, read-only) - **boolean** 1498 * True if the cellular network supports scanning. 1499 1500 1501### APN type 1502 1503* **AccessPointName** 1504 * (required) - **string** 1505 * The access point name used when making connections. 1506 1507* **Name** 1508 * (optional) - **string** 1509 * Description of the APN. 1510 1511* **LocalizedName** 1512 * (optional) - **string** 1513 * Localized description of the APN. 1514 1515* **Username** 1516 * (optional) - **string** 1517 * Username for making connections if required. 1518 1519* **Password** 1520 * (optional) - **string** 1521 * Password for making connections if required. 1522 1523* **Authentication** 1524 * (optional) - **string** 1525 * Type of authentication protocol for sending username and password. 1526 1527* **Language** 1528 * (optional, rquired if **LocalizedName** is provided) - **string** 1529 Two letter language code for Localizedname if provided. 1530 1531### FoundNetwork type 1532 1533* **Status** 1534 * (required) - **string** 1535 * The availability of the network. 1536 1537* **NetworkId** 1538 * (required) - **string** 1539 * The network id in the form MCC/MNC (without the '/'). 1540 1541* **Technology** 1542 * (required) - **string** 1543 * Access technology used by the network, 1544 e.g. "GSM", "UMTS", "EDGE", "HSPA", etc. 1545 1546* **ShortName** 1547 * (optional) - **string** 1548 * Short-format name of the network operator. 1549 1550* **LongName** 1551 * (optional) - **string** 1552 * Long-format name of the network operator. 1553 1554### PaymentPortal type 1555 1556* **Method** 1557 * (required) - **string** 1558 * The HTTP method to use, "GET" or "POST" 1559 1560* **PostData** 1561 * (required if **Method** is *POST*, otherwise ignored) - **string** 1562 * The postdata to send. 1563 1564* **Url** 1565 * (required) - **string** 1566 * The URL for the portal. 1567 1568### CellularProvider type 1569 1570* **Name** 1571 * (required) - **string** 1572 * The operator name. 1573 1574* **Code** 1575 * (required) - **string** 1576 * The network id in the form MCC/MNC (without the '/'). 1577 1578* **Country** 1579 * (optional) - **string** 1580 * The two-letter country code. 1581 1582### SIMLockStatus type 1583 1584* **LockType** 1585 * (required) - **string** 1586 * Specifies the type of lock in effect, or an empty string if unlocked. 1587 * Allowed values are: 1588 * *sim-pin*, 1589 * *sim-puk* 1590 1591* **LockEnabled** 1592 * (required) - **boolean** 1593 * Indicates whether SIM locking is enabled 1594 1595* **RetriesLeft** 1596 * (optional) - **integer** 1597 * If **LockType** is empty 1598 or *sim-pin*, then this property represents 1599 the number of attempts remaining to supply a correct PIN before the 1600 PIN becomes blocked, at which point a PUK provided by the carrier would 1601 be necessary to unlock the SIM (and **LockType** 1602 changes to *sim-puk*). 1603 1604 1605## Tether Networks 1606 1607For Tether connections, **Type** must be set to *Tether* and the 1608field **Tether** must be set to an object of type [Tether](#Tether-type). 1609 1610Used for representing a tether hotspot provided by an external device, e.g. 1611a phone. 1612 1613### Tether type 1614 1615* **BatteryPercentage** 1616 * (optional, read-only) - **integer** 1617 * The battery percentage of the device providing the tether hotspot in the 1618 range [0, 100]. 1619 1620* **Carrier** 1621 * (optional, read-only) - **string** 1622 * The name of the cellular carrier when the hotspot is provided by a 1623 cellular connection. 1624 1625* **HasConnectedToHost** 1626 * (read-only) - **boolean** 1627 * If *true*, the current device has already connected to a Tether network 1628 created by the same external device which is providing this Tether 1629 network. 1630 1631* **SignalStrength** 1632 * (optional, read-only) - **integer** 1633 * The current signal strength for the hotspot's connection in the range 1634 [0, 100]. Note that this value refers to the strength of the signal 1635 between the external device and its data provider, not the strength of the 1636 signal between the current device and the external device. 1637 1638 1639## Bluetooth / WiFi Direct Networks 1640 1641This format will eventually also cover configuration of Bluetooth and WiFi 1642Direct network technologies, however they are currently not supported. 1643 1644 1645## Certificates 1646 1647Certificate data is stored in a separate section. Each certificate may be 1648referenced from within the NetworkConfigurations array using a certificate 1649reference. A certificate reference is its GUID. 1650 1651The top-level field **Certificates** is an array of 1652objects of [Certificate](#Certificate-type) type. 1653 1654### Certificate type 1655 1656* **GUID** 1657 * (required) - **string** 1658 * A unique identifier for this certificate. Must be a non-empty string. 1659 1660* **PKCS12** 1661 * (required if **Type** is 1662 *Client*, otherwise ignored) - **string** 1663 * For certificates with 1664 private keys, this is the base64 encoding of the a PKCS#12 file. 1665 1666* **Remove** 1667 * (optional, defaults to *false*) - **boolean** 1668 * If *true*, remove this certificate (only GUID 1669 should be set). 1670 1671* **Scope** 1672 * (optional, default Scope if missing) - [Scope](#Scope-type) 1673 * If this is given, it specifies the scope in which the certificate should 1674 be applied. 1675 1676* **TrustBits** 1677 * (optional if **Type** 1678 is *Server* 1679 or *Authority*, otherwise ignored, defaults to []) - **array of string** 1680 * An array of trust flags. Clients should ignore unknown flags. For 1681 backwards compatibility, each flag should only increase the trust and 1682 never restrict. The trust flag *Web* implies that 1683 the certificate is to be trusted for HTTPS SSL identification. A typical 1684 web certificate authority would have **Type** set 1685 to *Authority* and **TrustBits** set to `["Web"]` 1686 1687* **Type** 1688 * (required if **Remove** is *false*, otherwise ignored) - **string** 1689 * Allowed values are: 1690 * *Client* 1691 * *Server* 1692 * *Authority* 1693 * *Client* indicates the certificate is for 1694 identifying the user or device over HTTPS or for 1695 VPN/802.1X. *Server* indicates the certificate 1696 identifies an HTTPS or VPN/802.1X peer. 1697 *Authority* indicates the certificate is a 1698 certificate authority and any certificates it issues should be 1699 trusted. Note that if **Type** disagrees with the 1700 x509 v3 basic constraints or key usage attributes, the 1701 **Type** field should be honored. 1702 1703* **X509** 1704 * (required if **Type** is 1705 *Server* or *Authority*, otherwise ignored) - **string** 1706 * For certificate 1707 without private keys, this is the X509 certificate in PEM format. 1708 1709 The passphrase of the PKCS#12 encoding must be empty. Encryption of key data 1710 should be handled at the level of the entire file, or the transport of the 1711 file. 1712 1713 If a global-scoped network connection refers to a user-scoped certificate, 1714 results are undefined, so this configuration should be prohibited by the 1715 configuration editor. 1716 1717### Scope type 1718* **Id** 1719 * (required if **Type** is *Extension*, otherwise ignored) - **string** 1720 * If *Type* is *Extension*, this is the ID of the chrome extension for which 1721 the certificate should be applied. 1722* **Type** 1723 * (required) - **string** 1724 * Allowed values are: 1725 * *Extension* 1726 * *Default* 1727 * *Extension* indicates that the certificate should only be applied in the 1728 scope of a chrome extension. 1729 *Default* indicates that the scope the certificate applies in should not 1730 be restricted. 1731 1732 1733## Encrypted Configuration 1734 1735We assume that when this format is imported as part of policy that 1736file-level encryption will not be necessary because the policy transport is 1737already encrypted, but when it is imported as a standalone file, it is 1738desirable to encrypt it. Since this file has private information (user 1739names) and secrets (passphrases and private keys) in it, and we want it to 1740be usable as a manual way to distribute network configuration, we must 1741support encryption. 1742 1743For this standalone export, the entire file will be encrypted in a symmetric 1744fashion with a passphrase stretched using salted PBKDF2 using at least 20000 1745iterations, and encrypted using an AES-256 CBC mode cipher with an SHA-1 1746HMAC on the ciphertext. 1747 1748An encrypted ONC file's top level object will have the 1749[EncryptedConfiguration](#EncryptedConfiguration-type) type. 1750 1751### EncryptedConfiguration type 1752 1753* **Cipher** 1754 * (required) - **string** 1755 * The type of cipher used. Currently only *AES256* 1756 is supported. 1757 1758* **Ciphertext** 1759 * (required) - **string** 1760 * The raw ciphertext of the encrypted ONC file, base64 encoded. 1761 1762* **HMAC** 1763 * (required) - **string** 1764 * The HMAC for the ciphertext, base64 encoded. 1765 1766* **HMACMethod** 1767 * (required) - **string** 1768 * The method used to compute the Hash-based Message Authentication Code 1769 (HMAC). Currently only *SHA1* is supported. 1770 1771* **Salt** 1772 * (required) - **string** 1773 * The salt value used during key stretching. 1774 1775* **Stretch** 1776 * (required) - **string** 1777 * The key stretching algorithm used. Currently 1778 only *PBKDF2* is supported. 1779 1780* **Iterations** 1781 * (required) - **integer** 1782 * The number of iterations to use during key stretching. 1783 1784* **IV** 1785 * (required) - **string** 1786 * The initial vector (IV) used for Cyclic Block Cipher (CBC) mode, base64 1787 encoded. 1788 1789* **Type** 1790 * (required) - **string** 1791 * The type of the ONC file, which must be set 1792 to *EncryptedConfiguration*. 1793 1794--- 1795 * When decrypted, the ciphertext must contain a JSON object of 1796 type [UnencryptedConfiguration](#UnencryptedConfiguration-type). 1797--- 1798 1799## String Expansions 1800 1801The values of some fields, such 1802as **WiFi.EAP.Identity** 1803and **VPN.*.Username**, are subject to string 1804expansions. These allow one ONC to have basic user-specific variations. 1805 1806### The expansions are: 1807 1808* Placeholders that will only be replaced in user-specific ONC: 1809 * ${LOGIN\_ID} - expands to the email address of the user, but before 1810 the '@'. 1811 * ${LOGIN\_EMAIL} - expands to the email address of the user. 1812 1813* Placeholders that will only be replaced in device-wide ONC: 1814 * ${DEVICE\_SERIAL\_NUMBER} - expands to the serial number of the device. 1815 * ${DEVICE\_ASSET\_ID} - expands to the administrator-set asset ID of the 1816 device. 1817 1818* Placeholders that will only be replaced when a client certificate has been 1819 matched by a [CertificatePattern](#CertificatePattern-type): 1820 * ${CERT\_SAN\_EMAIL} - expands to the first RFC822 SubjectAlternativeName 1821 extracted from the client certificate. 1822 * ${CERT\_SAN\_UPN} - expands to the first OtherName SubjectAlternativeName 1823 with OID 1.3.6.1.4.1.311.20.2.3 (UserPrincipalName) extracted from the 1824 client certificate. 1825 * ${CERT\_SUBJECT\_COMMON\_NAME} - expands to the ASCII value of the Subject 1826 CommonName extracted from the client certificate. 1827 1828### The following SED would properly handle resolution. 1829 1830* s/\$\{LOGIN\_ID\}/bobquail$1/g 1831 1832* s/\$\{LOGIN\_EMAIL\}/bobquail@example.com$1/g 1833 1834### Example expansions, assuming the user was bobquail@example.com: 1835 1836* "${LOGIN\_ID}" -> "bobquail" 1837 1838* "${LOGIN\_ID}@corp.example.com" -> "bobquail@corp.example.com" 1839 1840* "${LOGIN\_EMAIL}" -> "bobquail@example.com" 1841 1842* "${LOGIN\_ID}X" -> "bobquailX" 1843 1844* "${LOGIN\_IDX}" -> "${LOGIN\_IDX}" 1845 1846* "X${LOGIN\_ID}" -> "Xbobquail" 1847 1848 1849## String Substitutions 1850The value of **WiFi.EAP.Password** is subject to string substitution. These 1851differ from the **String Expansions** section above in that an exact match of 1852the substitution variable is required in order to substitute the real value. 1853 1854### Example expansions, assuming the user password was *helloworld*: 1855 1856* "${PASSWORD}" -> "helloworld" 1857 1858* "${PASSWORD}foo" -> "${PASSWORD}foo" 1859 1860## Recommended Values 1861When a policy is providing ONC configurations, the assumption is that all values 1862are mandatory and immutable. To specify values that can be overridden by a user 1863(e.g. proxy or username), use the **Recommended** property. 1864 1865* **Recommended** 1866 * (optional) - **array of string** 1867 * The field(s) with the names in the strings in this array are to be treated 1868 as recommended settings. Any fields not mentioned in this array remain 1869 mandatory. This also means that fields that are not mentioned in the array 1870 and also not mentioned in the objects are mandatory and have the default 1871 value of the field. If not present, all fields are mandatory. Fields that 1872 are objects or arrays of objects included in Recommended will be ignored. In 1873 those cases, the nested objects should have their own Recommended fields. A 1874 special case is if the string "." is included in the list. When this is 1875 present, it means that the entire certificate or network can be forgotten or 1876 deleted by the user. Including the "." has no implications on the rest of 1877 the settings. For instance, a network may have Recommended set to [ "." ], 1878 in which case its settings may not be changed by the user, but the whole 1879 network can be forgotten by the user. The "." is valid in a Certificate 1880 object and the NetworkConfiguration object, it is ignored elsewhere. 1881 1882 1883## Detection 1884 1885This format should be sent in files ending in the .onc extension. When 1886transmitted with a MIME type, the MIME type should be 1887application/x-onc. These two methods make detection of data to be handled in 1888this format, especially when encryption is used and the payload itself is 1889not detectable. 1890 1891 1892## Alternatives considered 1893 1894For the overall format, we considered XML, ASN.1, and protobufs. JSON and 1895ASN.1 seem more widely known than protobufs. Since administrators are 1896likely to want to tweak settings that will not exist in common UIs, we 1897should provide a format that is well known and human modifiable. ASN.1 is 1898not human modifiable. Protobufs formats are known by open source developers 1899but seem less likely to be known by administrators. JSON serialization 1900seems to have good support across languages. 1901 1902We considered sending the exact connection manager configuration format of 1903an open source connection manager like connman. There are a few issues 1904here, for instance, referencing certificates by identifiers not tied to a 1905particular PKCS#11 token, and tying to one OS's connection manager. 1906 1907## Examples 1908 1909### GlobalNetworkConfiguration Example 1910 1911In this example, we only allow managed networks to auto connect and 1912disallow any other networks if a managed network is available. We also blacklist 1913the "Guest" network (hex("Guest")=4775657374) and disable Cellular services. 1914``` 1915{ 1916 "Type": "UnencryptedConfiguration", 1917 "GlobalNetworkConfiguration": { 1918 "AllowOnlyPolicyNetworksToAutoconnect": true, 1919 “AllowOnlyPolicyNetworksToConnect”: false, 1920 “AllowOnlyPolicyNetworksToConnectIfAvailable”: true, 1921 “BlacklistedHexSSIDs”: [“4775657374”], 1922 "DisableNetworkTypes": ["Cellular"] 1923 } 1924} 1925``` 1926 1927### Simple format example: PEAP/MSCHAPv2 network (per device) 1928 1929``` 1930{ 1931 "Type": "UnencryptedConfiguration", 1932 "NetworkConfigurations": [ 1933 { 1934 "GUID": "{f2c17903-b0e1-8593-b3ca74f977236bd7}", 1935 "Name": "MySSID", 1936 "Type": "WiFi", 1937 "WiFi": { 1938 "AutoConnect": true, 1939 "EAP": { 1940 "Outer": "PEAP", 1941 "UseSystemCAs": true 1942 }, 1943 "HiddenSSID": false, 1944 "SSID": "MySSID", 1945 "Security": "WPA-EAP" 1946 } 1947 } 1948 ], 1949 "Certificates": [] 1950} 1951``` 1952 1953Notice that in this case, we do not provide a username and password - we set 1954SaveCredentials to *false* so we are prompted every 1955time. We could have passed in username and password - but such a file should 1956be encrypted. 1957 1958### Complex format example: TLS network with client certs (per device) 1959 1960``` 1961{ 1962 "Type": "UnencryptedConfiguration", 1963 "NetworkConfigurations": [ 1964 { 1965 "GUID": "{00f79111-51e0-e6e0-76b3b55450d80a1b}", 1966 "Name": "MyTTLSNetwork", 1967 "Type": "WiFi", 1968 "WiFi": { 1969 "AutoConnect": false, 1970 "EAP": { 1971 "ClientCertPattern": { 1972 "EnrollmentURI": [ 1973 "http://fetch-my-certificate.com" 1974 ], 1975 "IssuerCARef": [ 1976 "{6ed8dce9-64c8-d568-d225d7e467e37828}" 1977 ] 1978 }, 1979 "ClientCertType": "Pattern", 1980 "Outer": "EAP-TLS", 1981 "ServerCARef": "{6ed8dce9-64c8-d568-d225d7e467e37828}", 1982 "UseSystemCAs": true 1983 }, 1984 "HiddenSSID": false, 1985 "SSID": "MyTTLSNetwork", 1986 "Security": "WPA-EAP" 1987 } 1988 } 1989 ], 1990 "Certificates": [ 1991 { 1992 "GUID": "{6ed8dce9-64c8-d568-d225d7e467e37828}", 1993 "Type": "Authority", 1994 "X509": "MIIEpzCCA4+gAwIBAgIJAMueiWq5WEIAMA0GCSqGSIb3DQEBBQUAMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTExMDEyODA2MjA0MFoXDTEyMDEyODA2MjA0MFowgZMxCzAJBgNVBAYTAkZSMQ8wDQYDVQQIEwZSYWRpdXMxEjAQBgNVBAcTCVNvbWV3aGVyZTEVMBMGA1UEChMMRXhhbXBsZSBJbmMuMSAwHgYJKoZIhvcNAQkBFhFhZG1pbkBleGFtcGxlLmNvbTEmMCQGA1UEAxMdRXhhbXBsZSBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9EDplhyrVNJIoy1OsVqvD/K67B5PW2bDKKxGznodrzCu8jHsP1Ne3mgrK20vbzQUUBdmxTCWO6x3a3//r4ZuPOuZd1ViycWjt6mRfRbBzNrHzP7NiyFuXjdlz74beHQQLcHwvZ3qFAWZK37uweiLiDPaMaEQlka2Bztqx4PsogmSdoVPSCxi5Cl1XlJmITA03LlKpO79+0rEPRamWO/DMCwvffn2/UUjJLog4/lYe16HQ6iq/6bjhffm2rLXDFKOGZmBVbLNMCfANRMtdFWHYdBXERoUo2zpM9tduOOUNLy7E7kRKVm/wy38s51ChFPlpORrhimN2j1caar+KAv2tAgMBAAGjgfswgfgwHQYDVR0OBBYEFBTIImiXp+57jjgn2N5wq93GgAAtMIHIBgNVHSMEgcAwgb2AFBTIImiXp+57jjgn2N5wq93GgAAtoYGZpIGWMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5ggkAy56JarlYQgAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAnNd0YY7s2YVYPsgEgDS+rBNjcQloTFWgc9Hv4RWBjwcdJdSPIrpBp7LSjC96wH5U4eWpQjlWbOYQ9RBq9Z/RpuAPEjzRV78rIrQrCWQ3lxwywWEb5Th1EVJSN68eNv7Ke5BlZ2l9kfLRKFm5MEBXX9YoHMX0U8I8dPIXfTyevmKOT1PuEta5cQOM6/zH86XWn6WYx3EXkyjpeIbVOw49AqaEY8u70yBmut4MO03zz/pwLjV1BWyIkXhsrtuJyA+ZImvgLK2oAMZtGGFo7b0GW/sWY/P3R6Un3RFy35k6U3kXCDYYhgZEcS36lIqcj5y6vYUUVM732/etCsuOLz6ppw==" 1995 } 1996 ] 1997} 1998``` 1999 2000In this example, the client certificate is not sent in the ONC format, but 2001rather we send a certificate authority which we know will have signed the 2002client certificate that is needed, along with an enrollment URI to navigate 2003to if the required certificate is not yet available on the client. 2004 2005### Simple format example: HTTPS Certificate Authority 2006 2007In this example a new certificate authority is added to be trusted for HTTPS 2008server authentication. 2009 2010``` 2011{ 2012 "Type": "UnencryptedConfiguration", 2013 "NetworkConfigurations": [], 2014 "Certificates": [ 2015 { 2016 "GUID": "{f31f2110-9f5f-61a7-a8bd7c00b94237af}", 2017 "TrustBits": [ "Web" ], 2018 "Type": "Authority", 2019 "X509": "MIIEpzCCA4+gAwIBAgIJAMueiWq5WEIAMA0GCSqGSIb3DQEBBQUAMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTExMDEyODA2MjA0MFoXDTEyMDEyODA2MjA0MFowgZMxCzAJBgNVBAYTAkZSMQ8wDQYDVQQIEwZSYWRpdXMxEjAQBgNVBAcTCVNvbWV3aGVyZTEVMBMGA1UEChMMRXhhbXBsZSBJbmMuMSAwHgYJKoZIhvcNAQkBFhFhZG1pbkBleGFtcGxlLmNvbTEmMCQGA1UEAxMdRXhhbXBsZSBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9EDplhyrVNJIoy1OsVqvD/K67B5PW2bDKKxGznodrzCu8jHsP1Ne3mgrK20vbzQUUBdmxTCWO6x3a3//r4ZuPOuZd1ViycWjt6mRfRbBzNrHzP7NiyFuXjdlz74beHQQLcHwvZ3qFAWZK37uweiLiDPaMaEQlka2Bztqx4PsogmSdoVPSCxi5Cl1XlJmITA03LlKpO79+0rEPRamWO/DMCwvffn2/UUjJLog4/lYe16HQ6iq/6bjhffm2rLXDFKOGZmBVbLNMCfANRMtdFWHYdBXERoUo2zpM9tduOOUNLy7E7kRKVm/wy38s51ChFPlpORrhimN2j1caar+KAv2tAgMBAAGjgfswgfgwHQYDVR0OBBYEFBTIImiXp+57jjgn2N5wq93GgAAtMIHIBgNVHSMEgcAwgb2AFBTIImiXp+57jjgn2N5wq93GgAAtoYGZpIGWMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5ggkAy56JarlYQgAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAnNd0YY7s2YVYPsgEgDS+rBNjcQloTFWgc9Hv4RWBjwcdJdSPIrpBp7LSjC96wH5U4eWpQjlWbOYQ9RBq9Z/RpuAPEjzRV78rIrQrCWQ3lxwywWEb5Th1EVJSN68eNv7Ke5BlZ2l9kfLRKFm5MEBXX9YoHMX0U8I8dPIXfTyevmKOT1PuEta5cQOM6/zH86XWn6WYx3EXkyjpeIbVOw49AqaEY8u70yBmut4MO03zz/pwLjV1BWyIkXhsrtuJyA+ZImvgLK2oAMZtGGFo7b0GW/sWY/P3R6Un3RFy35k6U3kXCDYYhgZEcS36lIqcj5y6vYUUVM732/etCsuOLz6ppw==" 2020 } 2021 ] 2022} 2023``` 2024 2025### Encrypted format example 2026 2027In this example a simple wireless network is added, but the file is encrypted 2028with the passphrase "test0000". 2029 2030``` 2031{ 2032 "Cipher": "AES256", 2033 "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==", 2034 "HMAC": "3ylRy5InlhVzFGakJ/9lvGSyVH0=", 2035 "HMACMethod": "SHA1", 2036 "Iterations": 20000, 2037 "IV": "hcm6OENfqG6C/TVO6p5a8g==", 2038 "Salt": "/3O73QadCzA=", 2039 "Stretch": "PBKDF2", 2040 "Type": "EncryptedConfiguration" 2041} 2042``` 2043 2044### Recommended values example 2045 2046In this example, the EAP Identity and Password are marked as recommended, i.e. 2047they can be edited by the user. All other values are mandatory. 2048 2049``` 2050{ 2051 "Type": "UnencryptedConfiguration", 2052 "GlobalNetworkConfiguration": {}, 2053 "NetworkConfigurations": [ 2054 { 2055 "GUID": "{485e6176-dd34-6b6d-1234}", 2056 "Name": "wifi_test", 2057 "Type": "WiFi", 2058 "WiFi": { 2059 "SSID": "wifi_test", 2060 "Security": "WPA-EAP", 2061 "AutoConnect": true, 2062 "EAP": { 2063 "Inner": "MSCHAPv2", 2064 "Outer": "PEAP", 2065 "SaveCredentials": true, 2066 "UseSystemCAs": false, 2067 "Identity": "john-doe", 2068 "Password": "secret-password-123", 2069 "Recommended": ["Identity", "Password"] 2070 } 2071 } 2072 } 2073 } 2074 ] 2075} 2076``` 2077 2078 2079## Standalone editor 2080 2081The source code for a Chrome packaged app to generate ONC configuration can 2082be found here: https://chromium.googlesource.com/chromiumos/platform/spigots/ 2083 2084## Internationalization and Localization 2085 2086UIs will need to have internationalization and localizations - the file 2087format will remain in English. 2088 2089## Security Considerations 2090 2091Data stored inside of open network configuration files is highly sensitive 2092to users and enterprises. The file format itself provides adequate 2093encryption options to allow standalone use-cases to be secure. For automatic 2094updates sent by policy, the policy transport should be made secure. The file 2095should not be stored unencrypted on disk as part of policy fetching and 2096should be cleared from memory after use. 2097 2098## Privacy Considerations 2099 2100Similarly to the security considerations, user names will be present in 2101these files for certain kinds of connections, so any places where the file 2102is transmitted or saved to disk should be secure. On client device, when 2103user names for connections that are user-specific are persisted to disk, 2104they should be stored in a location that is encrypted. Users can also opt in 2105these cases to not save their user credentials in the config file and will 2106instead be prompted when they are needed. 2107 2108## Authors 2109 2110* pneubeck@chromium.org 2111* stevenjb@chromium.org 2112