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