components/onc/docs/onc_spec.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta charset="utf-8">
   5   <link rel="stylesheet" href="onc_spec.css" >
   6   <script src="onc_spec.js"></script>
   7   <title>Open Network Configuration Format</title>
   8 </head>
   9 <body>
  10
  11 <section id="root" class="not_in_toc">
  12   <h1>Open Network Configuration Format</h1>
  13
  14 <section class="not_in_toc">
  15   <h1>Outline</h1>
  16   <div id="outline"></div>
  17 </section>
  18
  19 <section>
  20   <h1>Objective</h1>
  21   <p>
  22     We would like to create a simple, open, but complete format to describe
  23     multiple network configurations for WiFi, Ethernet, Cellular,
  24     Bluetooth/WiFi-Direct, and VPN connections in a single file format, in order
  25     to simplify and automate network configuration for users.
  26   </p>
  27 </section>
  28
  29 <section>
  30   <h1>Background</h1>
  31   <p>
  32     Configuring networks is a painful and error-prone experience for users. It
  33     is a problem shared across desktop, laptop, tablet, and phone users of all
  34     operating system types. It is exacerbated in business and schools which
  35     often have complex network configurations (VPNs and 802.1X networking) that
  36     change often and have many connected devices. Configuration of WiFi is
  37     still done manually, often by administrators physically standing next to
  38     users working on devices. Certificate distribution is particularly painful
  39     which often results in admins instead using passphrases to protect networks
  40     or using protocols without client certificates that instead use LDAP
  41     passwords for authentication. Even after networks are configured, updates to
  42     the network configuration require another round of manual changes, and
  43     accidental changes by a user or malicious changes by an attacker can break
  44     connectivity or make connections less private or secure.
  45   </p>
  46
  47 <section>
  48   <h1>Overview</h1>
  49   <p>
  50     We propose a single-file format for network configuration that is
  51     human-readable, can describe all of the common kinds of network
  52     configurations, supports integrity checking, certificate and key
  53     provisioning, and updating. The file can be encrypted with a single
  54     passphrase so that upon entering the passphrase the entire configuration is
  55     loaded. The format can be described as an open format to enable multiple OS
  56     vendors to interoperate and share configuration editors.
  57   </p>
  58
  59   <p>
  60     This format neither supports configuring browser settings nor allows setting
  61     other types of system policies.
  62   </p>
  63 </section>
  64
  65 <section>
  66   <h1>Infrastructure</h1>
  67   <p>
  68     A standalone configuration editor will be created, downloadable as a Chrome
  69     app. This editor will allow creating, modifying, and encrypting an open
  70     network configuration file in a way that is intuitive for a system
  71     administrator.
  72   </p>
  73
  74   <p>
  75     This file format may be delivered to a user and manually imported into a
  76     device.
  77   </p>
  78
  79   <p>
  80     This file format may be created by an administrator, stored in a policy
  81     repository, and automatically pushed to a device.
  82   </p>
  83 </section>
  84
  85 </section>
  86
  87 <section>
  88   <h1>Detailed Design</h1>
  89   <p>
  90     We use JSON format for the files. The fields in a JSON file are always
  91     case-sensitive, so the exact case of the fields in this section must be
  92     matched. In addition, the values that are called out as explicit constants
  93     must also match the case specified (e.g. WiFi must not be written as wifi,
  94     etc.). This document describes a minimum set of required fields and optional
  95     fields. Other fields may be created, however, see the
  96     implementation-specific fields for guidelines for these fields.
  97   </p>
  98
  99   <p>
 100     The JSON consists of a top level dictionary containing
 101     a <span class="field">Type</span> field which must have either the
 102     value <span class="value">EncryptedConfiguration</span>
 103     or <span class="value">UnencryptedConfiguration</span>.
 104   </p>
 105
 106   <p>
 107     For a description of the <span class="type">EncryptedConfiguration</span>
 108     type, see the section on Encrypted Configuration
 109     below. The <span class="type">EncryptedConfiguration</span> format encrypts
 110     an unencrypted JSON object.
 111   </p>
 112
 113 <section>
 114   <h1>GUIDs and Updating</h1>
 115   <p>
 116     This format allows for importing updated network configurations and
 117     certificates by providing GUIDs to each network configuration and
 118     certificate so they can be modified or even removed in future updates.
 119   </p>
 120
 121   <p>
 122     GUIDs are non-empty strings that are meant to be stable and unique. When
 123     they refer to the same entity, they should be the same between ONC files. No
 124     two different networks or certificates should have the same GUID, similarly
 125     a network and certificate should not have the same GUID. A single ONC file
 126     should not contain the same entity twice (with the same GUID). Failing any
 127     of these tests indicates the ONC file is not valid.
 128   </p>
 129
 130   <p>
 131     Any GUID referred to in an ONC file must be present in the same ONC file. In
 132     particular, it is an error to create a certificate in one ONC file and refer
 133     to it in a NetworkConfiguration in another ONC file and not define it there,
 134     even if the previous ONC file has been imported.
 135   </p>
 136 </section>
 137
 138 <section>
 139   <h1>Implementation-specific fields</h1>
 140   <p>
 141     As there are many different kinds of connections and some that are not yet
 142     anticipated may require new fields. This format allows arbitrary other
 143     fields to be added.
 144   </p>
 145
 146   <p>
 147     Fields and values should follow these general guidelines:
 148   </p>
 149
 150   <ul>
 151     <li>
 152       Certificates (with and without keys) should always be placed in the
 153       certificate section - specifically certificate contents should not be
 154       placed in fields directly. Referring to certificates should be done using
 155       a field whose name ends in Ref and whose value is the GUID of the
 156       certificate, or if the certificate is not contained in this file, its
 157       pattern can be described using a field ending in Pattern of
 158       <span class="type">CertificatePattern</span> type.
 159     </li>
 160     <li>
 161       Fields should exist in the most-specific object in the hierarchy and
 162       should be named CamelCase style.
 163     </li>
 164     <li>
 165       Booleans and integers should be used directly instead of using a
 166       stringified version of the type.
 167     </li>
 168   </ul>
 169
 170   <p>
 171     Any editor of network configuration information should allows the user to
 172     modify any fields that are implementation-specific. It may not be present
 173     directly in the UI but it should be able to import files with such settings
 174     and leave preserve these settings on export.
 175   </p>
 176 </section>
 177
 178 <section>
 179   <h1>Unencrypted Configuration</h1>
 180   <p>
 181     When the top level <span class="field">Type</span> field
 182     is <span class="value">UnencryptedConfiguration</span>, the top level JSON
 183     has the <span class="type">UnencryptedConfiguration</span>
 184     type. <span class="type">UnencryptedConfiguration</span> type contains the
 185     following:
 186   </p>
 187
 188   <dl class="field_list">
 189     <dt class="field">Type</dt>
 190     <dd>
 191       <span class="field_meta">
 192         (optional, defaults to <span class="value">UnencryptedConfiguration
 193          </span>)
 194         <span class="type">string</span>
 195       </span>
 196       Must be <span class="value">UnencryptedConfiguration</span>.
 197     </dd>
 198
 199     <dt class="field">NetworkConfigurations</dt>
 200     <dd>
 201       <span class="field_meta">
 202         (optional)
 203         <span class="type">array of NetworkConfiguration</span>
 204       </span>
 205       Describes WiFi, Ethernet, VPN, and wireless connections.
 206     </dd>
 207
 208     <dt class="field">Certificates</dt>
 209     <dd>
 210       <span class="field_meta">
 211         (optional)
 212         <span class="type">array of Certificate</span>
 213       </span>
 214       Contains certificates stored in X.509 or PKCS#12 format.
 215     </dd>
 216   </dl>
 217
 218   At least one actual configuration field
 219   (<span class="field">NetworkConfigurations</span> or
 220    <span class="field">Certificates</span>) should be present, however it should
 221   not be considered an error if no such field is present.
 222
 223 <section>
 224   <h1>Network Configuration</h1>
 225   <p>
 226     Field <span class="field">NetworkConfigurations</span> is an array
 227     of <span class="type">NetworkConfiguration</span> typed
 228     objects. The <span class="type">NetworkConfiguration</span> type contains
 229     the following:
 230   </p>
 231
 232   <dl class="field_list">
 233     <dt class="field">Ethernet</dt>
 234     <dd>
 235       <span class="field_meta">
 236         (required if <span class="field">Type</span> is
 237         <span class="value">Ethernet</span>, otherwise ignored)
 238         <span class="type">Ethernet</span>
 239       </span>
 240       Ethernet settings.
 241     </dd>
 242
 243     <dt class="field">GUID</dt>
 244     <dd>
 245       <span class="field_meta">
 246         (required)
 247         <span class="type">string</span>
 248       </span>
 249       A unique identifier for this network connection, which exists to make it
 250       possible to update previously imported configurations. Must be a non-empty
 251       string.
 252     </dd>
 253
 254     <dt class="field">IPAddressConfigType</dt>
 255     <dd>
 256       <span class="field_meta">
 257         (optional if <span class="field">Remove</span> is
 258         <span class="value">false</span>, otherwise ignored. Defaults to
 259         <span class="value">DHCP</span> if
 260         <span class="field">NameServersConfigType</span> is specified)
 261         <span class="type">string</span>
 262       </span>
 263       <span class="rule">
 264         <span class="rule_id"></span>
 265         Allowed values are <span class="value">DHCP</span> and
 266         <span class="value">Static</span>.
 267       </span>
 268       Determines whether the IP Address configuration is statically configured,
 269       see <span class="field">StaticIPConfig</span>, or automatically configured
 270       using DHCP.
 271     </dd>
 272
 273     <dt class="field">NameServersConfigType</dt>
 274     <dd>
 275       <span class="field_meta">
 276         (optional if <span class="field">Remove</span> is
 277         <span class="value">false</span>, otherwise ignored. Defaults to
 278         <span class="value">DHCP</span> if
 279         <span class="field">IPAddressConfigType</span> is specified)
 280         <span class="type">string</span>
 281       </span>
 282       <span class="rule">
 283         <span class="rule_id"></span>
 284         Allowed values are <span class="value">DHCP</span> and
 285         <span class="value">Static</span>.
 286       </span>
 287       Determines whether the NameServers configuration is statically configured,
 288       see <span class="field">StaticIPConfig</span>, or automatically configured
 289       using DHCP.
 290     </dd>
 291
 292     <dt class="field">IPConfigs</dt>
 293     <dd>
 294       <span class="field_meta">
 295         (optional for connected networks, read-only)
 296         <span class="type">array of IPConfig</span>
 297       </span>
 298       Array of IPConfig properties associated with this connection.
 299     </dd>
 300
 301     <dt class="field">StaticIPConfig</dt>
 302     <dd>
 303       <span class="field_meta">
 304         (required if <span class="field">IPAddressConfigType</span> or
 305         <span class="field">NameServersConfigType</span> is set to
 306         <span class="value">Static</span>)
 307         <span class="type">IPConfig</span>
 308       </span>
 309       Each property set in this IPConfig object overrides the respective
 310       parameter received over DHCP.
 311       If <span class="field">IPAddressConfigType</span> is set to
 312       <span class="value">Static</span>, <span class="field">IPAddress</span>
 313       and <span class="field">Gateway</span> are required.
 314       If <span class="field">NameServersConfigType</span> is set to
 315       <span class="value">Static</span>, <span class="field">NameServers</span>
 316       is required.
 317     </dd>
 318
 319     <dt class="field">SavedIPConfig</dt>
 320     <dd>
 321       <span class="field_meta">
 322         (optional for connected networks, read-only)
 323         <span class="type">IPConfig</span>
 324       </span>
 325       IPConfig property containing the configuration that was received from the
 326       DHCP server prior to applying any StaticIPConfig parameters.
 327     </dd>
 328
 329     <dt class="field">Name</dt>
 330     <dd>
 331       <span class="field_meta">
 332         (required if <span class="field">Remove</span> is
 333         <span class="value">false</span>, otherwise ignored)
 334         <span class="type">string</span>
 335       </span>
 336       A user-friendly description of this connection. This name will not be used
 337       for referencing and may not be unique. Instead it may be used for
 338       describing the network to the user.
 339     </dd>
 340
 341     <dt class="field">Remove</dt>
 342     <dd>
 343       <span class="field_meta">
 344         (optional, defaults to <span class="value">false</span>)
 345         <span class="type">boolean</span>
 346       </span>
 347       If set, remove this network configuration (only GUID should be set).
 348     </dd>
 349
 350     <dt class="field">ProxySettings</dt>
 351     <dd>
 352       <span class="field_meta">
 353         (optional if <span class="field">Remove</span> is
 354         <span class="value">false</span>, otherwise ignored)
 355         <span class="type">ProxySettings</span>
 356       </span>
 357       Proxy settings for this network
 358     </dd>
 359
 360     <dt class="field">VPN</dt>
 361     <dd>
 362       <span class="field_meta">
 363         (required if <span class="field">Type</span> is
 364         <span class="value">VPN</span>, otherwise ignored)
 365         <span class="type">VPN</span>
 366       </span>
 367       VPN settings.
 368     </dd>
 369
 370     <dt class="field">WiFi</dt>
 371     <dd>
 372       <span class="field_meta">
 373         (required if <span class="field">Type</span> is
 374         <span class="value">WiFi</span>, otherwise ignored)
 375         <span class="type">WiFi</span>
 376       </span>
 377       WiFi settings.
 378     </dd>
 379
 380     <dt class="field">WiMAX</dt>
 381     <dd>
 382       <span class="field_meta">
 383         (required if <span class="field">Type</span> is
 384         <span class="value">WiMAX</span>, otherwise ignored)
 385         <span class="type">WiMAX</span>
 386       </span>
 387       WiMAX settings.
 388     </dd>
 389
 390     <dt class="field">Cellular</dt>
 391     <dd>
 392       <span class="field_meta">
 393         (required if <span class="field">Type</span> is
 394         <span class="value">Cellular</span>, otherwise ignored)
 395         <span class="type">Cellular</span>
 396       </span>
 397       Cellular settings.
 398     </dd>
 399
 400     <dt class="field">Type</dt>
 401     <dd>
 402       <span class="field_meta">
 403         (required if <span class="field">Remove</span> is
 404         <span class="value">false</span>, otherwise ignored)
 405         <span class="type">string</span>
 406       </span>
 407       <span class="rule">
 408         <span class="rule_id"></span>
 409         Allowed values are <span class="value">Cellular</span>,
 410         <span class="value">Ethernet</span>, <span class="value">WiFi</span>,
 411         <span class="value">Cellular</span> and <span class="value">VPN</span>.
 412       </span>
 413       Indicates which kind of connection this is.
 414     </dd>
 415
 416     <dt class="field">ConnectionState</dt>
 417     <dd>
 418       <span class="field_meta">
 419         (optional, read-only)
 420         <span class="type">string</span>
 421       </span>
 422       The current connection state for this network, provided by the system.
 423       <span class="rule">
 424         <span class="rule_id"></span>
 425         Allowed values are:
 426         <span class="value">Connected</span>,
 427         <span class="value">Connecting</span>,
 428         <span class="value">NotConnected</span>
 429       </span>
 430     </dd>
 431
 432     <dt class="field">RestrictedConnectivity</dt>
 433     <dd>
 434       <span class="field_meta">
 435         (optional, defaults to <span class="value">false</span>, read-only)
 436         <span class="type">boolean</span>
 437       </span>
 438       True if a connnected network has limited connectivity to the Internet,
 439       e.g. a connection is behind a portal or a cellular network is not
 440       activated or requires payment.
 441     </dd>
 442
 443     <dt class="field">Connectable</dt>
 444     <dd>
 445       <span class="field_meta">
 446         (optional, read-only)
 447         <span class="type">boolean</span>
 448       </span>
 449       True if the system indicates that the network can be connected to without
 450       any additional configuration.
 451     </dd>
 452
 453     <dt class="field">ErrorState</dt>
 454     <dd>
 455       <span class="field_meta">
 456         (optional, read-only)
 457         <span class="type">string</span>
 458       </span>
 459       The current error state for this network, if any. Error states are
 460       provided by the system and are not explicitly defined here. They may or
 461       may not be human-readable. This field will be empty or absent if the
 462       network is not in an error state.
 463     </dd>
 464
 465     <dt class="field">MacAddress</dt>
 466     <dd>
 467       <span class="field_meta">
 468         (optional, read-only)
 469         <span class="type">string</span>
 470       </span>
 471       The MAC address for the network. Only applies to connected non-virtual
 472       networks. The format is 00:11:22:AA:BB:CC.
 473     </dd>
 474
 475     <dt class="field">Source</dt>
 476     <dd>
 477       <span class="field_meta">
 478         (optional, read-only)
 479         <span class="type">string</span>
 480       </span>
 481       Indicates whether the network is configured and how it is configured:
 482       <ul>
 483         <li><span class="value">User</span>: Configured for the active
 484           user only, i.e. an unshared configuration.</li>
 485         <li><span class="value">Device</span>: Configured for all users of the
 486           device (e.g laptop), i.e. a shared configuration.</li>
 487         <li><span class="value">UserPolicy</span>: Configured by the user
 488           policy for the active user.</li>
 489         <li><span class="value">DevicePolicy</span>: Configured by the device
 490           policy for the device.</li>
 491         <li><span class="value">None</span>: Not configured, e.g. a visible
 492           but unconfigured WiFi network.</li>
 493       </ul>
 494       <span class="rule">
 495         <span class="rule_id"></span>
 496         Allowed values are:
 497         <span class="value">User</span>,
 498         <span class="value">Device</span>,
 499         <span class="value">UserPolicy</span>,
 500         <span class="value">DevicePolicy</span>,
 501         <span class="value">None</span>
 502       </span>
 503     </dd>
 504
 505     <dt class="field">Priority</dt>
 506     <dd>
 507       <span class="field_meta">
 508         (optional)
 509         <span class="type">integer</span>
 510       </span>
 511       Provides a suggested priority value for this network. May be used by the
 512       system to determine which network to connect to when multiple configured
 513       networks are available (or may be ignored).
 514     </dd>
 515
 516   </dl>
 517
 518 <section>
 519   <h1>Ethernet networks</h1>
 520   <p>
 521     For Ethernet connections, <span class="field">Type</span> must be set to
 522     <span class="value">Ethernet</span> and the
 523     field <span class="field">Ethernet</span> must be set to an object of
 524     type <span class="type">Ethernet</span> containing the following fields:
 525   </p>
 526
 527   <dl class="field_list">
 528     <dt class="field">Authentication</dt>
 529     <dd>
 530       <span class="field_meta">
 531         (optional)
 532         <span class="type">string</span>
 533       </span>
 534       <span class="rule">
 535         <span class="rule_id"></span>
 536         Allowed values are <span class="value">None</span> and
 537         <span class="value">8021X</span>.
 538       </span>
 539     </dd>
 540
 541     <dt class="field">EAP</dt>
 542     <dd>
 543       <span class="field_meta">
 544         (required if <span class="field">Authentication</span> is
 545         <span class="value">8021X</span>, otherwise ignored)
 546         <span class="type">EAP</span>
 547       </span>
 548       EAP settings.
 549     </dd>
 550   </dl>
 551 </section>
 552
 553 <section>
 554   <h1>IPConfig</h1>
 555   <p>
 556     Objects of type <span class="type">IPConfig</span> are used to report the
 557     actual IP configuration of a connected network (see
 558     <span class="field">IPConfigs</span>), the IP configuration received from
 559     DHCP (see <span class="field">SavedIPConfig</span>) and to configure a
 560     static IP configuration (see <span class="field">StaticIPConfig</span>).
 561   </p>
 562
 563   <dl class="field_list">
 564     <dt class="field">Type</dt>
 565     <dd>
 566       <span class="field_meta">
 567         (required)
 568         <span class="type">string</span>
 569       </span>
 570       <span class="rule">
 571         <span class="rule_id"></span>
 572         Allowed values are <span class="value">IPv4</span>
 573         and <span class="value">IPv6</span>
 574       </span>
 575       Describes the type of configuration this is.
 576     </dd>
 577
 578     <dt class="field">IPAddress</dt>
 579     <dd>
 580       <span class="field_meta">
 581         (optional)
 582         <span class="type">string</span>
 583       </span>
 584       Describes the IPv4 or IPv6 address of a connection, depending on the value
 585       of <span class="field">Type</span> field. It should not contain the
 586       routing prefix (i.e. should not end in something like /64).
 587     </dd>
 588
 589     <dt class="field">RoutingPrefix</dt>
 590     <dd>
 591       <span class="field_meta">
 592         (required if <span class="field">IPAddress</span> is set. Otherwise
 593         ignored.)
 594         <span class="type">integer</span>
 595       </span>
 596       <span class="rule">
 597         <span class="rule_id"></span>
 598         Must be a number in the range [1, 32] for IPv4 and [1, 128] for IPv6
 599         addresses.
 600       </span>
 601       Describes the routing prefix.
 602     </dd>
 603
 604     <dt class="field">Gateway</dt>
 605     <dd>
 606       <span class="field_meta">
 607         (required if <span class="field">IPAddress</span> is set. Otherwise
 608         ignored.)
 609         <span class="type">string</span>
 610       </span>
 611       Describes the gateway address to use for the configuration. Must match
 612       address type specified in <span class="field">Type</span> field. If not
 613       specified, DHCP values will be used.
 614     </dd>
 615
 616     <dt class="field">NameServers</dt>
 617     <dd>
 618       <span class="field_meta">
 619         (optional)
 620         <span class="type">array of string</span>
 621       </span>
 622       Array of addresses to use for name servers. Address format must match that
 623       specified in the <span class="field">Type</span> field. If not specified,
 624       DHCP values will be used.
 625     </dd>
 626
 627     <dt class="field">SearchDomains</dt>
 628     <dd>
 629       <span class="field_meta">
 630         (optional)
 631         <span class="type">array of string</span>
 632       </span>
 633       Array of strings to append to names for resolution. Items in this array
 634       should not start with a dot. Example: <span class="snippet">[
 635       "corp.acme.org", "acme.org" ]</span>. If not specified, DHCP values will
 636       be used.
 637     </dd>
 638
 639     <dt class="field">WebProxyAutoDiscoveryUrl</dt>
 640     <dd>
 641       <span class="field_meta">
 642         (optional if part of <span class="field">IPConfigs</span>, read-only)
 643         <span class="type">string</span>
 644       </span>
 645       The Web Proxy Auto-Discovery URL for this network as reported over DHCP.
 646     </dd>
 647
 648   </dl>
 649 </section>
 650
 651 <section>
 652   <h1>WiFi networks</h1>
 653   <p>
 654     For WiFi connections, <span class="field">Type</span> must be set to
 655     <span class="value">WiFi</span> and the
 656     field <span class="field">WiFi</span> must be set to an object of
 657     type <span class="type">WiFi</span> containing the following fields:
 658   </p>
 659
 660   <dl class="field_list">
 661     <dt class="field">AllowGatewayARPPolling</dt>
 662     <dd>
 663       <span class="field_meta">
 664         (optional, defaults to <span class="value">true</span>)
 665         <span class="type">boolean</span>
 666       </span>
 667       Indicaties if ARP polling of default gateway is allowed.
 668       When it is allowed, periodic ARP messages will be sent to
 669       the default gateway. This is used for monitoring the status
 670       of the current connection.
 671     </dd>
 672
 673     <dt class="field">AutoConnect</dt>
 674     <dd>
 675       <span class="field_meta">
 676         (optional, defaults to <span class="value">false</span>)
 677         <span class="type">boolean</span>
 678       </span>
 679       Indicating that the network should be connected to automatically when in
 680       range.
 681     </dd>
 682
 683     <dt class="field">EAP</dt>
 684     <dd>
 685       <span class="field_meta">
 686         (required if <span class="field">Security</span> is
 687         <span class="value">WEP-8021X</span> or
 688         <span class="value">WPA-EAP</span>, otherwise ignored)
 689         <span class="type">EAP</span>
 690       </span>
 691       EAP settings.
 692     </dd>
 693
 694     <dt class="field">HexSSID</dt>
 695     <dd>
 696       <span class="field_meta">
 697         (optional if <span class="field">SSID</span> is set, if so defaults to
 698         a hex representation of <span class="field">SSID</span>)
 699         <span class="type">string</span>
 700       </span>
 701       Hex representation of the network's SSID.
 702     </dd>
 703
 704     <dt class="field">HiddenSSID</dt>
 705     <dd>
 706       <span class="field_meta">
 707         (optional, defaults to <span class="value">false</span>)
 708         <span class="type">boolean</span>
 709       </span>
 710       Indicating if the SSID will be broadcast.
 711     </dd>
 712
 713     <dt class="field">Passphrase</dt>
 714     <dd>
 715       <span class="field_meta">
 716         (required if <span class="field">Security</span> is
 717         <span class="value">WEP-PSK</span> or
 718         <span class="value">WPA-PSK</span>, otherwise ignored)
 719         <span class="type">string</span>
 720       </span>
 721       Describes the passphrase for WEP/WPA/WPA2
 722       connections. If <span class="value">WEP-PSK</span> is used, the passphrase
 723       must be of the format 0x&lt;hex-number&gt;, where &lt;hex-number&gt; is
 724       40, 104, 128, or 232 bits.
 725     </dd>
 726
 727     <dt class="field">RoamThreshold</dt>
 728     <dd>
 729       <span class="field_meta">
 730         (optional)
 731         <span class="type">integer</span>
 732       </span>
 733       The roam threshold for this network, which is the signal-to-noise value
 734       (in dB) below which we will attempt to roam to a new network. If this
 735       value is not set, the default value will be used.
 736     </dd>
 737
 738     <dt class="field">Security</dt>
 739     <dd>
 740       <span class="field_meta">
 741         (required)
 742         <span class="type">string</span>
 743       </span>
 744       <span class="rule">
 745         <span class="rule_id"></span>
 746         Allowed values are <span class="value">None</span>,
 747         <span class="value">WEP-PSK</span>,
 748         <span class="value">WEP-8021X</span>,
 749         <span class="value">WPA-PSK</span>, and
 750         <span class="value">WPA-EAP</span>.
 751       </span>
 752     </dd>
 753
 754     <dt class="field">SSID</dt>
 755     <dd>
 756       <span class="field_meta">
 757         (optional if <span class="field">HexSSID</span> is set, otherwise
 758         ignored)
 759         <span class="type">string</span>
 760       </span>
 761       Property to access the decoded SSID of a network.<br/>
 762       If this field is set, but <span class="field">HexSSID</span> is not,
 763       its value will be UTF-8 encoded and the hex representation will be
 764       assigned to <span class="field">HexSSID</span>. To configure a non-UTF-8
 765       SSID, field <span class="field">HexSSID</span> must be used.<br/>
 766       When reading the configuration of a network, both this field and
 767       <span class="field">HexSSID</span> might be set. Then this field is the
 768       decoding of <span class="field">HexSSID</span>. If possible the HexSSID is
 769       decoded using UTF-8, otherwise an encoding is guessed on a best effort
 770       basis.
 771     </dd>
 772
 773     <dt class="field">SignalStrength</dt>
 774     <dd>
 775       <span class="field_meta">
 776         (optional, read-only)
 777         <span class="type">integer</span>
 778       </span>
 779       The current signal strength for this network in the range [0, 100],
 780       provided by the system. If the network is not in range this field will
 781       be set to '0' or not present.
 782     </dd>
 783   </dl>
 784   <span class="rule">
 785     <span class="rule_id"></span>
 786       At least one of the fields <span class="field">HexSSID</span> or
 787       <span class="field">SSID</span> must be present. If both
 788       <span class="field">HexSSID</span> and <span class="field">SSID</span>
 789       are set, the values must be consistent.
 790     </span>
 791   </span>
 792 </section>
 793
 794 <section>
 795   <h1>VPN networks</h1>
 796   <p>
 797     There are many kinds of VPNs with widely varying configuration options. We
 798     offer standard configuration options for a few common configurations at this
 799     time, and may add more later. For all others, implementation specific fields
 800     should be used.
 801   </p>
 802
 803   <p>
 804     For VPN connections, <span class="field">Type</span> must be set
 805     to <span class="value">VPN</span> and the
 806     field <span class="field">VPN</span> must be set to an object of
 807     type <span class="type">VPN</span> containing the following fields:
 808   </p>
 809
 810   <dl class="field_list">
 811     <dt class="field">AutoConnect</dt>
 812     <dd>
 813       <span class="field_meta">
 814         (optional, defaults to <span class="value">false</span>)
 815         <span class="type">boolean</span>
 816       </span>
 817       Indicating that the network should be connected to automatically.
 818     </dd>
 819
 820     <dt class="field">Host</dt>
 821     <dd>
 822       <span class="field_meta">
 823         (optional)
 824         <span class="type">string</span>
 825       </span>
 826       Host name or IP address of server to connect to. The only scenario that
 827       does not require a host is a VPN that encrypts but does not tunnel
 828       traffic. Standalone IPsec (v1 or v2, cert or PSK based -- this is not the
 829       same as L2TP over IPsec) is one such setup. For all other types of VPN,
 830       the <span class="field">Host</span> field is required.
 831     </dd>
 832
 833     <dt class="field">IPsec</dt>
 834     <dd>
 835       <span class="field_meta">
 836         (required if <span class="field">Type</span> is
 837         <span class="value">IPsec</span> or
 838         <span class="value">L2TP-IPsec</span>, otherwise ignored)
 839         <span class="type">IPsec</span>
 840       </span>
 841       IPsec layer settings.
 842     </dd>
 843
 844     <dt class="field">L2TP</dt>
 845     <dd>
 846       <span class="field_meta">
 847         (required if <span class="field">Type</span> is
 848         <span class="value">L2TP-IPsec</span>, otherwise ignored)
 849         <span class="type">L2TP</span>
 850       </span>
 851       L2TP layer settings.
 852     </dd>
 853
 854     <dt class="field">OpenVPN</dt>
 855     <dd>
 856       <span class="field_meta">
 857         (required if <span class="field">Type</span> is
 858         <span class="value">OpenVPN</span>, otherwise ignored)
 859         <span class="type">OpenVPN</span>
 860       </span>
 861       OpenVPN settings.
 862     </dd>
 863
 864     <dt class="field">ThirdPartyVPN</dt>
 865     <dd>
 866       <span class="field_meta">
 867         (required if <span class="field">Type</span> is
 868         <span class="value">ThirdPartyVPN</span>, otherwise ignored)
 869         <span class="type">ThirdPartyVPN</span>
 870       </span>
 871       Third-party VPN provider settings.
 872     </dd>
 873
 874     <dt class="field">Type</dt>
 875     <dd>
 876       <span class="field_meta">
 877         (required)
 878         <span class="type">string</span>
 879       </span>
 880       <span class="rule">
 881         <span class="rule_id"></span>
 882         Allowed values are <span class="value">IPsec</span>,
 883         <span class="value">L2TP-IPsec</span>,
 884         <span class="value">OpenVPN</span>, and
 885         <span class="value">ThirdPartyVPN</span>.
 886       </span>
 887       Type of the VPN.
 888     </dd>
 889   </dl>
 890
 891   <section>
 892     <h1>IPsec-based VPN types</h1>
 893     <p>
 894       The <span class="type">IPsec</span> type contains the following:
 895     </p>
 896
 897     <dl class="field_list">
 898       <dt class="field">AuthenticationType</dt>
 899       <dd>
 900         <span class="field_meta">
 901           (required)
 902           <span class="type">string</span>
 903         </span>
 904         <span class="rule">
 905           <span class="rule_id"></span>
 906           Allowed values are <span class="value">PSK</span> and
 907           <span class="value">Cert</span>. If <span class="value">Cert</span> is used, <span class="field">ClientCertType</span> and <span class="field">ServerCARefs</span> (or the deprecated <span class="field">ServerCARef</span>) must be set.
 908         </span>
 909       </dd>
 910
 911       <dt class="field">ClientCertPattern</dt>
 912       <dd>
 913         <span class="field_meta">
 914           (required if <span class="field">ClientCertType</span>
 915           is <span class="value">Pattern</span>, otherwise ignored)
 916           <span class="type">CertificatePattern</span>
 917         </span>
 918         Pattern describing the client certificate.
 919       </dd>
 920
 921       <dt class="field">ClientCertRef</dt>
 922       <dd>
 923         <span class="field_meta">
 924           (required if <span class="field">ClientCertType</span>
 925           is <span class="value">Ref</span>, otherwise ignored)
 926           <span class="type">string</span>
 927         </span>
 928         Reference to client certificate stored in certificate section.
 929       </dd>
 930
 931       <dt class="field">ClientCertType</dt>
 932       <dd>
 933         <span class="field_meta">
 934           (required if <span class="field">AuthenticationType</span>
 935           is <span class="value">Cert</span>, otherwise ignored)
 936           <span class="type">string</span>
 937         </span>
 938         <span class="rule">
 939           <span class="rule_id"></span>
 940           Allowed values are <span class="value">Ref</span> and
 941           <span class="value">Pattern</span>
 942         </span>
 943       </dd>
 944
 945       <dt class="field">EAP</dt>
 946       <dd>
 947         <span class="field_meta">
 948           (optional if <span class="field">IKEVersion</span> is 2, otherwise
 949           ignored)
 950           <span class="type">EAP</span>
 951         </span>
 952         Indicating that EAP authentication should be used with the provided
 953         parameters.
 954       </dd>
 955
 956       <dt class="field">Group</dt>
 957       <dd>
 958         <span class="field_meta">
 959           (optional if <span class="field">IKEVersion</span> is 1, otherwise
 960           ignored)
 961           <span class="type">string</span>
 962         </span>
 963         Group name used for machine authentication.
 964       </dd>
 965
 966       <dt class="field">IKEVersion</dt>
 967       <dd>
 968         <span class="field_meta">
 969           (required)
 970           <span class="type">integer</span>
 971         </span>
 972         Version of IKE protocol to use.
 973       </dd>
 974
 975       <dt class="field">PSK</dt>
 976       <dd>
 977         <span class="field_meta">
 978           (optional if <span class="field">AuthenticationType</span>
 979           is <span class="value">PSK</span>, otherwise ignored)
 980           <span class="type">string</span>
 981         </span>
 982         Pre-Shared Key. If not specified, user is prompted at time of
 983         connection.
 984       </dd>
 985
 986       <dt class="field">SaveCredentials</dt>
 987       <dd>
 988         <span class="field_meta">
 989           (optional if <span class="field">AuthenticationType</span>
 990           is <span class="value">PSK</span>, otherwise ignored, defaults
 991           to <span class="value">false</span>)
 992           <span class="type">boolean</span>
 993         </span>
 994         If <span class="value">false</span>, require user to enter credentials
 995         (PSK) each time they connect.
 996       </dd>
 997
 998       <dt class="field">ServerCARefs</dt>
 999       <dd>
