debian/cdesktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial import of the CDE 2.1.30 sources from the Open Group.

Browse Source
This commit is contained in:
Peter Howkins
2012-03-10 18:21:40 +00:00
commit 83b6996daa
18978 changed files with 3945623 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
cde/lib/pam/man/man3/pam.3 Normal file
View File

@@ -0,0 +1,260 @@
.\" $XConsortium: pam.3 /main/5 1996/10/29 15:17:56 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.nr X
.TH pam 3 "9 Jan 1996"
.SH NAME
PAM \- Pluggable Authentication Module
.SH SYNOPSIS
.LP
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.SH DESCRIPTION
.IX "PAM" "" "\fLPAM\fP \(em Pluggable Authentication Module"
.PP
.SM PAM
gives system administrators the flexibility of choosing any authentication
service available on the system to perform authentication. The framework
also allows new authentication service modules to be plugged in and made
available without modifying the applications.
.LP
The
.SM PAM
framework,
.B libpam,
consists of an interface library and multiple authentication
service modules. The
.SM PAM
interface library is the layer implementing the
Application Programming Interface (API). The authentication service modules
are a set of dynamically loadable objects invoked by the
.SM PAM
API to provide a particular type of user authentication.
.SS Interface Overview
The
.SM PAM
library interface
consists of functions which can be grouped into five categories. The
names for all the authentication library functions start with
.B pam_.
.PP
The first category contains functions for establishing and terminating an
authentication activity
(\f3pam_start\f1(3)
and
(\f3pam_end\f1(3)),
functions to maintain module specific data
(\f3pam_[sg]et_data\f1(3)),
functions to maintain state information
(\f3pam_[sg]et_item\f1(3)),
and a function to return error status information
(\f3pam_strerror\f1(3)).
.PP
The second category contains functions to authenticate an individual user
(\f3pam_authenticate\f1(3))
and to set the credentials of the user
(\f3pam_setcred\f1(3)).
.PP
The third category contains functions to do account management
(\f3pam_acct_mgmt\f1(3)).
This includes checking for password aging and access-hour restrictions.
.PP
The fourth category contains functions to perform session management
(\f3(pam_open_session\f1(3)
and
(\f3pam_close_session\f1(3))
after access to the system has been granted.
.PP
The fifth category consists of functions to change authentication tokens
.BR pam_chauthtok (3)).
An authentication token is the object used to verify the
identity of the user.
In
.SM UNIX,
an authentication
token is a user's password.
.PP
All the
.B pam_*(\|)
interfaces are implemented through the library
.B libpam.
For each of the categories listed above, excluding the first category
.BR pam_start(\|) ,
.BR pam_end(\|) ,
.BR pam_[sg]et_data(\|) ,
.BR pam_[sg]et_item(\|) ,
and
.BR pam_strerror(\|) )
there exists a dynamically loadable shared module
that provides the appropriate
service layer functionality upon demand.
The functional entry points in the
service layer start with the
.B pam_sm_
prefix. The only difference between the
.B pam_sm_*(\|)
interfaces and their corresponding
.B pam_
interfaces is that all the
.BR pam_sm_*(\|)
interfaces require extra parameters to pass service specific options
to the shared modules.
Please refer to
.BR pam_sm (3)
for an overview of the
.SM PAM
service module APIs.
.SS Stateful Interface
A sequence of calls sharing a common set of state information
is referred to as an authentication transaction. An authentication
transaction begins with a call to
.BR pam_start(\|).
.B pam_start(\|)
allocates space, performs various initialization activities,
and assigns a
.SM PAM
authentication handle to be used for subsequent calls
to the library.
.LP
After initiating an authentication transaction, applications can invoke
.B pam_authenticate(\|)
to authenticate a particular user, and
.B pam_acct_mgmt(\|)
to perform system entry management (the
application may want to determine if the user's
password has expired).
.LP
If the user has been successfully authenticated, applications call
.B pam_setcred(\|)
to set any user credentials associated with the authentication service.
Within one authentication transaction (between
.B pam_start(\|)
and
.BR pam_end(\|) ),
all calls to the
.SM PAM
interface should be made with the same authentication handle
returned by
.BR pam_start(\|) .
This is necessary because certain service modules
may store module-specific data in the handle
that is intended for use by other modules.
For example, during the call to
.BR pam_authenticate(\|) ,
service modules may store data in the handle
that is intended for use by
.BR pam_setcred(\|) .
.LP
To perform session management, applications call
.BR pam_open_session(\|) .
For example, the system may want to store
the total time for the session.
The function
.B pam_close_session(\|)
closes the current session.
.LP
When necessary, applications can call
.B pam_get_item(\|)
and
.B pam_set_item(\|)
to access and update specific authentication information.
Such information may include the current username.
.LP
To terminate an authentication transaction, the application simply calls
.BR pam_end(\|) ,
which frees previously allocated space used to store authentication information.
.PP
.SS Application - Authentication Service Interactive Interface
The authentication service in
.SM PAM
does not communicate directly with the user; instead it
relies on the application to perform all such interactions.
The application passes a pointer to the function,
.BR conv(\|) ,
along with any associated application data pointers, through a
.I pam_conv
structure to the authentication service when it initiates
an authentication transaction (via a call to
.BR pam_start(\|) ).
The service will then use the function,
.BR conv(\|) ,
to prompt the user for data,
output error messages, and display text information.
Refer to
.BR pam_start (3)
for more information.
.SS Stacking Multiple Schemes
The
.SM PAM
architecture enables authentication by multiple authentication services through
.I stacking.
System entry applications, such as
.BR login (1),
stack multiple service modules to authenticate users with multiple
authentication services.
The order in which authentication service
modules are stacked is specified in the configuration file,
.BR pam.conf (4).
A system administrator determines this ordering, and also determines
whether the same password can be used for all authentication services.
.SS Administrative Interface
The authentication library,
.BR /usr/lib/libpam.so.1 ,
implements the framework interface.
Various authentication services are
implemented by their own loadable modules
whose paths are specified through the
.BR pam.conf (4)
file.
.PP
.SH "RETURN VALUES"
.PP
The
.SM PAM
functions may return one of the following generic values,
or one of the values defined in the specific man pages:
.RS
.IP "PAM_SUCCESS" 22
Successful function return
.IP "PAM_OPEN_ERR" 22
.B dlopen(\|)
failure when dynamically loading a service module
.IP "PAM_SYMBOL_ERR" 22
Symbol not found
.IP "PAM_SERVICE_ERR" 22
Error in service module
.IP "PAM_SYSTEM_ERR" 22
System error
.IP "PAM_BUF_ERR" 22
Memory buffer error
.IP "PAM_CONV_ERR" 22
Conversation failure
.IP "PAM_PERM_DENIED
Permission denied
.RE
.SH "SEE ALSO"
.BR pam_authenticate (3),
.BR pam_open_session (3),
.BR pam_chauthtok (3),
.BR pam_set_item (3),
.BR pam_setcred (3),
.BR pam_sm (3),
.BR pam_start (3),
.BR pam_strerror (3),
.BR pam.conf (4)
.SH WARNING
Please note that all the
.SM PAM
APIs and the data structures are subject to
change without notice.

74
cde/lib/pam/man/man3/pam_acct_mgmt.3 Normal file
View File

@@ -0,0 +1,74 @@
.\" $XConsortium: pam_acct_mgmt.3 /main/5 1996/10/29 15:18:07 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" Don't forget to enter .IX index entries for each function.
.nr X
.TH pam_acct_mgmt 3 "9 Jan 1996"
.SH NAME
pam_acct_mgmt
\- perform PAM account validation procedures
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.BI "int pam_acct_mgmt(pam_handle_t *" "pamh" ,
.BI "int " "flags");
.SH DESCRIPTION
The function
.B pam_acct_mgmt(\|)
is called to determine if the current user's account is
valid. This includes checking for password and account expiration,
as well as verifying access hour restrictions. This function
is typically called after the user has been authenticated
with
.BR pam_authenticate (3).
.LP
The
.IR pamh
argument
is an authentication handle obtained by a prior call to
.BR pam_start(\|) .
The following flags may be set in the
.IR flags
field:
.RS
.IP PAM_SILENT 28
The account management service should not generate any messages
.IP PAM_DISALLOW_NULL_AUTHTOK 28
The account management service should return
.SM PAM_AUTHTOKEN_REQD
if the user has a null authentication token
.RE
.SH "RETURN VALUES"
.PP
Upon successful completion, PAM_SUCCESS is returned.
In addition to the error return values described in
.BR pam (3),
the following values may be returned:
.RS
.IP PAM_USER_UNKNOWN 28
User not known to underlying account management module
.IP PAM_AUTH_ERR 28
Authentication failure
.IP PAM_AUTHTOKEN_REQD 28
New authentication token required. This is normally returned if the machine
security policies require that the password should be changed because
the password is NULL or it has aged.
.IP PAM_ACCT_EXPIRED 28
User account has expired
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_start (3),
.BR pam_authenticate (3)

