← Back to branch summary

~ubuntu-branches/ubuntu/natty/pam/natty-security

« back to all changes in this revision

Viewing changes to doc/man/pam_get_authtok.3.xml

  • Committer: Bazaar Package Importer
  • Author(s): Steve Langasek
  • Date: 2009-08-26 00:40:14 UTC
  • mfrom: (1.1.5 upstream)
  • Revision ID: james.westby@ubuntu.com-20090826004014-qsd46mostuyljeqp
Tags: 1.1.0-1ubuntu1
* Merge from Debian, remaining changes:
  - debian/libpam-modules.postinst: Add PATH to /etc/environment if it's not
    present there or in /etc/security/pam_env.conf. (should send to Debian).
  - debian/libpam0g.postinst: only ask questions during update-manager when
    there are non-default services running.
  - debian/patches-applied/series: Ubuntu patches are as below ...
  - debian/patches-applied/ubuntu-no-error-if-missingok: add a new, magic
    module option 'missingok' which will suppress logging of errors by
    libpam if the module is not found.
  - debian/patches-applied/ubuntu-regression_fix_securetty: prompt for
    password on bad username.
  - debian/patches-applied/ubuntu-rlimit_nice_correction: Explicitly
    initialise RLIMIT_NICE rather than relying on the kernel limits.
  - Change Vcs-Bzr to point at the Ubuntu branch.
  - debian/local/common-password, debian/pam-configs/unix: switch from
    "md5" to "sha512" as password crypt default.
  - Make libpam-modules depend on base-files (>= 5.0.0ubuntu6), to ensure
    run-parts does the right thing in /etc/update-motd.d.
  - debian/patches-applied/pam_motd-legal-notice: display the contents of
    /etc/legal once, then set a flag in the user's homedir to prevent showing
    it again.
  - debian/local/common-{auth,account,password}.md5sums: include the
    Ubuntu-specific intrepid,jaunty md5sums for use during the
    common-session-noninteractive upgrade.
* Dropped changes, superseded upstream:
  - debian/patches-applied/ubuntu-fix_standard_types: Use standard u_int8_t
    type rather than __u8.
  - debian/patches-applied/ubuntu-user_defined_environment: Look at
    ~/.pam_environment too, with the same format as
    /etc/security/pam_env.conf.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/man/pam_get_authtok.3.xml
 
1
<?xml version="1.0" encoding="UTF-8"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 
3
                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 
4
 
 
5
<refentry id="pam_get_authtok">
 
6
 
 
7
  <refmeta>
 
8
    <refentrytitle>pam_get_authtok</refentrytitle>
 
9
    <manvolnum>3</manvolnum>
 
10
    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
 
11
  </refmeta>
 
12
 
 
13
  <refnamediv id="pam_get_authtok-name">
 
14
    <refname>pam_get_authtok</refname>
 
15
    <refpurpose>get authentication token</refpurpose>
 
16
  </refnamediv>
 
17
 
 
18
<!-- body begins here -->
 
19
 
 
20
  <refsynopsisdiv id="pam_get_authtok-synopsis">
 
21
    <funcsynopsis>
 
22
      <funcsynopsisinfo>#include &lt;security/pam_ext.h&gt;</funcsynopsisinfo>
 
23
      <funcprototype>
 
24
        <funcdef>int <function>pam_get_authtok</function></funcdef>
 
25
        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
 
26
        <paramdef>int <parameter>item</parameter></paramdef>
 
27
        <paramdef>const char **<parameter>authtok</parameter></paramdef>
 
28
        <paramdef>const char *<parameter>prompt</parameter></paramdef>
 
29
      </funcprototype>
 
30
    </funcsynopsis>
 
31
  </refsynopsisdiv>
 
32
 
 
33
  <refsect1 id='pam_get_authtok-description'>
 
34
    <title>DESCRIPTION</title>
 
35
    <para>
 
36
      The <function>pam_get_authtok</function> function returns the
 
37
      cached authentication token, or prompts the user if no token is
 
38
      currently cached. It is intended for internal use by Linux-PAM and
 
39
      PAM service modules. Upon successful return,
 
40
      <emphasis>authtok</emphasis> contains a pointer to the value of the
 
41
      authentication token. Note, this is a pointer to the
 
42
      <emphasis>actual</emphasis> data and should
 
43
      <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
 
44
      over-written!
 
45
    </para>
 
46
    <para>
 
47
      The <emphasis>prompt</emphasis> argument specifies a prompt to use
 
48
      if no token is cached. If a NULL pointer
 
49
      is given, <function>pam_get_authtok</function> uses pre-defined prompts.
 
50
    </para>
 
51
    <para>
 
52
      The following values are supported for <emphasis>item</emphasis>:
 
53
    </para>
 
54
    <variablelist>
 
55
      <varlistentry>
 
56
        <term>PAM_AUTHTOK</term>
 
57
        <listitem>
 
58
          <para>
 
59
            Returns the current authentication token. Called from
 
60
            <citerefentry><refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
 
61
            </citerefentry> <function>pam_get_authtok</function> will
 
