commit aca880acf4549a348ecb4fc6754ed30366b5b571 Author: Dominique Leuenberger Date: Mon Mar 3 16:07:34 2025 +0100 HACK: Add pam_gnome_keyring manpage diff --git a/docs/meson.build b/docs/meson.build index 8b2e6ab..acd2b7f 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -6,6 +6,10 @@ if get_option('manpage') 'gnome-keyring.xml', ] + xml_8_manfiles = [ + 'pam_gnome_keyring.xml', + ] + xsltproc = find_program('xsltproc') foreach xml_man : xml_manfiles custom_target('manpage-@0@'.format(xml_man), @@ -27,4 +31,25 @@ if get_option('manpage') ] ) endforeach + + foreach xml_man : xml_8_manfiles + custom_target('manpage-@0@'.format(xml_man), + input: xml_man, + output: '@BASENAME@.8', + install: true, + install_dir: get_option('mandir') / 'man8', + command: [ + xsltproc, + '--nonet', + '--stringparam', 'man.output.quietly', '1', + '--stringparam', 'funcsynopsis.style', 'ansi', + '--stringparam', 'man.th.extra1.suppress', '1', + '--stringparam', 'man.authors.section.enabled', '0', + '--stringparam', 'man.copyright.section.enabled', '0', + '-o', '@OUTPUT@', + 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl', + '@INPUT@' + ] + ) + endforeach endif 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 + 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> + + + +