blob: 9b370f52fba6fed9e8df8724988d244fee529203 (
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
|
<?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_start'>
<refmeta>
<refentrytitle>pam_start</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv id="pam_start-name">
<refname>pam_start</refname>
<refpurpose>initialization of PAM transaction</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis id="pam_start-synopsis">
<funcsynopsisinfo>#include <security/pam_appl.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_start</function></funcdef>
<paramdef>const char *<parameter>service_name</parameter></paramdef>
<paramdef>const char *<parameter>user</parameter></paramdef>
<paramdef>const struct pam_conv *<parameter>pam_conversation</parameter></paramdef>
<paramdef>pam_handle_t **<parameter>pamh</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="pam_start-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_start</function> function creates the PAM context
and initiates the PAM transaction. It is the first of the PAM
functions that needs to be called by an application. The transaction
state is contained entirely within the structure identified by this
handle, so it is possible to have multiple transactions in parallel.
But it is not possible to use the same handle for different
transactions, a new one is needed for every new context.
</para>
<para>
The <emphasis>service_name</emphasis> argument specifies the name
of the service to apply and will be stored as PAM_SERVICE item in
the new context. The policy for the service will be read from the
file <filename>/etc/pam.d/service_name</filename> or, if that file
does not exist, from <filename>/etc/pam.conf</filename>.
</para>
<para>
The <emphasis>user</emphasis> argument can specify the name
of the target user and will be stored as PAM_USER item. If
the argument is NULL, the module has to ask for this item if
necessary.
</para>
<para>
The <emphasis>pam_conversation</emphasis> argument points to
a <emphasis>struct pam_conv</emphasis> describing the
conversation function to use. An application must provide this
for direct communication between a loaded module and the
application.
</para>
<para>
Following a successful return (PAM_SUCCESS) the contents of
<emphasis>pamh</emphasis> is a handle that contains the PAM
context for successive calls to the PAM functions. In an error
case is the content of <emphasis>pamh</emphasis> undefined.
</para>
<para>
The <emphasis>pam_handle_t</emphasis> is a blind structure and
the application should not attempt to probe it directly for
information. Instead the PAM library provides the functions
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> and
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
The PAM handle cannot be used for mulitiple authentications at the
same time as long as <function>pam_end</function> was not called on
it before.
</para>
</refsect1>
<refsect1 id="pam_start-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_ABORT</term>
<listitem>
<para>
General failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Transaction was successful created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
System error, for example a NULL pointer was submitted
instead of a pointer to data.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="pam_start-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
|
