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