summaryrefslogtreecommitdiff
path: root/doc/man/pam_authenticate.3.xml
blob: 8549ccd42a64d6d51065402891f762fbaa796039 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
<?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_authenticate'>
  <refmeta>
    <refentrytitle>pam_authenticate</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv id="pam_authenticate-name">
    <refname>pam_authenticate</refname>
    <refpurpose>account authentication</refpurpose>
  </refnamediv>

<!-- body begins here -->

  <refsynopsisdiv>
    <funcsynopsis id='pam_authenticate-synopsis'>
      <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
      <funcprototype>
        <funcdef>int <function>pam_authenticate</function></funcdef>
        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
        <paramdef>int <parameter>flags</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>


  <refsect1 id='pam_authenticate-description'>
    <title>DESCRIPTION</title>
    <para>
      The <function>pam_authenticate</function> function is used to
      authenticate the user. The user is required to provide an
      authentication token depending upon the authentication service,
      usually this is a password, but could also be a finger print.
    </para>
    <para>
      The PAM service module may request that the user enter their
      username via the conversation mechanism (see
      <citerefentry>
        <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry> and
      <citerefentry>
        <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>). The name of the authenticated user
       will be present in the PAM item PAM_USER. This item may be
       recovered with a call to
      <citerefentry>
        <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>.
    </para>
    <para>
      The <emphasis>pamh</emphasis> argument is an authentication
      handle obtained by a prior call to pam_start().
      The flags argument is the binary or of zero or more of the
      following values:
    </para>
    <variablelist>
      <varlistentry>
        <term>PAM_SILENT</term>
        <listitem>
           <para>
             Do not emit any messages.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_DISALLOW_NULL_AUTHTOK</term>
        <listitem>
          <para>
            The PAM module service should return PAM_AUTH_ERR
            if the user does not have a registered authentication token.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="pam_authenticate-return_values">
    <title>RETURN VALUES</title>
    <variablelist>
      <varlistentry>
        <term>PAM_ABORT</term>
        <listitem>
          <para>
            The application should exit immediately after calling
            <citerefentry>
              <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
            </citerefentry> first.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_AUTH_ERR</term>
        <listitem>
          <para>
            The user was not authenticated.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_CRED_INSUFFICIENT</term>
        <listitem>
          <para>
            For some reason the application does not have sufficient
            credentials to authenticate the user.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_AUTHINFO_UNVAIL</term>
        <listitem>
          <para>
            The modules were not able to access the authentication
            information. This might be due to a network or hardware
            failure etc.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_MAXTRIES</term>
        <listitem>
          <para>
            One or more of the authentication modules has reached its
            limit of tries authenticating the user. Do not try again.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SUCCESS</term>
        <listitem>
           <para>
             The user was successfully authenticated.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_USER_UNKNOWN</term>
        <listitem>
          <para>
            User unknown to authentication service.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id='pam_authenticate-see_also'>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry>