.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PAM 3pm"
.TH PAM 3pm "2014-08-15" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Authen::PAM \- Perl interface to PAM library
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Authen::PAM;
\&
\&  $res = pam_start($service_name, $pamh);
\&  $res = pam_start($service_name, $user, $pamh);
\&  $res = pam_start($service_name, $user, \e&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(), \e&my_fail_delay_func);
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fIAuthen::PAM\fR module provides a Perl interface to the \fI\s-1PAM\s0\fR
library. The only difference with the standard \s-1PAM\s0 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).
.PP
If you want to pass a \s-1NULL\s0 pointer as a value of the \f(CW$user\fR 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).
.PP
The \f(CW$flags\fR argument is optional for all functions which use it
except for pam_setcred. The \f(CW$pam_status\fR argument is also optional for
pam_end function. Both of these arguments will be set to 0 if not given.
.PP
The names of some constants from the \s-1PAM\s0 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.
.PP
When this module supports some of the additional features of the \s-1PAM\s0
library (e.g. pam_fail_delay) then the corresponding \s-1HAVE_PAM_XXX\s0
constant will have a value 1 otherwise it will return 0.
.PP
For compatibility with older \s-1PAM\s0 libraries I have added the constant
\&\s-1HAVE_PAM_ENV_FUNCTIONS\s0 which is true if your \s-1PAM\s0 library has the
functions for handling environment variables (pam_putenv, pam_getenv,
pam_getenvlist).
.SS "Object Oriented Style"
.IX Subsection "Object Oriented Style"
If you prefer to use an object oriented style for accessing the \s-1PAM\s0
library here is the interface:
.PP
.Vb 1
\&  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, \e&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;
.Ve
.PP
The constructor new will call the pam_start function and if successfull
will return an object reference. Otherwise the \f(CW$pamh\fR will contain the
error number returned by pam_start.
The pam_end function will be called automatically when the object is no
longer referenced.
.SS "Examples"
.IX Subsection "Examples"
Here is an example of using \s-1PAM\s0 for changing the password of the current
user:
.PP
.Vb 1
\&  use Authen::PAM;
\&
\&  $login_name = getpwuid($<);
\&
\&  pam_start("passwd", $login_name, $pamh);
\&  pam_chauthtok($pamh);
\&  pam_end($pamh);
.Ve
.PP
or the same thing but using \s-1OO\s0 style:
.PP
.Vb 3
\&  $pamh = new Authen::PAM("passwd", $login_name);
\&  $pamh\->pam_chauthtok;
\&  $pamh = 0;  # Force perl to call the destructor for the $pamh
.Ve
.SS "Conversation function format"
.IX Subsection "Conversation function format"
When starting the \s-1PAM\s0 the user must supply a conversation function.
It is used for interaction between the \s-1PAM\s0 modules and the user. The
argument of the function is a list of pairs ($msg_type, \f(CW$msg\fR) and it
must return a list with the same number of pairs ($resp_retcode,
\&\f(CW$resp\fR) with replies to the input messages. For now the \f(CW$resp_retcode\fR
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 \s-1PAM_SUCCESS\s0). If you want to abort
the conversation function for some reason then just return an error
code, normally \s-1PAM_CONV_ERR.\s0
.PP
Here is a sample form of the \s-1PAM\s0 conversation function:
.PP
.Vb 5
\&  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;
\&  }
.Ve
.PP
More examples can be found in the Authen::PAM:FAQ.
.SH "COMPATIBILITY"
.IX Header "COMPATIBILITY"
The following constant names: \s-1PAM_AUTHTOKEN_REQD, PAM_CRED_ESTABLISH,
PAM_CRED_DELETE, PAM_CRED_REINITIALIZE, PAM_CRED_REFRESH\s0 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
.PP
.Vb 1
\&  use Authen::PAM qw(:DEFAULT :old);
.Ve
.PP
This module still does not support some of the new Linux-PAM
functions such as pam_system_log.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1PAM\s0 Application developer's Manual,
Authen::PAM::FAQ
.SH "AUTHOR"
.IX Header "AUTHOR"
Nikolay Pelov <\s-1NIKIP\s0 at cpan.org>
.SH "COPYRIGHT"
.IX Header "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.