PAM(3pm)

💖 NAME 💖

ok so like, Authen::PAM — it's the Perl interface to the PAM library. bestie, that's the whole vibe. (also this is the PAM(3pm) page, from the User Contributed Perl Documentation section, so now you know where you are 🫶)

---

✨ SYNOPSIS ✨

here's the whole menu of what you can call, no gatekeeping:

use Authen::PAM;

$res = pam_start($service_name, $pamh);
$res = pam_start($service_name, $user, $pamh);
$res = pam_start($service_name, $user, \&my_conv_func, $pamh);
$res = pam_end($pamh, $pam_status);

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

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

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

if (HAVE_PAM_ENV_FUNCTIONS()) {
    $res = pam_putenv($pamh, $name_value);
    $val = pam_getenv($pamh, $name);
    %env = pam_getenvlist($pamh);
}

if (HAVE_PAM_FAIL_DELAY()) {
    $res = pam_fail_delay($pamh, $musec_delay);
    $res = pam_set_item($pamh, PAM_FAIL_DELAY(), \&my_fail_delay_func);
}

---

🌸 DESCRIPTION 🌸

okay so the Authen::PAM module gives you a Perl interface to the PAM library, periodt. the only lil glow-up compared to the standard PAM interface is this: instead of handing over a pam_conv struct that has an extra context parameter called appdata_ptr, you just give an address to a conversation function that's written in Perl. that's it. (peep below for the deets 🍓)

if you wanna pass a NULL pointer as the value of the $user in pam_start, use undef or just the two-argument version, easy. both the two-argument and the three-argument flavors of pam_start use a default conversation function — it's Authen::PAM::pam_default_conv, iykyk.

the $flags argument is optional for every function that uses it except for pam_setcred. the $pam_status argument is also optional for the pam_end function. both of these args get set to 0 if you don't give them. slay, defaults.

the names of some constants from the PAM library have changed over the years. you can use any of the known names for a given constant, tho it's lowkey advisable to use the latest one 👑

when this module supports some of the additional features of the PAM library (like pam_fail_delay) then the corresponding HAVE_PAM_XXX constant will have a value of 1. otherwise it returns 0. no in-between, it's giving binary 💅

for compatibility with older PAM libraries, they added the constant HAVE_PAM_ENV_FUNCTIONS, which is true if your PAM library has the functions for handling environment variables — that's pam_putenv, pam_getenv, and pam_getenvlist. iconic of them tbh.

🎀 Object Oriented Style 🎀

if you're more of an object oriented kinda girly, here's that interface, literally:

use Authen::PAM qw(:constants);

$pamh = new Authen::PAM($service_name);
$pamh = new Authen::PAM($service_name, $user);
$pamh = new Authen::PAM($service_name, $user, \&my_conv_func);

ref($pamh) || die "Error code $pamh during PAM init!";

$res = $pamh->pam_authenticate($flags);
$res = $pamh->pam_setcred($flags);
$res = $pamh->pam_acct_mgmt($flags);
$res = $pamh->pam_open_session($flags);
$res = $pamh->pam_close_session($flags);
$res = $pamh->pam_chauthtok($flags);

$error_str = $pamh->pam_strerror($errnum);

$res = $pamh->pam_set_item($item_type, $item);
$res = $pamh->pam_get_item($item_type, $item);

$res = $pamh->pam_putenv($name_value);
$val = $pamh->pam_getenv($name);
%env = $pamh->pam_getenvlist;

so the constructor new will call the pam_start function, and if it's successful it returns an object reference. if it's not successful, the $pamh will hold the error number that pam_start returned. and bestie, the pam_end function gets called automatically once the object is no longer referenced — it cleans up after itself, we love a self-sufficient queen 💅

🦋 Examples 🦋

here's an example of using PAM to change the password of the current user:

use Authen::PAM;

$login_name = getpwuid($<);

pam_start("passwd", $login_name, $pamh);
pam_chauthtok($pamh);
pam_end($pamh);

or like, the same thing but in OO style:

$pamh = new Authen::PAM("passwd", $login_name);
$pamh->pam_chauthtok;
$pamh = 0;  # Force perl to call the destructor for the $pamh

💜 Conversation function format 💜

when you start the PAM, you have to supply a conversation function — no skipping this part, bestie. it's used for the interaction between the PAM modules and the user. the argument of the function is a list of pairs — ($msg_type, $msg) — and it has to return a list with the same number of pairs, ($resp_retcode, $resp), with the replies to the input messages. for now the $resp_retcode is not used and must always be set to 0. also you gotta append to the end of the resulting list the return code of the conversation function (usually PAM_SUCCESS). and if you want to abort the conversation function for some reason, just return an error code, normally PAM_CONV_ERR. simple as that fr fr.

here's a sample form of the PAM conversation function:

sub my_conv_func {
    my @res;
    while ( @_ ) {
        my $msg_type = shift;
        my $msg = shift;

        print $msg;

       # switch ($msg_type) { obtain value for $ans; }

       push @res, (0,$ans);
    }
    push @res, PAM_SUCCESS();
    return @res;
}

more examples live in the Authen::PAM:FAQ, go look, you'll eat them up 🌈

---

🌟 COMPATIBILITY 🌟

these constant names right here: PAM_AUTHTOKEN_REQD, PAM_CRED_ESTABLISH, PAM_CRED_DELETE, PAM_CRED_REINITIALIZE, PAM_CRED_REFRESH — they're used by some older version of the Linux-PAM library and are not exported by default. if you really want them, load the module like this:

use Authen::PAM qw(:DEFAULT :old);

and ngl, this module still does not support some of the new Linux-PAM functions such as pam_system_log. it's a known thing, not me being shady 💀

---

🫶 SEE ALSO 🫶

• PAM Application developer's Manual
• Authen::PAM::FAQ

---

👑 AUTHOR 👑

Nikolay Pelov <NIKIP at cpan.org>

---

🎀 COPYRIGHT 🎀

Copyright (c) 1998-2005 Nikolay Pelov. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay that's the whole page, you made it to the end, so proud of you 🥹 this was PAM(3pm), Perl v5.42.3, dated 2026-08-19 — mwah, go forth and authenticate, bestie 💖✨🦋