Pam error codes

������������� ������� ��������� ��������� ���������� (man-��)

pam (3)

BSD mandoc
 

NAME

pam_acct_mgmt

 
pam_authenticate

 
pam_chauthtok

 
pam_close_session

 
pam_end

 
pam_get_data

 
pam_get_item

 
pam_get_user

 
pam_getenv

 
pam_getenvlist

 
pam_open_session

 
pam_putenv

 
pam_set_data

 
pam_set_item

 
pam_setcred

 
pam_start

 
pam_strerror

 - Pluggable Authentication Modules Library

 

LIBRARY

Lb libpam

 

SYNOPSIS

   #include <security/pam_appl.h>

int
pam_acct_mgmt (pam_handle_t *pamh int flags);

int
pam_authenticate (pam_handle_t *pamh int flags);

int
pam_chauthtok (pam_handle_t *pamh int flags);

int
pam_close_session (pam_handle_t *pamh int flags);

int
pam_end (pam_handle_t *pamh int status);

int
pam_get_data (const pam_handle_t *pamh const char *module_data_name const void **data);

int
pam_get_item (const pam_handle_t *pamh int item_type const void **item);

int
pam_get_user (pam_handle_t *pamh const char **user const char *prompt);

const char *
pam_getenv (pam_handle_t *pamh const char *name);

char **
pam_getenvlist (pam_handle_t *pamh);

int
pam_open_session (pam_handle_t *pamh int flags);

int
pam_putenv (pam_handle_t *pamh const char *namevalue);

int
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));

int
pam_set_item (pam_handle_t *pamh int item_type const void *item);

int
pam_setcred (pam_handle_t *pamh int flags);

int
pam_start (const char *service const char *user const struct pam_conv *pam_conv pam_handle_t **pamh);

const char *
pam_strerror (const pam_handle_t *pamh int error_number);

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.
 

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.

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.

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.

The functionality embodied by PAM is divided into six primitives
grouped into four facilities: authentication, account management,
session management and password management.
 

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
pam_conv3

for details.
 

Initialization and Cleanup

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

The
pam_end ();

function releases all resources associated with the specified context,
and can be called at any time to terminate a PAM transaction.
 

Storage

The
pam_set_item ();

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

The
pam_set_data ();

and
pam_get_data ();

functions manage named chunks of free-form data, generally used by
modules to store state from one invocation to another.
 

Authentication

There are two authentication primitives:
pam_authenticate ();

and
pam_setcred (.);

The former authenticates the user, while the latter manages his
credentials.
 

Account Management

The
pam_acct_mgmt ();

function enforces policies such as password expiry, account expiry,
time-of-day restrictions, and so forth.
 

Session Management

The
pam_open_session ();

and
pam_close_session ();

functions handle session setup and teardown.
 

Password Management

The
pam_chauthtok ();

function allows the server to change the user’s password, either at
the user’s request or because the password has expired.
 

Miscellaneous

The
pam_putenv (,);

pam_getenv ();

and
pam_getenvlist ();

functions manage a private environment list in which modules can set
environment variables they want the server to export during the
session.

The
pam_strerror ();

function returns a pointer to a string describing the specified PAM
error code.
 

RETURN VALUES

The following return codes are defined by
In security/pam_constants.h :

Bq Er PAM_ABORT

General failure.

Bq Er PAM_ACCT_EXPIRED

User account has expired.

Bq Er PAM_AUTHINFO_UNAVAIL

Authentication information is unavailable.

Bq Er PAM_AUTHTOK_DISABLE_AGING

Authentication token aging disabled.

Bq Er PAM_AUTHTOK_ERR

Authentication token failure.

Bq Er PAM_AUTHTOK_EXPIRED

Password has expired.

Bq Er PAM_AUTHTOK_LOCK_BUSY

Authentication token lock busy.

Bq Er PAM_AUTHTOK_RECOVERY_ERR

Failed to recover old authentication token.

Bq Er PAM_AUTH_ERR

Authentication error.

Bq Er PAM_BUF_ERR

Memory buffer error.

Bq Er PAM_CONV_ERR

Conversation failure.

Bq Er PAM_CRED_ERR

Failed to set user credentials.

Bq Er PAM_CRED_EXPIRED

User credentials have expired.

Bq Er PAM_CRED_INSUFFICIENT

Insufficient credentials.

Bq Er PAM_CRED_UNAVAIL

Failed to retrieve user credentials.

Bq Er PAM_DOMAIN_UNKNOWN

Unknown authentication domain.

Bq Er PAM_IGNORE

Ignore this module.

Bq Er PAM_MAXTRIES

Maximum number of tries exceeded.

Bq Er PAM_MODULE_UNKNOWN

Unknown module type.

Bq Er PAM_NEW_AUTHTOK_REQD

New authentication token required.

Bq Er PAM_NO_MODULE_DATA

Module data not found.

Bq Er PAM_OPEN_ERR

Failed to load module.

Bq Er PAM_PERM_DENIED

Permission denied.

Bq Er PAM_SERVICE_ERR

Error in service module.

Bq Er PAM_SESSION_ERR

Session failure.

Bq Er PAM_SUCCESS

Success.

Bq Er PAM_SYMBOL_ERR

Invalid symbol.

Bq Er PAM_SYSTEM_ERR

System error.

Bq Er PAM_TRY_AGAIN

Try again.

Bq Er PAM_USER_UNKNOWN

Unknown user.

SEE ALSO

openpam(3),

pam_acct_mgmt3,

pam_authenticate3,

pam_chauthtok3,

pam_close_session3,

pam_conv3,

pam_end3,

pam_get_data3,

pam_getenv3,

pam_getenvlist3,

pam_get_item3,

pam_get_user3,

pam_open_session3,

