User Tools

Site Tools


networkconfigurationsettings

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
networkconfigurationsettings [2019/02/22 00:23]
Andrew Zaborowski Increase the header levels again to make sure all individual example configs appear in the ToC
networkconfigurationsettings [2021/05/25 23:45]
Andrew Zaborowski Warn about anonymous vs. secure identity in TTLS/PEAP.
Line 1: Line 1:
 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. 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.
 +
 +For most up-to-date information on network settings see the **iwd.network**(5) man page shipped with IWD ([[https://​git.kernel.org/​pub/​scm/​network/​wireless/​iwd.git/​tree/​src/​iwd.network.rst|source]]),​ which incorporates most of this page's content now.
  
 ====== File format ====== ====== File format ======
Line 8: Line 10:
 ^ Setting Key ^ Values ^ Description ^ ^ Setting Key ^ Values ^ Description ^
 | Group header: **''​[Settings]''​** ||| | Group header: **''​[Settings]''​** |||
-| ''​Autoconnect''​ | **''​true''​**,​ ''​false''​ | (optional) |+| ''​AutoConnect''​ | **''​true''​**,​ ''​false''​ | (optional) | 
 +| ''​Autoconnect''​ | **''​true''​**,​ ''​false''​ | (deprecated in favour or ''​AutoConnect''​) ​(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) | | ''​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) |
 +| ''​AlwaysRandomizeAddress''​ | ''​true'',​ **''​false''​** | Always randomize MAC address on each new connection. Requires ''​AddressRandomization=network''​ in main.conf (optional) |
 +| ''​AddressOverride''​ | ''​MAC Address''​ | Override the MAC address used for this network. Requires ''​AddressRandomization=network''​ in main.conf (optional) |
  
-===== Pre-Shared Key (WPA/WPA2 Personal) network settings =====+===== IP configuration settings ===== 
 + 
 +See [[ipconfiguration|IP configuration]]. 
 + 
 +===== Pre-Shared Key (WPA/WPA2 Personal/SAE) network settings =====
 ^ Setting Key ^ Values ^ Description ^ ^ Setting Key ^ Values ^ Description ^
 | Group header: **''​[Security]''​** ||| | Group header: **''​[Security]''​** |||
Line 23: Line 32:
 ^ Setting Key                                           ^ Values ​                                                                                                                   ^ Description ​                                                                                                                                                                                                                                                                                      ^ ^ Setting Key                                           ^ Values ​                                                                                                                   ^ Description ​                                                                                                                                                                                                                                                                                      ^
 | Group header: **''​[Security]''​** ​                                                                                                                                                                                                                                                                                                                                                                                                                                                   ||| | Group header: **''​[Security]''​** ​                                                                                                                                                                                                                                                                                                                                                                                                                                                   |||
-| ''​EAP-Method'' ​                                       | ''​AKA'',​ ''​%%AKA'​%%'',​ ''​GTC'',​ ''​MD5'',​ ''​MSCHAPV2'',​ ''​PEAP'',​ ''​PWD'',​ ''​SIM'',​ ''​TLS'',​ ''​TTLS'',​ ''​WSC''​ (internal) ​ | No default ​                                                                                                                                                                                                                                                                                       |+| ''​EAP-Method'' ​                                       | ''​AKA'',​ ''​%%AKA'​%%'',​ ''​GTC'' ​(*), ''​MD5'' ​(*), ''​MSCHAPV2'',​ ''​PEAP'',​ ''​PWD'',​ ''​SIM'',​ ''​TLS'',​ ''​TTLS'',​ ''​WSC''​ (internal) ​ | No default ​                                                                                                                                                                                                                                                                                       |
 |  Applies to: **EAP-SIM**,​ **EAP-AKA**,​ **EAP-AKA'​** ​                                                                                                                                                                                                                                                                                                                                                                                                                                ||| |  Applies to: **EAP-SIM**,​ **EAP-AKA**,​ **EAP-AKA'​** ​                                                                                                                                                                                                                                                                                                                                                                                                                                |||
 | ''​EAP-Identity'' ​                                     | //​text// ​                                                                                                                 | EAP identity string transmitted in plaintext, if any (optional) ​                                                                                                                                                                                                                                  | | ''​EAP-Identity'' ​                                     | //​text// ​                                                                                                                 | EAP identity string transmitted in plaintext, if any (optional) ​                                                                                                                                                                                                                                  |
-|  Applies to: **EAP-GTC** ​                                                                                                                                                                                                                                                                                                                                                                                                                                                           |||+|  Applies to: **EAP-GTC** ​(Only EAD or TTLS/PEAP inner method) ​                                                                                                                                                                                                                                                                                                                                                                                                                                |||
 | ''​EAP-Identity'' ​                                     | //​text// ​                                                                                                                 | EAP identity/​username string transmitted in plaintext. ​ No default, if not provided IWD will request a username at connection time                                                                                                                                                                | | ''​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-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''​) ​                                                                                                                                                                                                                                                       | | ''​EAP-GTC-Secret'' ​                                   | //​text// ​                                                                                                                 | (deprecated in favour of ''​EAP-Password''​) ​                                                                                                                                                                                                                                                       |
-|  Applies to: **EAP-MD5** ​                                                                                                                                                                                                                                                                                                                                                                                                                                                           |||+|  Applies to: **EAP-MD5** ​(Only EAD or TTLS/PEAP inner method) ​                                                                                                                                                                                                                                                                                                                                                                                                                                |||
 | ''​EAP-Identity'' ​                                     | //​text// ​                                                                                                                 | EAP identity/​username string transmitted in plaintext. ​ No default, if not provided IWD will request a username at connection time                                                                                                                                                                | | ''​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-Password'' ​                                     | //​text// ​                                                                                                                 | EAP MD5 secret string. ​ No default, if not provided IWD will request a passphrase at connection time                                                                                                                                                                                              |
Line 39: Line 48:
 | ''​EAP-Password-Hash'' ​                                | //16-byte hexstring// ​                                                                                                    | An alternative way to specify the MsCHAPv2 password as an MD4 hash, see RFC 2433                                                                                                                                                                                                                  | | ''​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** ​                                                                                                                                                                                                                                                                                                                                                                                                                               ||| |  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 [[https://​tools.ietf.org/​html/​rfc5216#​section-5.2|RFC 5216 Section 5.2]] for requirements on peer identity with regards to client certificate contents. ​ | +| ''​EAP-Identity'' ​                                     | //​text// ​                                                                                                                 | EAP identity/​username string transmitted in plaintext. ​ No default, if not provided IWD will request a username at connection time.  See [[https://​tools.ietf.org/​html/​rfc5216#​section-5.2|RFC 5216 Section 5.2]] for requirements on peer identity with regards to client certificate contents. //Note:// when adapting wpa_supplicant configurations,​ you may need to explicitly copy the value of the //secure// identity here if required by a poorly configured WPA-Enterprise network -- wpa_supplicant silently falls back to the value of ''​identity''​ for ''​anonymous_identity'',​ an undocumented feature/bug.  ​IWD doesn'​t do that to avoid exposing the value in plaintext, the user needs to explicitly set it. 
-| ''​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-CACert'',​\\ ''​EAP-TTLS-CACert'',​\\ ''​EAP-PEAP-CACert''​ | //file path// or //embedded pem// | 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-ClientCert'',​ | //file path// or //embedded pem// | Path to the client X.509 certificate or certificate chain to send on server request. ​ For some networks this is mandatory, for others optional.  Supported formats include PEM, DER and PKCS#12. | 
-| ''​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-ClientKey''​ | //file path// or //embedded pem// | Path to a 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.  Various PEM-based formats and binary PKCS#12 are supported, PKCS#8 is the recommended format. | 
-| ''​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-TLS-ClientKeyBundle'' ​| //file path// | Path to a container fail to load both the certificate(s) and the private key from.  Either this or ''​EAP-TLS-ClientCert'' ​''​EAP-TLS-ClientKey''​ can be present but not both.  Supported formats include PKCS#12 and concatenated PEM payloads. | 
 +| ''​EAP-TLS-ClientKeyPassphrase''​ | //text// | Decryption key for the client private key file.  Must be present iff the private key or the certificate ​under one of the three settings above is encrypted. | 
 +''​EAP-TTLS-ClientCert'',​\\ ''​EAP-PEAP-ClientCert'',​\\ ''​EAP-TTLS-ClientKey''​,\\ ''​EAP-PEAP-ClientKey'',​\\ ''​EAP-TTLS-ClientKeyPassphrase'',​\\ ''​EAP-PEAP-ClientKeyPassphrase''​ | //ignored// | Removed in 1.12 | 
 +| ''​EAP-TLS-ServerDomainMask'',​\\ ''​EAP-TTLS-ServerDomainMask'',​\\ ''​EAP-PEAP-ServerDomainMask''​ | //text// | A mask for the domain names contained in the server'​s certificate. ​ At least one of the domain names present in the certificate'​s Subject Alternative Name extension'​s DNS Name fields or the Common Name has to match at least one mask, or authentication will fail.  Multiple masks can be given separated by semicolons. ​ The masks are split into segments at the dots.  Each segment has to match its corresponding label in the domain name.  An asterisk segment in the mask matches any label. ​ An asterisk segment at the beginning of the mask matches one or more consecutive labels from the beginning of the domain string. |
 | ''​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-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-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-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-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-Method''​ | see ''​EAP-Method''​ | Phase 2 authentication method for EAP-PEAP. ​ No default value. ​ The PEAP phase 1 with no phase 2 (rare) is not supported. |
 | ''​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. | | ''​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** ​                                                                                                                                                                                                                                                                                                                                                                                                                                                           ||| |  Applies to: **EAP-PWD** ​                                                                                                                                                                                                                                                                                                                                                                                                                                                           |||
Line 53: Line 66:
 | ''​EAP-Password'' ​                                     | //​text// ​                                                                                                                 | EAP PWD password string. ​ No default, if not provided IWD will request a passphrase 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''​) ​                                                                                                                                                                                                                                                       | | ''​EAP-PWD-Secret'' ​                                   | //​text// ​                                                                                                                 | (deprecated in favour of ''​EAP-Password''​) ​                                                                                                                                                                                                                                                       |
 +
 +===== Embedded PEMs =====
 +Rather than including an absolute path to a PEM file (for certificates and keys), the PEM itself can be included inside the settings file and referenced directly. This allows IEEE 802.1x network provisioning using a single file without any references to certificates or keys on the system.
 +
 +An embedded PEM can appear anywhere in the settings file using the following format (in this example the PEM is named ''​my_ca_cert''​):​
 +
 +<code ini>
 +[@pem@my_ca_cert]
 +----- BEGIN CERTIFICATE -----
 +<PEM data>
 +----- END CERTIFICATE -----
 +</​code>​
 +
 +After this special group tag it's as simple as pasting in a PEM file including the ''​BEGIN''/''​END''​ tags. Now ''​my_ca_cert''​ can be used to reference the certificate elsewhere in the settings file by prefixing the value with ''​embed:''​
 +
 +<code ini>
 +EAP-TLS-CACert=embed:​my_ca_cert
 +</​code>​
 +
 +CA certificates,​ client certificate chains and client keys (encrypted or not) can be included in this way.
  
 ===== File naming and syntax ===== ===== File naming and syntax =====
Line 64: Line 97:
 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''​. 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 ''​]''​.+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 ''​]'' ​
 + 
 +If a group name starts with the ''​@''​ sign, that group'​s content is handled by a parser extension instead and does not cause the previous non-extension group to end.  The initial ''​@''​ sign must be followed by a non-empty extension name, another ''​@''​ sign and a group name as defined above. ​ The extension name consists of printable characters other than ''​@''​. ​ No whitespace is allowed after the group header in this case.  The extension payload syntax and length are determined by the extension name.  Normal parsing rules defined in this section resume at the end of the payload and any settings after the end of the payload are handled as part of the previous non-extension group. 
 + 
 +Currently the only extension supported is named ''​pem''​ and allows embedding the contents of a single [[https://​tools.ietf.org/​html/​rfc7468|RFC7468 PEM]]-formatted payload or a sequence of multiple PEM payloads. ​ The payload should start with the ''​-----BEGIN ''​ string on a line following the group header line and end with an ''​-----END ''​ line as specified in the RFC.  Newline characters before, between and after PEM payloads are included in the extension payload. ​ No other extra characters are allowed.
  
 ====== Example network configuration files ======= ====== Example network configuration files =======
networkconfigurationsettings.txt · Last modified: 2021/05/25 23:45 by Andrew Zaborowski