From 81fb36ff5c22f606ab89484b49be9523eb832e97 Mon Sep 17 00:00:00 2001 From: Giovanni Simoni Date: Fri, 6 Dec 2024 13:46:36 +0100 Subject: [PATCH] Update README file and manpages --- README | 42 ++++++++++++++++++++++++++++++++++++++++++ man/pam_u2f.8.txt | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) diff --git a/README b/README index 595041b..0efb2f7 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. + +- 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. + +- 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. + +- Square brackets around arguments, 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. Doing so will not affect 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..de2ce25 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 <>, + one per line. + +- 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. + +- 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. + +- Square brackets around arguments, 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. Doing so will not affect other +`/etc/pam.d/` files. + + == NOTES *Nodetect*