NetBSD-5.0.2/dist/openpam/doc/man/pam.3

.\"	$NetBSD: pam.3,v 1.5 2008/01/27 01:22:56 christos Exp $
.\"
.\"-
.\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
.\" Copyright (c) 2004-2007 Dag-Erling Smørgrav
.\" All rights reserved.
.\"
.\" This software was developed for the FreeBSD Project by ThinkSec AS and
.\" Network Associates Laboratories, the Security Research Division of
.\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
.\" ("CBOSS"), as part of the DARPA CHATS research program.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote
.\"    products derived from this software without specific prior written
.\"    permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $P4$
.\"
.Dd December 21, 2007
.Dt PAM 3
.Os
.Sh NAME
.Nm pam_acct_mgmt ,
.Nm pam_authenticate ,
.Nm pam_chauthtok ,
.Nm pam_close_session ,
.Nm pam_end ,
.Nm pam_get_data ,
.Nm pam_get_item ,
.Nm pam_get_user ,
.Nm pam_getenv ,
.Nm pam_getenvlist ,
.Nm pam_open_session ,
.Nm pam_putenv ,
.Nm pam_set_data ,
.Nm pam_set_item ,
.Nm pam_setcred ,
.Nm pam_start ,
.Nm pam_strerror
.Nd Pluggable Authentication Modules Library
.Sh LIBRARY
.Lb libpam
.Sh SYNOPSIS
.In security/pam_appl.h
.Ft "int"
.Fn pam_acct_mgmt "pam_handle_t *pamh" "int flags"
.Ft "int"
.Fn pam_authenticate "pam_handle_t *pamh" "int flags"
.Ft "int"
.Fn pam_chauthtok "pam_handle_t *pamh" "int flags"
.Ft "int"
.Fn pam_close_session "pam_handle_t *pamh" "int flags"
.Ft "int"
.Fn pam_end "pam_handle_t *pamh" "int status"
.Ft "int"
.Fn pam_get_data "const pam_handle_t *pamh" "const char *module_data_name" "const void **data"
.Ft "int"
.Fn pam_get_item "const pam_handle_t *pamh" "int item_type" "const void **item"
.Ft "int"
.Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt"
.Ft "const char *"
.Fn pam_getenv "pam_handle_t *pamh" "const char *name"
.Ft "char **"
.Fn pam_getenvlist "pam_handle_t *pamh"
.Ft "int"
.Fn pam_open_session "pam_handle_t *pamh" "int flags"
.Ft "int"
.Fn pam_putenv "pam_handle_t *pamh" "const char *namevalue"
.Ft "int"
.Fn pam_set_data "pam_handle_t *pamh" "const char *module_data_name" "void *data" "void (*cleanup)(pam_handle_t *pamh, void *data, int pam_end_status)"
.Ft "int"
.Fn pam_set_item "pam_handle_t *pamh" "int item_type" "const void *item"
.Ft "int"
.Fn pam_setcred "pam_handle_t *pamh" "int flags"
.Ft "int"
.Fn pam_start "const char *service" "const char *user" "const struct pam_conv *pam_conv" "pam_handle_t **pamh"
.Ft "const char *"
.Fn pam_strerror "const pam_handle_t *pamh" "int error_number"
.\"
.\" $Id: pam.3,v 1.5 2008/01/27 01:22:56 christos Exp $
.\"
.Sh DESCRIPTION
The Pluggable Authentication Modules (PAM) library abstracts a number
of common authentication-related operations and provides a framework
for dynamically loaded modules that implement these operations in
various ways.
.Ss Terminology
In PAM parlance, the application that uses PAM to authenticate a user
is the server, and is identified for configuration purposes by a
service name, which is often (but not necessarily) the program name.
.Pp
The user requesting authentication is called the applicant, while the
user (usually, root) charged with verifying his identity and granting
him the requested credentials is called the arbitrator.
.Pp
The sequence of operations the server goes through to authenticate a
user and perform whatever task he requested is a PAM transaction; the
context within which the server performs the requested task is called
a session.
.Pp
The functionality embodied by PAM is divided into six primitives
grouped into four facilities: authentication, account management,
session management and password management.
.Ss Conversation
The PAM library expects the application to provide a conversation
callback which it can use to communicate with the user.
Some modules may use specialized conversation functions to communicate
with special hardware such as cryptographic dongles or biometric
devices.
See
.Xr pam_conv 3
for details.
.Ss Initialization and Cleanup
The
.Fn pam_start
function initializes the PAM library and returns a handle which must
be provided in all subsequent function calls.
The transaction state is contained entirely within the structure
identified by this handle, so it is possible to conduct multiple
transactions in parallel.
.Pp
The
.Fn pam_end
function releases all resources associated with the specified context,
and can be called at any time to terminate a PAM transaction.
.Ss Storage
The
.Fn pam_set_item
and
.Fn pam_get_item
functions set and retrieve a number of predefined items, including the
service name, the names of the requesting and target users, the
conversation function, and prompts.
.Pp
The
.Fn pam_set_data
and
.Fn pam_get_data
functions manage named chunks of free-form data, generally used by
modules to store state from one invocation to another.
.Ss Authentication
There are two authentication primitives:
.Fn pam_authenticate
and
.Fn pam_setcred .
The former authenticates the user, while the latter manages his
credentials.
.Ss Account Management
The
.Fn pam_acct_mgmt
function enforces policies such as password expiry, account expiry,
time-of-day restrictions, and so forth.
.Ss Session Management
The
.Fn pam_open_session
and
.Fn pam_close_session
functions handle session setup and teardown.
.Ss Password Management
The
.Fn pam_chauthtok
function allows the server to change the user's password, either at
the user's request or because the password has expired.
.Ss Miscellaneous
The
.Fn pam_putenv ,
.Fn pam_getenv
and
.Fn pam_getenvlist
functions manage a private environment list in which modules can set
environment variables they want the server to export during the
session.
.Pp
The
.Fn pam_strerror
function returns a pointer to a string describing the specified PAM
error code.
.Sh RETURN VALUES
The following return codes are defined by
.In security/pam_constants.h :
.Bl -tag -width 18n
.It Bq Er PAM_ABORT
General failure.
.It Bq Er PAM_ACCT_EXPIRED
User account has expired.
.It Bq Er PAM_AUTHINFO_UNAVAIL
Authentication information is unavailable.
.It Bq Er PAM_AUTHTOK_DISABLE_AGING
Authentication token aging disabled.
.It Bq Er PAM_AUTHTOK_ERR
Authentication token failure.
.It Bq Er PAM_AUTHTOK_EXPIRED
Password has expired.
.It Bq Er PAM_AUTHTOK_LOCK_BUSY
Authentication token lock busy.
.It Bq Er PAM_AUTHTOK_RECOVERY_ERR
Failed to recover old authentication token.
.It Bq Er PAM_AUTH_ERR
Authentication error.
.It Bq Er PAM_BUF_ERR
Memory buffer error.
.It Bq Er PAM_CONV_ERR
Conversation failure.
.It Bq Er PAM_CRED_ERR
Failed to set user credentials.
.It Bq Er PAM_CRED_EXPIRED
User credentials have expired.
.It Bq Er PAM_CRED_INSUFFICIENT
Insufficient credentials.
.It Bq Er PAM_CRED_UNAVAIL
Failed to retrieve user credentials.
.It Bq Er PAM_DOMAIN_UNKNOWN
Unknown authentication domain.
.It Bq Er PAM_IGNORE
Ignore this module.
.It Bq Er PAM_MAXTRIES
Maximum number of tries exceeded.
.It Bq Er PAM_MODULE_UNKNOWN
Unknown module type.
.It Bq Er PAM_NEW_AUTHTOK_REQD
New authentication token required.
.It Bq Er PAM_NO_MODULE_DATA
Module data not found.
.It Bq Er PAM_OPEN_ERR
Failed to load module.
.It Bq Er PAM_PERM_DENIED
Permission denied.
.It Bq Er PAM_SERVICE_ERR
Error in service module.
.It Bq Er PAM_SESSION_ERR
Session failure.
.It Bq Er PAM_SUCCESS
Success.
.It Bq Er PAM_SYMBOL_ERR
Invalid symbol.
.It Bq Er PAM_SYSTEM_ERR
System error.
.It Bq Er PAM_TRY_AGAIN
Try again.
.It Bq Er PAM_USER_UNKNOWN
Unknown user.
.El
.Sh SEE ALSO
.Xr openpam 3 ,
.Xr pam_acct_mgmt 3 ,
.Xr pam_authenticate 3 ,
.Xr pam_chauthtok 3 ,
.Xr pam_close_session 3 ,
.Xr pam_conv 3 ,
.Xr pam_end 3 ,
.Xr pam_get_data 3 ,
.Xr pam_getenv 3 ,
.Xr pam_getenvlist 3 ,
.Xr pam_get_item 3 ,
.Xr pam_get_user 3 ,
.Xr pam_open_session 3 ,
.Xr pam_putenv 3 ,
.Xr pam_setcred 3 ,
.Xr pam_set_data 3 ,
.Xr pam_set_item 3 ,
.Xr pam_start 3 ,
.Xr pam_strerror 3
.Sh STANDARDS
.Rs
.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
.%D "June 1997"
.Re
.Sh AUTHORS
The OpenPAM library and this manual page were developed for the
.Fx
Project by ThinkSec AS and Network Associates Laboratories, the
Security Research Division of Network Associates, Inc.\& under
DARPA/SPAWAR contract N66001-01-C-8035
.Pq Dq CBOSS ,
as part of the DARPA CHATS research program.