User Tools

Site Tools


networkconfigurationsettings

This is an old revision of the document!


IWD stores information on known networks, and reads information on pre-provisioned networks, from small text configuration files. Those files live in $LIBDIR/iwd, by default /var/lib/iwd. You can create, modify or remove those files. IWD monitors the directory for changes and will also modify these files in the course of network connections as necessary.

File format

The syntax is similar to that of GNOME keyfile syntax and other popular formats, using comment lines, group header lines and Key=Value lines. The allowed keys and values in each group are documented here. Defaults are written in bold. Values marked as internal should not normally be used by users or administrators.

General network configuration settings

Setting Key Values Description
Group header: [Settings]
Autoconnect true, false (optional)
Hidden true, false Used for hidden networks i.e. those that do not reply to scan probing except when their SSIDs are included explicitly (optional)

Pre-Shared Key (WPA/WPA2 Personal) network settings

Setting Key Values Description
Group header: [Security]
Passphrase text The passphrase for passphrase-protected networks. No default, if not provided IWD will request the passphrase at connection time. 8 to 63 characters.
PreSharedKey 32-byte hexstring Processed version of the passphrase+SSID strings for daemon's internal use (optional)

802.1x (WPA/WPA2 Enterprise) settings

The values here will apply to both IWD and EAD.

Setting Key Values Description
Group header: [Security]
EAP-Method AKA, AKA', GTC, MD5, MSCHAPV2, PEAP, PWD, SIM, TLS, TTLS, WSC (internal) No default
Applies to: EAP-SIM, EAP-AKA, EAP-AKA'
EAP-Identity text EAP identity string transmitted in plaintext, if any (optional)
Applies to: EAP-GTC
EAP-Identity text EAP identity/username string transmitted in plaintext. No default, if not provided IWD will request a username at connection time
EAP-Password text EAP GTC secret string. No default, if not provided IWD will request a passphrase at connection time
EAP-GTC-Secret text (deprecated in favour of EAP-Password)
Applies to: EAP-MD5
EAP-Identity text EAP identity/username string transmitted in plaintext. No default, if not provided IWD will request a username at connection time
EAP-Password text EAP MD5 secret string. No default, if not provided IWD will request a passphrase at connection time
EAP-MD5-Secret text (deprecated in favour of EAP-Password)
Applies to: EAP-MSCHAPV2
EAP-Identity text EAP identity/username string transmitted in plaintext. No default, if not provided IWD will request a username at connection time
EAP-Password text EAP MsCHAPv2 password string. No default, if neither Password nor Password-Hash are provided IWD will request a passphrase at connection time
EAP-Password-Hash 16-byte hexstring An alternative way to specify the MsCHAPv2 password as an MD4 hash, see RFC 2433
Applies to: EAP-TLS, EAP-TTLS, EAP-PEAP
EAP-Identity text EAP identity/username string transmitted in plaintext. No default, if not provided IWD will request a username at connection time. See RFC 5216 Section 5.2 for requirements on peer identity with regards to client certificate contents.
EAP-TLS-CACert,
EAP-TTLS-CACert,
EAP-PEAP-CACert
file path Path to a PEM-formatted X.509 root certificate list to use for trust verification, both for the server's certificate chain and the chain specified with ClientCert (if any). IWD will require that the root in the verified certificate chains is trusted by at least one CA in the list. If not provided IWD will have no way to authenticate the server – discouraged. (optional)
EAP-TLS-ClientCert,
EAP-TTLS-ClientCert,
EAP-PEAP-ClientCert
file path Path to a PEM-formatted client X.509 certificate or certificate chain to send on server request. For some networks this is mandatory, for others optional.
EAP-TLS-ClientKey,
EAP-TTLS-ClientKey,
EAP-PEAP-ClientKey
file path Path to a PEM-formatted PKCS #8 private key corresponding to the certified client public key to authenticate ourselves to the server with. For some networks this is manadatory, for others optional.
EAP-TLS-ClientKeyPassphrase,
EAP-TTLS-ClientKeyPassphrase,
EAP-PEAP-ClientKeyPassphrase
text Decryption key for the client private key file. Must be present iff the private key under ClientKey is encrypted.
EAP-TTLS-Phase2-Method Tunneled-CHAP,
Tunneled-MSCHAP,
Tunneled-MSCHAPv2,
Tunneled-PAP or
a valid EAP method name (see EAP-Method)
Phase 2 authentication method for EAP-TTLS. Can be either one of the TTLS-specific non-EAP methods (Tunneled-*), or any EAP method documented here. The following two settings are used if any of the non-EAP methods is used. No default value.
EAP-TTLS-Phase2-Identity text The secure identity/username string for the TTLS non-EAP Phase 2 methods. No default, if not provided IWD will request a username at connection time.
EAP-TTLS-Phase2-Password text Password string for the TTLS non-EAP Phase 2 methods. No default, if not provided IWD will request a passphrase at connection time.
EAP-TTLS-Phase2-* Any settings to be used for the inner EAP method if one was specified as EAP-TTLS-Phase2-Method, rather than a TTLS-specific method. The prefix EAP-TTLS-Phase2- replaces the EAP- prefix in the setting keys and their usage is unchanged. Since the inner method's negotiation is encrypted, a secure identity string can be provided.
EAP-PEAP-Phase2-* Any settings to be used for the inner EAP method with EAP-PEAP as the outer method. The prefix EAP-PEAP-Phase2- replaces the EAP- prefix in the setting keys and their usage is unchanged. Since the inner method's negotiation is encrypted, a secure identity string can be provided.
Applies to: EAP-PWD
EAP-Identity text EAP identity/username string transmitted in plaintext. No default, if not provided IWD will request a username at connection time
EAP-Password text EAP PWD password string. No default, if not provided IWD will request a passphrase at connection time
EAP-PWD-Secret text (deprecated in favour of EAP-Password)

