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