components/onc/docs/onc_spec.html

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