summaryrefslogtreecommitdiff
path: root/doc/man/pam_get_authtok.3.xml
diff options
context:
space:
mode:
authorSteve Langasek <steve.langasek@ubuntu.com>2019-01-03 17:53:41 -0800
committerSteve Langasek <steve.langasek@ubuntu.com>2019-01-03 18:17:08 -0800
commit212b52cf29c06cc209bc8ac0540dbab1acdf1464 (patch)
tree58da0bf39f5c4122e4a1b4da20fdeea52b97a671 /doc/man/pam_get_authtok.3.xml
parent9c52e721044e7501c3d4567b36d222dc7326224a (diff)
parent56c8282d128fb484ffc77dff73abf42229b291d3 (diff)
New upstream version 1.1.0
Diffstat (limited to 'doc/man/pam_get_authtok.3.xml')
-rw-r--r--doc/man/pam_get_authtok.3.xml205
1 files changed, 205 insertions, 0 deletions
diff --git a/doc/man/pam_get_authtok.3.xml b/doc/man/pam_get_authtok.3.xml
new file mode 100644
index 00000000..4edf69e7
--- /dev/null
+++ b/doc/man/pam_get_authtok.3.xml
@@ -0,0 +1,205 @@
+<?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 &lt;security/pam_ext.h&gt;</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>
+ <varlistentry>
+ <term>
+ <option>authtok_type=<replaceable>XXX</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ The default action is for the module to use the
+ following prompts when requesting passwords:
+ "New UNIX password: " and "Retype UNIX password: ".
+ The example word <emphasis>UNIX</emphasis> can
+ be replaced with this option, by default it is empty.
+ </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>