100
cde/lib/pam/man/man3/pam_authenticate.3 Normal file
View File

@@ -0,0 +1,100 @@
.\" $XConsortium: pam_authenticate.3 /main/5 1996/10/29 15:18:17 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" Don't forget to enter .IX index entries for each function.
.nr X
.TH pam_authenticate 3 "9 Jan 1996"
.SH NAME
pam_authenticate
\- perform authentication within the PAM framework
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.BI "int pam_authenticate(pam_handle_t *" "pamh" ,
.BI "int " "flags");
.SH DESCRIPTION
.IX "pam_authenticate" "" "\fLpam_authenticate\fP \(em request authentication"
.B pam_authenticate(\|)
is called to authenticate the current user.
The user is usually required to enter
a password or similar authentication token depending upon
the authentication service configured within the system.
The user in question should have been specified by a prior call to
.B pam_start(\|)
or
.BR pam_set_item(\|) .
The following flags may be set in the
.IR flags
field:
.RS
.IP PAM_SILENT 35
Authentication service should not generate any messages
.IP PAM_DISALLOW_NULL_AUTHTOK 35
The authentication service should return PAM_AUTH_ERROR
if the user has a null authentication token
.RE
.SH NOTES
.PP
In the case of authentication failures due to an incorrect username
or password, it is the responsibility of the application to retry
.B pam_authenticate(\|)
and to maintain the retry count.
An authentication service module may implement an
internal retry count and return an error
PAM_MAXTRIES
if the module does not want the application to retry.
.LP
If the PAM framework can not load the authentication module, then
it will return PAM_ABORT.
This indicates a serious failure and that
the application should not attempt to retry the authentication.
.LP
For security reasons,
the location of authentication failures is hidden from the user.
Thus, if several authentication services are stacked and a single
service fails,
.B pam_authenticate(\|)
requires that the user re-authenticate to all the services.
.LP
A null authentication token in the authentication database will
result in successful authentication unless
.SM PAM_DISALLOW_NULL_AUTHTOK
was specified.
In such cases, there will not be any prompting
for the user to enter an authentication token.
.SH "RETURN VALUES"
.PP
Upon successful completion, PAM_SUCCESS is returned.
In addition to the error return values described in
.BR pam (3),
the following values may be returned:
.RS
.IP PAM_AUTH_ERR 29
Authentication failure
.IP PAM_CRED_INSUFFICIENT 29
Can not access authentication data due to insufficient credentials
.IP PAM_AUTHINFO_UNAVAIL 29
Underlying authentication service can not retrieve authentication information
.IP PAM_USER_UNKNOWN 29
User not known to the underlying authentication module
.IP PAM_MAXTRIES
An authentication service has maintained a retry count which
has been reached. No further retries should be attempted.
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_start (3),
.BR pam_open_session (3),
.BR pam_setcred (3)

100
cde/lib/pam/man/man3/pam_chauthtok.3 Normal file
View File

@@ -0,0 +1,100 @@
.\" $XConsortium: pam_chauthtok.3 /main/5 1996/10/29 15:18:27 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.nr X
.TH pam_chauthtok 3 "9 Jan 1996"
.SH NAME
pam_chauthtok
\- perform passord related functions within the PAM framework
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.BI "int pam_chauthtok(pam_handle_t " "*pamh" ,
.BI "const int" " flags");
.SH DESCRIPTION
.IX "pam_chauthtok" "" "\fLpam_chauthtok\fP \(em request changing authentication token or get/set authentication attributes"
.B pam_chauthtok(\|)
is called to change the authentication token
associated with a particular user
referenced by the authentication handle,
.IR pamh.
.LP
The following flag may be passed in to
.BR pam_chauthtok(\|) :
.RS
.IP PAM_SILENT 30
The password service should not generate any messages
.IP PAM_CHANGE_EXPIRED_AUTHTOK 30
The password service should only update those passwords that have aged.
If this flag is not passed,
all password services should update their passwords.
.RE
.LP
Upon successful completion of the call, the authentication
token of the user will be changed in accordance with the
password service configured in the system through
.BR pam.conf (4).
.SH NOTES
The flag
.SM PAM_CHANGE_EXPIRED_AUTHTOK
is typically used by a
.B login
application which has determined that the user's password has aged or expired.
Before allowing the user to login, the
.B login
application may invoke
.B pam_chauthtok(\|)
with this flag to allow the user to update the password.
Typically applications such as
.BR passwd (1)
should not use this flag.
.PP
.B pam_chauthtok(\|)
performs a preliminary check before attempting to update
passwords. This check is performed for each
password module in the stack as listed in
.BR pam.conf (4).
The check may include pinging remote name services to determine
if they are available. If
.B pam_chauthtok(\|)
returns
PAM_TRY_AGAIN,
then the check has failed, and passwords are not updated.
.SH "RETURN VALUES"
.PP
Upon successful completion, PAM_SUCCESS is returned.
In addition to the error return values described in
.BR pam (3),
the following values may be returned:
.RS
.IP PAM_PERM_DENIED 34
No permission
.IP PAM_AUTHTOK_ERR 34
Authentication token manipulation error
.IP PAM_AUTHTOK_RECOVERY_ERR 34
Authentication information cannot be recovered
.IP PAM_AUTHTOK_LOCK_BUSY 34
Authentication token lock busy
.IP PAM_AUTHTOK_DISABLE_AGING 34
Authentication token aging disabled
.IP PAM_USER_UNKNOWN 34
User unknown to password service
.IP PAM_TRY_AGAIN 34
Preliminary check by password service failed
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_start (3),
.BR pam_authenticate (3)

