1PAM(3)                User Contributed Perl Documentation               PAM(3)
2
3
4

NAME

6       Authen::PAM - Perl interface to PAM library
7

SYNOPSIS

9         use Authen::PAM;
10
11         $res = pam_start($service_name, $pamh);
12         $res = pam_start($service_name, $user, $pamh);
13         $res = pam_start($service_name, $user, \&my_conv_func, $pamh);
14         $res = pam_end($pamh, $pam_status);
15
16         $res = pam_authenticate($pamh, $flags);
17         $res = pam_setcred($pamh, $flags);
18         $res = pam_acct_mgmt($pamh, $flags);
19         $res = pam_open_session($pamh, $flags);
20         $res = pam_close_session($pamh, $flags);
21         $res = pam_chauthtok($pamh, $flags);
22
23         $error_str = pam_strerror($pamh, $errnum);
24
25         $res = pam_set_item($pamh, $item_type, $item);
26         $res = pam_get_item($pamh, $item_type, $item);
27
28         if (HAVE_PAM_ENV_FUNCTIONS()) {
29             $res = pam_putenv($pamh, $name_value);
30             $val = pam_getenv($pamh, $name);
31             %env = pam_getenvlist($pamh);
32         }
33
34         if (HAVE_PAM_FAIL_DELAY()) {
35             $res = pam_fail_delay($pamh, $musec_delay);
36             $res = pam_set_item($pamh, PAM_FAIL_DELAY(), \&my_fail_delay_func);
37         }
38

DESCRIPTION

40       The Authen::PAM module provides a Perl interface to the PAM library.
41       The only difference with the standard PAM interface is that instead of
42       passing a pam_conv struct which has an additional context parameter
43       appdata_ptr, you must only give an address to a conversation function
44       written in Perl (see below).
45
46       If you want to pass a NULL pointer as a value of the $user in pam_start
47       use undef or the two-argument version. Both in the two and the three-
48       argument versions of pam_start a default conversation function is used
49       (Authen::PAM::pam_default_conv).
50
51       The $flags argument is optional for all functions which use it except
52       for pam_setcred. The $pam_status argument is also optional for pam_end
53       function. Both of these arguments will be set to 0 if not given.
54
55       The names of some constants from the PAM library have changed over the
56       time. You can use any of the known names for a given constant although
57       it is advisable to use the latest one.
58
59       When this module supports some of the additional features of the PAM
60       library (e.g. pam_fail_delay) then the corresponding HAVE_PAM_XXX
61       constant will have a value 1 otherwise it will return 0.
62
63       For compatibility with older PAM libraries I have added the constant
64       HAVE_PAM_ENV_FUNCTIONS which is true if your PAM library has the
65       functions for handling environment variables (pam_putenv, pam_getenv,
66       pam_getenvlist).
67
68   Object Oriented Style
69       If you prefer to use an object oriented style for accessing the PAM
70       library here is the interface:
71
72         use Authen::PAM qw(:constants);
73
74         $pamh = new Authen::PAM($service_name);
75         $pamh = new Authen::PAM($service_name, $user);
76         $pamh = new Authen::PAM($service_name, $user, \&my_conv_func);
77
78         ref($pamh) || die "Error code $pamh during PAM init!";
79
80         $res = $pamh->pam_authenticate($flags);
81         $res = $pamh->pam_setcred($flags);
82         $res = $pamh->pam_acct_mgmt($flags);
83         $res = $pamh->pam_open_session($flags);
84         $res = $pamh->pam_close_session($flags);
85         $res = $pamh->pam_chauthtok($flags);
86
87         $error_str = $pamh->pam_strerror($errnum);
88
89         $res = $pamh->pam_set_item($item_type, $item);
90         $res = $pamh->pam_get_item($item_type, $item);
91
92         $res = $pamh->pam_putenv($name_value);
93         $val = $pamh->pam_getenv($name);
94         %env = $pamh->pam_getenvlist;
95
96       The constructor new will call the pam_start function and if successfull
97       will return an object reference. Otherwise the $pamh will contain the
98       error number returned by pam_start.  The pam_end function will be
99       called automatically when the object is no longer referenced.
100
101   Examples
102       Here is an example of using PAM for changing the password of the
103       current user:
104
105         use Authen::PAM;
106
107         $login_name = getpwuid($<);
108
109         pam_start("passwd", $login_name, $pamh);
110         pam_chauthtok($pamh);
111         pam_end($pamh);
112
113       or the same thing but using OO style:
114
115         $pamh = new Authen::PAM("passwd", $login_name);
116         $pamh->pam_chauthtok;
117         $pamh = 0;  # Force perl to call the destructor for the $pamh
118
119   Conversation function format
120       When starting the PAM the user must supply a conversation function.  It
121       is used for interaction between the PAM modules and the user. The
122       argument of the function is a list of pairs ($msg_type, $msg) and it
123       must return a list with the same number of pairs ($resp_retcode, $resp)
124       with replies to the input messages. For now the $resp_retcode is not
125       used and must be always set to 0. In addition the user must append to
126       the end of the resulting list the return code of the conversation
127       function (usually PAM_SUCCESS). If you want to abort the conversation
128       function for some reason then just return an error code, normally
129       PAM_CONV_ERR.
130
131       Here is a sample form of the PAM conversation function:
132
133         sub my_conv_func {
134             my @res;
135             while ( @_ ) {
136                 my $msg_type = shift;
137                 my $msg = shift;
138
139                 print $msg;
140
141                # switch ($msg_type) { obtain value for $ans; }
142
143                push @res, (0,$ans);
144             }
145             push @res, PAM_SUCCESS();
146             return @res;
147         }
148
149       More examples can be found in the Authen::PAM:FAQ.
150

COMPATIBILITY

152       The following constant names: PAM_AUTHTOKEN_REQD, PAM_CRED_ESTABLISH,
153       PAM_CRED_DELETE, PAM_CRED_REINITIALIZE, PAM_CRED_REFRESH are used by
154       some older version of the Linux-PAM library and are not exported by
155       default. If you really want them, load the module with
156
157         use Authen::PAM qw(:DEFAULT :old);
158
159       This module still does not support some of the new Linux-PAM functions
160       such as pam_system_log.
161

SEE ALSO

163       PAM Application developer's Manual, Authen::PAM::FAQ
164

AUTHOR

166       Nikolay Pelov <NIKIP at cpan.org>
167
169       Copyright (c) 1998-2005 Nikolay Pelov. All rights reserved. This
170       program is free software; you can redistribute it and/or modify it
171       under the same terms as Perl itself.
172
173
174
175perl v5.36.0                      2023-01-20                            PAM(3)
Impressum