62
            ask the user to confirm the new token by retyping it. If
 
63
            a prompt was specified, "Retype" will be used as prefix.
 
64
          </para>
 
65
        </listitem>
 
66
      </varlistentry>
 
67
      <varlistentry>
 
68
        <term>PAM_OLDAUTHTOK</term>
 
69
        <listitem>
 
70
          <para>
 
71
            Returns the previous authentication token when changing
 
72
            authentication tokens.
 
73
          </para>
 
74
        </listitem>
 
75
      </varlistentry>
 
76
    </variablelist>
 
77
  </refsect1>
 
78
 
 
79
  <refsect1 id="pam_get_authtok-options">
 
80
    <title>OPTIONS</title>
 
81
    <para>
 
82
      <function>pam_get_authtok</function> honours the following module
 
83
      options:
 
84
    </para>
 
85
    <variablelist>
 
86
      <varlistentry>
 
87
        <term>
 
88
          <option>try_first_pass</option>
 
89
        </term>
 
90
        <listitem>
 
91
          <para>
 
92
            Before prompting the user for their password, the module first
 
93
            tries the previous stacked module's password in case that
 
94
            satisfies this module as well.
 
95
          </para>
 
96
        </listitem>
 
97
      </varlistentry>
 
98
      <varlistentry>
 
99
        <term>
 
100
          <option>use_first_pass</option>
 
101
        </term>
 
102
        <listitem>
 
103
          <para>
 
104
            The argument <option>use_first_pass</option> forces the module
 
105
            to use a previous stacked modules password and will never prompt
 
106
            the user - if no password is available or the password is not
 
107
            appropriate, the user will be denied access.
 
108
          </para>
 
109
        </listitem>
 
110
      </varlistentry>
 
111
       <varlistentry>
 
112
        <term>
 
113
          <option>use_authtok</option>
 
114
        </term>
 
115
        <listitem>
 
116
          <para>
 
117
            When password changing enforce the module to set the new
 
118
            token to the one provided by a previously stacked
 
119
            <option>password</option> module. If no token is available
 
120
            token changing will fail.
 
121
          </para>
 
122
        </listitem>
 
123
      </varlistentry>
 
124
      <varlistentry>
 
125
        <term>
 
126
          <option>authtok_type=<replaceable>XXX</replaceable></option>
 
127
        </term>
 
128
        <listitem>
 
129
          <para>
 
130
            The default action is for the module to use the
 
131
            following prompts when requesting passwords:
 
132
            "New UNIX password: " and "Retype UNIX password: ".
 
133
            The example word <emphasis>UNIX</emphasis> can
 
134
            be replaced with this option, by default it is empty.
 
135
          </para>
 
136
        </listitem>
 
137
      </varlistentry>
 
138
    </variablelist>
 
139
  </refsect1>
 
140
 
 
141
 
 
142
  <refsect1 id="pam_get_authtok-return_values">
 
143
    <title>RETURN VALUES</title>
 
144
    <variablelist>
 
145
      <varlistentry>
 
146
        <term>PAM_AUTH_ERR</term>
 
147
        <listitem>
 
148
           <para>
 
149
             Authentication token could not be retrieved.
 
150
          </para>
 
151
        </listitem>
 
152
      </varlistentry>
 
153
      <varlistentry>
 
154
        <term>PAM_AUTHTOK_ERR</term>
 
155
        <listitem>
 
156
           <para>
 
157
             New authentication could not be retrieved.
 
158
          </para>
 
159
        </listitem>
 
160
      </varlistentry>
 
161
      <varlistentry>
 
162
        <term>PAM_SUCCESS</term>
 
163
        <listitem>
 
164
           <para>
 
165
             Authentication token was successful retrieved.
 
166
          </para>
 
167
        </listitem>
 
168
      </varlistentry>
 
169
      <varlistentry>
 
170
        <term>PAM_SYSTEM_ERR</term>
 
171
        <listitem>
 
172
           <para>
 
173
             No space for an authentication token was provided.
 
174
          </para>
 
175
        </listitem>
 
176
      </varlistentry>
 
177
      <varlistentry>
 
178
        <term>PAM_TRY_AGAIN</term>
 
179
        <listitem>
 
180
           <para>
 
181
             New authentication tokens mismatch.
 
182
          </para>
 
183
        </listitem>
 
184
      </varlistentry>
 
185
    </variablelist>
 
186
  </refsect1>
 
187
 
 
188
  <refsect1 id='pam_get_authtok-see_also'>
 
189
    <title>SEE ALSO</title>
 
190
    <para>
 
191
      <citerefentry>
 
192
        <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 
193
      </citerefentry>
 
194
    </para>
 
195
  </refsect1>
 
196
 
 
197
  <refsect1 id='pam_get_authtok-standards'>
 
198
    <title>STANDARDS</title>
 
199
    <para>
 
200
      The <function>pam_get_authtok</function> function is a Linux-PAM
 
201
      extensions.
 
202
    </para>
 
203
  </refsect1>
 
204
 
 
205
</refentry>