components/onc/docs/onc_spec.html

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