diff --git a/.gitignore b/.gitignore index a8412973..7581505b 100644 --- a/.gitignore +++ b/.gitignore @@ -21,6 +21,7 @@ ell src/iwd src/iwd.8 src/iwd.conf.5 +src/iwd.network.5 src/iwd.service client/iwctl client/iwctl.1 diff --git a/Makefile.am b/Makefile.am index 167b0cea..ecd1c228 100644 --- a/Makefile.am +++ b/Makefile.am @@ -156,8 +156,8 @@ if MANUAL_PAGES man_MANS = endif -manual_pages = src/iwd.8 src/iwd.conf.5 client/iwctl.1 monitor/iwmon.1 \ - wired/ead.8 tools/hwsim.1 +manual_pages = src/iwd.8 src/iwd.conf.5 src/iwd.network.5 \ + client/iwctl.1 monitor/iwmon.1 wired/ead.8 tools/hwsim.1 eap_sources = src/eap.c src/eap.h src/eap-private.h \ src/eap-wsc.c src/eap-wsc.h \ @@ -251,7 +251,7 @@ dbus_bus_DATA += src/net.connman.iwd.service endif if MANUAL_PAGES -man_MANS += src/iwd.8 src/iwd.conf.5 +man_MANS += src/iwd.8 src/iwd.conf.5 src/iwd.network.5 endif endif diff --git a/src/iwd.conf.rst b/src/iwd.conf.rst index 4897615d..d1ff34a3 100644 --- a/src/iwd.conf.rst +++ b/src/iwd.conf.rst @@ -1,6 +1,6 @@ -=========== - main.conf -=========== +===== + iwd +===== -------------------------------------- Configuration file for wireless daemon @@ -16,7 +16,7 @@ Configuration file for wireless daemon SYNOPSIS ======== -**main.conf** +Configuration file **main.conf** DESCRIPTION =========== @@ -28,6 +28,11 @@ by **systemd**. In the absence of such an environment variable it defaults to */etc/iwd*. If no *main.conf* is present, then default values are chosen. The presence of *main.conf* is not required. +FILE FORMAT +=========== + +See *iwd.network* for details on the file format. + SETTINGS ======== @@ -74,4 +79,4 @@ The group ``[General]`` contains general settings. SEE ALSO ======== -iwd(8) +iwd(8), iwd.network(5) diff --git a/src/iwd.network.rst b/src/iwd.network.rst new file mode 100644 index 00000000..9d925d24 --- /dev/null +++ b/src/iwd.network.rst @@ -0,0 +1,241 @@ +===== + iwd +===== + +----------------------------------------- +Network configuration for wireless daemon +----------------------------------------- + +:Author: Marcel Holtmann +:Author: Denis Kenzior +:Author: Andrew Zaborowski +:Author: Tim Kourt +:Copyright: 2013-2019 Intel Corporation +:Version: iwd +:Date: 22 September 2019 +:Manual section: 5 +:Manual group: Linux Connectivity + +SYNOPSIS +======== + +Network configuration files ``.open``, ``.psk`` and ``.8021x`` + +DESCRIPTION +=========== + +**iwd** stores information on known networks, and reads information on +pre-provisioned networks, from small text configuration files. Those files +live in the state directory specified by the environment variable +*$STATE_DIRECTORY*, which is normally provided by **systemd**. In the absence +of such an environment variable it defaults to *$LIBDIR/iwd*, which normally +is set to */var/lib/iwd*. You can create, modify or remove those files. +**iwd** monitors the directory for changes and will update its state +accordingly. **iwd** will also modify these files in the course of network +connections or as a result of D-Bus API invocations. + +FILE FORMAT +=========== + +The syntax is similar to that of GNOME keyfile syntax (which is based on the +format defined in the Desktop Entry Specification, see +*http://freedesktop.org/Standards/desktop-entry-spec*). The recognized groups +as well as keys and values in each group are documented here. Defaults are +written in bold. + +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 newline 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 ``]``. + +NAMING +====== + +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. + +SETTINGS +======== + +The settings below are split into several sections and grouped into broad +categories. Each category has a group associated with it which is given at +the beginning of each sub-section. Recognized keys and valid values are listed +following the group definition. + +General Settings +---------------- + +The group ``[General]`` contains general settings. + +.. list-table:: + :header-rows: 1 + :stub-columns: 0 + :widths: 20 80 + :align: left + + * - Key + - Description + * - Autoconnect + - Values: **true**, false + + Whether the network can be connected to automatically + * - Hidden + - Values: true, **false** + + Whether the network is hidden, i.e. its SSID must be included in an + active scan request + +Network Authentication Settings +------------------------------- + +The group ``[Security]`` contains settings for Wi-Fi security and +authentication configuration. + +.. list-table:: + :header-rows: 1 + :stub-columns: 0 + :widths: 20 80 + :align: left + + * - Key + - Description + * - Passphrase + - 8..63 character string + + Passphrase to be used when connecting to WPA-Personal networks. + Required when connecting to WPA3-Personal (SAE) networks. Also + required if the *PreSharedKey* is not provided. If not provided in + settings, the agent will be asked for the passphrase at connection + time. + * - PreSharedKey + - 64 character hex string + + Processed passphrase for this network in the form of a hex-encoded 32 + byte pre-shared key. Must be provided if *Passphrase* is omitted. + * - EAP-Method + - one of the following methods: + + AKA, AKA', GTC, MD5, MSCHAPV2, PEAP, PWD, SIM, TLS, TTLS + * - EAP-Identity + - string + + Identity string transmitted in plaintext. Depending on the EAP method, + this value can be optional or mandatory. GTC, MD5, MSCHAPV2, PWD + require an identity, so if not provided, the agent will be asked for it + at connection time. TLS based methods (PEAP, TLS, TTLS) might still + require an *EAP-Identity* to be set, depending on the RADIUS server + configuration. + * - EAP-Password + - string + + Password to be provided for WPA-Enterprise authentication. If not + provided, the agent will be asked for the password at connection time. + Required by: GTC, MD5, MSCHAPV2, PWD. + * - EAP-Password-Hash + - hex string + + Some EAP methods can accept a pre-hashed version of the password. For + MSCHAPV2, a MD4 hash of the password can be given here. + * - | EAP-TLS-CACert, + | EAP-TTLS-CACert, + | EAP-PEAP-CACert + - absolute file path or embedded pem + + Path to a PEM-formatted X.509 root certificate list to use for trust + verification of the authenticator. The authenticator's server's + certificate chain must be verified by at least one CA in the list for + the authentication to succeed. If omitted, then authenticator's + certificate chain will not be verified (not recommended.) + * - EAP-TLS-ClientCert + - absolute file path or embedded pem + + Path to a PEM-formatted client X.509 certificate or certificate chain + to send on server request. + * - EAP-TLS-ClientKey + - absolute file path or embedded pem + + Path to a PEM-formatted client PKCS#8 private key corresponding to the + public key provided in *EAP-TLS-ClientCert*. + * - | EAP-TLS- + | ClientKeyPassphrase + - string + + Decryption key for the client private key file. This is used if the + private key given by *EAP-TLS-ClientKey* is encrypted. If not provided, + then the agent is asked for the passphrase at connection time. + * - | EAP-TLS-ServerDomainMask, + | EAP-TTLS-ServerDomainMask, + | EAP-PEAP-ServerDomainMask + - string + + 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 + - | The following values are allowed: + | 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. + * - | EAP-TTLS-Phase2-Identity + - The secure identity/username string for the TTLS non-EAP Phase 2 + methods. If not provided IWD will request a username at connection + time. + * - | EAP-TTLS-Phase2-Password + - Password string for the TTLS non-EAP Phase 2 methods. 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. + +SEE ALSO +======== + +iwd(8), iwd.conf(5) diff --git a/src/iwd.rst b/src/iwd.rst index 2df29843..0f611ae9 100644 --- a/src/iwd.rst +++ b/src/iwd.rst @@ -40,217 +40,15 @@ OPTIONS --version, -v Show version number and exit. --help, -h Show help message and exit. -NETWORK CONFIGURATION -===================== - -**iwd** stores information on known networks, and reads information on -pre-provisioned networks, from small text configuration files. Those files -live in the state directory specified by the environment variable -*$STATE_DIRECTORY*, which is normally provided by **systemd**. In the absence -of such an environment variable it defaults to *$LIBDIR/iwd*, which normally -is set to */var/lib/iwd*. You can create, modify or remove those files. -**iwd** monitors the directory for changes and will update its state -accordingly. **iwd** will also modify these files in the course of network -connections or as a result of D-Bus API invocations. - -FILE FORMAT ------------ - -The syntax is similar to that of GNOME keyfile syntax (which is based on the -format defined in the Desktop Entry Specification, see -*http://freedesktop.org/Standards/desktop-entry-spec*). The recognized groups -as well as keys and values in each group are documented here. Defaults are -written in bold. - -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 newline 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 ``]``. - -NAMING ------- - -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. - -SETTINGS --------- - -The settings below are split into several sections and grouped into broad -categories. Each category has a group associated with it which is given at -the beginning of each sub-section. Recognized keys and valid values are listed -following the group definition. - -.. list-table:: General Settings / Group: ``[Settings]`` - :header-rows: 1 - :stub-columns: 1 - :widths: 20 80 - :align: left - - * - Key - - Description - * - Autoconnect - - Values: **true**, false - - Whether the network can be connected to automatically - * - Hidden - - Values: true, **false** - - Whether the network is hidden, i.e. its SSID must be included in an - active scan request - -.. list-table:: Network Authentication Settings / Group: ``[Security]`` - :header-rows: 1 - :stub-columns: 1 - :widths: 20 80 - :align: left - - * - Key - - Description - * - Passphrase - - 8..63 character string - - Passphrase to be used when connecting to WPA-Personal networks. - Required when connecting to WPA3-Personal (SAE) networks. Also - required if the *PreSharedKey* is not provided. If not provided in - settings, the agent will be asked for the passphrase at connection - time. - * - PreSharedKey - - 64 character hex string - - Processed passphrase for this network in the form of a hex-encoded 32 - byte pre-shared key. Must be provided if *Passphrase* is omitted. - * - EAP-Method - - one of the following methods: - - AKA, AKA', GTC, MD5, MSCHAPV2, PEAP, PWD, SIM, TLS, TTLS - * - EAP-Identity - - string - - Identity string transmitted in plaintext. Depending on the EAP method, - this value can be optional or mandatory. GTC, MD5, MSCHAPV2, PWD - require an identity, so if not provided, the agent will be asked for it - at connection time. TLS based methods (PEAP, TLS, TTLS) might still - require an *EAP-Identity* to be set, depending on the RADIUS server - configuration. - * - EAP-Password - - string - - Password to be provided for WPA-Enterprise authentication. If not - provided, the agent will be asked for the password at connection time. - Required by: GTC, MD5, MSCHAPV2, PWD. - * - EAP-Password-Hash - - hex string - - Some EAP methods can accept a pre-hashed version of the password. For - MSCHAPV2, a MD4 hash of the password can be given here. - * - | EAP-TLS-CACert, - | EAP-TTLS-CACert, - | EAP-PEAP-CACert - - absolute file path or embedded pem - - Path to a PEM-formatted X.509 root certificate list to use for trust - verification of the authenticator. The authenticator's server's - certificate chain must be verified by at least one CA in the list for - the authentication to succeed. If omitted, then authenticator's - certificate chain will not be verified (not recommended.) - * - EAP-TLS-ClientCert - - absolute file path or embedded pem - - Path to a PEM-formatted client X.509 certificate or certificate chain - to send on server request. - * - EAP-TLS-ClientKey - - absolute file path or embedded pem - - Path to a PEM-formatted client PKCS#8 private key corresponding to the - public key provided in *EAP-TLS-ClientCert*. - * - | EAP-TLS- - | ClientKeyPassphrase - - string - - Decryption key for the client private key file. This is used if the - private key given by *EAP-TLS-ClientKey* is encrypted. If not provided, - then the agent is asked for the passphrase at connection time. - * - | EAP-TLS-ServerDomainMask, - | EAP-TTLS-ServerDomainMask, - | EAP-PEAP-ServerDomainMask - - string - - 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 - - | The following values are allowed: - | 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. - * - | EAP-TTLS-Phase2-Identity - - The secure identity/username string for the TTLS non-EAP Phase 2 - methods. If not provided IWD will request a username at connection - time. - * - | EAP-TTLS-Phase2-Password - - Password string for the TTLS non-EAP Phase 2 methods. 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. - ENVIRONMENT =========== *$STATE_DIRECTORY* is used for network configuration files. See section -*NETWORK CONFIGURATION* for details. +*iwd.network* for details. *$CONFIGURATION_DIRECTORY* is used for daemon configuration settings. Only -the file **main.conf** is currently read from this directory. +the file **main.conf** is currently read from this directory. See *iwd.conf* +for details. *$IWD_RTNL_DEBUG* set to ``1`` enables RTNL debugging. @@ -263,6 +61,7 @@ the file **main.conf** is currently read from this directory. SEE ALSO ======== -iwd.conf(5), iwctl(1), iwmon(1), hwsim(1), ead(8), systemd.exec(5) +iwd.conf(5), iwd.network(5), iwctl(1), iwmon(1), hwsim(1), ead(8), +systemd.exec(5) http://iwd.wiki.kernel.org