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