106
cde/lib/pam/man/man3/pam_open_session.3 Normal file
View File

@@ -0,0 +1,106 @@
.\" $XConsortium: pam_open_session.3 /main/5 1996/10/29 15:18:42 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.nr X
.TH pam_open_session 3 "9 Jan 1996"
.SH NAME
pam_open_session, pam_close_session \- perform PAM session creation and
termination operations
.SH SYNOPSIS
.LP
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.BI "int pam_open_session(pam_handle_t " "*pamh" ,
.BI "int " "flags");
.LP
.BI "int pam_close_session(pam_handle_t " "*pamh" ,
.BI "int " "flags");
.SH DESCRIPTION
.IX "pam_open_session" "" "\fLpam_open_session\fP \(em request authentication"
.B pam_open_session(\|)
is called after a user has been successfully authenticated (refer to
.BR pam_authenticate (3)
and
.BR pam_acct_mgmt (3))
and is used to notify the session modules that a new session
has been initiated. All programs that use the
.BR pam (3)
library should invoke
.B pam_open_session(\|)
when beginning a new session.
Upon termination of this activity,
.B pam_close_session(\|)
should be invoked to inform
.BR pam (3)
that the
session has terminated.
.LP
The
.I pamh
argument
is an authentication handle obtained by a prior call to
.B pam_start(\|).
The following flag may be set in the
.I flags
field for
.B pam_open_session(\|)
and
.BR pam_close_session(\|) :
.RS
.IP PAM_SILENT 16
The session service should not generate any messages
.RE
.SH NOTES
In many instances, the
.B pam_open_session(\|)
and
.B pam_close_session(\|)
calls may be made by different processes.
For example, in UNIX the
.B login
process opens a session, while the
.B init
process closes
the session. In this case,
UTMP/WTMP entries may be used to link the call to
.B pam_close_session(\|)
with an earlier call to
.BR pam_open_session(\|) .
This is possible because
UTMP/WTMP entries are uniquely identified by a combination of attributes,
including the user login name and device name, which are accessible
through the PAM handle,
.I pamh.
The call to
.B pam_open_session(\|)
should precede UTMP/WTMP entry management and the call to
.B pam_close_session(\|)
should follow UTMP/WTMP exit management.
.PP
.SH "RETURN VALUES"
.PP
Upon successful completion, PAM_SUCCESS is returned. In addition to the
return values defined in
.BR pam (3),
the following value may be returned on error:
.RS
.IP PAM_SESSION_ERR 22
Can not make/remove an entry for the specified session
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_start (3),
.BR pam_authenticate (3),
.BR pam_acct_mgmt (3),
.BR getutxent (3C)

108
cde/lib/pam/man/man3/pam_set_data.3 Normal file
View File

@@ -0,0 +1,108 @@
.\" $XConsortium: pam_set_data.3 /main/5 1996/10/29 15:19:01 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" Don't forget to enter .IX index entries for each function.
.nr X
.TH pam_set_data 3 "9 Jan 1996"
.SH NAME
pam_set_data, pam_get_data
\- PAM routines to maintain module specific state
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.BI "int pam_set_data(pam_handle_t " "*pamh" ,
.BI "const char *" "module_data_name" ,
.BI "const void *" "data" ,
.BI "void " "(*cleanup)(pam_handle_t *pamh, void *data, int pam_end_status)" );
.LP
.BI "int pam_get_data(const pam_handle_t " "*pamh" ,
.BI "const char *" "module_data_name" ,
.BI "void **" "data" );
.SH DESCRIPTION
.IX "pam_set_data" "" "\fLpam_set_data\fP \(em set module info"
.B pam_set_data(\|)
and
.B pam_set_data(\|)
allow
.SM PAM
service modules to access and update module specific information as needed.
These functions should not be used by applications.
.LP
.B pam_set_data(\|)
stores module specific data within the PAM handle,
.I pamh.
The
.I module_data_name
argument
uniquely identifies the data, and the
.I data
argument
represents the actual data.
.I module_data_name
should be unique across all services (UNIX, etc).
.LP
The
.I cleanup
function is used to free any memory used by the
.I data
after it is no longer needed, and is invoked by
.BR pam_end(\|) .
The
.I cleanup
function takes as its arguments a pointer to the PAM handle,
.I pamh,
a pointer to the actual data,
.I data,
and a status code,
.I pam_end_status.
The status code determines exactly what state information needs to be
purged, and is therefore specific to each module.
.LP
If
.B pam_set_data(\|)
is called and module data already exists under the same
.I module_data_name
(from a prior call to
.BR pam_set_data(\|) ),
then the existing
.I data
is replaced by the new
.I data,
and the existing
.I cleanup
function is replaced by the new
.I cleanup
function.
.LP
.B pam_get_data(\|)
retrieves module specific data stored in the PAM handle,
.I pamh,
identified by the unique name,
.I module_data_name.
The
.I data
argument is assigned the address of the requested data.
.SH "RETURN VALUES"
.PP
In addition to the return values listed in
.BR pam (3),
the following value may also be returned:
.RS
.IP PAM_NO_MODULE_DATA 28
No module specific data is present
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_end (3)

137
cde/lib/pam/man/man3/pam_set_item.3 Normal file
View File

@@ -0,0 +1,137 @@
.\" $XConsortium: pam_set_item.3 /main/5 1996/10/29 15:19:14 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" Don't forget to enter .IX index entries for each function.
.nr X
.TH pam_set_item 3 "9 Jan 1996"
.SH NAME
pam_set_item, pam_get_item
\- authentication information routines for PAM
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.BI "int pam_set_item(pam_handle_t " "*pamh" ,
.BI "int " "item_type" ,
.BI "const void *" "item" );
.LP
.BI "int pam_get_item(const pam_handle_t " "*pamh" ,
.BI "int " "item_type" ,
.BI "void **" "item" );
.SH DESCRIPTION
.IX "pam_set_item" "" "\fLpam_set_item\fP \(em set authentication info"
.B pam_get_item(\|)
and
.B pam_set_item(\|)
allow applications and PAM service modules to access and update
.SM PAM
information as needed. The information is specified by
.IR item_type,
and can be one of the following:
.RS
.IP "PAM_SERVICE" 25
The service name
.IP "PAM_USER" 25
The user name
.IP "PAM_AUTHTOK" 25
The user authentication token
.IP "PAM_OLDAUTHTOK" 25
The old user authentication token
.IP "PAM_TTY" 25
The tty name
.IP "PAM_RHOST" 25
The remote host name
.IP "PAM_RUSER" 25
The remote user name
.IP "PAM_CONV" 25
The pam_conv structure
.IP "PAM_USER_PROMPT" 25
The default prompt used by
.BR pam_get_user(\|)
.RE
.LP
The
.IR item_type
.SM PAM_AUTHTOK
and
.SM PAM_OLDAUTHTOK
are available only to the module providers for security reasons.
The authentication module, account module, and session management module
should treat
.SM PAM_AUTHTOK
as the current authentication token,
and should ignore
.SM PAM_OLDAUTHTOK.
The password management module should treat
.SM PAM_OLDAUTHTOK
as the current authentication token and
.SM PAM_AUTHTOK
as the new authentication token.
.LP
.B pam_set_item(\|)
is passed the authentication handle,
.IR pamh,
returned by
.BR pam_start(\|) ,
a pointer to the object,
.IR item,
and its type,
.IR item_type.
If successful,
.B pam_set_item(\|)
copies the item to an internal storage area allocated by the
authentication module and returns PAM_SUCCESS. An item that had
been previously set will be overwritten by the new value.
.LP
.B pam_get_item(\|)
is passed the authentication handle,
.IR pamh,
returned by
.BR pam_start(\|) ,
an
.IR item_type ,
and the address of the pointer,
.IR item ,
which is assigned the address of the requested object.
The object data is valid until modified by a subsequent call to
.B pam_set_item(\|)
for the same
.IR item_type ,
or unless it is modified by any of the underlying service modules.
If the item has not been previously set,
.B pam_get_item(\|)
returns a NULL pointer.
An
.IR item
retrieved by
.B pam_get_item(\|)
should not be modified or freed. The item will be released by
.BR pam_end(\|) .
.SH "RETURN VALUES"
.PP
Upon success
.B pam_get_item(\|)
returns PAM_SUCCESS; otherwise it returns an error code.
Refer to
.BR pam (3)
for information on error related return values.
.SH "SEE ALSO"
.BR pam_start (3),
.BR pam_authenticate (3),
.BR pam_acct_mgmt (3),
.BR pam_open_session (3),
.BR pam_setcred (3),
.BR pam_chauthtok (3),
.BR pam_get_user (3),
.BR pam (3)

