Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pam(3PAM)		     PAM Library Functions		     pam(3PAM)

NAME
       pam - PAM (Pluggable Authentication Module)

SYNOPSIS
       #include	<security/pam_appl.h>
       cc [ flag... ] file ... -lpam [ library ... ]

DESCRIPTION
       The  PAM	framework, libpam, consists of an interface library and	multi-
       ple authentication  service modules.  The PAM interface library is  the
       layer implementing the  Application Programming Interface ( API ).  The
       authentication service modules are a set	of  dynamically	 loadable  ob-
       jects  invoked  by the PAM API to provide a particular type of user au-
       thentication. PAM gives system administrators the flexibility of	choos-
       ing  any	 authentication	service	available on the system	to perform au-
       thentication. This framework also  allows  new  authentication  service
       modules	to  be plugged in and made available without modifying the ap-
       plications.

   Interface Overview
       The PAM library interface consists of six categories of functions,  the
       names for which all start with the prefix  pam_.

       The  first category contains functions for establishing and terminating
       an    authentication   activity,	  which	  are	pam_start(3PAM)	   and
       pam_end(3PAM). The functions pam_set_data(3PAM) and  pam_get_data(3PAM)
       maintain	module specific	data.  The  functions  pam_set_item(3PAM)  and
       pam_get_item(3PAM)  maintain  state  information. pam_strerror(3PAM) is
       the function that returns error status information.

       The second category contains the	functions that authenticate  an	 indi-
       vidual user and set the credentials of the user,	pam_authenticate(3PAM)
       and pam_setcred(3PAM).

       The third category of  PAM interfaces is	account	management. The	 func-
       tion  pam_acct_mgmt(3PAM) checks	for password aging and access-hour re-
       strictions.

       Category	four contains the functions that  perform  session  management
       after access to the system has been granted. See	pam_open_session(3PAM)
       and pam_close_session(3PAM)

       The fifth category consists of the function that	changes	authentication
       tokens,	pam_chauthtok(3PAM).   An  authentication  token is the	object
       used to verify the identity of the user.	In UNIX, an authentication to-
       ken is a	user's password.

       The sixth category of functions can be used to set values for PAM envi-
       ronment	variables.   See   pam_putenv(3PAM),   pam_getenv(3PAM),   and
       pam_getenvlist(3PAM).

       The  pam_*() interfaces are implemented through the library libpam. For
       each of the categories listed above, excluding categories one and  six,
       dynamically loadable shared modules exist that provides the appropriate
       service layer functionality upon	demand.	The functional entry points in
       the  service layer start	with the  pam_sm_ prefix.
	The only difference between the	pam_sm_*() interfaces and their	corre-
       sponding	pam_ interfaces	is that	all the	pam_sm_*() interfaces  require
       extra  parameters  to  pass service-specific options to the shared mod-
       ules.   Refer to	pam_sm(3PAM) for an overview of	the PAM	service	module
       APIs.

   Stateful Interface
       A  sequence  of	calls sharing a	common set of state information	is re-
       ferred to as an authentication transaction.  An authentication	trans-
       action  begins with a call to pam_start(). pam_start() allocates	space,
       performs	various	initialization activities, and assigns a PAM authenti-
       cation handle to	be used	for subsequent calls to	the library.

       After initiating	an authentication transaction, applications can	invoke
       pam_authenticate()   to	 authenticate	a   particular	  user,	   and
       pam_acct_mgmt()	to  perform  system entry management. For example, the
       application may want to determine if the	user's	password has expired.

       If the user has been successfully authenticated,	the application	 calls
       pam_setcred() to	set any	user credentials associated with the authenti-
       cation  service.	 Within	 one   authentication	transaction   (between
       pam_start()  and	 pam_end()), all calls to the  PAM interface should be
       made with the same authentication handle	returned by pam_start().  This
       is  necessary because certain service modules may store module-specific
       data in a handle	that is	intended for use by other modules.  For	 exam-
       ple,  during  the call to pam_authenticate(), service modules may store
       data in the handle that is intended for use by pam_setcred().

       To perform session management,  applications  call  pam_open_session().
       Specifically, the system	may want to store  the total time for the ses-
       sion. The function pam_close_session() closes the current session.

       When necessary, applications can	call pam_get_item() and	pam_set_item()
       to  access  and to update specific authentication information. Such in-
       formation may include the current username.

       To terminate an	authentication	transaction,  the  application	simply
       calls  pam_end(),  which	frees previously allocated space used to store
       authentication information.

   Application-Authentication Service Interactive Interface
       The authentication service in PAM does not  communicate	directly  with
       the  user; instead it relies on the application to perform all such in-
       teractions. The application passes a pointer to the  function,  conv(),
       along with any associated application data pointers, through a pam_conv
       structure to the	authentication service when it initiates an  authenti-
       cation  transaction,  via  a call to pam_start(). The service will then
       use the function, conv(), to prompt the user for	 data,	 output	 error
       messages,  and  display	text information. Refer	to pam_start(3PAM) for
       more information.

   Stacking Multiple Schemes
       The PAM architecture enables authentication by multiple	authentication
       services	through	stacking. System entry applications, such as login(1),
       stack multiple service modules to authenticate users with multiple  au-
       thentication  services. The order in which authentication service  mod-
       ules are	stacked	is specified in	the configuration file,	pam.conf(4). A
       system  administrator  determines  this	ordering,  and also determines
       whether the same	password can be	used for all authentication services.

   Administrative Interface
       The authentication library, /usr/lib/libpam.so.1, implements the	frame-
       work  interface.	 Various  authentication  services are	implemented by
       their own loadable  modules  whose  paths  are  specified  through  the
       pam.conf(4) file.

RETURN VALUES
       The  PAM	 functions may return one of the following generic values,  or
       one of the values defined in the	specific man pages:

       PAM_SUCCESS
	     The function returned successfully.

       PAM_OPEN_ERR
	     dlopen() failed when dynamically loading a	service	module.

       PAM_SYMBOL_ERR
	     Symbol not	found.

       PAM_SERVICE_ERR
	     Error in service module.

       PAM_SYSTEM_ERR
	     System error.

       PAM_BUF_ERR
	     Memory buffer error.

       PAM_CONV_ERR
	     Conversation failure.

       PAM_PERM_DENIED
	     Permission	denied.

ATTRIBUTES
       See attributes(5) for description of the	following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+

SEE ALSO
       login(1),  pam_authenticate(3PAM),  pam_chauthtok(3PAM),	 pam_open_ses-
       sion(3PAM),    pam_set_item(3PAM),   pam_setcred(3PAM),	 pam_sm(3PAM),
       pam_start(3PAM),	pam_strerror(3PAM), pam.conf(4), attributes(5)

NOTES
       The interfaces in  libpam() are MT-Safe only if each thread within  the
       multithreaded application uses its own  PAM handle.

SunOS 5.9			  13 Oct 1998			     pam(3PAM)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pam&sektion=3pam&manpath=SunOS+5.9>

home | help