NAME

Authen::PAM - Perl interface to PAM library

SYNOPSIS

use Authen::PAM;

$retval = pam_start($service_name, $user, $pamh);
$retval = pam_start($service_name, $user, $conv_func, $pamh);
$retval = pam_end($pamh, $pam_status);

$retval = pam_authenticate($pamh, $flags);
$retval = pam_setcred($pamh, $flags);
$retval = pam_acct_mgmt($pamh, $flags);
$retval = pam_open_session($pamh, $flags);
$retval = pam_close_session($pamh, $flags);
$retval = pam_chauthtok($pamh, $flags);

$error_str = pam_strerror($pamh, $errnum);

$retval = pam_set_item($pamh, $item_type, $item);
$retval = pam_get_item($pamh, $item_type, $item);

$retval = pam_putenv($pamh, $name_value);
$val = pam_getenv($pamh, $name);
%env = pam_getenvlist($pamh);

DESCRIPTION

The Authen::PAM module provides a Perl interface to the PAM library. The only difference with the standart PAM interface is that instead of passing a pam_conv struct which has an additional context parameter appdata_ptr, you must only give an address to a conversation function written in Perl (see below). You can pass a context to the conversation function using the Perl function local. If you use the 3 argument version of pam_start then a default conversation function is used (Authen::PAM::pam_default_conv).

Examples

Here is an example of using PAM for changing the password of the current user:

use Authen::PAM;

$login_name = getlogin || getpwuid($<);

pam_start("passwd", $login_name, \&pam_default_conv, $pamh);
pam_chauthtok($pamh, 0);
pam_end($pamh, 0);

Conversation function format

When starting the PAM the user must supply a conversation function. It is used for interaction between the PAM modules and the user. The function takes as arguments a list of pairs ($msg_type, $msg) and must return a list with the same number of pairs ($resp_retcode, $resp) with replies to the input messages. For now the $resp_retcode is not used and must be always set to 0. In addition the user must append to the end of the resulting list the return code of the conversation function (usualy PAM_SUCCESS).

Here is a sample form of the PAM conversation function:

sub pam_conv_func { my @res; while ( @_ ) { my $code = shift; my $msg = shift;

        print $msg;

	# switch ($code) { obtain value for $ans; }
      
        push @res, 0;
        push @res, $ans;
    }
    push @res, PAM_SUCCESS;
    return @res;
}
 

COMPATIBILITY

This module was tested with the following versions of the Linux-PAM library: 0.56, 0.59 and 0.65. This means that it supports the pre 0.58 interface of the PAM functions and constants as well as the latest (0.65) constant definitions.

This module still does not support some of the new Linux-PAM functions such as pam_system_log. This will be added in the near future if necessary.

AUTHOR

Nikolay Pelov <nikip@iname.com>

SEE ALSO

PAM Application developer's Manual