86
cde/lib/pam/man/man3/pam_setcred.3 Normal file
View File

@@ -0,0 +1,86 @@
.\" $XConsortium: pam_setcred.3 /main/5 1996/10/29 15:19:22 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.nr X
.TH pam_setcred 3 "9 Jan 1996"
.SH NAME
pam_setcred \- modify\/delete user credentials for
an authentication service
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.\" .BI "int pam_setcred(pam_handle_t " "*pamh" ,
.\" .BI "int " flags");
\fBint pam_setcred(pam_handle_t \fI*pamh\fB, int \fIflags\fB);
.SH DESCRIPTION
.IX "pam_setcred" "" "\fLpam_setcred\fP \(em request setting credentials"
.B pam_setcred(\|)
is used to establish, modify, or delete user credentials.
.B pam_setcred(\|)
is typically called after the user has been authenticated
and after a session has been opened (refer to
.BR pam_authenticate (3),
.BR pam_acct_mgmt (3),
and
.BR pam_open_session (3)).
.LP
The user is specified by a prior call to
.B pam_start(\|)
or
.B pam_set_item(\|),
and is referenced by the authentication handle,
.IR pamh.
The following flags may be set in the
.IR flags
field. Note that the first four flags are mutually exclusive:
.RS
.IP "PAM_CRED_ESTABLISH" 26
Set user credentials for an authentication service
.IP "PAM_CRED_DELETE" 26
Delete user credentials associated with an authentication service
.IP "PAM_CRED_REINITIALIZE" 26
Reinitialize user credentials
.IP "PAM_CRED_REFRESH" 26
Extend lifetime of user credentials
.IP "PAM_SILENT" 26
Authentication service should not generate any messages
.RE
.LP
If none of the flags are set, PAM_CRED_ESTABLISH
is used as the default.
.SH "RETURN VALUES"
.PP
Upon success,
.B pam_setcred(\|)
returns PAM_SUCCESS.
In addition to the error return values described in
.BR pam (3),
the following values may be returned upon error:
.RS
.IP PAM_CRED_UNAVAIL 25
Underlying authentication service can not retrieve user credentials unavailable
.IP PAM_CRED_EXPIRED 25
User credentials expired
.IP PAM_USER_UNKNOWN 25
User unknown to underlying authentication service
.IP PAM_CRED_ERR 25
Failure setting user credentials
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_start (3),
.BR pam_authenticate (3),
.BR pam_acct_mgmt (3),
.BR pam_open_session (3)

295
cde/lib/pam/man/man3/pam_sm.3 Normal file
View File

