We would like to create a simple, open, but complete format to describe multiple network configurations for Wi-Fi, Ethernet, Cellular, Bluetooth/WiFi-Direct, and VPN connections in a single file format, in order to simplify and automate network configuration for users.
Configuring networks is a painful and error-prone experience for users. It is a problem shared across desktop, laptop, tablet, and phone users of all operating system types. It is exacerbated in business and schools which often have complex network configurations (VPNs and 802.1X networking) that change often and have many connected devices. Configuration of Wi-Fi is still done manually, often by administrators physically standing next to users working on devices. Certificate distribution is particularly painful which often results in admins instead using passphrases to protect networks or using protocols without client certificates that instead use LDAP passwords for authentication. Even after networks are configured, updates to the network configuration require another round of manual changes, and accidental changes by a user or malicious changes by an attacker can break connectivity or make connections less private or secure.
We propose a single-file format for network configuration that is human-readable, can describe all of the common kinds of network configurations, supports integrity checking, certificate and key provisioning, and updating. The file can be encrypted with a single passphrase so that upon entering the passphrase the entire configuration is loaded. The format can be described as an open format to enable multiple OS vendors to interoperate and share configuration editors.
This format neither supports configuring browser settings nor allows setting other types of system policies.
A standalone configuration editor will be created, downloadable as a Chrome app. This editor will allow creating, modifying, and encrypting an open network configuration file in a way that is intuitive for a system administrator.
This file format may be delivered to a user and manually imported into a device.
This file format may be created by an administrator, stored in a policy repository, and automatically pushed to a device.
We use JSON format for the files. The fields in a JSON file are always case-sensitive, so the exact case of the fields in this section must be matched. In addition, the values that are called out as explicit constants must also match the case specified (e.g. WiFi must not be written as wifi, etc.). This document describes a minimum set of required fields and optional fields. Other fields may be created, however, see the implementation-specific fields for guidelines for these fields.
The JSON consists of a top level dictionary containing a Type field which must have either the value EncryptedConfiguration or UnencryptedConfiguration.
For a description of the EncryptedConfiguration type, see the section on Encrypted Configuration below. The EncryptedConfiguration format encrypts an unencrypted JSON object.
This format allows for importing updated network configurations and certificates by providing GUIDs to each network configuration and certificate so they can be modified or even removed in future updates.
GUIDs are non-empty strings that are meant to be stable and unique. When they refer to the same entity, they should be the same between ONC files. No two different networks or certificates should have the same GUID, similarly a network and certificate should not have the same GUID. A single ONC file should not contain the same entity twice (with the same GUID). Failing any of these tests indicates the ONC file is not valid.
Any GUID referred to in an ONC file must be present in the same ONC file. In particular, it is an error to create a certificate in one ONC file and refer to it in a NetworkConfiguration in another ONC file and not define it there, even if the previous ONC file has been imported.
As there are many different kinds of connections and some that are not yet anticipated may require new fields. This format allows arbitrary other fields to be added.
Fields and values should follow these general guidelines:
Any editor of network configuration information should allows the user to modify any fields that are implementation-specific. It may not be present directly in the UI but it should be able to import files with such settings and leave preserve these settings on export.
When the top level Type field is UnencryptedConfiguration, the top level JSON has the UnencryptedConfiguration type. UnencryptedConfiguration type contains the following:
At least one array (either NetworkConfigurations and/or Certificates) must be present.
Field NetworkConfigurations is an array of NetworkConfiguration typed objects. The NetworkConfiguration type contains the following:
For Ethernet connections, Type must be set to Ethernet and the field Ethernet must be set to an object of type Ethernet containing the following fields:
Field IPConfigs is an array of IPConfig objects. Each IPConfig object describes a particular static IP configuration and contains the following fields:
For Wi-Fi connections, Type must be set to WiFi and the field WiFi must be set to an object of type WiFi containing the following fields:
There are many kinds of VPNs with widely varying configuration options. We offer standard configuration options for a few common configurations at this time, and may add more later. For all others, implementation specific fields should be used.
For VPN connections, Type must be set to VPN and the field VPN must be set to an object of type VPN containing the following fields:
The IPsec type contains the following:
L2TP type contains the following:
XAUTH type contains the following:
VPN.Type must be IPsec, IKEVersion must be 1. Do not use this for L2TP over IPsec. This may be used for machine-authentication-only IKEv1 or for IKEv1 with XAUTH. See the IPsec type described below.
VPN.Type must be IPsec, IKEVersion must be 2. This may be used with EAP-based user authentication.
There are two major configurations L2TP over IPsec which depend on how IPsec is authenticated. In either case Type must be L2TP-IPsec. They are described below.
L2TP over IPsec with pre-shared key:
VPN.Type must be OpenVPN.
OpenVPN type contains the following:
In order to allow clients to securely key their private keys and request certificates through PKCS#10 format or through a web flow, we provide alternative CertificatePattern types. The CertificatePattern type contains the following:
The IssuerSubjectPattern type contains the following:
One field in Subject, Issuer, or IssuerCARef must be given for a CertificatePattern typed field to be valid.
For a certificate to be considered matching, it must match all the fields in the certificate pattern. If multiple certificates match, the certificate with the latest issue date that is still in the past, and hence valid, will be used.
If EnrollmentURI is not given and no match is found to this pattern, the importing tool may show an error to the user.
Every network can be configured to use a proxy. The ProxySettings type contains the following:
The ManualProxySettings type contains the following:
The ProxyLocation type contains the following:
For networks with 802.1X authentication, an EAP type exists to configure the authentication. The EAP type contains the following:
This format will eventually also cover configuration of cellular network technologies, however they are currently not supported.
This format will eventually also cover configuration of Bluetooth and Wi-Fi Direct network technologies, however they are currently not supported.
Certificate data is stored in a separate section. Each certificate may be referenced from within the NetworkConfigurations array using a certificate reference. A certificate reference is its GUID.
The top-level field Certificates is an array of objects of Certificate type.
The Certificate type contains the following:
The passphrase of the PKCS#12 encoding must be empty. Encryption of key data should be handled at the level of the entire file, or the transport of the file.
If a global-scoped network connection refers to a user-scoped certificate, results are undefined, so this configuration should be prohibited by the configuration editor.
We assume that when this format is imported as part of policy that file-level encryption will not be necessary because the policy transport is already encrypted, but when it is imported as a standalone file, it is desirable to encrypt it. Since this file has private information (user names) and secrets (passphrases and private keys) in it, and we want it to be usable as a manual way to distribute network configuration, we must support encryption.
For this standalone export, the entire file will be encrypted in a symmetric fashion with a passphrase stretched using salted PBKDF2 using at least 20000 iterations, and encrypted using an AES-256 CBC mode cipher with an SHA-1 HMAC on the ciphertext.
An encrypted ONC file's top level object will have the EncryptedConfiguration type. EncryptedConfiguration type contains the following:
When decrypted, the ciphertext must contain a JSON object of type UnencryptedConfiguration.
The values of some fields, such as WiFi.EAP.Identity and VPN.*.Username, are subject to string expansions. These allow one ONC to have basic user-specific variations.
The expansions are:
The following SED would properly handle resolution.
Example expansions, assuming the user was bobquail@example.com:
This format should be sent in files ending in the .onc extension. When transmitted with a MIME type, the MIME type should be application/x-onc. These two methods make detection of data to be handled in this format, especially when encryption is used and the payload itself is not detectable.
For the overall format, we considered XML, ASN.1, and protobufs. JSON and ASN.1 seem more widely known than protobufs. Since administrators are likely to want to tweak settings that will not exist in common UIs, we should provide a format that is well known and human modifiable. ASN.1 is not human modifiable. Protobufs formats are known by open source developers but seem less likely to be known by administrators. JSON serialization seems to have good support across languages.
We considered sending the exact connection manager configuration format of an open source connection manager like connman. There are a few issues here, for instance, referencing certificates by identifiers not tied to a particular PKCS#11 token, and tying to one OS's connection manager.
This format should be sent in files ending in the .onc extension. When transmitted with a MIME type, the MIME type should be application/x-onc. These two methods make detection of data to be handled in this format, especially when encryption is used and the payload itself is not detectable.
{
"Type": "UnencryptedConfiguration",
"NetworkConfigurations": [
{
"GUID": "{f2c17903-b0e1-8593-b3ca74f977236bd7}",
"Name": "MySSID",
"Type": "WiFi",
"WiFi": {
"AutoConnect": true,
"EAP": {
"Outer": "PEAP",
"UseSystemCAs": true
},
"HiddenSSID": false,
"SSID": "MySSID",
"Security": "WPA-EAP"
}
}
],
"Certificates": []
}
Notice that in this case, we do not provide a username and password - we set SaveCredentials to false so we are prompted every time. We could have passed in username and password - but such a file should be encrypted.
{
"Type": "UnencryptedConfiguration",
"NetworkConfigurations": [
{
"GUID": "{00f79111-51e0-e6e0-76b3b55450d80a1b}",
"Name": "MyTTLSNetwork",
"Type": "WiFi",
"WiFi": {
"AutoConnect": false,
"EAP": {
"ClientCertPattern": {
"EnrollmentURI": [
"http://fetch-my-certificate.com"
],
"IssuerCARef": [
"{6ed8dce9-64c8-d568-d225d7e467e37828}"
]
},
"ClientCertType": "Pattern",
"Outer": "EAP-TLS",
"ServerCARef": "{6ed8dce9-64c8-d568-d225d7e467e37828}",
"UseSystemCAs": true
},
"HiddenSSID": false,
"SSID": "MyTTLSNetwork",
"Security": "WPA-EAP"
}
}
],
"Certificates": [
{
"GUID": "{6ed8dce9-64c8-d568-d225d7e467e37828}",
"Type": "Authority",
"X509": "MIIEpzCCA4+gAwIBAgIJAMueiWq5WEIAMA0GCSqGSIb3DQEBBQUAMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTExMDEyODA2MjA0MFoXDTEyMDEyODA2MjA0MFowgZMxCzAJBgNVBAYTAkZSMQ8wDQYDVQQIEwZSYWRpdXMxEjAQBgNVBAcTCVNvbWV3aGVyZTEVMBMGA1UEChMMRXhhbXBsZSBJbmMuMSAwHgYJKoZIhvcNAQkBFhFhZG1pbkBleGFtcGxlLmNvbTEmMCQGA1UEAxMdRXhhbXBsZSBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9EDplhyrVNJIoy1OsVqvD/K67B5PW2bDKKxGznodrzCu8jHsP1Ne3mgrK20vbzQUUBdmxTCWO6x3a3//r4ZuPOuZd1ViycWjt6mRfRbBzNrHzP7NiyFuXjdlz74beHQQLcHwvZ3qFAWZK37uweiLiDPaMaEQlka2Bztqx4PsogmSdoVPSCxi5Cl1XlJmITA03LlKpO79+0rEPRamWO/DMCwvffn2/UUjJLog4/lYe16HQ6iq/6bjhffm2rLXDFKOGZmBVbLNMCfANRMtdFWHYdBXERoUo2zpM9tduOOUNLy7E7kRKVm/wy38s51ChFPlpORrhimN2j1caar+KAv2tAgMBAAGjgfswgfgwHQYDVR0OBBYEFBTIImiXp+57jjgn2N5wq93GgAAtMIHIBgNVHSMEgcAwgb2AFBTIImiXp+57jjgn2N5wq93GgAAtoYGZpIGWMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5ggkAy56JarlYQgAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAnNd0YY7s2YVYPsgEgDS+rBNjcQloTFWgc9Hv4RWBjwcdJdSPIrpBp7LSjC96wH5U4eWpQjlWbOYQ9RBq9Z/RpuAPEjzRV78rIrQrCWQ3lxwywWEb5Th1EVJSN68eNv7Ke5BlZ2l9kfLRKFm5MEBXX9YoHMX0U8I8dPIXfTyevmKOT1PuEta5cQOM6/zH86XWn6WYx3EXkyjpeIbVOw49AqaEY8u70yBmut4MO03zz/pwLjV1BWyIkXhsrtuJyA+ZImvgLK2oAMZtGGFo7b0GW/sWY/P3R6Un3RFy35k6U3kXCDYYhgZEcS36lIqcj5y6vYUUVM732/etCsuOLz6ppw=="
}
]
}
In this example, the client certificate is not sent in the ONC format, but rather we send a certificate authority which we know will have signed the client certificate that is needed, along with an enrollment URI to navigate to if the required certificate is not yet available on the client.
In this example a new certificate authority is added to be trusted for HTTPS server authentication.
{
"Type": "UnencryptedConfiguration",
"NetworkConfigurations": [],
"Certificates": [
{
"GUID": "{f31f2110-9f5f-61a7-a8bd7c00b94237af}",
"TrustBits": [ "Web" ],
"Type": "Authority",
"X509": "MIIEpzCCA4+gAwIBAgIJAMueiWq5WEIAMA0GCSqGSIb3DQEBBQUAMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTExMDEyODA2MjA0MFoXDTEyMDEyODA2MjA0MFowgZMxCzAJBgNVBAYTAkZSMQ8wDQYDVQQIEwZSYWRpdXMxEjAQBgNVBAcTCVNvbWV3aGVyZTEVMBMGA1UEChMMRXhhbXBsZSBJbmMuMSAwHgYJKoZIhvcNAQkBFhFhZG1pbkBleGFtcGxlLmNvbTEmMCQGA1UEAxMdRXhhbXBsZSBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9EDplhyrVNJIoy1OsVqvD/K67B5PW2bDKKxGznodrzCu8jHsP1Ne3mgrK20vbzQUUBdmxTCWO6x3a3//r4ZuPOuZd1ViycWjt6mRfRbBzNrHzP7NiyFuXjdlz74beHQQLcHwvZ3qFAWZK37uweiLiDPaMaEQlka2Bztqx4PsogmSdoVPSCxi5Cl1XlJmITA03LlKpO79+0rEPRamWO/DMCwvffn2/UUjJLog4/lYe16HQ6iq/6bjhffm2rLXDFKOGZmBVbLNMCfANRMtdFWHYdBXERoUo2zpM9tduOOUNLy7E7kRKVm/wy38s51ChFPlpORrhimN2j1caar+KAv2tAgMBAAGjgfswgfgwHQYDVR0OBBYEFBTIImiXp+57jjgn2N5wq93GgAAtMIHIBgNVHSMEgcAwgb2AFBTIImiXp+57jjgn2N5wq93GgAAtoYGZpIGWMIGTMQswCQYDVQQGEwJGUjEPMA0GA1UECBMGUmFkaXVzMRIwEAYDVQQHEwlTb21ld2hlcmUxFTATBgNVBAoTDEV4YW1wbGUgSW5jLjEgMB4GCSqGSIb3DQEJARYRYWRtaW5AZXhhbXBsZS5jb20xJjAkBgNVBAMTHUV4YW1wbGUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5ggkAy56JarlYQgAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAnNd0YY7s2YVYPsgEgDS+rBNjcQloTFWgc9Hv4RWBjwcdJdSPIrpBp7LSjC96wH5U4eWpQjlWbOYQ9RBq9Z/RpuAPEjzRV78rIrQrCWQ3lxwywWEb5Th1EVJSN68eNv7Ke5BlZ2l9kfLRKFm5MEBXX9YoHMX0U8I8dPIXfTyevmKOT1PuEta5cQOM6/zH86XWn6WYx3EXkyjpeIbVOw49AqaEY8u70yBmut4MO03zz/pwLjV1BWyIkXhsrtuJyA+ZImvgLK2oAMZtGGFo7b0GW/sWY/P3R6Un3RFy35k6U3kXCDYYhgZEcS36lIqcj5y6vYUUVM732/etCsuOLz6ppw=="
}
]
}
In this example a simple wireless network is added, but the file is encrypted with the passphrase "test0000".
{
"Cipher": "AES256",
"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==",
"HMAC": "3ylRy5InlhVzFGakJ/9lvGSyVH0=",
"HMACMethod": "SHA1",
"Iterations": 20000,
"IV": "hcm6OENfqG6C/TVO6p5a8g==",
"Salt": "/3O73QadCzA=",
"Stretch": "PBKDF2",
"Type": "EncryptedConfiguration"
}
The source code for a Chrome packaged app to generate ONC configuration can be found here: "https://gerrit.chromium.org/gitweb/?p=chromiumos/platform/spigots.git;a=tree"
UIs will need to have internationalization and localizations - the file format will remain in English.
Data stored inside of open network configuration files is highly sensitive to users and enterprises. The file format itself provides adequate encryption options to allow standalone use-cases to be secure. For automatic updates sent by policy, the policy transport should be made secure. The file should not be stored unencrypted on disk as part of policy fetching and should be cleared from memory after use.
Similarly to the security considerations, user names will be present in these files for certain kinds of connections, so any places where the file is transmitted or saved to disk should be secure. On client device, when user names for connections that are user-specific are persisted to disk, they should be stored in a location that is encrypted. Users can also opt in these cases to not save their user credentials in the config file and will instead be prompted when they are needed.