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