diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/man/.cvsignore | 1 | ||||
| -rw-r--r-- | doc/man/Makefile.am | 8 | ||||
| -rw-r--r-- | doc/man/pam_get_authtok.3.xml | 191 |
3 files changed, 196 insertions, 4 deletions
diff --git a/doc/man/.cvsignore b/doc/man/.cvsignore index d1987738..cc2afe9b 100644 --- a/doc/man/.cvsignore +++ b/doc/man/.cvsignore @@ -18,6 +18,7 @@ pam_fail_delay.3 pam_get_data.3 pam_getenv.3 pam_getenvlist.3 +pam_get_authtok.3 pam_get_item.3 pam_get_user.3 pam_info.3 diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 52e5caab..9b229b16 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -12,8 +12,8 @@ man_MANS = pam.3 PAM.8 pam.8 pam.conf.5 pam.d.5 \ pam_chauthtok.3 pam_close_session.3 pam_conv.3 \ pam_end.3 pam_error.3 \ pam_fail_delay.3 pam_xauth_data.3 \ - pam_get_data.3 pam_get_item.3 pam_get_user.3 pam_getenv.3 \ - pam_getenvlist.3 \ + pam_get_authtok.3 pam_get_data.3 pam_get_item.3 pam_get_user.3 \ + pam_getenv.3 pam_getenvlist.3 \ pam_info.3 \ pam_open_session.3 \ pam_prompt.3 pam_putenv.3 \ @@ -29,8 +29,8 @@ XMLS = pam.3.xml pam.8.xml \ pam_chauthtok.3.xml pam_close_session.3.xml pam_conv.3.xml \ pam_end.3.xml pam_error.3.xml \ pam_fail_delay.3.xml pam_xauth_data.3 \ - pam_get_data.3.xml pam_get_item.3.xml pam_get_user.3.xml \ - pam_getenv.3.xml pam_getenvlist.3.xml \ + pam_get_authtok.3.xml pam_get_data.3.xml pam_get_item.3.xml \ + pam_get_user.3.xml pam_getenv.3.xml pam_getenvlist.3.xml \ pam_info.3.xml \ pam_open_session.3.xml \ pam_prompt.3.xml pam_putenv.3.xml \ diff --git a/doc/man/pam_get_authtok.3.xml b/doc/man/pam_get_authtok.3.xml new file mode 100644 index 00000000..bac30be9 --- /dev/null +++ b/doc/man/pam_get_authtok.3.xml @@ -0,0 +1,191 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="pam_get_authtok"> + + <refmeta> + <refentrytitle>pam_get_authtok</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo> + </refmeta> + + <refnamediv id="pam_get_authtok-name"> + <refname>pam_get_authtok</refname> + <refpurpose>get authentication token</refpurpose> + </refnamediv> + +<!-- body begins here --> + + <refsynopsisdiv id="pam_get_authtok-synopsis"> + <funcsynopsis> + <funcsynopsisinfo>#include <security/pam_ext.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>pam_get_authtok</function></funcdef> + <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef> + <paramdef>int <parameter>item</parameter></paramdef> + <paramdef>const char **<parameter>authtok</parameter></paramdef> + <paramdef>const char *<parameter>prompt</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1 id='pam_get_authtok-description'> + <title>DESCRIPTION</title> + <para> + The <function>pam_get_authtok</function> function returns the + cached authentication token, or prompts the user if no token is + currently cached. It is intended for internal use by Linux-PAM and + PAM service modules. Upon successful return, + <emphasis>authtok</emphasis> contains a pointer to the value of the + authentication token. Note, this is a pointer to the + <emphasis>actual</emphasis> data and should + <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or + over-written! + </para> + <para> + The <emphasis>prompt</emphasis> argument specifies a prompt to use + if no token is cached. If a NULL pointer + is given, <function>pam_get_authtok</function> uses pre-defined prompts. + </para> + <para> + The following values are supported for <emphasis>item</emphasis>: + </para> + <variablelist> + <varlistentry> + <term>PAM_AUTHTOK</term> + <listitem> + <para> + Returns the current authentication token. Called from + <citerefentry><refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> <function>pam_get_authtok</function> will + ask the user to confirm the new token by retyping it. If + a prompt was specified, "Retype" will be used as prefix. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PAM_OLDAUTHTOK</term> + <listitem> + <para> + Returns the previous authentication token when changing + authentication tokens. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id="pam_get_authtok-options"> + <title>OPTIONS</title> + <para> + <function>pam_get_authtok</function> honours the following module + options: + </para> + <variablelist> + <varlistentry> + <term> + <option>try_first_pass</option> + </term> + <listitem> + <para> + Before prompting the user for their password, the module first + tries the previous stacked module's password in case that + satisfies this module as well. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>use_first_pass</option> + </term> + <listitem> + <para> + The argument <option>use_first_pass</option> forces the module + to use a previous stacked modules password and will never prompt + the user - if no password is available or the password is not + appropriate, the user will be denied access. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>use_authtok</option> + </term> + <listitem> + <para> + When password changing enforce the module to set the new + token to the one provided by a previously stacked + <option>password</option> module. If no token is available + token changing will fail. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1 id="pam_get_authtok-return_values"> + <title>RETURN VALUES</title> + <variablelist> + <varlistentry> + <term>PAM_AUTH_ERR</term> + <listitem> + <para> + Authentication token could not be retrieved. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PAM_AUTHTOK_ERR</term> + <listitem> + <para> + New authentication could not be retrieved. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PAM_SUCCESS</term> + <listitem> + <para> + Authentication token was successful retrieved. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PAM_SYSTEM_ERR</term> + <listitem> + <para> + No space for an authentication token was provided. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PAM_TRY_AGAIN</term> + <listitem> + <para> + New authentication tokens mismatch. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id='pam_get_authtok-see_also'> + <title>SEE ALSO</title> + <para> + <citerefentry> + <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum> + </citerefentry> + </para> + </refsect1> + + <refsect1 id='pam_get_authtok-standards'> + <title>STANDARDS</title> + <para> + The <function>pam_get_authtok</function> function is a Linux-PAM + extensions. + </para> + </refsect1> + +</refentry> |