diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/man/pam_get_authtok.3 | 170 | ||||
| -rw-r--r-- | doc/man/pam_get_authtok.3.xml | 248 |
2 files changed, 418 insertions, 0 deletions
diff --git a/doc/man/pam_get_authtok.3 b/doc/man/pam_get_authtok.3 new file mode 100644 index 0000000..755dd68 --- /dev/null +++ b/doc/man/pam_get_authtok.3 @@ -0,0 +1,170 @@ +'\" t +.\" Title: pam_get_authtok +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> +.\" Date: 09/03/2021 +.\" Manual: Linux-PAM Manual +.\" Source: Linux-PAM Manual +.\" Language: English +.\" +.TH "PAM_GET_AUTHTOK" "3" "09/03/2021" "Linux-PAM Manual" "Linux-PAM Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pam_get_authtok, pam_get_authtok_verify, pam_get_authtok_noverify \- get authentication token +.SH "SYNOPSIS" +.sp +.ft B +.nf +#include <security/pam_ext\&.h> +.fi +.ft +.HP \w'int\ pam_get_authtok('u +.BI "int pam_get_authtok(pam_handle_t\ *" "pamh" ", int\ " "item" ", const\ char\ **" "authtok" ", const\ char\ *" "prompt" ");" +.HP \w'int\ pam_get_authtok_noverify('u +.BI "int pam_get_authtok_noverify(pam_handle_t\ *" "pamh" ", const\ char\ **" "authtok" ", const\ char\ *" "prompt" ");" +.HP \w'int\ pam_get_authtok_verify('u +.BI "int pam_get_authtok_verify(pam_handle_t\ *" "pamh" ", const\ char\ **" "authtok" ", const\ char\ *" "prompt" ");" +.SH "DESCRIPTION" +.PP +The +\fBpam_get_authtok\fR +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, +\fIauthtok\fR +contains a pointer to the value of the authentication token\&. Note, this is a pointer to the +\fIactual\fR +data and should +\fBnot\fR +be +\fIfree()\fR\*(Aqed or over\-written! +.PP +The +\fIprompt\fR +argument specifies a prompt to use if no token is cached\&. If a NULL pointer is given, +\fBpam_get_authtok\fR +uses pre\-defined prompts\&. +.PP +The following values are supported for +\fIitem\fR: +.PP +PAM_AUTHTOK +.RS 4 +Returns the current authentication token\&. Called from +\fBpam_sm_chauthtok\fR(3) +\fBpam_get_authtok\fR +will ask the user to confirm the new token by retyping it\&. If a prompt was specified, "Retype" will be used as prefix\&. +.RE +.PP +PAM_OLDAUTHTOK +.RS 4 +Returns the previous authentication token when changing authentication tokens\&. +.RE +.PP +The +\fBpam_get_authtok_noverify\fR +function can only be used for changing the password (from +\fBpam_sm_chauthtok\fR(3))\&. It returns the cached authentication token, or prompts the user if no token is currently cached\&. The difference to +\fBpam_get_authtok\fR +is, that this function does not ask a second time for the password to verify it\&. Upon successful return, +\fIauthtok\fR +contains a pointer to the value of the authentication token\&. Note, this is a pointer to the +\fIactual\fR +data and should +\fBnot\fR +be +\fIfree()\fR\*(Aqed or over\-written! +.PP +The +\fBpam_get_authtok_verify\fR +function can only be used to verify a password for mistypes gotten by +\fBpam_get_authtok_noverify\fR(3)\&. This function asks a second time for the password and verify it with the password provided by +\fIauthtok\fR +argument\&. In case of an error, the value of +\fIauthtok\fR +is undefined\&. Else this argument will point to the +\fIactual\fR +data and should +\fBnot\fR +be +\fIfree()\fR\*(Aqed or over\-written! +.SH "OPTIONS" +.PP +\fBpam_get_authtok\fR +honours the following module options: +.PP +\fBtry_first_pass\fR +.RS 4 +Before prompting the user for their password, the module first tries the previous stacked module\*(Aqs password in case that satisfies this module as well\&. +.RE +.PP +\fBuse_first_pass\fR +.RS 4 +The argument +\fBuse_first_pass\fR +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\&. +.RE +.PP +\fBuse_authtok\fR +.RS 4 +When password changing enforce the module to set the new token to the one provided by a previously stacked +\fBpassword\fR +module\&. If no token is available token changing will fail\&. +.RE +.PP +\fBauthtok_type=\fR\fB\fIXXX\fR\fR +.RS 4 +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 +\fIUNIX\fR +can be replaced with this option, by default it is empty\&. +.RE +.SH "RETURN VALUES" +.PP +PAM_AUTH_ERR +.RS 4 +Authentication token could not be retrieved\&. +.RE +.PP +PAM_AUTHTOK_ERR +.RS 4 +New authentication could not be retrieved\&. +.RE +.PP +PAM_SUCCESS +.RS 4 +Authentication token was successfully retrieved\&. +.RE +.PP +PAM_SYSTEM_ERR +.RS 4 +No space for an authentication token was provided\&. +.RE +.PP +PAM_TRY_AGAIN +.RS 4 +New authentication tokens mismatch\&. +.RE +.SH "SEE ALSO" +.PP +\fBpam\fR(8) +.SH "STANDARDS" +.PP +The +\fBpam_get_authtok\fR +function is a Linux\-PAM extensions\&. diff --git a/doc/man/pam_get_authtok.3.xml b/doc/man/pam_get_authtok.3.xml new file mode 100644 index 0000000..5d50b16 --- /dev/null +++ b/doc/man/pam_get_authtok.3.xml @@ -0,0 +1,248 @@ +<?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> + <refname>pam_get_authtok_verify</refname> + <refname>pam_get_authtok_noverify</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> + <funcprototype> + <funcdef>int <function>pam_get_authtok_noverify</function></funcdef> + <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef> + <paramdef>const char **<parameter>authtok</parameter></paramdef> + <paramdef>const char *<parameter>prompt</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pam_get_authtok_verify</function></funcdef> + <paramdef>pam_handle_t *<parameter>pamh</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> + <para> + The <function>pam_get_authtok_noverify</function> function can + only be used for changing the password + (from <citerefentry> + <refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>). It returns the cached + authentication token, or prompts the user if no token is + currently cached. The difference to <function>pam_get_authtok</function> + is, that this function does not ask a second time for the password + to verify it. 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 <function>pam_get_authtok_verify</function> function can + only be used to verify a password for mistypes gotten by + <citerefentry> + <refentrytitle>pam_get_authtok_noverify</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. This function asks a second time for the password + and verify it with the password provided by <emphasis>authtok</emphasis> + argument. In case of an error, the value of <emphasis>authtok</emphasis> + is undefined. Else this argument will point to the + <emphasis>actual</emphasis> data and should + <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or + over-written! + </para> + </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 successfully 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> |