185 lines
No EOL
7 KiB
XML
185 lines
No EOL
7 KiB
XML
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="misc_conv">
|
|
|
|
<refmeta>
|
|
<refentrytitle>misc_conv</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
|
|
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv xml:id="misc_conv-name">
|
|
<refname>misc_conv</refname>
|
|
<refpurpose>text based conversation function</refpurpose>
|
|
</refnamediv>
|
|
|
|
<!-- body begins here -->
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis xml:id="misc_conv-synopsis">
|
|
<funcsynopsisinfo>#include <security/pam_misc.h></funcsynopsisinfo>
|
|
<funcprototype>
|
|
<funcdef>int <function>misc_conv</function></funcdef>
|
|
<paramdef>int <parameter>num_msg</parameter></paramdef>
|
|
<paramdef>const struct pam_message **<parameter>msgm</parameter></paramdef>
|
|
<paramdef>struct pam_response **<parameter>response</parameter></paramdef>
|
|
<paramdef>void *<parameter>appdata_ptr</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 xml:id="misc_conv-description">
|
|
<title>DESCRIPTION</title>
|
|
<para>
|
|
The <function>misc_conv</function> function is part of
|
|
<command>libpam_misc</command> and not of the standard
|
|
<command>libpam</command> library. This function will prompt
|
|
the user with the appropriate comments and obtain the appropriate
|
|
inputs as directed by authentication modules.
|
|
</para>
|
|
<para>
|
|
In addition to simply slotting into the appropriate <citerefentry>
|
|
<refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
|
|
</citerefentry>, this function provides some time-out facilities.
|
|
The function exports five variables that can be used by an
|
|
application programmer to limit the amount of time this conversation
|
|
function will spend waiting for the user to type something. The
|
|
five variables are as follows:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>time_t pam_misc_conv_warn_time;</term>
|
|
<listitem>
|
|
<para>
|
|
This variable contains the <emphasis>time</emphasis> (as
|
|
returned by <citerefentry>
|
|
<refentrytitle>time</refentrytitle><manvolnum>2</manvolnum>
|
|
</citerefentry>) that the user should be first warned that
|
|
the clock is ticking. By default it has the value
|
|
<returnvalue>0</returnvalue>, which indicates that no such
|
|
warning will be given. The application may set its value to
|
|
sometime in the future, but this should be done prior to
|
|
passing control to the <emphasis>Linux-PAM</emphasis> library.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>const char *pam_misc_conv_warn_line;</term>
|
|
<listitem>
|
|
<para>
|
|
Used in conjunction with
|
|
<varname>pam_misc_conv_warn_time</varname>, this variable is
|
|
a pointer to the string that will be displayed when it becomes
|
|
time to warn the user that the timeout is approaching. Its
|
|
default value is a translated version of
|
|
<quote>...Time is running out...</quote>, but this can be
|
|
changed by the application prior to passing control to
|
|
<emphasis>Linux-PAM</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>time_t pam_misc_conv_die_time;</term>
|
|
<listitem>
|
|
<para>
|
|
This variable contains the <emphasis>time</emphasis> (as
|
|
returned by <citerefentry>
|
|
<refentrytitle>time</refentrytitle><manvolnum>2</manvolnum>
|
|
</citerefentry>) that the will time out. By default it has
|
|
the value <returnvalue>0</returnvalue>, which indicates that
|
|
the conversation function will not timeout. The application
|
|
may set its value to sometime in the future, but this should
|
|
be done prior to passing control to the
|
|
<emphasis>Linux-PAM</emphasis> library.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>const char *pam_misc_conv_die_line;</term>
|
|
<listitem>
|
|
<para>
|
|
Used in conjunction with
|
|
<varname>pam_misc_conv_die_time</varname>, this variable is
|
|
a pointer to the string that will be displayed when the
|
|
conversation times out. Its default value is a translated
|
|
version of
|
|
<quote>...Sorry, your time is up!</quote>, but this can be
|
|
changed by the application prior to passing control to
|
|
<emphasis>Linux-PAM</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>int pam_misc_conv_died;</term>
|
|
<listitem>
|
|
<para>
|
|
Following a return from the <emphasis>Linux-PAM</emphasis>
|
|
library, the value of this variable indicates whether the
|
|
conversation has timed out. A value of
|
|
<returnvalue>1</returnvalue> indicates the time-out occurred.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
The following two function pointers are available for supporting
|
|
binary prompts in the conversation function. They are optimized
|
|
for the current incarnation of the <command>libpamc</command>
|
|
library and are subject to change.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
int (*pam_binary_handler_fn)(void *appdata, pamc_bp_t *prompt_p);
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This function pointer is initialized to
|
|
<returnvalue>NULL</returnvalue> but can be filled with a
|
|
function that provides machine-machine (hidden) message
|
|
exchange. It is intended for use with hidden authentication
|
|
protocols such as RSA or Diffie-Hellman key exchanges.
|
|
(This is still under development.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
int (*pam_binary_handler_free)(void *appdata, pamc_bp_t *delete_me);
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This function pointer is initialized to
|
|
<function>PAM_BP_RENEW(delete_me, 0, 0)</function>, but can be
|
|
redefined as desired by the application.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1 xml:id="misc_conv-see_also">
|
|
<title>SEE ALSO</title>
|
|
<para>
|
|
<citerefentry>
|
|
<refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
|
|
</citerefentry>,
|
|
<citerefentry>
|
|
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
|
|
</citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 xml:id="misc_conv-standards">
|
|
<title>STANDARDS</title>
|
|
<para>
|
|
The <function>misc_conv</function> function is part of the
|
|
<command>libpam_misc</command> Library and not defined in any
|
|
standard.
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry> |