File naming and syntax

File names are based on the network's SSID and security type: Open, PSK-protected or 802.1x. The name consist of the encoding of the SSID followed by .open, .psk or .8021x. The SSID appears verbatim in the name if it contains only alphanumeric characters, spaces, underscores or minus signs. Otherwise it is encoded as an equal sign followed by the lower-case hex encoding of the name.

For completeness we include the description of the file syntax here. This is the syntax that the ell library's l_settings class implements. The syntax is based on lines and lines are delimited by the \n characters.

Empty lines are ignored and whitespace at the beginning of a line is ignored. Comment lines have # as their first non-whitespace character.

Key-value lines contain a setting key, an equal sign and the value of the setting. Whitespace preceding the key, the equal sign or the value, is ignored. The key must be a continuous string of alphanumeric and underscore characters and minus signs only. The value starts at the first non-whitespace character after the first equal sign on the line and ends at the end of the line and must be correctly UTF-8-encoded. A boolean value can be true or false but 0 or 1 are also allowed. Integer values are written in base 10. String values, including file paths and hexstrings, are written as is except for five characters that may be backslash-escaped: space, \t, \r, \n and backslash itself. The latter three must be escaped. A space character must be escaped if it is the first character in the value string and is written as \s.

Settings are interpreted depending on the group they are in. A group starts with a group header line and contains all settings until the next group's header line. A group header line contains a [ character followed by the group name and a ] character. Whitespace is allowed before the [ and after the ]. A group name consists of printable characters other than [ and ].

Example network configuration files

EAP Transport Layer Security (EAP-TLS)

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TLS-ClientCert=</certs/client-cert.pem>
#EAP-TLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TLS-ClientKeyPassphrase=<client private key passphrase>

EAP Tunneled Transport Layer Security (EAP-TTLS)

iNet Wireless Daemon (iwd) supports Extensible Authentication Protocol Tunneled Transport Layer Security Authenticated Protocol Version 0 (EAP-TTLSv0). The tunneled authentication mechanism may itself be EAP, or it may be another authentication protocol such as PAP, CHAP, MS-CHAP, or MS-CHAP-V2.

EAP-TTLS with tunneled CHAP

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TTLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TTLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TTLS-ClientCert=</certs/client-cert.pem>
#EAP-TTLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TTLS-ClientKeyPassphrase=<client private key passphrase>
 
EAP-TTLS-Phase2-Method=Tunneled-CHAP
 
# Uncomment to provide CHAP Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-TTLS-Phase2-Identity=<username>
#EAP-TTLS-Phase2-Password=<password>

EAP-TTLS with tunneled MS-CHAP

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TTLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TTLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TTLS-ClientCert=</certs/client-cert.pem>
#EAP-TTLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TTLS-ClientKeyPassphrase=<client private key passphrase>
 
EAP-TTLS-Phase2-Method=Tunneled-MSCHAP
 