1000         <span class="field_meta">
1001           (optional if <span class="field">AuthenticationType</span>
1002           is <span class="value">Cert</span>, otherwise rejected)
1003           <span class="type">array of string</span>
1004         </span>
1005         Non-empty list of references to CA certificates in <span class="field">Certificates</span> to be used for verifying the host's certificate chain. At least one of the CA certificates must match. If this field is set, <span class="field">ServerCARef</span> must be unset.
1006       </dd>
1007
1008       <dt class="field">ServerCARef</dt>
1009       <dd>
1010         <span class="field_meta">
1011           (optional if <span class="field">AuthenticationType</span>
1012           is <span class="value">Cert</span>, otherwise rejected)
1013           <span class="type">string</span>
1014         </span>
1015         DEPRECATED, use <span class="field">ServerCARefs</span> instead.<br/>
1016         Reference to a CA certificate in <span class="field">Certificates</span>. Certificate authority to use for verifying connection. If this field is set, <span class="field">ServerCARefs</span> must be unset.
1017       </dd>
1018
1019       <dt class="field">XAUTH</dt>
1020       <dd>
1021         <span class="field_meta">
1022           (optional if <span class="field">IKEVersion</span> is 1, otherwise
1023           ignored)
1024           <span class="type">XAUTH</span>
1025         </span>
1026         Describing XAUTH credentials. XAUTH is not used if this object is not
1027         present.
1028       </dd>
1029     </dl>
1030
1031     <p class="rule">
1032       <span class="rule_id"></span>
1033       If <span class="field">AuthenticationType</span> is set to <span class="value">Cert</span>, <span class="field">ServerCARefs</span> or <span class="field">ServerCARef</span> must be set.
1034     </p>
1035
1036     <p class="rule">
1037       <span class="rule_id"></span>
1038       At most one of <span class="field">ServerCARefs</span> and <span class="field">ServerCARef</span> can be set.
1039     </p>
1040
1041     <p>
1042       <span class="type">L2TP</span> type contains the following:
1043     </p>
1044
1045     <dl class="field_list">
1046       <dt class="field">LcpEchoDisabled</dt>
1047       <dd>
1048         <span class="field_meta">
1049           (optional, defaults to <span class="value">false</span>)
1050           <span class="type">boolean</span>
1051         </span>
1052         Disable L2TP connection monitoring via PPP LCP frames.  This
1053         allows the VPN client to work around server implementations
1054         that do not support the LCP echo feature.
1055       </dd>
1056
1057       <dt class="field">Password</dt>
1058       <dd>
1059         <span class="field_meta">
1060           (optional)
1061           <span class="type">string</span>
1062         </span>
1063         User authentication password. If not specified, user is prompted at time
1064         of connection.
1065       </dd>
1066
1067       <dt class="field">SaveCredentials</dt>
1068       <dd>
1069         <span class="field_meta">
1070           (optional, defaults to <span class="value">false</span>)
1071           <span class="type">boolean</span>
1072         </span>
1073         If <span class="value">false</span>, require user to enter credentials
1074         each time they connect.
1075       </dd>
1076
1077       <dt class="field">Username</dt>
1078       <dd>
1079         <span class="field_meta">
1080           (optional)
1081           <span class="type">string</span>
1082         </span>
1083         User identity. This value is subject to string expansions. If not
1084         specified, user is prompted at time of connection.
1085       </dd>
1086     </dl>
1087
1088     <p>
1089       <span class="type">XAUTH</span> type contains the following:
1090     </p>
1091
1092     <dl class="field_list">
1093       <dt class="field">Password</dt>
1094       <dd>
1095         <span class="field_meta">
1096           (optional)
1097           <span class="type">string</span>
1098         </span>
1099         XAUTH password. If not specified, user is prompted at time of
1100         connection.
1101       </dd>
1102
1103       <dt class="field">SaveCredentials</dt>
1104       <dd>
1105         <span class="field_meta">
1106           (optional, defaults to <span class="value">false</span>)
1107           <span class="type">boolean</span>
1108         </span>
1109         If <span class="value">false</span>, require user to enter credentials
1110         each time they connect.
1111       </dd>
1112
1113       <dt class="field">Username</dt>
1114       <dd>
1115         <span class="field_meta">
1116           (optional)
1117           <span class="type">string</span>
1118         </span>
1119         XAUTH user name. This value is subject to string expansions. If not
1120         specified, user is prompted at time of connection.
1121       </dd>
1122     </dl>
1123
1124 <section>
1125   <h1>IPsec IKE v1 VPN connections</h1>
1126   <p>
1127     <span class="field">VPN.Type</span> must
1128     be <span class="value">IPsec</span>, <span class="field">IKEVersion</span>
1129     must be 1. Do not use this for L2TP over IPsec. This may be used for
1130     machine-authentication-only IKEv1 or for IKEv1 with XAUTH. See
1131     the <span class="type">IPsec</span> type described below.
1132   </p>
1133 </section>
1134
1135 <section>
1136   <h1>IPsec IKE v2 VPN connections</h1>
1137   <p>
1138     <span class="field">VPN.Type</span> must
1139     be <span class="value">IPsec</span>, <span class="field">IKEVersion</span>
1140     must be 2. This may be used with EAP-based user authentication.
1141   </p>
1142 </section>
1143
1144 <section>
1145   <h1>L2TP over IPsec VPN connections</h1>
1146   <p>
1147     There are two major configurations L2TP over IPsec which depend on how IPsec
1148     is authenticated. In either case <span class="field">Type</span> must be
1149     <span class="value">L2TP-IPsec</span>. They are described below.
1150   </p>
1151
1152   <p>
1153     L2TP over IPsec with pre-shared key:
1154   </p>
1155
1156   <ul>
1157     <li>The field <span class="field">IPsec</span> must be present and have the
1158     following settings:
1159       <ul>
1160         <li><span class="field">IKEVersion</span> must be 1.</li>
1161         <li><span class="field">AuthenticationType</span> must be PSK.</li>
1162         <li><span class="field">XAUTH</span> must not be set.</li>
1163       </ul>
1164     </li>
1165     <li>The field <span class="field">L2TP</span> must be present.</li>
1166   </ul>
1167 </section>
1168
1169 </section>
1170
1171 <section>
1172   <h1>OpenVPN connections and types</h1>
1173   <p>
1174     <span class="field">VPN.Type</span> must be
1175     <span class="value">OpenVPN</span>.
1176   </p>
1177
1178   <p>
1179     <span class="type">OpenVPN</span> type contains the following:
1180   </p>
1181
1182   <dl class="field_list">
1183     <dt class="field">Auth</dt>
1184     <dd>
1185       <span class="field_meta">
1186         (optional, defaults to <span class="value">SHA1</span>)
1187         <span class="type">string</span>
1188       </span>
1189     </dd>
1190
1191     <dt class="field">AuthRetry</dt>
1192     <dd>
1193       <span class="field_meta">
1194         (optional, defaults to <span class="value">none</span>)
1195         <span class="type">string</span>
1196       </span>
1197       <span class="rule">
1198         <span class="rule_id"></span>
1199         Allowed values are <span class="value">none</span>,
1200         <span class="value">nointeract</span>, and
1201         <span class="value">interact</span>.
1202       </span>
1203       Controls how OpenVPN responds to username/password verification
1204       errors:<br> Either fail with error on retry
1205       (<span class="value">none</span>), retry without asking for authentication
1206       (<span class="value">nointeract</span>), or ask again for authentication
1207       each time (<span class="value">interact</span>).
1208     </dd>
1209
1210     <dt class="field">AuthNoCache</dt>
1211     <dd>
1212       <span class="field_meta">
1213         (optional, defaults to <span class="value">false</span>)
1214         <span class="type">boolean</span>
1215       </span>
1216       Disable caching of credentials in memory.
1217     </dd>
1218
1219     <dt class="field">Cipher</dt>
1220     <dd>
1221       <span class="field_meta">
1222         (optional, defaults to <span class="value">BF-CBC</span>)
1223         <span class="type">string</span>
1224       </span>
1225       Cipher to use.
1226     </dd>
1227
1228     <dt class="field">ClientCertRef</dt>
1229     <dd>
1230       <span class="field_meta">
1231         (required if <span class="field">ClientCertType</span> is
1232         <span class="value">Ref</span>, otherwise ignored)
1233         <span class="type">string</span>
1234       </span>
1235       Reference to client certificate stored in certificate section.
1236     </dd>
1237
1238     <dt class="field">ClientCertPattern</dt>
1239     <dd>
1240       <span class="field_meta">
1241         (required if <span class="field">ClientCertType</span> is
1242         <span class="value">Pattern</span>, otherwise ignored)
1243         <span class="type">CertificatePattern</span>
1244       </span>
1245       Pattern to use to find the client certificate.
1246     </dd>
1247
1248     <dt class="field">ClientCertType</dt>
1249     <dd>
1250       <span class="field_meta">
1251         (required)
1252         <span class="type">string</span>
1253       </span>
1254       <span class="rule">
1255         <span class="rule_id"></span>
1256         Allowed values are <span class="value">Ref</span>,
1257         <span class="value">Pattern</span>, and <span class="value">None</span>.
1258       </span>
1259       <span class="value">None</span> implies that the server is configured to
1260       not require client certificates.
1261     </dd>
1262
1263     <dt class="field">CompLZO</dt>
1264     <dd>
1265       <span class="field_meta">
1266         (optional, defaults to <span class="value">adaptive</span>)
1267         <span class="type">string</span>
1268       </span>
1269       Decides to fast LZO compression with <span class="value">true</span>
1270       and <span class="value">false</span> as other values.
1271     </dd>
1272
1273     <dt class="field">CompNoAdapt</dt>
1274     <dd>
1275       <span class="field_meta">
1276         (optional, defaults to <span class="value">false</span>)
1277         <span class="type">boolean</span>
1278       </span>
1279       Disables adaptive compression.
1280     </dd>
1281
1282     <dt class="field">IgnoreDefaultRoute</dt>
1283     <dd>
1284       <span class="field_meta">
1285         (optional, defaults to <span class="value">false</span>)
1286         <span class="type">bool</span>
1287       </span>
1288       Omits a default route to the VPN gateway while the connection is active.
1289       By default, the client creates a default route to the gateway address
1290       advertised by the VPN server.  Setting this value to
1291       <span class="value">true</span> will allow split tunnelling for
1292       configurations where the VPN server omits explicit default routes.
1293       This is roughly equivalent to omitting "redirect-gateway" OpenVPN client
1294       configuration option.  If the server pushes a "redirect-gateway"
1295       configuration flag to the client, this option is ignored.
1296     </dd>
1297
1298     <dt class="field">KeyDirection</dt>
1299     <dd>
1300       <span class="field_meta">
1301         (optional)
1302         <span class="type">string</span>
1303       </span>
1304       Passed as --key-direction.
1305     </dd>
1306
1307     <dt class="field">NsCertType</dt>
1308     <dd>
1309       <span class="field_meta">
1310         (optional)
1311         <span class="type">string</span>
1312       </span>
1313       If set, checks peer certificate type. Should only be set
1314       to <span class="value">server</span> if set.
1315     </dd>
1316
1317     <dt class="field">OTP</dt>
1318     <dd>
1319       <span class="field_meta">
1320         (optional if <span class="field">UserAuthenticationType</span> is
1321         <span class="value">OTP</span>,
1322         <span class="value">PasswordAndOTP</span> or unset, otherwise ignored,
1323         defaults to empty string)
1324         <span class="type">string</span>
1325       </span>
1326       If <span class="field">UserAuthenticationType</span> is
1327       <span class="value">OTP</span> or <span class="value">PasswordAndOTP</span>
1328       and this field is not set, the user will be asked for an OTP.
1329       The OTP is never persisted and must be provided on every connection
1330       attempt.
1331     </dd>
1332
1333     <dt class="field">Password</dt>
1334     <dd>
1335       <span class="field_meta">
1336         (optional if <span class="field">UserAuthenticationType</span> is
1337         <span class="value">Password</span>,
1338         <span class="value">PasswordAndOTP</span> or unset, otherwise ignored,
1339         defaults to empty string)
1340         <span class="type">string</span>
1341       </span>
1342       If <span class="field">UserAuthenticationType</span> is
1343       <span class="value">Password</span> or
1344       <span class="value">PasswordAndOTP</span> and this field is not set, the user
1345       will be asked for a password.
1346       If <span class="field">SaveCredentials</span> is
1347       <span class="value">true</span>, the password is persisted for future
1348       connection attempts. Otherwise it is not persisted but might still be
1349       reused for consecutive connection attempts (opposed to an OTP, which will
1350       never be reused).
1351     </dd>
1352
1353     <dt class="field">Port</dt>
1354     <dd>
1355       <span class="field_meta">
1356         (optional, defaults to <span class="value">1194</span>)
1357         <span class="type">integer</span>
1358       </span>
1359       Port for connecting to server.
1360     </dd>
1361
1362     <dt class="field">Proto</dt>
1363     <dd>
1364       <span class="field_meta">
1365         (optional, defaults to <span class="value">udp</span>)
1366         <span class="type">string</span>
1367       </span>
1368       Protocol for communicating with server.
1369     </dd>
1370
1371     <dt class="field">PushPeerInfo</dt>
1372     <dd>
1373       <span class="field_meta">
1374         (optional, defaults to <span class="value">false</span>)
1375         <span class="type">boolean</span>
1376       </span>
1377     </dd>
1378
1379     <dt class="field">RemoteCertEKU</dt>
1380     <dd>
1381       <span class="field_meta">
1382         (optional)
1383         <span class="type">string</span>
1384       </span>
1385       Require that the peer certificate was signed with this explicit extended
1386       key usage in oid notation.
1387     </dd>
1388
1389     <dt class="field">RemoteCertKU</dt>
1390     <dd>
1391       <span class="field_meta">
1392         (optional, defaults to [])
1393         <span class="type">array of string</span>
1394       </span>
1395       Require the given array of key usage numbers. These are strings that are
1396       hex encoded numbers.
1397     </dd>
1398
1399     <dt class="field">RemoteCertTLS</dt>
1400     <dd>
1401       <span class="field_meta">
1402         (optional, defaults to <span class="value">server</span>)
1403         <span class="type">string</span>
1404       </span>
1405       <span class="rule">
1406         <span class="rule_id"></span>
1407         Allowed values are <span class="value">none</span> and
1408         <span class="value">server</span>.
1409       </span>
1410       Require peer certificate signing based on RFC3280 TLS rules.
1411     </dd>
1412
1413     <dt class="field">RenegSec</dt>
1414     <dd>
1415       <span class="field_meta">
1416         (optional, defaults to <span class="value">3600</span>)
1417         <span class="type">integer</span>
1418       </span>
1419       Renegotiate data channel key after this number of seconds.
1420     </dd>
1421
1422     <dt class="field">SaveCredentials</dt>
1423     <dd>
1424       <span class="field_meta">
1425         (optional, defaults to <span class="value">false</span>)
1426         <span class="type">boolean</span>
1427       </span>
1428       If <span class="value">false</span>, require user to enter credentials
1429       each time they connect.
1430     </dd>
1431
1432     <dt class="field">ServerCARefs</dt>
1433     <dd>
1434       <span class="field_meta">
1435         (optional)
1436         <span class="type">array of string</span>
1437       </span>
1438       Non-empty list of references to CA certificates in <span class="field">Certificates</span> to be used for verifying the host's certificate chain. At least one of the CA certificates must match. See also OpenVPN's command line option "--ca". If this field is set, <span class="field">ServerCARef</span> must be unset.
1439     </dd>
1440
1441     <dt class="field">ServerCARef</dt>
1442     <dd>
1443       <span class="field_meta">
1444         (optional)
1445         <span class="type">string</span>
1446       </span>
1447       DEPRECATED, use <span class="field">ServerCARefs</span> instead.<br/>
1448       Reference to a CA certificate in <span class="field">Certificates</span>. Certificate authority to use for verifying connection. If this field is set, <span class="field">ServerCARefs</span> must be unset.
1449     </dd>
1450
1451     <dt class="field">ServerCertRef</dt>
1452     <dd>
1453       <span class="field_meta">
1454         (optional)
1455         <span class="type">string</span>
1456       </span>
1457       Reference to a certificate. Peer's signed certificate.
1458     </dd>
1459
1460     <dt class="field">ServerPollTimeout</dt>
1461     <dd>
1462       <span class="field_meta">
1463         (optional)
1464         <span class="type">integer</span>
1465       </span>
1466       Spend no more than this number of seconds before trying the next server.
1467     </dd>
1468
1469     <dt class="field">Shaper</dt>
1470     <dd>
1471       <span class="field_meta">
1472         (optional)
1473         <span class="type">integer</span>
1474       </span>
1475       If not specified no bandwidth limiting, otherwise limit bandwidth of
1476       outgoing tunnel data to this number of bytes per second.
1477     </dd>
1478
1479     <dt class="field">StaticChallenge</dt>
1480     <dd>
1481       <span class="field_meta">
1482         (optional)
1483         <span class="type">string</span>
1484       </span>
1485       String is used in static challenge response. Note that echoing is always
1486       done.
1487     </dd>
1488
1489     <dt class="field">TLSAuthContents</dt>
1490     <dd>
1491       <span class="field_meta">
1492         (optional)
1493         <span class="type">string</span>
1494       </span>
1495       If not set, tls auth is not used. If set, this is the TLS Auth key
1496       contents (usually starts with "-----BEGIN OpenVPN Static Key..."
1497     </dd>
1498
1499     <dt class="field">TLSRemote</dt>
1500     <dd>
1501       <span class="field_meta">
1502         (optional)
1503         <span class="type">string</span>
1504       </span>
1505       If set, only allow connections to server hosts with X509 name or common
1506       name equal to this string.
1507     </dd>
1508
1509     <dt class="field">UserAuthenticationType</dt>
1510     <dd>
1511       <span class="field_meta">
1512         (optional, defaults to <span class="value">None</span>)
1513         <span class="type">string</span>
1514       </span>
1515       <span class="rule">
1516         <span class="rule_id"></span>
1517         Allowed values are <span class="value">None</span>,
1518         <span class="value">Password</span>,
1519         <span class="value">PasswordAndOTP</span> and
1520         <span class="value">OTP</span>.
1521       </span>
1522       Determines the required form of user authentication:
1523       <ul><li>
1524         <span class="value">PasswordAndOTP</span>: This VPN requires a password
1525         and an OTP (possibly empty). Both will be send to the server in the
1526         'password' response using the SCRv1 encoding.
1527       </li><li>
1528         <span class="value">Password</span>: This VPN requires only a password,
1529         which will be send without modification to the server in the 'password'
1530         response (no CRv1 or SCRv1 encoding).
1531       </li><li>
1532         <span class="value">OTP</span>: This VPN requires only an OTP, which
1533         will be send without modification to the server in the 'password'
1534         response (no CRv1 or SCRv1 encoding).
1535       </li><li>
1536         <span class="value">None</span>: Neither password nor OTP are required.
1537         No password request from the server is expected.
1538       </li></ul>
1539       If not set, the user can provide a password and an OTP (both not
1540       mandatory) and the network manager will send both in the SCRv1 encoding,
1541       when the server sends a static-challenge. If the server does not send a
1542       static-challenge, the client will reply with only the password (without
1543       any encoding). This behavior is deprecated and new configurations should
1544       explicitly set one of the above values.
1545
1546       See the fields <span class="field">Password</span> and
1547       <span class="field">OTP</span> for configuring the password and OTP.
1548     </dd>
1549
1550     <dt class="field">Username</dt>
1551     <dd>
1552       <span class="field_meta">
1553         (optional)
1554         <span class="type">string</span>
1555       </span>
1556       OpenVPN user name. This value is subject to string expansions. If not
1557       specified, user is prompted at time of connection.
1558     </dd>
1559
1560     <dt class="field">Verb</dt>
1561     <dd>
1562       <span class="field_meta">
1563         (optional)
1564         <span class="type">string</span>
1565       </span>
1566       Verbosity level, defaults to OpenVpn's default if not specified.
1567     </dd>
1568
1569     <dt class="field">VerifyHash</dt>
1570     <dd>
1571       <span class="field_meta">
1572         (optional)
1573         <span class="type">string</span>
1574       </span>
1575       If set, this value is passed as the "--verify-hash" argument to OpenVPN,
1576       which specifies the SHA1 fingerprint for the level-1 certificate.
1577     </dd>
1578
1579     <dt class="field">VerifyX509</dt>
1580     <dd>
1581       <span class="field_meta">
1582         (optional)
1583         <span class="type">VerifyX509</span>
1584       </span>
1585        If set, the "--verify-x509-name" argument is passed to OpenVPN with the values of this object and only connections will be accepted if a host's X.509 name is equal to the given name.
1586     </dd>
1587   </dl>
1588
1589   <p class="rule">
1590     <span class="rule_id"></span>
1591     At most one of <span class="field">ServerCARefs</span> and <span class="field">ServerCARef</span> can be set.
1592   </p>
1593
1594   <p>
1595     <span class="type">VerifyX509</span> type contains the following:
1596   </p>
1597   <dl class="field_list">
1598     <dt class="field">Name</dt>
1599     <dd>
1600       <span class="field_meta">
1601         (required)
1602         <span class="type">string</span>
1603       </span>
1604       The name that the host's X.509 name is compared to. Which host name is compared depends on the value of <span class="field">Type</span>.
1605     </dd>
1606
1607     <dt class="field">Type</dt>
1608     <dd>
1609       <span class="field_meta">
1610         (optional)
1611         <span class="type">string</span>
1612       </span>
1613       Determines which of the host's X.509 names will be verified. Allowed values are <span class="value">name</span>, <span class="value">name-prefix</span> and <span class="value">subject</span>. See OpenVPN's documentation for "--verify-x509-name" for the meaning of each value. Defaults to OpenVPN's default if not specified.
1614     </dd>
1615   </dl>
1616 </section>
1617
1618 <section>
1619   <h1>Third-party VPN provider based connections and types</h1>
1620   <p>
1621     <span class="field">VPN.Type</span> must be
1622     <span class="value">ThirdPartyVPN</span>.
1623   </p>
1624
1625   <p>
1626     <span class="type">ThirdPartyVPN</span> type contains the following:
1627   </p>
1628
1629   <dl class="field_list">
1630     <dt class="field">ExtensionID</dt>
1631     <dd>
1632       <span class="field_meta">
1633         (required)
1634         <span class="type">string</span>
1635       </span>
1636       The extension ID of the third-party VPN provider used by this network.
1637     </dd>
1638     <dt class="field">ProviderName</dt>
1639     <dd>
1640       <span class="field_meta">
1641         (optional, read-only)
1642         <span class="type">string</span>
1643       </span>
1644       The name of the third-party VPN provider used by this network.
1645     </dd>
1646   </dl>
1647 </section>
1648
1649 </section>
1650
1651 <section>
1652   <h1>Client certificate patterns</h1>
1653   <p>
1654     In order to allow clients to securely key their private keys and request
1655     certificates through PKCS#10 format or through a web flow, we provide
1656     alternative CertificatePattern types. The
1657     <span class="type">CertificatePattern</span> type contains the following:
1658   </p>
1659
1660   <dl class="field_list">
1661     <dt class="field">IssuerCARef</dt>
1662     <dd>
1663       <span class="field_meta">
1664         (optional)
1665         <span class="type">array of string</span>
1666       </span>
1667       Array of references to certificates. At least one must have signed the
1668       client certificate.
1669     </dd>
1670
1671     <dt class="field">Issuer</dt>
1672     <dd>
1673       <span class="field_meta">
1674         (optional)
1675         <span class="type">IssuerSubjectPattern</span>
1676       </span>
1677       Pattern to match the issuer X.509 settings against. If not specified, the
1678       only checks done will be a signature check against
1679       the <span class="field">IssuerCARef</span> field. Issuer of the
1680       certificate must match this field exactly to match the pattern.
1681     </dd>
1682
1683     <dt class="field">Subject</dt>
1684     <dd>
1685       <span class="field_meta">
1686         (optional)
1687         <span class="type">IssuerSubjectPattern</span>
1688       </span>
1689       Pattern to match the subject X.509 settings against. If not specified, the
1690       subject settings are not checked and any certificate matches. Subject of
1691       the certificate must match this field exactly to match the pattern.
1692     </dd>
1693
1694     <dt class="field">EnrollmentURI</dt>
1695     <dd>
1696       <span class="field_meta">
1697         (optional)
1698         <span class="type">array of string</span>
1699       </span>
1700       If no certificate matches this CertificatePattern, the first URI from this
1701       array with a recognized scheme is navigated to, with the intention this
1702       informs the user how to either get the certificate or gets the certificate
1703       for the user. For instance, the array may be [
1704       "chrome-extension://asakgksjssjwwkeielsjs/fetch-client-cert.html",
1705       "http://intra/connecting-to-wireless.html" ] so that for Chrome browsers a
1706       Chrome app or extension is shown to the user, but for other browsers, a
1707       web URL is shown.
1708     </dd>
1709   </dl>
1710
1711   <p>
1712     The <span class="type">IssuerSubjectPattern</span> type contains the
1713     following:
1714   </p>
1715
1716   <dl class="field_list">
1717     <dt class="field">CommonName</dt>
1718     <dd>
1719       <span class="field_meta">
1720         (optional)
1721         <span class="type">string</span>
1722       </span>
1723       Certificate subject's commonName must match this string if present.
1724     </dd>
1725
1726     <dt class="field">Locality</dt>
1727     <dd>
1728       <span class="field_meta">
1729         (optional)
1730         <span class="type">string</span>
1731       </span>
1732       Certificate subject's location must match this string if present.
1733     </dd>
1734
1735     <dt class="field">Organization</dt>
1736     <dd>
1737       <span class="field_meta">
1738         (optional)
1739         <span class="type">string</span>
1740       </span>
1741       At least one of certificate subject's organizations must match this string
1742       if present.
1743     </dd>
1744
1745     <dt class="field">OrganizationalUnit</dt>
1746     <dd>
1747       <span class="field_meta">
1748         (optional)
1749         <span class="type">string</span>
1750       </span>
1751       At least one of certificate subject's organizational units must match this
1752       string if present.
1753     </dd>
1754   </dl>
1755
1756   <p class="rule">
1757     <span class="rule_id"></span>
1758     One field in <span class="field">Subject</span>,
1759     <span class="field">Issuer</span>, or <span class="field">IssuerCARef</span>
1760     must be given for a <span class="type">CertificatePattern</span> typed field
1761     to be valid.
1762   </p>
1763
1764   <p>
1765     For a certificate to be considered matching, it must match all
1766     the fields in the certificate pattern. If multiple certificates match, the
1767     certificate with the latest issue date that is still in the past, and hence
1768     valid, will be used.
1769   </p>
1770
1771   <p>
1772     If <span class="field">EnrollmentURI</span> is not given and no match is
1773     found to this pattern, the importing tool may show an error to the user.
1774   </p>
1775 </section>
1776
1777 <section>
1778   <h1>Proxy settings</h1>
1779   <p>
1780     Every network can be configured to use a
1781     proxy. The <span class="type">ProxySettings</span> type contains the
1782     following:
1783   </p>
1784
1785   <dl class="field_list">
1786     <dt class="field">Type</dt>
1787     <dd>
1788       <span class="field_meta">
1789         (required)
1790         <span class="type">string</span>
1791       </span>
1792       <span class="rule">
1793         <span class="rule_id"></span>
1794         Allowed values are <span class="value">Direct</span>,
1795         <span class="value">Manual</span>, <span class="value">PAC</span>, and
1796         <span class="value">WPAD</span>.
1797       </span>
1798       <span class="value">PAC</span> indicates Proxy Auto-Configuration.
1799       <span class="value">WPAD</span> indicates Web Proxy Autodiscovery.
1800     </dd>
1801
1802     <dt class="field">Manual</dt>
1803     <dd>
1804       <span class="field_meta">
1805         (required if <span class="field">Type</span>
1806         is <span class="value">Manual</span>, otherwise ignored)
1807         <span class="type">ManualProxySettings</span>
1808       </span>
1809       Manual proxy settings.
1810     </dd>
1811
1812     <dt class="field">ExcludeDomains</dt>
1813     <dd>
1814       <span class="field_meta">
1815         (optional if <span class="field">Type</span>
1816         is <span class="value">Manual</span>, otherwise ignored)
1817         <span class="type">array of string</span>
1818       </span>
1819       Domains and hosts for which to exclude proxy settings.
1820     </dd>
1821
1822     <dt class="field">PAC</dt>
1823     <dd>
1824       <span class="field_meta">
1825         (required if <span class="field">Type</span> is
1826         <span class="value">PAC</span>, otherwise ignored)
1827         <span class="type">string</span>
1828       </span>
1829       URL of proxy auto-config file.
1830     </dd>
1831   </dl>
1832
1833   <p>
1834     The <span class="type">ManualProxySettings</span> type contains the
1835     following:
1836   </p>
1837
1838   <dl class="field_list">
1839     <dt class="field">HTTPProxy</dt>
1840     <dd>
1841       <span class="field_meta">
1842         (optional)
1843         <span class="type">ProxyLocation</span>
1844       </span>
1845       settings for HTTP proxy.
1846     </dd>
1847
1848     <dt class="field">SecureHTTPProxy</dt>
1849     <dd>
1850       <span class="field_meta">
1851         (optional)
1852         <span class="type">ProxyLocation</span>
1853       </span>
1854       settings for secure HTTP proxy.
1855     </dd>
1856
1857     <dt class="field">FTPProxy</dt>
1858     <dd>
1859       <span class="field_meta">
1860         (optional)
1861         <span class="type">ProxyLocation</span>
1862       </span>
1863       settings for FTP proxy
1864     </dd>
1865
1866     <dt class="field">SOCKS</dt>
1867     <dd>
1868       <span class="field_meta">
1869         (optional)
1870         <span class="type">ProxyLocation</span>
1871       </span>
1872       settings for SOCKS proxy.
1873     </dd>
1874   </dl>
1875
1876   <p>
1877     The <span class="type">ProxyLocation</span> type contains the following:
1878   </p>
1879
1880   <dl class="field_list">
1881     <dt class="field">Host</dt>
1882     <dd>
1883       <span class="field_meta">
1884         (required)
1885         <span class="type">string</span>
1886       </span>
1887       Host (or IP address) to use for proxy
1888     </dd>
1889
1890     <dt class="field">Port</dt>
1891     <dd>
1892       <span class="field_meta">
1893         (required)
1894         <span class="type">integer</span>
1895       </span>
1896       Port to use for proxy
1897     </dd>
1898   </dl>
1899 </section>
1900
1901 <section>
1902   <h1>EAP configurations</h1>
1903   <p>
1904     For networks with 802.1X authentication, an <span class="type">EAP</span>
1905     type exists to configure the
1906     authentication. The <span class="type">EAP</span> type contains the
1907     following:
1908   </p>
1909
1910   <dl class="field_list">
1911     <dt class="field">AnonymousIdentity</dt>
1912     <dd>
1913       <span class="field_meta">
1914         (optional if <span class="field">Outer</span> is
1915         <span class="value">PEAP</span> or <span class="value">EAP-TTLS</span>,
1916         otherwise ignored)
1917         <span class="type">string</span>
1918       </span>
1919       For tunnelling protocols only, this indicates the identity of the user
1920       presented to the outer protocol. This value is subject to string
1921       expansions. If not specified, use empty string.
1922     </dd>
1923
1924     <dt class="field">ClientCertPattern</dt>
1925     <dd>
1926       <span class="field_meta">
1927         (required if <span class="field">ClientCertType</span> is
1928         <span class="value">Pattern</span>, otherwise ignored)
1929         <span class="type">CertificatePattern</span>
1930       </span>
1931       Pattern to use to find the client certificate.
1932     </dd>
1933
1934     <dt class="field">ClientCertRef</dt>
1935     <dd>
1936       <span class="field_meta">
1937         (required if <span class="field">ClientCertType</span> is
1938         <span class="value">Ref</span>, otherwise ignored)
1939         <span class="type">string</span>
1940       </span>
1941       Reference to client certificate stored in certificate section.
1942     </dd>
1943
1944     <dt class="field">ClientCertType</dt>
1945     <dd>
1946       <span class="field_meta">
1947         (optional) <span class="type">string</span>
1948       </span>
1949       <span class="rule">
1950         <span class="rule_id"></span>
1951         Allowed values are <span class="value">Ref</span>, and
1952         <span class="value">Pattern</span>.
1953       </span>
1954     </dd>
1955
1956     <dt class="field">Identity</dt>
1957     <dd>
1958       <span class="field_meta">
1959         (optional)
1960         <span class="type">string</span>
1961       </span>
1962       Identity of user. For tunneling outer protocols
1963       (<span class="value">PEAP</span>, <span class="value">EAP-TTLS</span>, and
1964       <span class="value">EAP-FAST</span>), this is used to authenticate inside
1965       the tunnel, and <span class="field">AnonymousIdentity</span> is used for
1966       the EAP identity outside the tunnel. For non-tunneling outer protocols,
1967       this is used for the EAP identity. This value is subject to string
1968       expansions.
1969     </dd>
1970
1971     <dt class="field">Inner</dt>
1972     <dd>
1973       <span class="field_meta">
1974         (optional if <span class="field">Outer</span> is
1975         <span class="value">EAP-FAST</span>, <span class="value">EAP-TTLS</span>
1976         or <span class="value">PEAP</span>, otherwise ignored, defaults to
1977         <span class="value">Automatic</span>)
1978         <span class="type">string</span>
1979       </span>
1980       <span class="rule">
1981         <span class="rule_id"></span>
1982         Allowed values are <span class="value">Automatic</span>,
1983         <span class="value">MD5</span>, <span class="value">MSCHAPv2</span>,
1984         <span class="value">EAP-MSCHAPv2</span>,
1985         <span class="value">PAP</span>, and <span class="value">GTC</span>.
1986       </span>
1987       For tunneling outer protocols.
1988     </dd>
1989
1990     <dt class="field">Outer</dt>
1991     <dd>
1992       <span class="field_meta">
1993         (required)
1994         <span class="type">string</span>
1995       </span>
1996       <span class="rule">
1997         <span class="rule_id"></span>
1998         Allowed values are <span class="value">LEAP</span>,
1999         <span class="value">EAP-AKA</span>, <span class="value">EAP-FAST</span>,
2000         <span class="value">EAP-TLS</span>, <span class="value">EAP-TTLS</span>,
2001         <span class="value">EAP-SIM</span> and <span class="value">PEAP</span>.
2002       </span>
2003     </dd>
2004
2005     <dt class="field">Password</dt>
2006     <dd>
2007       <span class="field_meta">
2008         (optional)
2009         <span class="type">string</span>
2010       </span>
2011       Password of user. If not specified, defaults to prompting the user.
2012     </dd>
2013
2014     <dt class="field">SaveCredentials</dt>
2015     <dd>
2016       <span class="field_meta">
2017         (optional, defaults to <span class="value">false</span>)
2018         <span class="type">boolean</span>
2019       </span>
2020       If <span class="value">false</span>, require user to enter credentials
2021       each time they connect. Specifying <span class="field">Identity</span>
2022       and/or <span class="field">Password</span> when
2023       <span class="field">SaveCredentials</span> is
2024       <span class="value">false</span> is not allowed.
2025     </dd>
2026
2027     <dt class="field">ServerCARefs</dt>
2028     <dd>
2029       <span class="field_meta">
2030         (optional)
2031         <span class="type">array of string</span>
2032       </span>
2033       Non-empty list of references to CA certificates in <span class="field">Certificates</span> to be used for verifying the host's certificate chain. At least one of the CA certificates must match. If this field is set, <span class="field">ServerCARef</span> must be unset. If neither <span class="field">ServerCARefs</span> nor <span class="field">ServerCARef</span> is set, the client does not check that the server certificate is signed by a specific CA. A verification using the system's CA certificates may still apply. See <span class="field">UseSystemCAs</span> for this.
2034     </dd>
2035
2036     <dt class="field">ServerCARef</dt>
2037     <dd>
2038       <span class="field_meta">
2039         (optional)
2040         <span class="type">string</span>
2041       </span>
2042       DEPRECATED, use <span class="field">ServerCARefs</span> instead.<br/>
2043       Reference to a CA certificate in <span class="field">Certificates</span>. If this field is set, <span class="field">ServerCARefs</span> must be unset. If neither <span class="field">ServerCARefs</span> nor <span class="field">ServerCARef</span> is set, the client does not check that the server certificate is signed by a specific CA. A verification using the system's CA certificates may still apply. See <span class="field">UseSystemCAs</span> for this.
2044     </dd>
2045
2046     <dt class="field">UseSystemCAs</dt>
2047     <dd>
2048       <span class="field_meta">
2049         (optional, defaults to <span class="value">true</span>)
2050         <span class="type">boolean</span>
2051       </span>
2052       Required server certificate to be signed by "system default certificate
2053       authorities". If both <span class="field">ServerCARefs</span> (or <span class="field">ServerCARef</span>)
2054       and <span class="field">UseSystemCAs</span> are supplied, a server
2055       certificate will be allowed if it either has a chain of trust to a system
2056       CA or to one of the given CA certificates. If <span class="field">UseSystemCAs</span>
2057       is <span class="value">false</span>, and no <span class="field">ServerCARef</span> is set, the certificate
2058       must be a self signed certificate, and no CA signature is required.
2059     </dd>
2060
2061     <dt class="field">UseProactiveKeyCaching</dt>
2062     <dd>
2063       <span class="field_meta">
2064         (optional, defaults to <span class="value">false</span>)
2065         <span class="type">boolean</span>
2066       </span>
2067       Indicates whether Proactive Key Caching (also known as Opportunistic
2068       Key Caching) should be used on a per-service basis.
2069     </dd>
2070   </dl>
2071
2072   <p class="rule">
2073     <span class="rule_id"></span>
2074     At most one of <span class="field">ServerCARefs</span> and <span class="field">ServerCARef</span> can be set.
2075   </p>
2076 </section>
2077
2078 <section>
2079   <h1>WiMAX Networks</h1>
2080   <p>
2081     For WiMAX connections, <span class="field">Type</span> must be set to
2082     <span class="value">WiMAX</span> and the
2083     field <span class="field">WiMAX</span> must be set to an object of
2084     type <span class="type">WiMAX</span>. Currently only used for
2085     representing an existing configuration; ONC configuration of
2086     of <span class="field">WiMAX</span> networks is not yet fully supported.
2087     Contains the following fields:
2088   </p>
2089
2090   <dl class="field_list">
2091     <dt class="field">AutoConnect</dt>
2092     <dd>
2093       <span class="field_meta">
2094         (optional, defaults to <span class="value">false</span>)
2095         <span class="type">boolean</span>
2096       </span>
2097       Indicating that the network should be connected to automatically when
2098       possible.
2099     </dd>
2100
2101     <dt class="field">EAP</dt>
2102     <dd>
2103       <span class="field_meta">
2104         (required)
2105         <span class="type">EAP</span>
2106       </span>
2107       EAP settings.
2108     </dd>
2109
2110     <dt class="field">SignalStrength</dt>
2111     <dd>
2112       <span class="field_meta">
2113         (optional, read-only)
2114         <span class="type">integer</span>
2115       </span>
2116       The current signal strength for this network in the range [0, 100],
2117       provided by the system. If the network is not in range this field will
2118       be set to '0' or not present.
2119     </dd>
2120   </dl>
2121
2122 </section>
2123
2124 <section>
2125   <h1>Cellular Networks</h1>
2126   <p>
2127     For Cellular connections, <span class="field">Type</span> must be set to
2128     <span class="value">Cellular</span> and the
2129     field <span class="field">Cellular</span> must be set to an object of
2130     type <span class="type">Cellular</span>. Currently only used for
2131     representing an existing configuration; ONC configuration of
2132     of <span class="field">Cellular</span> networks is not yet supported.
2133     Contains the following fields:
2134   </p>
2135
2136   <dl class="field_list">
2137     <dt class="field">AutoConnect</dt>
2138     <dd>
2139       <span class="field_meta">
2140         (optional, defaults to <span class="value">false</span>)
2141         <span class="type">boolean</span>
2142       </span>
2143       Indicating that the network should be connected to automatically when
2144       possible. Note, that disabled <span class="field">AllowRoaming</span>
2145       takes precedence over autoconnect.
2146     </dd>
2147
2148     <dt class="field">APN</dt>
2149     <dd>
2150       <span class="field_meta">(optional)
2151         <span class="type">APN</span>
2152       </span>
2153       Currently active  <span class="type">APN</span> object to be used with a
2154       GSM carrier for making data connections.
2155     </dd>
2156
2157     <dt class="field">APNList</dt>
2158     <dd>
2159       <span class="field_meta">(optional, read-only)
2160         <span class="type">array of APN</span>
2161       </span>
2162       List of available APN configurations.
2163     </dd>
2164
2165     <dt class="field">ActivationType</dt>
2166     <dd>
2167       <span class="field_meta">(optional)
2168         <span class="type">string</span>
2169       </span>
2170       Activation type.
2171     </dd>
2172
2173     <dt class="field">ActivationState</dt>
2174     <dd>
2175       <span class="field_meta">(optional, read-only)
2176         <span class="type">string</span>
2177       </span>
2178       Carrier account activation state.
2179       <span class="rule">
2180         <span class="rule_id"></span>Allowed values are
2181         <span class="value">Activated</span>,
2182         <span class="value">Activating</span>,
2183         <span class="value">NotActivated</span>,
2184         <span class="value">PartiallyActivated</span>
2185       </span>
2186     </dd>
2187
2188     <dt class="field">AllowRoaming</dt>
2189     <dd>
2190       <span class="field_meta">(optional)
2191         <span class="type">boolean</span>
2192       </span>
2193       Whether cellular data connections are allowed when the device is roaming.
2194     </dd>
2195
2196     <dt class="field">Carrier</dt>
2197     <dd>
2198       <span class="field_meta">(optional, read-only)
2199         <span class="type">string</span>
2200       </span>
2201       The name of the carrier for which the device is configured.
2202     </dd>
2203
2204     <dt class="field">ESN</dt>
2205     <dd>
2206       <span class="field_meta">(optional, read-only)
2207         <span class="type">string</span>
2208       </span>
2209       The Electronic Serial Number of the cellular modem.
2210     </dd>
2211
2212     <dt class="field">Family</dt>
2213     <dd>
2214       <span class="field_meta">(optional, read-only)
2215         <span class="type">string</span>
2216       </span>
2217       Technology family.
2218       <span class="rule"><span class="rule_id"></span>
2219         Allowed values are
2220         <span class="value">CDMA</span>,
2221         <span class="value">GSM</span>
2222       </span>
2223     </dd>
2224
2225     <dt class="field">FirmwareRevision</dt>
2226     <dd>
2227       <span class="field_meta">(optional, read-only)
2228         <span class="type">string</span>
2229       </span>
2230       The revision of firmware that is loaded in the modem.
2231     </dd>
2232
2233     <dt class="field">FoundNetworks</dt>
2234     <dd>
2235       <span class="field_meta">(optional, read-only, provided only
2236         if <span class="field">Family</span> is <span class="value">GSM</span>)
2237         <span class="type">array of FoundNetwork</span>
2238       </span>
2239       The list of cellular netwoks found in the most recent scan operation.
2240     </dd>
2241
2242     <dt class="field">HardwareRevision</dt>
2243     <dd>
2244       <span class="field_meta">(optional, read-only)
2245         <span class="type">string</span>
2246       </span>
2247       The hardware revision of the cellular modem.
2248     </dd>
2249
2250     <dt class="field">HomeProvider</dt>
2251     <dd>
2252       <span class="field_meta">(optional, read-only)
2253         <span class="type">array of CellularProvider</span>
2254       </span>
2255       Description of the operator that issued the SIM card currently installed
2256       in the modem.
2257     </dd>
2258
2259     <dt class="field">ICCID</dt>
2260     <dd>
2261       <span class="field_meta">(optional, read-only, provided only
2262         if <span class="field">Family</span> is <span class="value">GSM</span>
2263         or <span class="field">NetworkTechnology</span>
2264         is <span class="value">LTE</span>)
2265         <span class="type">string</span>
2266       </span>
2267       For GSM / LTE modems, the Integrated Circuit Card Identifer of the SIM
2268       card installed in the device.
2269     </dd>
2270
2271     <dt class="field">IMEI</dt>
2272     <dd>
2273       <span class="field_meta">(optional, read-only)
2274         <span class="type">string</span>
2275       </span>
2276       The International Mobile Equipment Identity of the cellular modem.
2277     </dd>
2278
2279     <dt class="field">IMSI</dt>
2280     <dd>
2281       <span class="field_meta">(optional, read-only, provided only
2282         if <span class="field">Family</span> is <span class="value">GSM</span>)
2283         <span class="type">string</span>
2284       </span>
2285       For GSM modems, the International Mobile Subscriber Identity of the SIM
2286       card installed in the device.
2287     </dd>
2288
2289     <dt class="field">LastGoodAPN</dt>
2290     <dd>
2291       <span class="field_meta">(optional, read-only)
2292         <span class="type">APN</span>
2293       </span>
2294       The APN information used in the last successful connection attempt.
2295     </dd>
2296
2297     <dt class="field">Manufacturer</dt>
2298     <dd>
2299       <span class="field_meta">(optional, read-only)
2300         <span class="type">string</span>
2301       </span>
2302       The manufacturer of the cellular modem.
2303     </dd>
2304
2305     <dt class="field">MDN</dt>
2306     <dd>
2307       <span class="field_meta">(optional)
2308         <span class="type">string</span>
2309       </span>
2310       The Mobile Directory Number (i.e., phone number) of the device.
2311     </dd>
2312
2313     <dt class="field">MEID</dt>
2314     <dd>
2315       <span class="field_meta">(optional, read-only, provided only
2316         if <span class="field">Family</span> is <span class="value">CDMA</span>)
2317         <span class="type">string</span>
2318       </span>
2319       For CDMA modems, the Mobile Equipment Identifer of the cellular modem.
2320     </dd>
2321
2322     <dt class="field">MIN</dt>
2323     <dd>
2324       <span class="field_meta">(optional, read-only)
2325         <span class="type">string</span>
2326       </span>
2327       The Mobile Identification Number of the device.
2328     </dd>
2329
2330     <dt class="field">ModelID</dt>
2331     <dd>
2332       <span class="field_meta">(optional, read-only)
2333         <span class="type">string</span>
2334       </span>
2335       The hardware model of the cellular modem.
2336     </dd>
2337
2338     <dt class="field">NetworkTechnology</dt>
2339     <dd>
2340       <span class="field_meta">(optional, read-only)
2341         <span class="type">string</span>
2342       </span>
2343       If the modem is registered on a network, then this is set to the
2344       network technology currently in use.
2345       <span class="rule"><span class="rule_id"></span>
2346         Allowed values are
2347         <span class="value">CDMA1XRTT</span>,
2348         <span class="value">EDGE</span>,
2349         <span class="value">EVDO</span>,
2350         <span class="value">GPRS</span>,
2351         <span class="value">GSM</span>,
2352         <span class="value">HSPA</span>,
2353         <span class="value">HSPAPlus</span>,
2354         <span class="value">LTE</span>,
2355         <span class="value">LTEAdvanced</span>
2356         <span class="value">UMTS</span>,
2357       </span>
2358     </dd>
2359
2360     <dt class="field">PaymentPortal</dt>
2361     <dd>
2362       <span class="field_meta">(optional, read-only)
2363         <span class="type">PaymentPortal</span>
2364       </span>
2365       Properties describing the online payment portal (OLP) at which a user can
2366       sign up for or modify a mobile data plan.
2367     </dd>
2368
2369     <dt class="field">PRLVersion</dt>
2370     <dd>
2371       <span class="field_meta">(optional, read-only)
2372         <span class="type">integer</span>
2373       </span>
2374       The revision of the Preferred Roaming List that is loaded in the modem.
2375     </dd>
2376
2377     <dt class="field">RoamingState</dt>
2378     <dd>
2379       <span class="field_meta">(optional, read-only)
2380         <span class="type">string</span>
2381       </span>
2382       The roaming status of the cellular modem on the current network.
2383       <span class="rule"><span class="rule_id"></span>
2384         Allowed values are <span class="value">Home</span>,
2385         <span class="value">Roaming</span>, or if the provider has no home
2386         network, <span class="value">Required</span>.
2387       </span>
2388     </dd>
2389
2390     <dt class="field">ServingOperator</dt>
2391     <dd>
2392       <span class="field_meta">(optional, read-only, provided only
2393         if <span class="field">Family</span> is <span class="value">GSM</span>)
2394         <span class="type">CellularProvider</span>
2395       </span>
2396       Description of the operator on whose network the modem is currently
2397       registered
2398     </dd>
2399
2400     <dt class="field">SIMLockStatus</dt>
2401     <dd>
2402       <span class="field_meta">(optional, read-only, provided only
2403         if <span class="field">Family</span> is <span class="value">GSM</span>)
2404         <span class="type">SIMLockStatus</span>
2405       </span>
2406       For GSM modems, a dictionary containing two properties describing the
2407       state of the SIM card lock.
2408     </dd>
2409
2410     <dt class="field">SIMPresent</dt>
2411     <dd>
2412       <span class="field_meta">(optional, read-only, provided only
2413         if <span class="field">Family</span> is <span class="value">GSM</span>
2414         or <span class="field">NetworkTechnology</span>
2415         is <span class="value">LTE</span>)
2416         <span class="type">boolean</span>
2417       </span>
2418       For GSM or LTE modems, indicates whether a SIM card is present or not.
2419     </dd>
2420
2421     <dt class="field">SupportNetworkScan</dt>
2422     <dd>
2423       <span class="field_meta">(optional, read-only)
2424         <span class="type">boolean</span>
2425       </span>
2426       True if the cellular network supports scanning.
2427     </dd>
2428
2429     <dt class="field">SupportedCarriers</dt>
2430     <dd>
2431       <span class="field_meta">(optional, read-only)
2432         <span class="type">array of string</span>
2433       </span>
2434       A list of supported carriers.
2435     </dd>
2436
2437   </dl>
2438
2439   <p><span class="type">APN</span> type contains the following:</p>
2440   <dl class="field_list">
2441     <dt class="field">AccessPointName</dt>
2442     <dd>
2443       <span class="field_meta">(required)
2444         <span class="type">string</span>
2445       </span>
2446       The access point name used when making connections.
2447     </dd>
2448
2449     <dt class="field">Name</dt>
2450     <dd>
2451       <span class="field_meta">(optional)
2452         <span class="type">string</span>
2453       </span>
2454       Description of the APN.
2455     </dd>
2456
2457     <dt class="field">LocalizedName</dt>
2458     <dd>
2459       <span class="field_meta">(optional)
2460         <span class="type">string</span>
2461       </span>
2462       Localized description of the APN.
2463     </dd>
2464
2465     <dt class="field">Username</dt>
2466     <dd>
2467       <span class="field_meta">(optional)
2468         <span class="type">string</span>
2469       </span>
2470       Username for making connections if required.
2471     </dd>
2472
2473     <dt class="field">Password</dt>
2474     <dd>
2475       <span class="field_meta">(optional)
2476         <span class="type">string</span>
2477       </span>
2478       Password for making connections if required.
2479     </dd>
2480
2481     <dt class="field">Language</dt>
2482     <dd>
2483       <span class="field_meta">(optional, rquired if <span class="field">
2484           LocalizedName</span> is provided)
2485         <span class="type">string</span>
2486       </span>
2487       Two letter language code for Localizedname if provided.
2488     </dd>
2489   </dl>
2490
2491   <p><span class="type">FoundNetwork</span> type contains the following:</p>
2492   <dl class="field_list">
2493     <dt class="field">Status</dt>
2494     <dd>
2495       <span class="field_meta">(required)
2496         <span class="type">string</span>
2497       </span>
2498       The availability of the network.
2499     </dd>
2500
2501     <dt class="field">NetworkId</dt>
2502     <dd>
2503       <span class="field_meta">(required)
2504         <span class="type">string</span>
2505       </span>
2506       The network id in the form MCC/MNC (without the '/').
2507     </dd>
2508
2509     <dt class="field">Technology</dt>
2510     <dd>
2511       <span class="field_meta">(required)
2512         <span class="type">string</span>
2513       </span>
2514       Access technology used by the network,
2515       e.g. "GSM", "UMTS", "EDGE", "HSPA", etc.
2516     </dd>
2517
2518     <dt class="field">ShortName</dt>
2519     <dd>
2520       <span class="field_meta">(optional)
2521         <span class="type">string</span>
2522       </span>
2523       Short-format name of the network operator.
2524     </dd>
2525
2526     <dt class="field">LongName</dt>
2527     <dd>
2528       <span class="field_meta">(optional)
2529         <span class="type">string</span>
2530       </span>
2531       Long-format name of the network operator.
2532     </dd>
2533   </dl>
2534
2535   <p><span class="type">PaymentPortal</span> type contains the following:</p>
2536   <dl class="field_list">
2537     <dt class="field">Method</dt>
2538     <dd>
2539       <span class="field_meta">(required)
2540         <span class="type">string</span>
2541       </span>
2542       The HTTP method to use, "GET" or "POST"
2543     </dd>
2544
2545     <dt class="field">PostData</dt>
2546     <dd>
2547       <span class="field_meta">
2548         (required if <span class="field">Method</span> is
2549         <span class="value">POST</span>, otherwise ignored)
2550         <span class="type">string</span>
2551       </span>
2552       The postdata to send.
2553     </dd>
2554
2555     <dt class="field">Url</dt>
2556     <dd>
2557       <span class="field_meta">(required)
2558         <span class="type">string</span>
2559       </span>
2560       The URL for the portal.
2561     </dd>
2562   </dl>
2563
2564   <p><span class="type">CellularProvider</span> type contains the following:</p>
2565   <dl class="field_list">
2566     <dt class="field">Name</dt>
2567     <dd>
2568       <span class="field_meta">(required)
2569         <span class="type">string</span>
2570       </span>
2571       The operator name.
2572     </dd>
2573
2574     <dt class="field">Code</dt>
2575     <dd>
2576       <span class="field_meta">(required)
2577         <span class="type">string</span>
2578       </span>
2579       The network id in the form MCC/MNC (without the '/').
2580     </dd>
2581
2582     <dt class="field">Country</dt>
2583     <dd>
2584       <span class="field_meta">(optional)
2585         <span class="type">string</span>
2586       </span>
2587       The two-letter country code.
2588     </dd>
2589   </dl>
2590
2591   <p><span class="type">SIMLockStatus</span> type contains the following:</p>
2592   <dl class="field_list">
2593     <dt class="field">LockType</dt>
2594     <dd>
2595       <span class="field_meta">(required)
2596         <span class="type">string</span>
2597       </span>
2598       Specifies the type of lock in effect, or an empty string if unlocked.
2599       <span class="rule"><span class="rule_id"></span>
2600         Allowed values are
2601         <span class="value">sim-pin</span>,
2602         <span class="value">sim-puk</span>
2603       </span>
2604     </dd>
2605
2606     <dt class="field">LockEnabled</dt>
2607     <dd>
2608       <span class="field_meta">(required)
2609         <span class="type">boolean</span>
2610       </span>
2611       Indicates whether SIM locking is enabled
2612     </dd>
2613
2614     <dt class="field">RetriesLeft</dt>
2615     <dd>
2616       <span class="field_meta">(optional)
2617         <span class="type">integer</span>
2618       </span>
2619       If <span class="field">LockType</span> is empty
2620       or <span class="value">sim-pin</span>, then this property represents
2621       the number of attempts remaining to supply a correct PIN before the
2622       PIN becomes blocked, at which point a PUK provided by the carrier would
2623       be necessary to unlock the SIM (and <span class="field">LockType</span>
2624       changes to <span class="value">sim-puk</span>).
2625     </dd>
2626   </dl>
2627
2628 </section>
2629
2630 <section>
2631   <h1>Bluetooth / WiFi Direct Networks</h1>
2632   <p>
2633     This format will eventually also cover configuration of Bluetooth and WiFi
2634     Direct network technologies, however they are currently not supported.
2635   </p>
2636 </section>
2637
2638 </section>
2639
2640 <section>
2641   <h1>Certificates</h1>
2642   <p>
2643     Certificate data is stored in a separate section. Each certificate may be
2644     referenced from within the NetworkConfigurations array using a certificate
2645     reference. A certificate reference is its GUID.
2646   </p>
2647
2648   <p>
2649     The top-level field <span class="field">Certificates</span> is an array of
2650     objects of <span class="type">Certificate</span> type.
2651   </p>
2652
2653   <p>
2654     The <span class="type">Certificate</span> type contains the following:
2655   </p>
2656
2657   <dl class="field_list">
2658     <dt class="field">GUID</dt>
2659     <dd>
2660       <span class="field_meta">
2661         (required)
2662         <span class="type">string</span>
2663       </span>
2664       A unique identifier for this certificate. Must be a non-empty string.
2665     </dd>
2666
2667     <dt class="field">PKCS12</dt>
2668     <dd>
2669       <span class="field_meta">
2670         (required if <span class="field">Type</span> is
2671         <span class="value">Client</span>, otherwise ignored)
2672         <span class="type">string</span>
2673       </span> For certificates with
2674       private keys, this is the base64 encoding of the a PKCS#12 file.
2675     </dd>
2676
2677     <dt class="field">Remove</dt>
2678     <dd>
2679       <span class="field_meta">
2680         (optional, defaults to <span class="value">false</span>)
2681         <span class="type">boolean</span>
2682       </span>
2683       If <span class="value">true</span>, remove this certificate (only GUID
2684       should be set).
2685     </dd>
2686
2687     <dt class="field">TrustBits</dt>
2688     <dd>
2689       <span class="field_meta">
2690         (optional if <span class="field">Type</span>
2691         is <span class="value">Server</span>
2692         or <span class="value">Authority</span>, otherwise ignored, defaults to
2693         [])
2694         <span class="type">array of string</span>
2695       </span>
2696       An array of trust flags. Clients should ignore unknown flags. For
2697       backwards compatibility, each flag should only increase the trust and
2698       never restrict. The trust flag <span class="value">Web</span> implies that
2699       the certificate is to be trusted for HTTPS SSL identification. A typical
2700       web certificate authority would have <span class="field">Type</span> set
2701       to <span class="value">Authority</span> and
2702       <span class="field">TrustBits</span> set to
2703       <span class="snippet">["Web"]</span>.
2704     </dd>
2705
2706     <dt class="field">Type</dt>
2707     <dd>
2708       <span class="field_meta">
2709         (required if <span class="field">Remove</span> is
2710         <span class="value">false</span>, otherwise ignored)
2711         <span class="type">string</span>
2712       </span>
2713       <span class="rule">
2714         <span class="rule_id"></span>
2715         Allowed values are <span class="value">Client</span>,
2716         <span class="value">Server</span>, and
2717         <span class="value">Authority</span>.
2718       </span>
2719       <span class="value">Client</span> indicates the certificate is for
2720       identifying the user or device over HTTPS or for
2721       VPN/802.1X. <span class="value">Server</span> indicates the certificate
2722       identifies an HTTPS or VPN/802.1X peer.
2723       <span class="value">Authority</span> indicates the certificate is a
2724       certificate authority and any certificates it issues should be
2725       trusted. Note that if <span class="field">Type</span> disagrees with the
2726       x509 v3 basic constraints or key usage attributes, the
2727       <span class="field">Type</span> field should be honored.
2728     </dd>
2729
2730     <dt class="field">X509</dt>
2731     <dd>
2732       <span class="field_meta">
2733         (required if <span class="field">Type</span> is
2734         <span class="value">Server</span> or
2735         <span class="value">Authority</span>, otherwise ignored)
2736         <span class="type">string</span>
2737       </span> For certificate
2738       without private keys, this is the X509 certificate in PEM format.
2739     </dd>
2740   </dl>
2741
2742   <p>
2743     The passphrase of the PKCS#12 encoding must be empty. Encryption of key data
2744     should be handled at the level of the entire file, or the transport of the
2745     file.
2746   </p>
2747
2748   <p>
2749     If a global-scoped network connection refers to a user-scoped certificate,
2750     results are undefined, so this configuration should be prohibited by the
2751     configuration editor.
2752   </p>
2753 </section>
2754
2755 </section>
2756
2757 <section>
2758   <h1>Encrypted Configuration</h1>
2759   <p>
2760     We assume that when this format is imported as part of policy that
2761     file-level encryption will not be necessary because the policy transport is
2762     already encrypted, but when it is imported as a standalone file, it is
2763     desirable to encrypt it. Since this file has private information (user
2764     names) and secrets (passphrases and private keys) in it, and we want it to
2765     be usable as a manual way to distribute network configuration, we must
2766     support encryption.
2767   </p>
2768
2769   <p>
2770     For this standalone export, the entire file will be encrypted in a symmetric
2771     fashion with a passphrase stretched using salted PBKDF2 using at least 20000
2772     iterations, and encrypted using an AES-256 CBC mode cipher with an SHA-1
2773     HMAC on the ciphertext.
2774   </p>
2775
2776   <p>
2777     An encrypted ONC file's top level object will have the
2778     <span class="type">EncryptedConfiguration</span>
2779     type. <span class="type">EncryptedConfiguration</span> type contains the
2780     following:
2781   </p>
2782
2783   <dl class="field_list">
2784     <dt class="field">Cipher</dt>
2785     <dd>
2786       <span class="field_meta">
2787         (required)
2788         <span class="type">string</span>
2789       </span>
2790       The type of cipher used. Currently only <span class="value">AES256</span>
2791       is supported.
2792     </dd>
2793
2794     <dt class="field">Ciphertext</dt>
2795     <dd>
2796       <span class="field_meta">
2797         (required)
2798         <span class="type">string</span>
2799       </span>
2800       The raw ciphertext of the encrypted ONC file, base64 encoded.
2801     </dd>
2802
2803     <dt class="field">HMAC</dt>
2804     <dd>
2805       <span class="field_meta">
2806         (required)
2807         <span class="type">string</span>
2808       </span>
2809       The HMAC for the ciphertext, base64 encoded.
2810     </dd>
2811
2812     <dt class="field">HMACMethod</dt>
2813     <dd>
2814       <span class="field_meta">
2815         (required)
2816         <span class="type">string</span>
2817       </span>
2818       The method used to compute the Hash-based Message Authentication Code
2819       (HMAC). Currently only <span class="value">SHA1</span> is supported.
2820     </dd>
2821
2822     <dt class="field">Salt</dt>
2823     <dd>
2824       <span class="field_meta">
2825         (required)
2826         <span class="type">string</span>
2827       </span>
2828       The salt value used during key stretching.
2829     </dd>
2830
2831     <dt class="field">Stretch</dt>
2832     <dd>
2833       <span class="field_meta">
2834         (required)
2835         <span class="type">string</span>
2836       </span>
2837       The key stretching algorithm used. Currently
2838       only <span class="value">PBKDF2</span> is supported.
2839     </dd>
2840
2841     <dt class="field">Iterations</dt>
2842     <dd>
2843       <span class="field_meta">
2844         (required)
2845         <span class="type">integer</span>
2846       </span>
2847       The number of iterations to use during key stretching.
2848     </dd>
2849
2850     <dt class="field">IV</dt>
2851     <dd>
2852       <span class="field_meta">
2853         (required)
2854         <span class="type">string</span>
2855       </span>
2856       The initial vector (IV) used for Cyclic Block Cipher (CBC) mode, base64
2857       encoded.
2858     </dd>
2859
2860     <dt class="field">Type</dt>
2861     <dd>
2862       <span class="field_meta">
2863         (required)
2864         <span class="type">string</span>
2865       </span>
2866       The type of the ONC file, which must be set
2867       to <span class="value">EncryptedConfiguration</span>.
2868     </dd>
2869   </dl>
2870
2871   <p class="rule">
2872     <span class="rule_id"></span>
2873     When decrypted, the ciphertext must contain a JSON object of
2874     type <span class="type">UnencryptedConfiguration</span>.
2875   </p>
2876 </section>
2877
2878 <section>
2879   <h1>String Expansions</h1>
2880   <p>
2881     The values of some fields, such
2882     as <span class="field">WiFi.EAP.Identity</span>
2883     and <span class="field">VPN.*.Username</span>, are subject to string
2884     expansions. These allow one ONC to have basic user-specific variations.
2885   </p>
2886
2887   <p>
2888     The expansions are:
2889   </p>
2890
2891   <ul>
2892     <li>
2893       ${LOGIN_ID} - expands to the email address of the user, but before the
2894       '@'.
2895     </li>
2896     <li>
2897       ${LOGIN_EMAIL} - expands to the email address of the user.
2898     </li>
2899   </ul>
2900
2901   <p>
2902     The following SED would properly handle resolution.
2903   </p>
2904
2905   <ul>
2906     <li>
2907       s/\$\{LOGIN_ID\}/bobquail$1/g
2908     </li>
2909     <li>
2910       s/\$\{LOGIN_EMAIL\}/bobquail@example.com$1/g
2911     </li>
2912   </ul>
2913
2914   <p>
2915     Example expansions, assuming the user was bobquail@example.com:
2916   </p>
2917
2918   <ul>
2919     <li>
2920       "${LOGIN_ID}" -> "bobquail"
2921     </li>
2922     <li>
2923       "${LOGIN_ID}@corp.example.com" -> "bobquail@corp.example.com"
2924     </li>
2925     <li>
2926       "${LOGIN_EMAIL}" -> "bobquail@example.com"
2927     </li>
2928     <li>
2929       "${LOGIN_ID}X" -> "bobquailX"
2930     </li>
2931     <li>
2932       "${LOGIN_IDX}" -> "${LOGIN_IDX}"
2933     </li>
2934     <li>
2935       "X${LOGIN_ID}" -> "Xbobquail"
2936     </li>
2937   </ul>
2938 </section>
2939
2940 <section>
2941   <h1>Detection</h1>
2942   <p>
2943     This format should be sent in files ending in the .onc extension. When
2944     transmitted with a MIME type, the MIME type should be
2945     application/x-onc. These two methods make detection of data to be handled in
2946     this format, especially when encryption is used and the payload itself is
2947     not detectable.
2948   </p>
2949 </section>
2950
2951 </section>
2952
2953 <section>
2954   <h1>Alternatives considered</h1>
2955   <p>
2956     For the overall format, we considered XML, ASN.1, and protobufs. JSON and
2957     ASN.1 seem more widely known than protobufs. Since administrators are
2958     likely to want to tweak settings that will not exist in common UIs, we
2959     should provide a format that is well known and human modifiable. ASN.1 is
2960     not human modifiable. Protobufs formats are known by open source developers
2961     but seem less likely to be known by administrators. JSON serialization
2962     seems to have good support across languages.
2963   </p>
2964
2965   <p>
2966     We considered sending the exact connection manager configuration format of
2967     an open source connection manager like connman. There are a few issues
2968     here, for instance, referencing certificates by identifiers not tied to a
2969     particular PKCS#11 token, and tying to one OS's connection manager.
2970   </p>
2971 </section>
2972
2973 <section>
2974   <h1>Detection</h1>
2975   <p>
2976     This format should be sent in files ending in the .onc extension. When
2977     transmitted with a MIME type, the MIME type should be
2978     application/x-onc. These two methods make detection of data to be handled in
2979     this format, especially when encryption is used and the payload itself is
2980     not detectable.
2981   </p>
2982 </section>
2983
2984 <section>
2985   <h1>Mocks</h1>
2986
2987 <section>
2988   <h1>Simple format example: PEAP/MSCHAPv2 network (per device)</h1>
2989
2990   <pre>
2991 {
2992   "Type": "UnencryptedConfiguration",
2993   "NetworkConfigurations": [
2994     {
2995       "GUID": "{f2c17903-b0e1-8593-b3ca74f977236bd7}",
2996       "Name": "MySSID",
2997       "Type": "WiFi",
2998       "WiFi": {
2999         "AutoConnect": true,
3000         "EAP": {
3001           "Outer": "PEAP",
3002           "UseSystemCAs": true
3003         },
3004         "HiddenSSID": false,
3005         "SSID": "MySSID",
3006         "Security": "WPA-EAP"
3007       }
3008     }
3009   ],
3010   "Certificates": []
3011 }
3012   </pre>
3013
3014   <p>
3015     Notice that in this case, we do not provide a username and password - we set
3016     SaveCredentials to <span class="value">false</span> so we are prompted every
3017     time. We could have passed in username and password - but such a file should
3018     be encrypted.
3019   </p>
3020 </section>
3021
3022 <section>
3023   <h1>Complex format example: TLS network with client certs (per device)</h1>
3024
3025   <pre>
3026 {
3027   "Type": "UnencryptedConfiguration",
3028   "NetworkConfigurations": [
3029     {
3030       "GUID": "{00f79111-51e0-e6e0-76b3b55450d80a1b}",
3031       "Name": "MyTTLSNetwork",
3032       "Type": "WiFi",
3033       "WiFi": {
3034         "AutoConnect": false,
3035         "EAP": {
3036           "ClientCertPattern": {
3037             "EnrollmentURI": [
3038               "http://fetch-my-certificate.com"
3039             ],
3040             "IssuerCARef": [
3041               "{6ed8dce9-64c8-d568-d225d7e467e37828}"
3042             ]
3043           },
3044           "ClientCertType": "Pattern",
3045           "Outer": "EAP-TLS",
3046           "ServerCARef": "{6ed8dce9-64c8-d568-d225d7e467e37828}",
3047           "UseSystemCAs": true
3048         },
3049         "HiddenSSID": false,
3050         "SSID": "MyTTLSNetwork",
3051         "Security": "WPA-EAP"
3052       }
3053     }
3054   ],
3055   "Certificates": [
3056     {
3057       "GUID": "{6ed8dce9-64c8-d568-d225d7e467e37828}",
3058       "Type": "Authority",
3059       "X509": "MIIEpzCCA4+gAwIBAgIJAMueiWq5WEIAMA0GCSqGSIb3DQEBBQUAMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTExMDEyODA2MjA0MFoXDTEyMDEyODA2MjA0MFowgZMxCzAJBgNVBAYTAkZSMQ8wDQYDVQQIEwZSYWRpdXMxEjAQBgNVBAcTCVNvbWV3aGVyZTEVMBMGA1UEChMMRXhhbXBsZSBJbmMuMSAwHgYJKoZIhvcNAQkBFhFhZG1pbkBleGFtcGxlLmNvbTEmMCQGA1UEAxMdRXhhbXBsZSBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9EDplhyrVNJIoy1OsVqvD/K67B5PW2bDKKxGznodrzCu8jHsP1Ne3mgrK20vbzQUUBdmxTCWO6x3a3//r4ZuPOuZd1ViycWjt6mRfRbBzNrHzP7NiyFuXjdlz74beHQQLcHwvZ3qFAWZK37uweiLiDPaMaEQlka2Bztqx4PsogmSdoVPSCxi5Cl1XlJmITA03LlKpO79+0rEPRamWO/DMCwvffn2/UUjJLog4/lYe16HQ6iq/6bjhffm2rLXDFKOGZmBVbLNMCfANRMtdFWHYdBXERoUo2zpM9tduOOUNLy7E7kRKVm/wy38s51ChFPlpORrhimN2j1caar+KAv2tAgMBAAGjgfswgfgwHQYDVR0OBBYEFBTIImiXp+57jjgn2N5wq93GgAAtMIHIBgNVHSMEgcAwgb2AFBTIImiXp+57jjgn2N5wq93GgAAtoYGZpIGWMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5ggkAy56JarlYQgAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAnNd0YY7s2YVYPsgEgDS+rBNjcQloTFWgc9Hv4RWBjwcdJdSPIrpBp7LSjC96wH5U4eWpQjlWbOYQ9RBq9Z/RpuAPEjzRV78rIrQrCWQ3lxwywWEb5Th1EVJSN68eNv7Ke5BlZ2l9kfLRKFm5MEBXX9YoHMX0U8I8dPIXfTyevmKOT1PuEta5cQOM6/zH86XWn6WYx3EXkyjpeIbVOw49AqaEY8u70yBmut4MO03zz/pwLjV1BWyIkXhsrtuJyA+ZImvgLK2oAMZtGGFo7b0GW/sWY/P3R6Un3RFy35k6U3kXCDYYhgZEcS36lIqcj5y6vYUUVM732/etCsuOLz6ppw=="
3060     }
3061   ]
3062 }
3063   </pre>
3064
3065   <p>
3066     In this example, the client certificate is not sent in the ONC format, but
3067     rather we send a certificate authority which we know will have signed the
3068     client certificate that is needed, along with an enrollment URI to navigate
3069     to if the required certificate is not yet available on the client.
3070   </p>
3071 </section>
3072
3073 <section>
3074   <h1>Simple format example: HTTPS Certificate Authority</h1>
3075
3076   <p>
3077     In this example a new certificate authority is added to be trusted for HTTPS
3078     server authentication.
3079   </p>
3080
3081   <pre>
3082 {
3083   "Type": "UnencryptedConfiguration",
3084   "NetworkConfigurations": [],
3085   "Certificates": [
3086     {
3087       "GUID": "{f31f2110-9f5f-61a7-a8bd7c00b94237af}",
3088       "TrustBits": [ "Web" ],
3089       "Type": "Authority",
3090       "X509": "MIIEpzCCA4+gAwIBAgIJAMueiWq5WEIAMA0GCSqGSIb3DQEBBQUAMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTExMDEyODA2MjA0MFoXDTEyMDEyODA2MjA0MFowgZMxCzAJBgNVBAYTAkZSMQ8wDQYDVQQIEwZSYWRpdXMxEjAQBgNVBAcTCVNvbWV3aGVyZTEVMBMGA1UEChMMRXhhbXBsZSBJbmMuMSAwHgYJKoZIhvcNAQkBFhFhZG1pbkBleGFtcGxlLmNvbTEmMCQGA1UEAxMdRXhhbXBsZSBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9EDplhyrVNJIoy1OsVqvD/K67B5PW2bDKKxGznodrzCu8jHsP1Ne3mgrK20vbzQUUBdmxTCWO6x3a3//r4ZuPOuZd1ViycWjt6mRfRbBzNrHzP7NiyFuXjdlz74beHQQLcHwvZ3qFAWZK37uweiLiDPaMaEQlka2Bztqx4PsogmSdoVPSCxi5Cl1XlJmITA03LlKpO79+0rEPRamWO/DMCwvffn2/UUjJLog4/lYe16HQ6iq/6bjhffm2rLXDFKOGZmBVbLNMCfANRMtdFWHYdBXERoUo2zpM9tduOOUNLy7E7kRKVm/wy38s51ChFPlpORrhimN2j1caar+KAv2tAgMBAAGjgfswgfgwHQYDVR0OBBYEFBTIImiXp+57jjgn2N5wq93GgAAtMIHIBgNVHSMEgcAwgb2AFBTIImiXp+57jjgn2N5wq93GgAAtoYGZpIGWMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5ggkAy56JarlYQgAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAnNd0YY7s2YVYPsgEgDS+rBNjcQloTFWgc9Hv4RWBjwcdJdSPIrpBp7LSjC96wH5U4eWpQjlWbOYQ9RBq9Z/RpuAPEjzRV78rIrQrCWQ3lxwywWEb5Th1EVJSN68eNv7Ke5BlZ2l9kfLRKFm5MEBXX9YoHMX0U8I8dPIXfTyevmKOT1PuEta5cQOM6/zH86XWn6WYx3EXkyjpeIbVOw49AqaEY8u70yBmut4MO03zz/pwLjV1BWyIkXhsrtuJyA+ZImvgLK2oAMZtGGFo7b0GW/sWY/P3R6Un3RFy35k6U3kXCDYYhgZEcS36lIqcj5y6vYUUVM732/etCsuOLz6ppw=="
3091     }
3092   ]
3093 }
3094   </pre>
3095 </section>
3096
3097 <section>
3098   <h1>Encrypted format example</h1>
3099
3100   <p>
3101 In this example a simple wireless network is added, but the file is encrypted
3102 with the passphrase "test0000".
3103   </p>
3104
3105   <pre>
3106 {
3107   "Cipher": "AES256",
3108   "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==",
3109   "HMAC": "3ylRy5InlhVzFGakJ/9lvGSyVH0=",
3110   "HMACMethod": "SHA1",
3111   "Iterations": 20000,
3112   "IV": "hcm6OENfqG6C/TVO6p5a8g==",
3113   "Salt": "/3O73QadCzA=",
3114   "Stretch": "PBKDF2",
3115   "Type": "EncryptedConfiguration"
3116 }
3117   </pre>
3118 </section>
3119
3120 </section>
3121
3122 <section>
3123   <h1>Standalone editor</h1>
3124
3125   <p>
3126     The source code for a Chrome packaged app to generate ONC configuration can
3127     be found here:
3128     <a href="https://gerrit.chromium.org/gitweb/?p=chromiumos/platform/spigots.git;a=tree">"https://gerrit.chromium.org/gitweb/?p=chromiumos/platform/spigots.git;a=tree"</a>
3129   </p>
3130 </section>
3131
3132 <section>
3133   <h1>Internationalization and Localization</h1>
3134
3135   <p>
3136     UIs will need to have internationalization and localizations - the file
3137     format will remain in English.
3138   </p>
3139 </section>
3140
3141 <section>
3142   <h1>Security Considerations</h1>
3143
3144   <p>
3145     Data stored inside of open network configuration files is highly sensitive
3146     to users and enterprises. The file format itself provides adequate
3147     encryption options to allow standalone use-cases to be secure. For automatic
3148     updates sent by policy, the policy transport should be made secure. The file
3149     should not be stored unencrypted on disk as part of policy fetching and
3150     should be cleared from memory after use.
3151   </p>
3152 </section>
3153
3154 <section>
3155   <h1>Privacy Considerations</h1>
3156
3157   <p>
3158     Similarly to the security considerations, user names will be present in
3159     these files for certain kinds of connections, so any places where the file
3160     is transmitted or saved to disk should be secure. On client device, when
3161     user names for connections that are user-specific are persisted to disk,
3162     they should be stored in a location that is encrypted. Users can also opt in
3163     these cases to not save their user credentials in the config file and will
3164     instead be prompted when they are needed.
3165   </p>
3166 </section>
3167 </section>
3168 </body>
3169 </html>