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