summaryrefslogtreecommitdiff
path: root/doc/man/misc_conv.3.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man/misc_conv.3.xml')
-rw-r--r--doc/man/misc_conv.3.xml188
1 files changed, 188 insertions, 0 deletions
diff --git a/doc/man/misc_conv.3.xml b/doc/man/misc_conv.3.xml
new file mode 100644
index 00000000..825dd10c
--- /dev/null
+++ b/doc/man/misc_conv.3.xml
@@ -0,0 +1,188 @@
+<?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 &lt;security/pam_misc.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>void <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 variabls 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 conjuction 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 conjuction 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>
+ libraray, 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>