@@ -0,0 +1,295 @@
.\" $XConsortium: pam_sm.3 /main/4 1996/10/29 15:19:34 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.nr X
.TH pam_sm 3 "9 Jan 1996"
.SH NAME
PAM \- PAM Service Module APIs
.SH SYNOPSIS
.LP
.nf
.ft 3
#include <security/pam_appl.h>
#include <security/pam_modules.h>
.ft
.fi
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.SH DESCRIPTION
.IX "PAM" "" "\fLPAM\fP \(em Pluggable Authentication Module"
.PP
.SM PAM
gives system administrators the flexibility of choosing any authentication
service available on the system to perform authentication. The framework
also allows new authentication service modules to be plugged in and made
available without modifying the applications.
.LP
The
.SM PAM
framework,
.B libpam,
consists of an interface library and multiple authentication
service modules. The
.SM PAM
interface library is the layer implementing the
Application Programming Interface (API). The authentication service modules
are a set of dynamically loadable objects invoked by the
.SM PAM
API to provide a particular type of user authentication.
.PP
This manual page gives an overview of the PAM APIs for the service modules.
.SS Interface Overview
The
.SM PAM
service module interface
consists of functions which can be grouped into four categories. The
names for all the authentication library functions start with
.B pam_sm.
The only difference between the
.B pam_*(\|)
interfaces and their corresponding
.B pam_sm_*(\|)
interfaces is that all the
.B pam_sm_*(\|)
interfaces require extra parameters to pass service specific options
to the shared modules.
They are otherwise identical.
.PP
The first category contains functions to authenticate an individual user
(\f3pam_sm_authenticate\f1(3))
and to set the credentials of the user
.B (\f3pam_sm_setcred\f1(3)).
These back-end functions implement the functionality of
.BR pam_authenticate (3)
and
.BR pam_setcred (3)
respectively.
.PP
The second category contains functions to do account management
(\f3pam_sm_acct_mgmt\f1(3)).
This includes checking for password aging and access-hour restrictions.
This back-end function implements the functionality of
.BR pam_acct_mgmt (3).
.PP
The third category contains functions to perform session management
(\f3pam_sm_open_session\f1(3)
and
.BR pam_sm_close_session (3))
after access to the system has been granted.
These back-end functions implement the functionality of
.BR pam_open_session (3)
and
.BR pam_close_session (3),
respectively.
.PP
The fourth category consists a function to change authentication tokens
(\f3pam_sm_chauthtok\f1(3)).
This back-end function implements the functionality of
.BR pam_chauthtok (3).
.SS Stateful Interface
A sequence of calls sharing a common set of state information
is referred to as an authentication transaction. An authentication
transaction begins with a call to
.BR pam_start(\|) .
.B pam_start(\|)
allocates space, performs various initialization activities,
and assigns an authentication handle to be used for subsequent calls
to the library.
Note that the service modules do not get called or
initialized when
.B pam_start(\|)
is called.
The modules are loaded and the symbols resolved upon first use
of that function.
.LP
The PAM handle keeps certain information about the transaction
that can be accessed through the
.B pam_get_item(\|)
API.
Though the modules can also use
.B pam_set_item(\|)
to change any of the item information, it
is recommended that nothing be changed except PAM_AUTHTOK and
PAM_OLDAUTHTOK.
.LP
If the modules want to store any module specific state information
then they can use the
.BR pam_set_data (3)
function to store that
information with the PAM handle. The data should be stored with a
name which is unique across all modules and module types. For
example,
.SM SUNW_PAM_UNIX_AUTH_userid
can be used as a name by the UNIX
module to store information about the state of user's
authentication. Some modules use this technique to share data
across two different module types.
.LP
Also, during the call to
.BR pam_authenticate(\|) ,
the UNIX module may store the authentication status
(success or reason for failure)
in the handle, using a unique name such as
.SM SUNW_SECURE_RPC_DATA.
This information is intended for use by
.BR pam_setcred(\|) .
.LP
During the call to
.BR pam_acct_mgmt(\|) ,
the account modules may store data in the handle to indicate
which passwords have aged.
This information is intended for use by
.BR pam_chauthtok(\|) .
.LP
The module can also store a cleanup function associated with the
data. The PAM framework calls this cleanup function, when the
application calls
.BR pam_end(\|)
to close the transaction.
.SS Interaction with the User
.PP
The PAM service modules do not communicate directly with the user;
instead they rely on the application to perform all
such interactions. The application passes a pointer to the
function,
.BR conv(\|),
along with any associated application data
pointers, through the
.B pam_conv
structure when it initiates an
authentication transaction (via a call to
.BR pam_start(\|) ).
The service module will then use the function,
.BR conv(\|) ,
to prompt the user for data, output error messages,
and display text information.
Refer to
.BR pam_start (3)
for more information.
The modules are responsible for the localization of all
messages to the user.
.SH CONVENTIONS
.PP
By convention, applications that need to prompt for a user name should
call
.BR pam_set_item(\|)
and set the value of PAM_USER_PROMPT before calling
.BR pam_authenticate(\|) .
The service module's
.BR pam_sm_authenticate(\|)
function will then call
.BR pam_get_user(\|)
to prompt for the user name. Note that
certain PAM service modules (such as a smart card module) may override
the value of PAM_USER_PROMPT and pass in their own prompt.
.PP
Though the PAM framework enforces no rules about the module's names,
location, options and such, there are certain conventions that all
module providers are expected to follow.
.LP
By convention, the modules should be located in the
.B /usr/lib/security
directory. Additional modules may
be located in
.B /opt/<pkg>/lib.
.LP
By convention, the modules are named
.B pam_<service_name>_<module_type>.so.1.
If the given module implements
more than one module type (for example,
.B pam_unix.so.1
module), then
the module_type suffix should be dropped.
.LP
For every such module, there should be a corresponding manual page
in section 5 which should describe the
.I module_type
it supports,
the functionality of the module, along with the options it
supports. The dependencies should be clearly identified to the
system administrator. For example, it should be made clear
whether this module is a stand-alone module or depends upon the
presence of some other module. One should also specify whether
this module should come before or after some other module in the
stack.
.LP
By convention, the modules should support
the following options:
.RS
.IP debug 15
Syslog debugging information at LOG_DEBUG
level. Be careful as to not log any sensitive
information such as passwords.
.IP nowarn 15
Turn off warning messages such as "password is
about to expire"
.RE
.PP
In addition, it is recommended that the auth and the
password module support the following options:
.RS
.IP use_first_pass 15
Instead of prompting the user for the password,
use the user's initial password (entered when
the user was authenticated to the first authentication module
in the stack) for authentication.
If the passwords do not match, or if no
password has been entered, return failure and do not
prompt the user for a password. Support for
this scheme allows the user to type only one
password for multiple schemes.
.IP try_first_pass 15
Instead of prompting the user for the password,
use the user's initial password (entered when
the user was authenticated to the first authentication
module in the stack) for authentication.
If the passwords do not match, or if no password
has been entered, prompt the user for a password
after identifying which type of password (ie. UNIX,
etc.) is being requested.
Support for this scheme allows the user to try to
use only one password for multiple schemes, and type
multiple passwords only if necessary.
.RE
.PP
If an unsupported option is passed to the modules, it should
syslog the error at LOG_ERR level.
.PP
The permission bits on the service module should be set
such that it is not writable by either "group" or "other".
The PAM framework will not
load the module if the above permission rules are not followed.
.SH ERROR LOGGING
If there are any errors, the modules should log them using
.BR syslog (3)
at the LOG_ERR level.
.SH RETURN VALUES
The PAM service module functions may return any of the PAM
error numbers specified in the specific man pages. It can also
return a PAM_IGNORE error number to mean that the PAM framework
should ignore this module regardless of whether it is required, optional
or sufficient. This error number is normally returned when the
module does not want to deal with the given user at all.
.SH SEE ALSO
.BR pam (3),
.BR pam_start (3),
.BR pam_set_item (3),
.BR pam_get_user (3),
.BR pam_authenticate (3),
.BR pam_open_session (3),
.BR pam_setcred (3),
.BR pam_chauthtok (3),
.BR pam_strerror (3),
.BR pam_sm_authenticate (3),
.BR pam_sm_open_session (3),
.BR pam_sm_setcred (3),
.BR pam_sm_chauthtok (3),
.BR pam.conf (4)

113
cde/lib/pam/man/man3/pam_sm_acct_mgmt.3 Normal file
View File

@@ -0,0 +1,113 @@
.\" $XConsortium: pam_sm_acct_mgmt.3 /main/5 1996/10/29 15:19:45 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" Don't forget to enter .IX index entries for each function.
.nr X
.TH pam_sm_acct_mgmt 3 "9 Jan 1996"
.SH NAME
pam_sm_acct_mgmt
\- Service provider implementation for pam_acct_mgmt
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
#include <security/pam_modules.h>
.ft
.fi
.LP
.BI "int pam_sm_acct_mgmt(pam_handle_t *" "pamh" ,
.BI "int " "flags" ,
.BI "int " "argc",
.BI "const char **" "argv" );
.SH DESCRIPTION
.IX "pam_sm_acct_mgmt" "" "\fLpam_sm_acct_mgmt\fP \(em account management"
In response to a call to
.BR pam_acct_mgmt (3),
the PAM framework calls
.B pam_sm_acct_mgmt(\|)
from the modules listed in the
.BR pam.conf (4)
file.
The account management provider supplies the back-end functionality for
this interface function.
The applications should not call this API directly.
.PP
The function,
.BR pam_sm_acct_mgmt(\|) ,
determines whether the current user's account and password are valid.
This includes checking for password
and account expiration, valid log-in times, etc.
The user in question is specified by a prior call to
.BR pam_start(\|) ,
and is referenced by the authentication handle,
.IR pamh,
which is passed as the first argument to
.B pam_sm_acct_mgmt(\|).
The following flags may be set in the
.IR flags
field:
.RS
.IP PAM_SILENT 30
The account management service should not generate any messages
.IP PAM_DISALLOW_NULL_AUTHTOK 30
The account management service should return PAM_AUTHTOKEN_REQD
if the user has a null authentication token
.RE
.PP
The
.I argc
argument
represents the number of module options passed in from the configuration file
.BR pam.conf (4).
.I argv
specifies the module options, which are interpreted and processed
by the account management service. Please refer to the specific
module man pages for the various available
.I options.
If an unknown option is passed to the module, an error should be
logged through
.BR syslog (3)
and the option ignored.
.PP
If an account management module determines that the user
password has aged or expired, it should save this information
as state in the authentication handle,
.I pamh,
using
.BR pam_set_data(\|) .
.B pam_chauthok(\|)
uses this information to determine which passwords have
expired.
.SH "RETURN VALUES"
.PP
If there are no restrictions to logging in, PAM_SUCCESS is returned.
The following error values may also be returned upon error:
.RS
.IP PAM_USER_UNKNOWN 30
User not known to underlying authentication module
.IP PAM_AUTHTOKEN_REQD 30
New authentication token required
.IP PAM_ACCT_EXPIRED 30
User account has expired
.IP PAM_PERM_DENIED 30
User denied access to account at this time
.IP PAM_IGNORE 30
Ignore underlying account module regardless of whether the control
flag is
.I required, optional
or
.I sufficient
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_acct_mgmt (3),
.BR syslog (3),
.BR pam.conf (4)