pam_putenv3,

pam_setcred3,

pam_set_data3,

pam_set_item3,

pam_start3,

pam_strerror3

STANDARDS

«X/Open Single Sign-On Service (XSSO) — Pluggable Authentication Modules»
«June 1997»

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
(«CBOSS»

)

as part of the DARPA CHATS research program.

Index

NAME

LIBRARY

SYNOPSIS

DESCRIPTION

Terminology

Conversation

Initialization and Cleanup

Storage

Authentication

Account Management

Session Management

Password Management

Miscellaneous

RETURN VALUES

SEE ALSO

STANDARDS

AUTHORS

X/Open Single Sign-on Service (XSSO) -<br>
Pluggable Authentication Modules

X/Open Single Sign-on Service (XSSO) —
Pluggable Authentication Modules

Copyright © 1997 The Open Group

This chapter describes the data types and constants used by the PAM
functions.
It also explains calling conventions for these functions.

Structured Data Types

Wherever these PAM-API C-bindings describe structured data, only
fields that must be provided by all PAM-API implementations are
documented. Individual implementations may provide additional
fields, either for internal use within PAM-API routines, or for
use by non-portable applications.

Messages

The structure
pam_message
is used to pass prompt, error message,
or any text information from the PAM services to the application or
user. It is the responsibility of the PAM service modules to localize
the messages. The memory used by pam_message has to be allocated
and freed by the PAM modules. The pam_message structure has the
following structure:



 

struct pam_message{
    int    msg_style;
    char  *msg;        /* message */
};

The msg_style can be set to a number of values. See

Message Constants
.
The structure
pam_response
is used to get the response back from the application or user.
The storage used by pam_response has to be allocated by the
application and freed by the PAM modules.
It is defined as:



 

struct pam_response{
    char  *response;
    int    resp_retcode;
};

Call Back Information

The structure
pam_conv
contains the address of the conversation function provided by the
application. The underlying PAM service module invokes this function to
output information to and retrieve input from the user.
The pam_conv structure has the following entries:



 

struct pam_conv{
    int (*conv) (int, struct pam_message **,
          struct pam_response **, void *);
    void *appdata_ptr;
};

    where
    int conv(int num_msg,
             const struct pam_message **msg, struct pam_response **resp,
             void *appdata_ptr);

The function,
conv()
is called by a service module to hold a 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.

The parameter, num_msg is the number of messages associated with
the call. The parameter, msg, is a pointer to an array of
length num_msg of the pam_message structure.

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.

Opaque Data Types

pam_handle

This is opaque to the caller and returned to the caller upon initiation of
a PAM session.
It is subsequently passed as a parameter to each PAM-API call.

Status Values

One or more status codes are returned by each PAM-API routine.
An implementation of PAM functions shall return PAM_SUCCESS and other
status values appropriate for the implementation of the function.
The characteristics of a particular implementation may make some
status returns inappropriate for that implementation.

PAM Status Codes

PAM-API routines return PAM status codes as their
int

function value. These codes indicate major status errors that are
independent of the underlying mechanism used to provide the
security service.

Table: Routine Errors

Constants

The table below sets out the constants defined by the specification,
and the value to which they are set.

Table: Message Constants

Flags

The table below sets out the flags defined by the specification,
and the value to which they are set.

Table: Flags

Item_type

The table below sets out the item_types defined by the specification,
and the value to which they are set.

Table: Item Types

PAM Configuration Entry Constants

Each entry has the following format:



<service_name> <module_type> <control_flag> <module_path> <options>

An entry commencing with a «#» character will be ignored.

The following subsections define the string constants that are used
within a PAM configuration entry.

Service Name

The service_name denotes the service (for example, login,
dtlogin, or rlogin).
The service name is defined by the supplier of the application that is
calling PAM.

The keyword, other, indicates the module that should be
used for all applications which have not been included in the
PAM configuration under a specific service name.
The other keyword can also be used if all services using the same
module_type have the same requirements.

Module Type

The PAM framework supports five module types.
These are listed in

Module Type
.

Table: Module Type

Control Flags

Table: Control Flags

The PAM framework processes each service module in the stack.

If a requisite module fails the PAM framework immediately returns
to the application with the error returned by the requisite module
and stops processing the module stack.

If all requisite and required modules in the stack
succeed, then success is returned (optional and sufficient
error values are ignored).

If one or more required modules fail, then the error value
from the first required module that failed is returned.

If none of the service modules in the stack are designated as
required or requisite, then the PAM framework requires
that at least one optional or sufficient module succeed.
If all fail then the error value from the first service module
in the stack is returned.

The exception to the above is caused by the sufficient flag.
If a service module that is designated as sufficient
succeeds, then the PAM framework immediately returns success
to the application (all subsequent service modules, even
required and requisite ones, in the stack are
ignored), given that all prior required and requisite
modules have also succeeded.
If a prior required
module failed, then the error value from that module is returned.

If a module does not exist or cannot be opened,
then the entry is ignored.

Module Path

The module_path field specifies the pathname to a shared library
object which implements the service functionality.
If the pathname is not absolute, it is assumed to be
relative to an implementation-defined base directory.

The PAM configuration syntax does not dictate either the name or the
location of the service specific modules. The convention, however, is the
following:



/usr/lib/security/pam_<service_name>_<module_name>.<extension>

Options

The options field is used by the PAM
framework layer to pass module specific options to the modules. It is
up to the module to parse and interpret the options. This field can
be used by the modules to turn on debugging or to pass any module
specific parameters such as a TIMEOUT value. It can also be used to
support unified login. The options supported by
a modules shall be documented by the supplier of the module.

Why not acquire a nicely bound hard copy?

Click here to return to the publication details or order a copy
of this publication.