Objective
  
    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.
  
  Background
  
    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.
  
  Overview
  
    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.
  
  Infrastructure
  
    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.
  
  Detailed Design
  
    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.
  
  GUIDs and Updating
  
    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.
  
  Implementation-specific fields
  
    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:
  
  
    - 
      Certificates (with and without keys) should always be placed in the
      certificate section - specifically certificate contents should not be
      placed in fields directly. Referring to certificates should be done using
      a field whose name ends in Ref and whose value is the GUID of the
      certificate, or if the certificate is not contained in this file, its
      pattern can be described using a field ending in Pattern of
      CertificatePattern type.
    
- 
      Fields should exist in the most-specific object in the hierarchy and
      should be named CamelCase style.
    
- 
      Booleans and integers should be used directly instead of using a
      stringified version of the type.
    
    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.
  
  Unencrypted Configuration
  
    When the top level Type field
    is UnencryptedConfiguration, the top level JSON
    has the UnencryptedConfiguration
    type. UnencryptedConfiguration type contains the
    following:
  
  
    - Type
- 
      
        (required)
        string
      
      Must be UnencryptedConfiguration.
    
- NetworkConfigurations
- 
      
        (optional)
        array of NetworkConfiguration
      
      Describes Wi-Fi, Ethernet, VPN, and wireless connections.
    
- Certificates
- 
      
        (optional)
        array of Certificate
      
      Contains certificates stored in X.509 or PKCS#12 format.
    
    
    At least one array (either NetworkConfigurations
    and/or Certificates) must be present.
  
  Network Configuration
  
    Field NetworkConfigurations is an array
    of NetworkConfiguration typed
    objects. The NetworkConfiguration type contains
    the following:
  
  
    - Ethernet
- 
      
        (required if Type is
        Ethernet, otherwise ignored)
        Ethernet
      
      Ethernet settings.
    
- GUID
- 
      
        (required)
        string
      
      A unique identifier for this network connection, which exists to make it
      possible to update previously imported configurations. Must be a non-empty
      string.
    
- IPConfigs
- 
      
        (optional if Remove is
        false, otherwise ignored)
        array of IPConfig
      
      Static IPv4 or IPv6 parameters to associate with this connection.
    
- Name
- 
      
        (required if Remove is
        false, otherwise ignored)
        string
      
      A user-friendly description of this connection. This name will not be used
      for referencing and may not be unique. Instead it may be used for
      describing the network to the user.
    
- Remove
- 
      
        (optional, defaults to false)
        boolean
      
      If set, remove this network configuration (only GUID should be set).
    
- ProxySettings
- 
      
        (optional if Remove is
        false, otherwise ignored)
        ProxySettings
      
      Proxy settings for this network
    
- NameServers
- 
      
        (optional if Remove is
        false, otherwise ignored)
        array of string
      
      Array of addresses to use for name servers. If not specified, DHCP values
      will be used.
    
- SearchDomains
- 
      
        (optional if Remove is
        false, otherwise ignored)
        array of string
      
      Array of strings to append to names for resolution. Items in this array
      should not start with a dot. Example:
      ["corp.acme.org", "acme.org"]. If not
      specified, DHCP values will be used.
    
- VPN
- 
      
        (required if Type is
        VPN, otherwise ignored)
        VPN
      
      VPN settings.
    
- WiFi
- 
      
        (required if Type is
        WiFi, otherwise ignored)
        WiFi
      
      Wi-Fi settings.
    
- Type
- 
      
        (required if Remove is
        false, otherwise ignored)
        string
      
      
        
        Allowed values are Cellular,
        Ethernet, WiFi,
        and VPN.
      
      Indicates which kind of connection this is.
    
Ethernet networks
  
    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:
  
  
    - Authentication
- 
      
        (optional)
        string
      
      
        
        Allowed values are None and
        8021X.
      
    
- EAP
- 
      
        (required if Authentication is
        8021X, otherwise ignored)
        EAP
      
      EAP settings.
    
IP Config
  
    Field IPConfigs is an array
    of IPConfig
    objects. Each IPConfig object describes a
    particular static IP configuration and contains the following fields:
  
  
    - Type