# Uncomment to provide MS-CHAP Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-TTLS-Phase2-Identity=<username>
#EAP-TTLS-Phase2-Password=<password>

EAP-TTLS with tunneled MS-CHAP-V2

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TTLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TTLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TTLS-ClientCert=</certs/client-cert.pem>
#EAP-TTLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TTLS-ClientKeyPassphrase=<client private key passphrase>
 
EAP-TTLS-Phase2-Method=Tunneled-MSCHAPv2
 
# Uncomment to provide MS-CHAPv2 Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-TTLS-Phase2-Identity=<username>
#EAP-TTLS-Phase2-Password=<password>

EAP-TTLS with tunneled PAP

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TTLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TTLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TTLS-ClientCert=</certs/client-cert.pem>
#EAP-TTLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TTLS-ClientKeyPassphrase=<client private key passphrase>
 
EAP-TTLS-Phase2-Method=Tunneled-PAP
 
# Uncomment to provide PAP Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-TTLS-Phase2-Identity=<username>
#EAP-TTLS-Phase2-Password=<password>

EAP-TTLS with tunneled EAP method

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=TTLS
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-TTLS-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-TTLS-ClientCert=</certs/client-cert.pem>
#EAP-TTLS-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-TTLS-ClientKeyPassphrase=<client private key passphrase>
 
EAP-TTLS-Phase2-Method=MSCHAPV2
 
# Uncomment to provide EAP-MSCHAPV2 Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-TTLS-Phase2-Identity=<username>
#EAP-TTLS-Phase2-Password=<password>

EAP-PEAP

Protected EAP (PEAP) is comprised of a two-part conversation:

  • In Part 1, a TLS session is negotiated, with server authenticating to the client and optionally the client to the server. The negotiated key is then used to encrypt the rest of the conversation.
  • In Part 2, within the TLS session, a complete EAP conversation is carried out. The configuration examples of the most commonly supported methods: EAP-MSCHAPV2, EAP-GTC and EAP-SIM are provided below.

iNet Wireless Daemon (iwd) offers two versions of PEAP: PEAPv0 and PEAPv1. The highest version supported by authenticator will be negotiated at the connection time.

EAP-PEAP with tunneled EAP-MSCHAPV2

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=PEAP
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-PEAP-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-PEAP-ClientCert=</certs/client-cert.pem>
#EAP-PEAP-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-PEAP-ClientKeyPassphrase=<client private key passphrase>
 
EAP-PEAP-Phase2-Method=MSCHAPV2
 
# Uncomment to provide EAP-MSCHAPV2 Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-PEAP-Phase2-Identity=<username>
#EAP-PEAP-Phase2-Password=<password>

EAP-PEAP with tunneled EAP-GTC

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=PEAP
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-PEAP-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-PEAP-ClientCert=</certs/client-cert.pem>
#EAP-PEAP-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-PEAP-ClientKeyPassphrase=<client private key passphrase>
 
EAP-PEAP-Phase2-Method=GTC
 
# Uncomment to provide EAP-GTC Identity and Password. These fields are mandatory and
# if left out, will be requested by iwd at the connection time.
#EAP-PEAP-Phase2-Identity=<username>
#EAP-PEAP-Phase2-Password=<password>

EAP-PEAP with tunneled EAP-SIM

Network configuration file: /var/lib/iwd/<network name>.8021x

# Note: The lines starting with # are ignored. To enable any of the
# configuration options below, remove # from the beginning of a respective line.
 
[Security]
 
EAP-Method=PEAP
 
# Uncomment to provide the anonymous identity.
#EAP-Identity=<anonymous identity>
 
# Uncomment to validate the server's certificate by checking it was
# signed by this CA.
#EAP-PEAP-CACert=</certs/ca-cert.pem>
 
# Uncomment to provide the client cert and private key. These fields must be
# provided together.
#EAP-PEAP-ClientCert=</certs/client-cert.pem>
#EAP-PEAP-ClientKey=</certs/client-key.pem>
 
# Uncomment to provide the client private key passphrase if the client private
# key has been protected with the passphrase.
#EAP-PEAP-ClientKeyPassphrase=<client private key passphrase>
 
EAP-PEAP-Phase2-Method=SIM
 
# Uncomment to provide EAP-SIM Identity
#EAP-PEAP-Phase2-Identity=<identity>
networkconfigurationsettings.1550794991.txt.gz · Last modified: 2019/02/22 00:23 (external edit)