diff --git a/pam/Makefile.am b/pam/Makefile.am index 5c83c00..9b5bcc8 100644 --- a/pam/Makefile.am +++ b/pam/Makefile.am @@ -72,3 +72,18 @@ test_pam_CFLAGS = $(pam_CFLAGS) check_PROGRAMS += $(pam_TESTS) TESTS += $(pam_TESTS) + +# ----------------------------------------------------------------------------- +# Man page + +man_MANS = pam_gnome_keyring.8 + +if ENABLE_DOC + +%.8: pam/%.8.xml + @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + +endif + +BUILT_EXTRA_DIST = $(man_MANS) +EXTRA_DIST += pam_gnome_keyring.8.xml diff --git a/pam/pam_gnome_keyring.8.xml b/pam/pam_gnome_keyring.8.xml new file mode 100644 index 0000000..d4679a4 --- /dev/null +++ b/pam/pam_gnome_keyring.8.xml @@ -0,0 +1,268 @@ + + + + + + + pam_gnome_keyring + 8 + Gnome Keyring PAM Module Manual + + + + pam_gnome_keyring + automatic unlocking of Gnome Keyring + + + + + pam_gnome_keyring.so + + + + + + DESCRIPTION + + + The Gnome Keyring service module for PAM provides functionality for three + PAM categories: authentication, session management and password + management. In terms of module-type parameter, they are auth, session and + password. + + + + + Authentication Module + + + Gnome Keyring authentication module retrieves password obtained by + previous module in PAM stack and stores it for later use. When no + password was obtained this module does nothing and returns success. It + will never prompt for password by itself. Unless otherwise noted, this + module returns success. + + + + The following options may be passed to authentication module: + + + + + + + + + + Gnome Keyring daemon is started if not already running and login + keyring unlocked using provided password. If any of this fail, + this module returns error. + + + + + + + + + + + Comma separated list of services (eg. gdm,xdm) this module will + handle. If a service is not in this list, module returns success + without doing anything. + + + + + + + + + + Session Management Module + + + The Gnome Keyring session management module provides functions to + initiate and terminate sessions. If Gnome Keyring daemon is not running + or no password was stored by authentication module, this module returns + success. Otherwise it will attempt to unlock login keyring. If + unlocking fails, this module will return error. When session is + terminated and daemon was started in either module, then that daemon + will be terminated. + + + + The following options may be passed to session management module: + + + + + + + + + + Same as in authentication. Please note that either authentication + or session management module must have option auto_start for + Gnome Keyring daemon to be started. + + + + + + + + + + + List of services to handle. + + + + + + + + + + Password Management Module + + + The Gnome Keyring password module allows changing password for login + keyring. If no old password was obtained by previous module in the stack, this + module is ignored. On the other hand, when no new password was obtained, this + module will prompt for one. Gnome Keyring daemon will be started if not already + running and stopped after concluding operation if it was not running before. + + + + The following options may be passed to password management module: + + + + + + + + + + Keep daemon running even when started by this module. + + + + + + + + + + + List of services to handle. + + + + + + + + + + + Do not prompt for new password. If not provided, return error. + + + + + + + + + + + FILES + + + + + $HOME/.local/share/keyrings/login.keyring + + + + Encrypted login keyring. + + + + + + + + + + EXAMPLES + + + The following example of file /etc/pam.d/gdm configures gdm service to + use standard UNIX authentication, as well as start and unlock Gnome + Keyring. Rest of configuration is inherited from login service + configuration. + + + +auth required pam_unix.so +auth optional pam_gnome_keyring.so +account include login +session include login +session optional pam_gnome_keyring.so auto_start +password include login + + + + The following example of file /etc/pam.d/passwd configures passwd program + to update keyring password along with user's system password: + + + +password required pam_unix.so +password optional pam_gnome_keyring.so + + + + + + NOTES + + Gnome Keyring implements its own SSH agent, therefore you should not stack + it with pam_ssh for session management. + + + + + SEE ALSO + + + pam.conf5 + , + + pam.d5 + , + + pam8 + , + + auditctl8 + , + + auditd8 + + + + + + AUTHOR + + pam_gnome_keyring was written by Stef Walter <stef@thewalter.net> + + + +