commit aca880acf4549a348ecb4fc6754ed30366b5b571
Author: Dominique Leuenberger <dimstar@opensuse.org>
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 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<refentry id="pam_gnome_keyring">
+
+ <refmeta>
+ <refentrytitle>pam_gnome_keyring</refentrytitle>
+ <manvolnum>8</manvolnum>
+ <refmiscinfo class="sectdesc">Gnome Keyring PAM Module Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_gnome_keyring-name">
+ <refname>pam_gnome_keyring</refname>
+ <refpurpose>automatic unlocking of Gnome Keyring</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis id="pam_gnome_keyring-cmdsynopsis">
+ <command>pam_gnome_keyring.so</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="pam_gnome_keyring-description">
+
+ <title>DESCRIPTION</title>
+
+ <para>
+ 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.
+ </para>
+
+ <refsect2 id="pam_gnome_keyring-description-auth">
+
+ <title>Authentication Module</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ The following options may be passed to authentication module:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>auto_start</option>
+ </term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>only_if=service</option>
+ </term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </refsect2>
+
+ <refsect2 id="pam_gnome_keyring-description-session">
+
+ <title>Session Management Module</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ The following options may be passed to session management module:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>auto_start</option>
+ </term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>only_if=service</option>
+ </term>
+ <listitem>
+ <para>
+ List of services to handle.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </refsect2>
+
+ <refsect2 id="pam_gnome_keyring-description-password">
+
+ <title>Password Management Module</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ The following options may be passed to password management module:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>auto_start</option>
+ </term>
+ <listitem>
+ <para>
+ Keep daemon running even when started by this module.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>only_if=service</option>
+ </term>
+ <listitem>
+ <para>
+ List of services to handle.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>use_authtok</option>
+ </term>
+ <listitem>
+ <para>
+ Do not prompt for new password. If not provided, return error.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </refsect2>
+ </refsect1>
+
+ <refsect1 id='pam_gnome_keyring-files'>
+
+ <title>FILES</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ $HOME/.local/share/keyrings/login.keyring
+ </term>
+ <listitem>
+ <para>
+ Encrypted login keyring.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </refsect1>
+
+ <refsect1 id='pam_gnome_keyring-examples'>
+
+ <title>EXAMPLES</title>
+
+ <para>
+ 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.
+ </para>
+
+ <programlisting>
+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
+ </programlisting>
+
+ <para>
+ The following example of file /etc/pam.d/passwd configures passwd program
+ to update keyring password along with user's system password:
+ </para>
+
+ <programlisting>
+password required pam_unix.so
+password optional pam_gnome_keyring.so
+ </programlisting>
+
+ </refsect1>
+
+ <refsect1 id='pam_gnome_keyring-notes'>
+ <title>NOTES</title>
+ <para>
+ Gnome Keyring implements its own SSH agent, therefore you should not stack
+ it with pam_ssh for session management.
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_gnome_keyring-see_also'>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>auditctl</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>auditd</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_gnome_keyring-author'>
+ <title>AUTHOR</title>
+ <para>
+ pam_gnome_keyring was written by Stef Walter <stef@thewalter.net>
+ </para>
+ </refsect1>
+
+</refentry>