130
cde/lib/pam/man/man3/pam_sm_authenticate.3 Normal file
View File

@@ -0,0 +1,130 @@
.\" $XConsortium: pam_sm_authenticate.3 /main/5 1996/10/29 15:19:54 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" Don't forget to enter .IX index entries for each function.
.nr X
.TH pam_sm_authenticate 3 "9 Jan 1996"
.SH NAME
pam_sm_authenticate
\- Service provider implementation for pam_authenticate
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
#include <security/pam_modules.h>
.ft
.fi
.LP
.BI "int pam_sm_authenticate(pam_handle_t *" "pamh" ,
.BI "int " "flags" ,
.BI "int " "argc",
.BI "const char **" "argv");
.SH DESCRIPTION
.IX "pam_auth" "" "\fLpam_auth\fP \(em request authentication"
In response to a call to
.BR pam_authenticate (3),
the PAM framework calls
.B pam_sm_authenticate(\|)
from the modules listed in the
.BR pam.conf (4)
file.
The authentication provider supplies the back-end functionality for
this interface function.
.LP
The function,
.BR pam_sm_authenticate(\|) ,
is called to verify the identity of the current user.
The user is usually required to enter
a password or similar authentication token depending upon
the authentication scheme configured within the system.
The user in question is specified by a prior call to
.BR pam_start(\|) ,
and is referenced by the authentication handle,
.IR pamh.
.LP
If the user is unknown to the authentication service,
the service module should mask this error
and continue to prompt the user for a password.
It should then return the error,
PAM_USER_UNKNOWN.
.LP
The following flag may be passed in to
.B pam_sm_authenticate(\|):
.RS
.IP PAM_SILENT 35
The authentication service should not generate any messages
.IP PAM_DISALLOW_NULL_AUTHTOK 35
The authentication service should return PAM_AUTH_ERROR
if the user has a null authentication token
.RE
.PP
The
.I argc
argument
represents the number of module options passed in from the configuration file
.BR pam.conf (4).
.I argv
specifies the module options, which are interpreted and processed
by the authentication service.
Please refer to the specific module man pages
for the various available
.I options.
If any unknown option is passed in, the module should log the error and
ignore the option.
.LP
Before returning,
.B pam_sm_authenticate(\|)
should call
.B pam_get_item(\|)
and retrieve PAM_AUTHTOK.
If it has not been set before (ie. the value is NULL),
.B pam_sm_authenticate(\|)
should set it to the password entered by the user
using
.BR pam_set_item(\|) .
.PP
An authentication module may save the authentication status
(success or reason for failure)
as state in the authentication handle using
.BR pam_set_data (3).
This information is intended for use by
.BR pam_setcred(\|) .
.SH NOTES
Modules should not retry the authentication in the event of a failure.
Applications handle authentication retries and maintain the retry count.
To limit the number of retries, the module can return a
PAM_MAXTRIES error.
.SH "RETURN VALUES"
.PP
Upon successful completion, PAM_SUCCESS must be returned.
In addition, the following values may be returned:
.RS
.IP PAM_MAXTRIES 29
Maximum number of authentication attempts exceeded
.IP PAM_AUTH_ERR 29
Authentication failure
.IP PAM_CRED_INSUFFICIENT 29
Can not access authentication data due to insufficient credentials
.IP PAM_AUTHINFO_UNAVAIL 29
Underlying authentication service can not retrieve authentication information
.IP PAM_USER_UNKNOWN 29
User not known to underlying authentication module
.IP PAM_IGNORE 29
Ignore underlying authentication module regardless of whether the control
flag is
.I required, optional
or
.I sufficient
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_authenticate (3),
.BR pam.conf (4)

159
cde/lib/pam/man/man3/pam_sm_chauthtok.3 Normal file
View File

