mirror of
https://github.com/linux-pam/linux-pam.git
synced 2024-11-28 04:03:40 +08:00
189 lines
7.4 KiB
XML
189 lines
7.4 KiB
XML
<?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="misc_conv">
|
|
|
|
<refmeta>
|
|
<refentrytitle>misc_conv</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
<refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv id="misc_conv-name">
|
|
<refname>misc_conv</refname>
|
|
<refpurpose>text based conversation function</refpurpose>
|
|
</refnamediv>
|
|
|
|
<!-- body begins here -->
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis 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 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><type>time_t</type> <varname>pam_misc_conv_warn_time</varname>;</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><type>const char *</type><varname>pam_misc_conv_warn_line</varname>;</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><type>time_t</type> <varname>pam_misc_conv_die_time</varname>;</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><type>const char *</type><varname>pam_misc_conv_die_line</varname>;</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><type>int</type> <varname>pam_misc_conv_died</varname>;</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>
|
|
<type>int</type> <varname>(*pam_binary_handler_fn)</varname>(<type>void *</type><varname>appdata</varname>, <type>pamc_bp_t *</type><varname>prompt_p</varname>);
|
|
</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>
|
|
<type>int</type> <varname>(*pam_binary_handler_free)</varname>(<type>void *</type><varname>appdata</varname>, <type>pamc_bp_t *</type><varname>delete_me</varname>);
|
|
</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 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 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>
|