- 
      
        (required)
        string
      
      
        
        Allowed values are IPv4
        and IPv6
      
      Describes the type of configuration this is.
    
- IPAddress
- 
      
        (required)
        string
      
      Describes the IPv4 or IPv6 address of a connection, depending on the value
      of Type field. It should not contain the
      routing prefix (i.e. should not end in something like /64).
    
- RoutingPrefix
- 
      
        (required)
        integer
      
      
        
        Must be a number in the range [1, 32] for IPv4 and [1, 128] for IPv6
        addresses.
      
      Describes the routing prefix.
    
- Gateway
- 
      
        (optional)
        string
      
      Describes the gateway address to use for the configuration. Must match
      address type specified in Type field. If not
      specified, DHCP values will be used.
    
- NameServers
- 
      
        (optional)
        array of string
      
      Array of addresses to use for name servers. Address format must match that
      specified in the Type field. Overrides values
      in the top level NameServers field for this configuration. If not
      specified, top level values will be used.
    
- SearchDomains
- 
      
        (optional)
        array of string
      
      Array of strings to append to names for resolution. Items in this array
      should not start with a dot. Example: [
      "corp.acme.org", "acme.org" ]. Overrides values in the top level
      SearchDomains field for this configuration. If not specified, top level
      values will be used.
    
Wi-Fi networks
  
    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:
  
  
    - AutoConnect
- 
      
        (optional, defaults to false)
        boolean
      
      Indicating that the network should be connected to automatically when in
      range.
    
- EAP
- 
      
        (required if Security is
        WEP-8021X or
        WPA-EAP, otherwise ignored)
        EAP
      
      EAP settings.
    
- HiddenSSID
- 
      
        (optional, defaults to false)
        boolean
      
      Indicating if the SSID will be broadcast.
    
- Passphrase
- 
      
        (required if Security is
        WEP-PSK or
        WPA-PSK, otherwise ignored)
        string
      
      Describes the passphrase for WEP/WPA/WPA2
      connections. If WEP-PSK is used, the passphrase
      must be of the format 0x<hex-number>, where <hex-number> is
      40, 104, 128, or 232 bits.
    
- Security
- 
      
        (required)
        string
      
      
        
        Allowed values are None,
        WEP-PSK,
        WEP-8021X,
        WPA-PSK, and
        WPA-EAP.
      
    
- SSID
- 
      
        (required)
        string
      
      SSID of the network.
    
VPN networks
  
    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:
  
  
    - AutoConnect
- 
      
        (optional, defaults to false)
        boolean
      
      Indicating that the network should be connected to automatically.
    
- Host
- 
      
        (optional)
        string
      
      Host name or IP address of server to connect to. The only scenario that
      does not require a host is a VPN that encrypts but does not tunnel
      traffic. Standalone IPsec (v1 or v2, cert or PSK based -- this is not the
      same as L2TP over IPsec) is one such setup. For all other types of VPN,
      the Host field is required.
    
- IPsec
- 
      
        (required if Type is
        IPsec or
        L2TP-IPsec, otherwise ignored)
        IPsec
      
      IPsec layer settings.
    
- L2TP
- 
      
        (required if Type is
        L2TP-IPsec, otherwise ignored)
        L2TP
      
      L2TP layer settings.
    
- OpenVPN
- 
      
        (required if Type is
        OpenVPN, otherwise ignored)
        OpenVPN
      
      OpenVPN settings.
    
- Type
- 
      
        (required)
        string
      
      
        
        Allowed values are IPsec,
        L2TP-IPsec, and
        OpenVPN.
      
      Type of the VPN.
    
IPsec-based VPN types
    
      The IPsec type contains the following:
    
    
      - AuthenticationType
- 
        
          (required)
          string
        
        
          
          Allowed values are PSK and
          Cert. If Cert is used, ClientCertType and ServerCARefs (or the deprecated ServerCARef) must be set.
        
      
- ClientCertPattern
- 
        
          (required if ClientCertType
          is Pattern, otherwise ignored)
          CertificatePattern
        
        Pattern describing the client certificate.
      