@@ -0,0 +1,159 @@
.\" $XConsortium: pam_sm_chauthtok.3 /main/5 1996/10/29 15:20:04 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.nr X
.TH pam_sm_chauthtok 3 "9 Jan 1996"
.SH NAME
pam_sm_chauthtok
\- Service provider implementation for pam_chauthtok
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
#include <security/pam_modules.h>
.ft
.fi
.LP
.BI "int pam_sm_chauthtok(pam_handle_t " "*pamh" ,
.BI "const int " "flags");
.SH DESCRIPTION
.IX "pam_authtok" "" "\fLpam_authtok\fP \(em request changing authentication token"
In response to a call to
.BR pam_chauthtok (3)
the PAM framework calls
.BR pam_sm_chauthtok (3)
from the modules listed in the
.BR pam.conf (4)
file.
The password management provider
supplies the back-end functionality for
this interface function.
.PP
.B pam_sm_chauthtok(\|)
changes the authentication token associated with a
particular user referenced by the authentication handle,
.IR pamh.
.LP
The following flag may be passed in to
.BR pam_chauthtok(\|) :
.RS
.IP PAM_SILENT 30
The password service should not generate any messages
.IP PAM_CHANGE_EXPIRED_AUTHTOK 30
The password service should only update those passwords that have aged.
If this flag is not passed, the password service should update all passwords.
.IP PAM_PRELIM_CHECK 30
The password service should only perform preliminary checks.
No passwords should be updated.
.IP PAM_UPDATE_AUTHTOK 30
The password service should update passwords
.RE
.LP
Note that PAM_PRELIM_CHECK and PAM_UPDATE_AUTHTOK can not be
set at the same time.
.LP
Upon successful completion of the call, the authentication
token of the user will be ready for change or will be changed
(depending upon the flag)
in accordance with the authentication scheme
configured within the system.
.PP
The
.I argc
argument
represents the number of module options passed in from the configuration file
.BR pam.conf (4).
.I argv
specifies the module options, which are interpreted and processed
by the password management service. Please refer to the specific
module man pages for the various available
.I options.
.LP
It is the responsibility of
.B pam_sm_chauthtok(\|)
to determine if the new password meets certain strength requirements.
.B pam_sm_chauthtok(\|)
may continue to re-prompt the user (for a limited number of times)
for a new password until the password entered
meets the strength requirements.
.LP
Before returning,
.B pam_sm_chauthtok(\|)
should call
.B pam_get_item(\|)
and retrieve both PAM_AUTHTOK
and PAM_OLDAUTHTOK. If both are NULL,
.B pam_sm_chauthtok(\|)
should set them to the new and old passwords
as entered by the user.
.SH NOTES
The
.SM PAM
framework invokes the password services twice. The first time the modules
are invoked with the flag, PAM_PRELIM_CHECK.
During this stage, the password modules should only perform preliminary
checks (ping remote name services to see if they are
ready for updates, for example). If a password module
detects a transient error (remote name service temporarily down, for example)
it should return PAM_TRY_AGAIN to the
.SM PAM
framework, which
will immediately return the error back to the application.
If all password modules pass the preliminary check, the
.SM PAM
framework invokes the password services again with the flag,
PAM_UPDATE_AUTHTOK. During this stage, each password module should
proceed to update the appropriate password. Any error will again be
reported back to application.
.LP
If a service module receives the flag, PAM_CHANGE_EXPIRED_AUTHTOK,
it should check whether the password has aged or expired.
If the password has aged or expired,
then the service module should proceed to update the password.
If the status indicates that the
password has not yet aged/expired, then the password module
should return PAM_IGNORE.
.LP
If a user's password has aged or expired, a
.SM PAM
account module could save this information as state
in the authentication handle,
pamh, using
.BR pam_set_data(\|) .
The related password management module could retreive this information
using
.B pam_get_data(\|)
to determine whether or not it should prompt
the user to update the password for this particular module.
.SH "RETURN VALUES"
.PP
Upon successful completion, PAM_SUCCESS must be returned.
The following values may also be returned:
.RS
.IP PAM_PERM_DENIED 34
No permission
.IP PAM_AUTHTOK_ERR 34
Authentication token manipulation error
.IP PAM_AUTHTOK_RECOVERY_ERR 34
Old authentication token cannot be recovered
.IP PAM_AUTHTOK_LOCK_BUSY 34
Authentication token lock busy
.IP PAM_AUTHTOK_DISABLE_AGING 34
Authentication token aging disabled
.IP PAM_USER_UNKNOWN 34
User unknown to password service
.IP PAM_TRY_AGAIN 34
Preliminary check by password service failed
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_chauthtok (3),
.BR pam.conf (4)

92
cde/lib/pam/man/man3/pam_sm_open_session.3 Normal file
View File

@@ -0,0 +1,92 @@
.\" $XConsortium: pam_sm_open_session.3 /main/5 1996/10/29 15:20:14 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.nr X
.TH pam_sm_open_session 3 "9 Jan 1996"
.SH NAME
pam_sm_open_session, pam_sm_close_session
\- Service provider implementation for pam_open_session and pam_close_session respectively
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
#include <security/pam_modules.h>
.ft
.fi
.LP
.BI "int pam_sm_open_session(pam_handle_t " "*pamh" ,
.BI "int " "flags" ,
.BI "int " "argc",
.BI "const char **" "argv" );
.LP
.BI "int pam_sm_close_session(pam_handle_t " "*pamh" ,
.BI "int " "flags" ,
.BI "int " "argc",
.BI "const char **" "argv" );
.SH DESCRIPTION
.IX "pam_sm_open_session" "" "\fLpam_open_session\fP \(em session management"
In response to a call to
.RB pam_open_session (3)
and
.BR pam_close_session (3),
the PAM framework calls
.B pam_sm_open_session(\|)
and
.BR pam_sm_close_session(\|) ,
respectively from the modules listed in the
.BR pam.conf (4)
file. The session management provider supplies the back-end functionality for
this interface function.
.PP
.B pam_sm_open_session(\|)
is called to initiate session management.
.B pam_sm_close_session(\|)
is invoked when a session has terminated.
The argument
.IR pamh
is an authentication handle.
The following flag may be set in the
.IR flags
field:
.RS
.IP PAM_SILENT 16
Session service should not generate any messages
.RE
The
.I argc
argument
represents the number of module options passed in from the configuration file
.BR pam.conf (4).
.I argv
specifies the module options, which are interpreted and processed
by the session management service. If an unknown option is passed in,
an error should be logged through
.BR syslog (3)
and the option ignored.
.SH "RETURN VALUES"
.PP
Upon successful completion, PAM_SUCCESS should be returned.
The following values may also be returned upon error:
.RS
.IP PAM_SESSION_ERR 22
Can not make/remove an entry for the specified session
.IP PAM_IGNORE 22
Ignore underlying session module regardless of whether the control
flag is
.I required, optional
or
.I sufficient
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_open_session (3),
.BR syslog (3),
.BR pam.conf (4)

114
cde/lib/pam/man/man3/pam_sm_setcred.3 Normal file
View File

@@ -0,0 +1,114 @@
.\" $XConsortium: pam_sm_setcred.3 /main/5 1996/10/29 15:20:23 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.nr X
.TH pam_sm_setcred 3 "9 Jan 1996"
.SH NAME
pam_sm_setcred \- Service provider implementation for pam_setcred
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
#include <security/pam_modules.h>
.ft
.fi
.LP
.BI "int pam_sm_setcred(pam_handle_t " "*pamh" ,
.BI "int " "flags" ,
.BI "int " "argc",
.BI "const char **" "argv" );
.SH DESCRIPTION
.IX "pam_setcred" "" "\fLpam_setcred\fP \(em request setting credentials"
In response to a call to
.BR pam_set_cred (3),
the PAM framework calls
.B pam_sm_setcred(\|)
from the modules listed in the
.BR pam.conf (4)
file. The authentication provider supplies the back-end functionality for
this interface function.
.PP
.B pam_sm_setcred(\|)
is called to set the credentials of the current user
associated with the authentication handle,
.IR pamh.
The following flags may be set in the
.IR flags
field. Note that the first four flags are mutually exclusive:
.RS
.IP "PAM_CRED_ESTABLISH" 26
Set user credentials for the authentication service
.IP "PAM_CRED_DELETE" 26
Delete user credentials associated with the authentication service
.IP "PAM_CRED_REINITIALIZE" 26
Reinitialize user credentials
.IP "PAM_CRED_REFRESH" 26
Extend lifetime of user credentials
.IP "PAM_SILENT" 26
Authentication service should not generate messages
.RE
.PP
If none of these flags are set, PAM_CRED_ESTABLISH is used as
the default.
.PP
The
.I argc
argument
represents the number of module options passed in from the configuration file
.BR pam.conf (4).
.I argv
specifies the module options, which are interpreted and processed
by the authentication service. If an unknown option is passed to the
module, an error should be logged and the option ignored.
.LP
If the PAM_SILENT flag is not set, then
.B pam_sm_setcred(\|)
should print any failure status from the corresponding
.B pam_sm_authenticate(\|)
function using the conversation function.
.PP
The authentication status (success or reason for failure)
is saved as module-specific state in the authentication
handle by the authentication module.
The status should be retreived using
.BR pam_get_data(\|) ,
and used to determine if user credentials should be set.
.SH NOTES
.PP
.B pam_sm_setcred(\|)
is passed the same module options that are used by
.BR pam_sm_authenticate(\|) .
.SH "RETURN VALUES"
.PP
Upon successful completion, PAM_SUCCESS should be returned.
The following values may also be returned upon error:
.RS
.IP PAM_CRED_UNAVAIL 25
Underlying authentication service can not retrieve user credentials
.IP PAM_CRED_EXPIRED 25
User credentials have expired
.IP PAM_USER_UNKNOWN 25
User unknown to the authentication service
.IP PAM_CRED_ERR 25
Failure in setting user credentials
.IP PAM_IGNORE 25
Ignore underlying authentication module regardless of whether the
control flag is
.I required, optional
or
.I sufficient
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_authenticate (3),
.BR pam_setcred (3),
.BR pam_sm_authenticate (3),
.BR pam.conf (4)

