Previous section.

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

Parameter Passing Conventions in PAM

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.

Name Value in Meaning
  Field  
[PAM_SUCCESS] 0 Successful completion.
[PAM_OPEN_ERR] 1 Failure when dynamically loading a service module.
[PAM_SYMBOL_ERR] 2 Symbol not found in service module.
[PAM_SERVICE_ERR] 3 Error in underlying service module.
[PAM_SYSTEM_ERR] 4 System error.
[PAM_BUF_ERR] 5 Memory buffer error.
[PAM_CONV_ERR 6 Conversation failure.
[PAM_PERM_DENIED] 7 The caller does not possess the required authority.
[PAM_MAXTRIES] 8 Maximum number of tries exceeded.
[PAM_AUTH_ERR] 9 Authentication error.
[PAM_NEW_AUTHTOK_REQD] 10 New authentication token required from user.
[PAM_CRED_INSUFFICIENT] 11 Cannot access authentication database because credentials supplied are insufficient.
[PAM_AUTHINFO_UNAVAIL] 12 Cannot retrieve authentication information.
[PAM_USER_UNKNOWN] 13 The user is not known to the underlying account management module.
[PAM_CRED_UNAVAIL] 14 Cannot retrieve user credentials.
[PAM_CRED_EXPIRED] 15 User credentials have expired.
[PAM_CRED_ERR] 16 Failure setting user credentials.
[PAM_ACCT_EXPIRED] 17 User account has expired.
[PAM_AUTHTOK_EXPIRED] 18 Password expired and no longer usable.
[PAM_SESSION_ERR] 19 Cannot initiate/terminate a PAM session.
[PAM_AUTHTOK_ERR] 20 Error in manipulating authentication token.
[PAM_AUTHTOK_RECOVERY_ERR] 21 Old authentication token cannot be recovered.
[PAM_AUTHTOK_LOCK_BUSY] 22 The authentication token lock is busy.
[PAM_AUTHTOK_DISABLE_AGING] 23 Authentication token ageing is disabled.
[PAM_NO_MODULE_DATA] 24 Module data not found.
[PAM_IGNORE] 25 Ignore this module.
[PAM_ABORT] 26 General PAM failure.
[PAM_TRY_AGAIN] 27 Unable to complete operation. Try again.
[PAM_MODULE_UNKNOWN] 28 Module type unknown.
[PAM_DOMAIN_UNKNOWN] 29 Domain unknown.

Table: Routine Errors

Constants

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

Name Value Meaning
[PAM_PROMPT_ECHO_OFF] 1 Echo off when getting response.
[PAM_PROMPT_ECHO_ON] 2 Echo on when getting response.
[PAM_ERROR_MSG] 3 Error message.
[PAM_TEXT_INFO] 4 Textual information.
[PAM_MAX_NUM_MSG] 32 Maximum number of messages passed to the application through the conversation function call.
[PAM_MAX_MSG_SIZE] 512 Maximum size in characters of messages passed to application through the conversation function call.
[PAM_MAX_RESP_SIZE] 512 Maximum size in characters of each response passed from the application through the conversation function call.

Table: Message Constants

Flags

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

Name Value Meaning
General flags    
PAM_SILENT 0x80000000 Switch off messages from service.
Flags for pam_authenticate    
PAM_DISALLOW_NULL_AUTHTOK 0x1 Disallow a NULL authentication token.
Flags for pam_setcred    
PAM_ESTABLISH_CRED 0x1 Set user credentials for the authentication service.
PAM_DELETE_CRED 0x2 Delete user credentials from the authentication service.
PAM_REINITIALISE_CRED 0x4 Reinitialize user credentials.
PAM_REFRESH_CRED 0x8 Extend lifetime of user credentials.
Flags for pam_sm_chauthtok    
PAM_CRED_PRELIM_CHECK 0x1 Preliminary check for update readiness.
PAM_UPDATE_AUTHTOK 0x2 Update authentication token.
Flags for pam_sm_chauthtok and    
pam_chauthtok    
PAM_CHANGE_EXPIRED_AUTHTOK 0x4 Force a change to an expired authentication token.

Table: Flags

Item_type

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

Name Value Meaning
PAM_SERVICE 1 The program service name.
PAM_USER 2 The user name.
PAM_TTY 3 The tty name.
PAM_RHOST 4 The remote host name.
PAM_CONV 5 The conversation structure.
PAM_AUTHTOK 6 The authentication token.
PAM_OLDAUTHTOK 7 The old authentication token.
PAM_RUSER 8 The remote user name.
PAM_USER_PROMPT 9 The user prompt.


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 .

Module_type Module
auth Authentication module.  
account Account management module.  
mapping Mapping module.  
password Password management module.  
session Session management module.  


Table: Module Type

Control Flags


Control Flags
required
sufficient
requisite
optional


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.

Contents Next section Index