- ClientCertRef
- 
        
          (required if ClientCertType
          is Ref, otherwise ignored)
          string
        
        Reference to client certificate stored in certificate section.
      
- ClientCertType
- 
        
          (required if AuthenticationType
          is Cert, otherwise ignored)
          string
        
        
          
          Allowed values are Ref and
          Pattern
        
      
- EAP
- 
        
          (optional if IKEVersion is 2, otherwise
          ignored)
          EAP
        
        Indicating that EAP authentication should be used with the provided
        parameters.
      
- Group
- 
        
          (optional if IKEVersion is 1, otherwise
          ignored)
          string
        
        Group name used for machine authentication.
      
- IKEVersion
- 
        
          (required)
          integer
        
        Version of IKE protocol to use.
      
- PSK
- 
        
          (optional if AuthenticationType
          is PSK, otherwise ignored)
          string
        
        Pre-Shared Key. If not specified, user is prompted at time of
        connection.
      
- SaveCredentials
- 
        
          (optional if AuthenticationType
          is PSK, otherwise ignored, defaults
          to false)
          boolean
        
        If false, require user to enter credentials
        (PSK) each time they connect.
      
- ServerCARefs
- 
        
          (optional if AuthenticationType
          is Cert, otherwise rejected)
          array of string
        
        Non-empty list of references to CA certificates in Certificates to be used for verifying the host's certificate chain. At least one of the CA certificates must match. If this field is set, ServerCARef must be unset.
      
- ServerCARef
- 
        
          (optional if AuthenticationType
          is Cert, otherwise rejected)
          string
        
        DEPRECATED, use ServerCARefs instead.
 Reference to a CA certificate in Certificates. Certificate authority to use for verifying connection. If this field is set, ServerCARefs must be unset.
- XAUTH
- 
        
          (optional if IKEVersion is 1, otherwise
          ignored)
          XAUTH
        
        Describing XAUTH credentials. XAUTH is not used if this object is not
        present.
      
      
      If AuthenticationType is set to Cert, ServerCARefs or ServerCARef must be set.
    
    
      
      At most one of ServerCARefs and ServerCARef can be set.
    
    
      L2TP type contains the following:
    
    
      - Password
- 
        
          (optional)
          string
        
        User authentication password. If not specified, user is prompted at time
        of connection.
      
- SaveCredentials
- 
        
          (optional, defaults to false)
          boolean
        
        If false, require user to enter credentials
        each time they connect.
      
- Username
- 
        
          (optional)
          string
        
        User identity. This value is subject to string expansions. If not
        specified, user is prompted at time of connection.
      
      XAUTH type contains the following:
    
    
      - Password
- 
        
          (optional)
          string
        
        XAUTH password. If not specified, user is prompted at time of
        connection.
      
- SaveCredentials
- 
        
          (optional, defaults to false)
          boolean
        
        If false, require user to enter credentials
        each time they connect.
      
- Username
- 
        
          (optional)
          string
        
        XAUTH user name. This value is subject to string expansions. If not
        specified, user is prompted at time of connection.
      
IPsec IKE v1 VPN connections
  
    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.
  
  IPsec IKE v2 VPN connections
  
    VPN.Type must
    be IPsec, IKEVersion
    must be 2. This may be used with EAP-based user authentication.
  
  L2TP over IPsec VPN connections
  
    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:
  
  
    - The field IPsec must be present and have the
    following settings:
      
        - IKEVersion must be 1.
- AuthenticationType must be PSK.
- XAUTH must not be set.
 
- The field L2TP must be present.
OpenVPN connections and types
  
    VPN.Type must be
    OpenVPN.
  
  
    OpenVPN type contains the following:
  
  
    - Auth
- 
      
        (optional, defaults to SHA1)
        string
      
    
- AuthRetry
- 
      
        (optional, defaults to none)
        string
      
      
        
        Allowed values are none,
        nointeract, and
        interact.
      
      Controls how OpenVPN responds to username/password verification
      errors:
 Either fail with error on retry
      (none), retry without asking for authentication
      (nointeract), or ask again for authentication
      each time (interact).
