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