diff --git a/README b/README index 595041b..e73acad 100644 --- a/README +++ b/README @@ -108,8 +108,14 @@ recommended that you start a separate shell with root privileges while configuring PAM to be able to revert changes if something goes wrong. Test your configuration thoroughly before closing the root shell. +[[moduleArguments]] === Module Arguments +The following table documents the set of arguments recognized by the module. +Hard-wired defaults can be overridden by a <>. +The definitions from the configuration file can be in turn overridden by +individual files under `/etc/pam.d/`. + [horizontal] debug:: Enables debug output @@ -240,6 +246,12 @@ FIDO devices. It is not possible to mix native credentials and SSH credentials. Once this option is enabled all credentials will be parsed as SSH. +conf_file=file:: +Set an alternative location for the <>. +The supplied path must be absolute, and must correspond to an existing +regular file. +The file can be empty. + IMPORTANT: On dynamic networks (e.g. where hostnames are set by DHCP), users should not rely on the default origin and appid ("pam://$HOSTNAME") but set those parameters explicitly to the same @@ -404,6 +416,36 @@ defined in the authorization mapping file. If during an authentication attempt a connected device is removed or a new device is plugged in, the authentication restarts from the top of the list. +[[confFile]] +== Configuration file + +A configuration file can be supplied in order to provide system-level default +values for the `pam_u2f.so` module arguments. + +- The file can contain the same arguments as <>, + one per line, exception made for the `conf_file=` argument which can only appear + under `/etc/pam.d/`. + +- Lines starting with `#` are interpreted as comments and skipped, together with + empty lines. + +- In every line heading white-spaces (intended as in `isspace(3)`) are ignored. + Everything from the first non-white-space character till the end of line is + interpreted verbatim. Note that it is not possible to add trailing comments + to lines. + +- Square brackets around arguments, usually needed under `/etc/pam.d` to get + spaces correctly recognized, must not be supplied. + +The default path of the system-level configuration file is +`/etc/security/pam_u2f.conf`. The file is allowed to be missing or empty, in +which case the `pam_u2f.so` configuration will default to the hard-wired +values. + +Individual files under `/etc/pam.d/` can specify a different configuration file +by means of the `conf_file=` argument, without affecting other +`/etc/pam.d/` files. + == SELinux Note Due to an issue with Fedora Linux, and possibly with other diff --git a/man/pam_u2f.8.txt b/man/pam_u2f.8.txt index 4524d39..f33d6d2 100644 --- a/man/pam_u2f.8.txt +++ b/man/pam_u2f.8.txt @@ -88,6 +88,7 @@ will be ignored. Set to prompt a message and wait before testing the presence of a U2F device. Recommended if your device doesn't have tactile trigger. + *[prompt=your prompt here]*:: Set individual prompt message for interactive mode. Watch the square brackets around this parameter to get spaces correctly recognized by @@ -134,6 +135,13 @@ FIDO devices. It is not possible to mix native credentials and SSH credentials. Once this option is enabled all credentials will be parsed as SSH. +*conf_file*=_path_:: +Set an alternative location for the configuration file. +The supplied path must be absolute, and must correspond to an existing +regular file. +The file can be empty. +See *CONFIGURATION FILE*. + == EXAMPLES Second factor authentication deferring user verification configuration to the @@ -162,6 +170,35 @@ mapping file in an encrypted home directory, will result in the impossibility of logging into the system. The partition is decrypted after login and the mapping file can not be accessed. +== CONFIGURATION FILE +A configuration file can be supplied in order to provide system-level default +values for the `pam_u2f.so` module arguments. + +- The file can contain the same arguments as defined in the *OPTIONS* section, + one per line, exception made for the `conf_file=` argument, which can only + appear under `/etc/pam.d/`. + +- Lines starting with `#` are interpreted as comments and skipped, together with + empty lines. + +- In every line heading white-spaces (intended as in `isspace(3)`) are ignored. + Everything from the first non-white-space character till the end of line is + interpreted verbatim. Note that it is not possible to add trailing comments + to lines. + +- Square brackets around arguments, usually needed under `/etc/pam.d` to get + spaces correctly recognized, must not be supplied. + +The default path of the system-level configuration file is +`/etc/security/pam_u2f.conf`. The file is allowed to be missing or empty, in +which case the `pam_u2f.so` configuration will default to the hard-wired +values. + +Individual files under `/etc/pam.d/` can specify a different configuration file +by means of the `conf_file=` argument, without affecting other `/etc/pam.d/` +files. + + == NOTES *Nodetect*