- AuthNoCache
- 
      
        (optional, defaults to false)
        boolean
      
      Disable caching of credentials in memory.
    
- Cipher
- 
      
        (optional, defaults to BF-CBC)
        string
      
      Cipher to use.
    
- ClientCertRef
- 
      
        (required if ClientCertType is
        Ref, otherwise ignored)
        string
      
      Reference to client certificate stored in certificate section.
    
- ClientCertPattern
- 
      
        (required if ClientCertType is
        Pattern, otherwise ignored)
        CertificatePattern
      
      Pattern to use to find the client certificate.
    
- ClientCertType
- 
      
        (required)
        string
      
      
        
        Allowed values are Ref,
        Pattern, and None.
      
      None implies that the server is configured to
      not require client certificates.
    
- CompLZO
- 
      
        (optional, defaults to adaptive)
        string
      
      Decides to fast LZO compression with true
      and false as other values.
    
- CompNoAdapt
- 
      
        (optional, defaults to false)
        boolean
      
      Disables adaptive compression.
    
- KeyDirection
- 
      
        (optional)
        string
      
      Passed as --key-direction.
    
- NsCertType
- 
      
        (optional)
        string
      
      If set, checks peer certificate type. Should only be set
      to server if set.
    
- Password
- 
      
        (optional)
        string
      
      XAUTH password. If not specified, user is prompted at time of connection.
    
- Port
- 
      
        (optional, defaults to 1194)
        integer
      
      Port for connecting to server.
    
- Proto
- 
      
        (optional, defaults to udp)
        string
      
      Protocol for communicating with server.
    
- PushPeerInfo
- 
      
        (optional, defaults to false)
        boolean
      
    
- RemoteCertEKU
- 
      
        (optional)
        string
      
      Require that the peer certificate was signed with this explicit extended
      key usage in oid notation.
    
- RemoteCertKU
- 
      
        (optional, defaults to [])
        array of string
      
      Require the given array of key usage numbers. These are strings that are
      hex encoded numbers.
    
- RemoteCertTLS
- 
      
        (optional, defaults to server)
        string
      
      
        
        Allowed values are none and
        server.
      
      Require peer certificate signing based on RFC3280 TLS rules.
    
- RenegSec
- 
      
        (optional, defaults to 3600)
        integer
      
      Renegotiate data channel key after this number of seconds.
    
- SaveCredentials
- 
      
        (optional, defaults to false)
        boolean
      
      If false, require user to enter credentials
      each time they connect.
    
- ServerCARefs
- 
      
        (optional)
        array of string
      
      Non-empty list of references to CA certificates in Certificates 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, ServerCARef must be unset.
    
- ServerCARef
- 
      
        (optional)
        string
      
      DEPRECATED, use ServerCARefs instead.
 Reference to a CA certificate in Certificates. Certificate authority to use for verifying connection. If this field is set, ServerCARefs must be unset.
- ServerCertRef
- 
      
        (optional)
        string
      
      Reference to a certificate. Peer's signed certificate.
    
- ServerPollTimeout
- 
      
        (optional)
        integer
      
      Spend no more than this number of seconds before trying the next server.
    
- Shaper
- 
      
        (optional)
        integer
      
      If not specified no bandwidth limiting, otherwise limit bandwidth of
      outgoing tunnel data to this number of bytes per second.
    
- StaticChallenge
- 
      
        (optional)
        string
      
      String is used in static challenge response. Note that echoing is always
      done.
    
