components/onc/docs/onc_spec.html

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