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