1#This is a dummy file so CPAN will find a VERSION
2package Authen::PAM;
3$VERSION = "0.16";
4#This is to make sure require will return an error
50;
6__END__
7
8=head1 NAME
9
10Authen::PAM - Perl interface to PAM library
11
12=head1 SYNOPSIS
13
14  use Authen::PAM;
15
16  $res = pam_start($service_name, $pamh);
17  $res = pam_start($service_name, $user, $pamh);
18  $res = pam_start($service_name, $user, \&my_conv_func, $pamh);
19  $res = pam_end($pamh, $pam_status);
20
21  $res = pam_authenticate($pamh, $flags);
22  $res = pam_setcred($pamh, $flags);
23  $res = pam_acct_mgmt($pamh, $flags);
24  $res = pam_open_session($pamh, $flags);
25  $res = pam_close_session($pamh, $flags);
26  $res = pam_chauthtok($pamh, $flags);
27
28  $error_str = pam_strerror($pamh, $errnum);
29
30  $res = pam_set_item($pamh, $item_type, $item);
31  $res = pam_get_item($pamh, $item_type, $item);
32
33  if (HAVE_PAM_ENV_FUNCTIONS()) {
34      $res = pam_putenv($pamh, $name_value);
35      $val = pam_getenv($pamh, $name);
36      %env = pam_getenvlist($pamh);
37  }
38
39  if (HAVE_PAM_FAIL_DELAY()) {
40      $res = pam_fail_delay($pamh, $musec_delay);
41      $res = pam_set_item($pamh, PAM_FAIL_DELAY(), \&my_fail_delay_func);
42  }
43
44=head1 DESCRIPTION
45
46The I<Authen::PAM> module provides a Perl interface to the I<PAM>
47library. The only difference with the standard PAM interface is that
48instead of passing a pam_conv struct which has an additional context
49parameter appdata_ptr, you must only give an address to a conversation
50function written in Perl (see below).
51
52If you want to pass a NULL pointer as a value of the $user in
53pam_start use undef or the two-argument version. Both in the two and
54the three-argument versions of pam_start a default conversation
55function is used (Authen::PAM::pam_default_conv).
56
57The $flags argument is optional for all functions which use it
58except for pam_setcred. The $pam_status argument is also optional for
59pam_end function. Both of these arguments will be set to 0 if not given.
60
61The names of some constants from the PAM library have changed over the
62time. You can use any of the known names for a given constant although
63it is advisable to use the latest one.
64
65When this module supports some of the additional features of the PAM
66library (e.g. pam_fail_delay) then the corresponding HAVE_PAM_XXX
67constant will have a value 1 otherwise it will return 0.
68
69For compatibility with older PAM libraries I have added the constant
70HAVE_PAM_ENV_FUNCTIONS which is true if your PAM library has the
71functions for handling environment variables (pam_putenv, pam_getenv,
72pam_getenvlist).
73
74
75=head2 Object Oriented Style
76
77If you prefer to use an object oriented style for accessing the PAM
78library here is the interface:
79
80  use Authen::PAM qw(:constants);
81
82  $pamh = new Authen::PAM($service_name);
83  $pamh = new Authen::PAM($service_name, $user);
84  $pamh = new Authen::PAM($service_name, $user, \&my_conv_func);
85
86  ref($pamh) || die "Error code $pamh during PAM init!";
87
88  $res = $pamh->pam_authenticate($flags);
89  $res = $pamh->pam_setcred($flags);
90  $res = $pamh->pam_acct_mgmt($flags);
91  $res = $pamh->pam_open_session($flags);
92  $res = $pamh->pam_close_session($flags);
93  $res = $pamh->pam_chauthtok($flags);
94
95  $error_str = $pamh->pam_strerror($errnum);
96
97  $res = $pamh->pam_set_item($item_type, $item);
98  $res = $pamh->pam_get_item($item_type, $item);
99
100  $res = $pamh->pam_putenv($name_value);
101  $val = $pamh->pam_getenv($name);
102  %env = $pamh->pam_getenvlist;
103
104The constructor new will call the pam_start function and if successfull
105will return an object reference. Otherwise the $pamh will contain the
106error number returned by pam_start.
107The pam_end function will be called automatically when the object is no
108longer referenced.
109
110=head2 Examples
111
112Here is an example of using PAM for changing the password of the current
113user:
114
115  use Authen::PAM;
116
117  $login_name = getpwuid($<);
118
119  pam_start("passwd", $login_name, $pamh);
120  pam_chauthtok($pamh);
121  pam_end($pamh);
122
123
124or the same thing but using OO style:
125
126  $pamh = new Authen::PAM("passwd", $login_name);
127  $pamh->pam_chauthtok;
128  $pamh = 0;  # Force perl to call the destructor for the $pamh
129
130=head2 Conversation function format
131
132When starting the PAM the user must supply a conversation function.
133It is used for interaction between the PAM modules and the user. The
134argument of the function is a list of pairs ($msg_type, $msg) and it
135must return a list with the same number of pairs ($resp_retcode,
136$resp) with replies to the input messages. For now the $resp_retcode
137is not used and must be always set to 0. In addition the user must
138append to the end of the resulting list the return code of the
139conversation function (usually PAM_SUCCESS). If you want to abort
140the conversation function for some reason then just return an error
141code, normally PAM_CONV_ERR.
142
143Here is a sample form of the PAM conversation function:
144
145  sub my_conv_func {
146      my @res;
147      while ( @_ ) {
148          my $msg_type = shift;
149          my $msg = shift;
150
151          print $msg;
152
153	 # switch ($msg_type) { obtain value for $ans; }
154
155         push @res, (0,$ans);
156      }
157      push @res, PAM_SUCCESS();
158      return @res;
159  }
160
161More examples can be found in the L<Authen::PAM:FAQ>.
162
163=head1 COMPATIBILITY
164
165The following constant names: PAM_AUTHTOKEN_REQD, PAM_CRED_ESTABLISH,
166PAM_CRED_DELETE, PAM_CRED_REINITIALIZE, PAM_CRED_REFRESH are used by
167some older version of the Linux-PAM library and are not exported by
168default. If you really want them, load the module with
169
170  use Authen::PAM qw(:DEFAULT :old);
171
172This module still does not support some of the new Linux-PAM
173functions such as pam_system_log.
174
175=head1 SEE ALSO
176
177PAM Application developer's Manual,
178L<Authen::PAM::FAQ>
179
180=head1 AUTHOR
181
182Nikolay Pelov <NIKIP at cpan.org>
183
184=head1 COPYRIGHT
185
186Copyright (c) 1998-2005 Nikolay Pelov. All rights reserved. This
187program is free software; you can redistribute it and/or modify it
188under the same terms as Perl itself.
189
190=cut
191