---
name: "Authen::PAM"
section: "3pm"
platform: "linux"
package: "libauthen-pam-perl"
version: "0.16-6+b4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Authen::PAM"
---

# Authen::PAM(3pm)

Perl interface to PAM library

## NAME

Authen::PAM - Perl interface to PAM library

## SYNOPSIS

```
  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

The *Authen::PAM* module provides a Perl interface to the *PAM* library. The only difference with the standard 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).

If you want to pass a NULL pointer as a value of the `$user` in pam\_start use undef or the two-argument version. Both in the two and the three-argument versions of pam\_start a default conversation function is used (Authen::PAM::pam\_default\_conv).

The `$flags` argument is optional for all functions which use it except for pam\_setcred. The `$pam_status` argument is also optional for pam\_end function. Both of these arguments will be set to 0 if not given.

The names of some constants from the PAM library have changed over the time. You can use any of the known names for a given constant although it is advisable to use the latest one.

When this module supports some of the additional features of the PAM library (e.g. pam\_fail\_delay) then the corresponding HAVE\_PAM\_XXX constant will have a value 1 otherwise it will return 0.

For compatibility with older PAM libraries I have added the constant HAVE\_PAM\_ENV\_FUNCTIONS which is true if your PAM library has the functions for handling environment variables (pam\_putenv, pam\_getenv, pam\_getenvlist).

### Object Oriented Style

If you prefer to use an object oriented style for accessing the PAM library here is the interface:

```
  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;
```

The constructor new will call the pam\_start function and if successfull will return an object reference. Otherwise the `$pamh` will contain the error number returned by pam\_start. The pam\_end function will be called automatically when the object is no longer referenced.

### Examples

Here is an example of using PAM for changing 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 the same thing but using 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 starting the PAM the user must supply a conversation function. It is used for interaction between the PAM modules and the user. The argument of the function is a list of pairs ($msg\_type, `$msg`) and it 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 (usually PAM\_SUCCESS). If you want to abort the conversation function for some reason then just return an error code, normally PAM\_CONV\_ERR.

Here is 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 can be found in the Authen::PAM:FAQ.

## COMPATIBILITY

The following constant names: PAM\_AUTHTOKEN\_REQD, PAM\_CRED\_ESTABLISH, PAM\_CRED\_DELETE, PAM\_CRED\_REINITIALIZE, PAM\_CRED\_REFRESH are used by some older version of the Linux-PAM library and are not exported by default. If you really want them, load the module with

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

This module still does not support some of the new Linux-PAM functions such as pam\_system\_log.

## 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.