diff --git a/docs/meson.build b/docs/meson.build index 8b2e6abf..2026128c 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -4,6 +4,7 @@ if get_option('manpage') xml_manfiles = [ 'gnome-keyring-daemon.xml', 'gnome-keyring.xml', + 'pam_gnome_keyring.xml', ] xsltproc = find_program('xsltproc') diff --git a/docs/pam_gnome_keyring.xml b/docs/pam_gnome_keyring.xml new file mode 100644 index 0000000..d4679a4 --- /dev/null +++ b/docs/pam_gnome_keyring.xml @@ -0,0 +1,268 @@ + + + + + + + pam_gnome_keyring + 1 + 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> + + + +