223
cde/lib/pam/man/man3/pam_start.3 Normal file
View File

@@ -0,0 +1,223 @@
.\" $XConsortium: pam_start.3 /main/5 1996/10/29 15:20:32 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" Don't forget to enter .IX index entries for each function.
.nr X
.TH pam_start 3 "9 Jan 1996"
.SH NAME
pam_start, pam_end
\- authentication transaction routines for PAM
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.BI "int pam_start(const char *" "service" ,
.BI "const char *" "user" ,
.BI "const struct pam_conv *" "pam_conv" ,
.BI "pam_handle_t " "**pamh");
.LP
.BI "int pam_end(pam_handle_t *" "pamh" ,
.BI "int" " status" );
.SH DESCRIPTION
.IX "pam_start" "" "\fLpam_start\fP \(em initiate authentication transaction"
.B pam_start(\|)
is called to initiate an authentication transaction.
.B pam_start(\|)
takes as arguments the name of the current service,
.IR service,
the name of the user to be authenticated,
.IR user,
the address of the conversation structure,
.IR pam_conv,
and the address of a variable to be assigned the authentication handle,
.IR pamh.
Upon successful completion,
.IR pamh
will refer to a
.SM PAM
handle for use with subsequent calls to the authentication library.
.LP
The pam_conv structure,
.IR pam_conv,
contains the address of the conversation function provided by the
application. The underlying
.SM PAM
service module invokes this function
to output information to and retrieve input from the user.
The
.IR pam_conv
structure has the following entries:
.RS
.PP
.nf
.ft 3
struct pam_conv {
int (\(**conv)(); /* Conversation function */
void \(**appdata_ptr; /* Application data */
};
.ft 1
.fi
.RE
where
.RS
.PP
.nf
.ft 3
int conv(int num_msg,
const struct pam_message **msg, struct pam_response **resp,
void *appdata_ptr);
.ft 1
.fi
.RE
.LP
The function
.B conv(\|)
is called by a service module to hold a
.SM PAM
conversation with the application or user.
For window applications, the application can create a new
pop-up window to be used by the interaction.
.PP
The parameter
.IR num_msg
is the number of messages associated with the call.
The parameter
.IR msg
is a pointer to an array of length
.IR num_msg
of the
.IR pam_message
structure.
.PP
The structure
.IR pam_message
is used to pass prompt, error message, or any text
information from the authentication service to the application or user.
It is the responsibility of the
.SM PAM
service modules to localize the messages.
The memory used by
.IR pam_message
has to be allocated and freed by the PAM modules.
The
.IR pam_message
structure has the following entries:
.RS
.PP
.nf
.ft 3
struct pam_message{
int msg_style;
char \(**msg;
};
.ft 1
.fi
.RE
.PP
The message style,
.IR msg_style,
can be set to one of the following values:
.RS
.PP
.nf
.ft 1
.IP PAM_PROMPT_ECHO_OFF 26
prompt user, disabling echoing of response
.IP PAM_PROMPT_ECHO_ON 26
prompt user, enabling echoing of response
.IP PAM_ERROR_MSG 26
print error message
.IP PAM_TEXT_INFO 26
print general text information
.\"};
.ft 1
.fi
.RE
.PP
The maximum size of the message and the response string is
PAM_MAX_MSG_SIZE defined in
.BR <security/pam.appl.h> .
.PP
The structure
.I pam_response
is used by the authentication service to get the user's response back from
the application or user.
The storage used by
.I pam_response
has to be allocated by the application and freed by the PAM modules.
The
.I pam_response
structure has the following entries:
.RS
.PP
.nf
.ft 3
struct pam_response{
char \(**resp;
int resp_retcode; /* currently not used, should be set to 0 */
};
.ft 1
.fi
.RE
.LP
It is the responsibility of the conversation function
to strip off newline characters for
.SM PAM_PROMPT_ECHO_OFF
and
.SM PAM_PROMPT_ECHO_ON
message styles, and to add
newline characters (if appropriate) for
.SM PAM_ERROR_MSG
and
.SM PAM_TEXT_INFO
message styles.
.PP
.I appdata_ptr
is an application data pointer which is passed by the application
to the PAM service modules.
Since the PAM modules pass it back through the conversation function,
the applications can use this pointer to point to any application-specific
data.
.LP
.B pam_end(\|)
is called to terminate the authentication transaction identified
by
.I pamh
and to free any
storage area allocated by the authentication module.
The argument,
.IR status ,
is passed to the
.I cleanup(|\)
function stored within the pam handle, and is used to determine
what module specific state must be purged. A cleanup function
is attached to the handle by the underlying
.SM PAM
modules through a call to
.BR pam_set_item (3)
to free module specific data.
.SH "RETURN VALUES"
.PP
Refer to
.BR pam (3)
for information on error related return values.
.SH "SEE ALSO"
.BR pam_authenticate (3),
.BR pam_set_item (3),
.BR pam_acct_mgmt (3),
.BR pam_open_session (3),
.BR pam_setcred (3),
.BR pam_chauthtok (3),
.BR pam_strerror (3),
.BR pam (3)

60
cde/lib/pam/man/man3/pam_strerror.3 Normal file
View File

@@ -0,0 +1,60 @@
.\" $XConsortium: pam_strerror.3 /main/5 1996/10/29 15:20:47 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.nr X
.TH pam_strerror 3 "9 Jan 1996"
.SH NAME
pam_strerror \- get PAM error message string
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.BI "const char *pam_strerror(pam_handle_t" "*pamh" ,
.BI "int " "errnum" );
.SH DESCRIPTION
.IX "string operation" "get PAM error message string" "" "get PAM error message string \(em \fLpam_strerror\fP"
.IX "PAM error messages" "get string" "" "get string \(em \fLpam_strerror\fP"
.B pam_strerror(\|)
maps the
.SM PAM
error number in
.I errnum
to a
.SM PAM
error message string, and returns a pointer to that string.
The application should not free or modify the string returned.
.LP
The
.I pamh
arguement is the
.SM PAM
handle obtained by a prior call to
.BR pam_start(\|) .
If
.B pam_start(\|)
returns an error, a
.SB NULL
.SM PAM
handle should be passed.
.SH ERRORS
.LP
.B pam_strerror(\|)
returns
.SB NULL
if
.I errnum
is out-of-range.
.SH "SEE ALSO"
.BR pam (3),
.BR pam_start (3)