man pages section 5: Standards, Environments, and Macros

pam_unix(5)

NAME

pam_unix- authentication, account, session, and password management PAM modules for UNIX

SYNOPSIS

/usr/lib/security/pam_unix.so.1

DESCRIPTION

The UNIX service module for PAM, /usr/lib/security/pam_unix.so.1, provides functionality for all four PAM modules: authentication, account management, session management and password management. The pam_unix.so.1 module is a shared object that can be dynamically loaded to provide the necessary functionality upon demand. Its path is specified in the PAM configuration file.

Unix Authentication Module

The UNIX authentication component provides functions to verify the identity of a user, (pam_sm_authenticate()) and to set user specific credentials (pam_sm_setcred()). pam_sm_authenticate() compares the user entered password with the password from the UNIX password database. If the passwords match, the user is authenticated. If the user also has secure RPC credentials and the secure RPC password is the same as the UNIX password, then the secure RPC credentials are also obtained.

The following options may be passed to the UNIX service module:

check_retries

If this option is passed, the UNIX authentication module maintains a count of failed logins per user. This count is kept in the lowest byte of the flag field in the shadow database. When this count exceeds or equals the allowed number of retries as defined by RETRIES in /etc/default/login (or a default value of 5), the user's account is locked, and the module returns PAM_MAXTRIES. The account is not locked if the user has lock_after_retries set to no in his user_attr entry, or if LOCK_AFTER_RETRIES is set to NO in /etc/security/policy.conf. If the count is less than RETRIES (or the default value of 5), the module returns PAM_AUTH_ERR. If authentication succeeds, the count is reset to 0. When the user gets a new password, the account is unlocked and the failed login count is reset to 0. This option works for local files and NIS+ only.

debug

syslog(3C) debugging information at LOG_DEBUG level.

nowarn

Turn off warning messages.

use_first_pass

It compares the password in the password database with the user's initial password (entered when the user authenticated to the first authentication module in the stack). If the passwords do not match, or if no password has been entered, it quits and does not prompt the user for a password. This option should only be used if the authentication service is designated as optional in the pam.conf configuration file.

try_first_pass

It compares the password in the password database with the user's initial password (entered when the user authenticated to the first authentication module in the stack). If the passwords do not match, or if no password has been entered, prompt the user for a password. When prompting for the current password, the UNIX authentication module will use the prompt, "password:" unless one of the following scenarios occur:

The option try_first_pass is specified and the password entered for the first module in the stack fails for the UNIX module.
The option try_first_pass is not specified, and the earlier authentication modules listed in the pam.conf file have prompted the user for the password.

In these two cases, the UNIX authentication module will use the prompt "SYSTEM password:". The pam_sm_setcred() function sets user specific credentials. If the user had secure RPC credentials, but the secure RPC password was not the same as the UNIX password, then a warning message is printed. If the user wants to get secure RPC credentials, then keylogin(1) needs to be run.

Unix Account Management Module

The UNIX account management component provides a function to perform account management, pam_sm_acct_mgmt(). The function retrieves the user's password entry from the UNIX password database and verifies that the user's account and password have not expired. The following options may be passed in to the UNIX service module:

debug: syslog(3C) debugging information at LOG_DEBUG level.
nowarn: Turn off warning messages.

Unix Session Management Module

The UNIX session management component provides functions to initiate pam_sm_open_session() and terminate pam_sm_close_session() UNIX sessions. For UNIX, pam_open_session updates the /var/adm/lastlog file. The account management module reads this file to determine the previous time the user logged in. The following options may be passed in to the UNIX service module:

debug: syslog(3C) debugging information at LOG_DEBUG level.
nowarn: Turn off warning messages. pam_close_session is a null function.

Unix Password Management Module

The UNIX password management component provides a function to change passwords pam_sm_chauthtok() in the UNIX password database. This module must be required in pam.conf. It cannot be optional or sufficient. The following options may be passed in to the UNIX service module:

debug: syslog(3C) Debugging information at LOG_DEBUG level.
nowarn: Turn off warning messages.
use_first_pass: It compares the password in the password database with the user's old password (entered to the first password module in the stack). If the passwords do not match, or if no password has been entered, it quits and does not prompt the user for the old password. It also attempts to use the new password (entered to the first password module in the stack) as the new password for this module. If the new password fails, it quits and does not prompt the user for a new password.
try_first_pass: It compares the password in the password database with the user's old password (entered to the first password module in the stack). If the passwords do not match, or if no password has been entered, it prompts the user for the old password. It also attempts to use the new password (entered to the first password module in the stack) as the new password for this module. If the new password fails, it prompts the user for a new password. If the user's password has expired, the UNIX account module saves this information in the authentication handle using pam_set_data(), with a unique name, SUNW_UNIX_AUTHOK_DATA. The UNIX password module retrieves this information from the authentication handle using pam_get_data() to determine whether or not to force the user to update the user's password.

ATTRIBUTES

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

`ATTRIBUTE TYPE`	`ATTRIBUTE VALUE`
MT Level	MT-Safe with exceptions

SUMMARY OF TRUSTED SOLARIS CHANGES

The Trusted Solaris environment adds the check_retries option for the UNIX authentication module.

SunOS 5.8 Reference Manual

keylogin(1), pam(3PAM), pam_authenticate(3PAM), pam_setcred(3PAM), syslog(3C), libpam(3LIB), pam.conf(4), attributes(5)

NOTES

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

SunOS 5.8 Last Revised 22 Jun 2000