- TLSAuthContents
- 
      
        (optional)
        string
      
      If not set, tls auth is not used. If set, this is the TLS Auth key
      contents (usually starts with "-----BEGIN OpenVPN Static Key..."
    
- TLSRemote
- 
      
        (optional)
        string
      
      If set, only allow connections to server hosts with X509 name or common
      name equal to this string.
    
- Username
- 
      
        (optional)
        string
      
      OpenVPN user name. This value is subject to string expansions. If not
      specified, user is prompted at time of connection.
    
- Verb
- 
      
        (optional)
        string
      
      Verbosity level, defaults to OpenVpn's default if not specified.
    
- VerifyHash
- 
      
        (optional)
        string
      
      If set, this value is passed as the "--verify-hash" argument to OpenVPN,
      which specifies the SHA1 fingerprint for the level-1 certificate.
    
- VerifyX509
- 
      
        (optional)
        VerifyX509
      
       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.
    
    
    At most one of ServerCARefs and ServerCARef can be set.
  
  
    VerifyX509 type contains the following:
  
  
    - Name
- 
      
        (required)
        string
      
      The name that the host's X.509 name is compared to. Which host name is compared depends on the value of Type.
    
- Type
- 
      
        (optional)
        string
      
      Determines which of the host's X.509 names will be verified. Allowed values are name, name-prefix and subject. See OpenVPN's documentation for "--verify-x509-name" for the meaning of each value. Defaults to OpenVPN's default if not specified. 
    
Client certificate patterns
  
    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:
  
  
    - IssuerCARef
- 
      
        (optional)
        array of string
      
      Array of references to certificates. At least one must have signed the
      client certificate.
    
- Issuer
- 
      
        (optional)
        IssuerSubjectPattern
      
      Pattern to match the issuer X.509 settings against. If not specified, the
      only checks done will be a signature check against
      the IssuerCARef field. Issuer of the
      certificate must match this field exactly to match the pattern.
    
- Subject
- 
      
        (optional)
        IssuerSubjectPattern
      
      Pattern to match the subject X.509 settings against. If not specified, the
      subject settings are not checked and any certificate matches. Subject of
      the certificate must match this field exactly to match the pattern.
    
- EnrollmentURI
- 
      
        (optional)
        array of string
      
      If no certificate matches this CertificatePattern, the first URI from this
      array with a recognized scheme is navigated to, with the intention this
      informs the user how to either get the certificate or gets the certificate
      for the user. For instance, the array may be [
      "chrome-extension://asakgksjssjwwkeielsjs/fetch-client-cert.html",
      "http://intra/connecting-to-wireless.html" ] so that for Chrome browsers a
      Chrome app or extension is shown to the user, but for other browsers, a
      web URL is shown.
    
    The IssuerSubjectPattern type contains the
    following:
  
  
    - CommonName
- 
      
        (optional)
        string
      
      Certificate subject's commonName must match this string if present.
    
- Locality
- 
      
        (optional)
        string
      
      Certificate subject's location must match this string if present.
    
- Organization
- 
      
        (optional)
        string
      
      At least one of certificate subject's organizations must match this string
      if present.
    
- OrganizationalUnit
- 
      
        (optional)
        string
      
      At least one of certificate subject's organizational units must match this
      string if present.
    
    
    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.
  
  Proxy settings
  
    Every network can be configured to use a
    proxy. The ProxySettings type contains the
    following:
  
  
    - Type
- 
      
        (required)
        string
      
      
        
        Allowed values are Direct,
        Manual, PAC, and
        WPAD.
      
      PAC indicates Proxy Auto-Configuration.
      WPAD indicates Web Proxy Autodiscovery.
    
- Manual
- 
      
        (required if Type
        is Manual, otherwise ignored)
        ManualProxySettings
      
      Manual proxy settings.
    
- ExcludeDomains
- 
      
        (optional if Type
        is Manual, otherwise ignored)
        array of string
      
      Domains and hosts for which to exclude proxy settings.
    
- PAC
- 
      
        (required if Type is
        PAC, otherwise ignored)
        string
      
      URL of proxy auto-config file.
    
    The ManualProxySettings type contains the
    following:
  
  
    - HTTPProxy
- 
      
        (optional)
        ProxyLocation
      
      settings for HTTP proxy.
    
- SecureHTTPProxy
- 
      
        (optional)
        ProxyLocation
      
      settings for secure HTTP proxy.
    
- FTPProxy
- 
      
        (optional)
        ProxyLocation
      
      settings for FTP proxy
    
- SOCKS
- 
      
        (optional)
        ProxyLocation
      
      settings for SOCKS proxy.
    
    The ProxyLocation type contains the following:
  
  
    - Host
- 
      
        (required)
        string
      
      Host (or IP address) to use for proxy
    
- Port
- 
      
        (required)
        integer
      
      Port to use for proxy
    
EAP configurations
  
    For networks with 802.1X authentication, an EAP
    type exists to configure the
    authentication. The EAP type contains the
    following:
  
  
    - AnonymousIdentity
- 
      
        (optional if Outer is
        PEAP or EAP-TTLS,
        otherwise ignored)
        string
      
      For tunnelling protocols only, this indicates the identity of the user
      presented to the outer protocol. This value is subject to string
      expansions. If not specified, use empty string.
    
- ClientCertPattern
- 
      
        (required if ClientCertType is
        Pattern, otherwise ignored)
        CertificatePattern
      
      Pattern to use to find the client certificate.
    
- ClientCertRef
- 
      
        (required if ClientCertType is
        Ref, otherwise ignored)
        string
      
      Reference to client certificate stored in certificate section.
    
- ClientCertType
- 
      
        (optional) string
      
      
        
        Allowed values are Ref, and
        Pattern.
      
    
- Identity
- 
      
        (optional)
        string
      
      Identity of user. For tunneling outer protocols
      (PEAP, EAP-TTLS, and
      EAP-FAST), this is used to authenticate inside
      the tunnel, and AnonymousIdentity is used for
      the EAP identity outside the tunnel. For non-tunneling outer protocols,
      this is used for the EAP identity. This value is subject to string
      expansions.
    
- Inner
- 
      
        (optional if Outer is
        EAP-FAST, EAP-TTLS
        or PEAP, otherwise ignored, defaults to
        Automatic)
        string
      
      
        
        Allowed values are Automatic,
        MD5, MSCHAPv2,
        EAP-MSCHAPv2, and
        PAP.
      
      For tunneling outer protocols.
    
- Outer
- 
      
        (required)
        string
      
      
        
        Allowed values are LEAP,
        EAP-AKA, EAP-FAST,
        EAP-TLS, EAP-TTLS,
        EAP-SIM and PEAP.
      
    
- Password
- 
      
        (optional)
        string
      
      Password of user. If not specified, defaults to prompting the user.
    
- SaveCredentials
- 
      
        (optional, defaults to false)
        boolean
      
      If false, require user to enter credentials
      each time they connect. Specifying Identity
      and/or Password when
      SaveCredentials is
      false is not allowed.
    
- ServerCARefs
- 
      
        (optional)
        array of string
      
      Non-empty list of references to CA certificates in Certificates to be used for verifying the host's certificate chain. At least one of the CA certificates must match. If this field is set, ServerCARef must be unset. If neither ServerCARefs nor ServerCARef 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 UseSystemCAs for this.
    
- ServerCARef
- 
      
        (optional)
        string
      
      DEPRECATED, use ServerCARefs instead.
 Reference to a CA certificate in Certificates. If this field is set, ServerCARefs must be unset. If neither ServerCARefs nor ServerCARef 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 UseSystemCAs for this.
- UseSystemCAs
- 
      
        (optional, defaults to true)
        boolean
      
      Required server certificate to be signed by "system default certificate
      authorities". If both ServerCARefs (or ServerCARef)
      and UseSystemCAs are supplied, a server
      certificate will be allowed if it either has a chain of trust to a system
      CA or to one of the given CA certificates. If UseSystemCAs
      is false, and no ServerCARef is set, the certificate
      must be a self signed certificate, and no CA signature is required.
    
    
    At most one of ServerCARefs and ServerCARef can be set.
  
  Cellular Networks
  
    This format will eventually also cover configuration of cellular network
    technologies, however they are currently not supported.
  
  Bluetooth / WiFi Direct Networks
  
    This format will eventually also cover configuration of Bluetooth and Wi-Fi
    Direct network technologies, however they are currently not supported.
  
  Certificates
  
    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:
  
  
    - GUID
- 
      
        (required)
        string
      
      A unique identifier for this certificate. Must be a non-empty string.
    
- PKCS12
- 
      
        (required if Type is
        Client, otherwise ignored)
        string
       For certificates with
      private keys, this is the base64 encoding of the a PKCS#12 file.
    
- Remove
- 
      
        (optional, defaults to false)
        boolean
      
      If true, remove this certificate (only GUID
      should be set).
    
- TrustBits
- 
      
        (optional if Type
        is Server
        or Authority, otherwise ignored, defaults to
        [])
        array of string
      
      An array of trust flags. Clients should ignore unknown flags. For
      backwards compatibility, each flag should only increase the trust and
      never restrict. The trust flag Web implies that
      the certificate is to be trusted for HTTPS SSL identification. A typical
      web certificate authority would have Type set
      to Authority and
      TrustBits set to
      ["Web"].
    
- Type
- 
      
        (required if Remove is
        false, otherwise ignored)
        string
      
      
        
        Allowed values are Client,
        Server, and
        Authority.
      
      Client indicates the certificate is for
      identifying the user or device over HTTPS or for
      VPN/802.1X. Server indicates the certificate
      identifies an HTTPS or VPN/802.1X peer.
      Authority indicates the certificate is a
      certificate authority and any certificates it issues should be
      trusted. Note that if Type disagrees with the
      x509 v3 basic constraints or key usage attributes, the
      Type field should be honored.
    
- X509
- 
      
        (required if Type is
        Server or
        Authority, otherwise ignored)
        string
       For certificate
      without private keys, this is the X509 certificate in PEM format.
    
    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.
  
  Encrypted Configuration
  
    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:
  
  
    - Cipher
- 
      
        (required)
        string
      
      The type of cipher used. Currently only AES256
      is supported.
    
- Ciphertext
- 
      
        (required)
        string
      
      The raw ciphertext of the encrypted ONC file, base64 encoded.
    
- HMAC
- 
      
        (required)
        string
      
      The HMAC for the ciphertext, base64 encoded.
    
- HMACMethod
- 
      
        (required)
        string
      
      The method used to compute the Hash-based Message Authentication Code
      (HMAC). Currently only SHA1 is supported.
    
- Salt
- 
      
        (required)
        string
      
      The salt value used during key stretching.
    
- Stretch
- 
      
        (required)
        string
      
      The key stretching algorithm used. Currently
      only PBKDF2 is supported.
    
- Iterations
- 
      
        (required)
        integer
      
      The number of iterations to use during key stretching.
    
- IV
- 
      
        (required)
        string
      
      The initial vector (IV) used for Cyclic Block Cipher (CBC) mode, base64
      encoded.
    
- Type
- 
      
        (required)
        string
      
      The type of the ONC file, which must be set
      to EncryptedConfiguration.
    
    
    When decrypted, the ciphertext must contain a JSON object of
    type UnencryptedConfiguration.
  
  String Expansions
  
    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:
  
  
    - 
      ${LOGIN_ID} - expands to the email address of the user, but before the
      '@'.
    
- 
      ${LOGIN_EMAIL} - expands to the email address of the user.
    
    The following SED would properly handle resolution.
  
  
    - 
      s/\$\{LOGIN_ID\}/bobquail$1/g
    
- 
      s/\$\{LOGIN_EMAIL\}/bobquail@example.com$1/g
    
    Example expansions, assuming the user was bobquail@example.com:
  
  
    - 
      "${LOGIN_ID}" -> "bobquail"
    
- 
      "${LOGIN_ID}@corp.example.com" -> "bobquail@corp.example.com"
    
- 
      "${LOGIN_EMAIL}" -> "bobquail@example.com"
    
- 
      "${LOGIN_ID}X" -> "bobquailX"
    
- 
      "${LOGIN_IDX}" -> "${LOGIN_IDX}"
    
- 
      "X${LOGIN_ID}" -> "Xbobquail"
    
Detection
  
    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.
  
  Alternatives considered
  
    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.
  
  Mocks
  Simple format example: PEAP/MSCHAPv2 network (per device)
  
{
  "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.
  
  Complex format example: TLS network with client certs (per device)
  
{
  "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.
  
  Simple format example: HTTPS Certificate Authority
  
    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==" 
    }
  ]
}
  
  Encrypted format example
  
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"
}