Plugable Authentication Modules

Plugable Authentication Modules

Copyright 2006, Sun Microsystems, Inc

Policy Synopsis

Identification, Authentication or Re-authentication, Password Change requires the use of PAM

Contents

• Applicability
• Audience
• Background
• Policy
• Documentation
• Advice
• Appeals
• CaseHistory
• ManPages
• References
• PolicyChangeLog

Overview

Applicability

All Sun programs which are delivered with, installed on, or executed on Solaris/Linux which perform user identification and authentication, re-authentication, user session establishment or password change of Solaris/Linux user accounts

Audience

ARCs, Project teams

Background

The general concept of this best practice is that all Sun programs which use PAM (see pam(3PAM)) should do so in a uniform manner. PAM provides for a set of service modules (see pam_sm(3PAM)) which implement the semantics of the PAM interfaces. These service modules may be delivered with Solaris or may come from ISVs or local sites. The local site administrator is responsible for building an appropriate pam.conf(4) file to define the site's policy. Assumptions cannot be made on what the configured service modules actually do, only that they will return various success and failure codes to the application.

Furthermore, PAM service modules can communicate with the user through PAM conversation call backs (see pam_start(3PAM)). Applications need to ensure that communication with the user is free from alteration. Applications can make no assumptions relative to this communication other than it is already in the application's locale. They must not interpret the information content of messages supplied to the conversation functions. Applications should code conversation functions to communicate whatever comes from the PAM service modules and to return user input as requested.

Messages may contain multiple lines denoted by the newline character ('\n') and other C language formatting characters such as alert (bell, '\a'), backspace ('\b'), and tab ('\t'). When processing prompting messages (PAM_PROMPT_ECHO_OFF, PAM_PROMPT_ECHO_ON), a final newline should not be output. When processing error (PAM_ERROR_MSG) and informational (PAM_TEXT_INFO) messages, a final newline should be output.

Policy

• Applies to Software that runs on Solaris that does any form of authentication, re-authentication, or password change.
• Authority PSARC
• Effective Solaris 2.6
• Policy PAM provides a set of interfaces that all Solaris programs which do user identification and authentication, or re-authentication, or user session establishment, or user password change of Solaris user accounts are required to use.
• Details When using the PAM interfaces outlined below, a single "PAM session" should be maintained across the calls. pam_start() returns a "PAM handle", which defines the PAM session. pam_end() ends the PAM session and frees the PAM resources.

  The program calling PAM interfaces must be sufficiently privileged to do the requested operations (authentication, password change, process credential manipulation, audit state initialization).

  User Identification and Authentication (or re-authentication)

  The interfaces necessary to use whenever authenticating a user are:

  • Initialization
    pam_start()

    pam_set_item()

    As needed, various PAM items should be set. In particular, PAM_TTY should reflect the terminal through which the user communication takes place; PAM_RHOST should reflect the remote host from which the user is entering the system (such as from a TELNET or XDMCP request); PAM_REPOSITORY should reflect any user account repository restrictions; PAM_RESOURCE should reflect any specific resource controls.

  • Authentication
    pam_authenticate()

    The PAM_DISALLOW_NULL_AUTHTOK flag must be passed, if the application configuration file specifies whether null passwords are disallowed. If the application does not have a configuration file which has a null password configuration option, /etc/default/login:PASSREQ=YES, must be used.

    pam_acct_mgmt()

    Similarly, if the PAM_DISALLOW_NULL_AUTHTOK flag would be passed to pam_authenticate above, it must also be passed here.

    If pam_acct_mgmt() returns PAM_SUCCESS, the user is authenticated.

    If pam_acct_mgmt() returns PAM_NEW_AUTHTOK_REQD, then pam_chauthtok() should be called to allow the user to change password. See Password Change below for more details. Following a correct password change, the user is authenticated.

    If pam_acct_mgmt() returns any other value, then the authentication has failed and the application should terminate the PAM session and take action consistent with an authentication failure. 

  • Credential Establishment

    pam_setcred() should be called with the PAM_ESTABLISH_CRED flag if a new user session is being established (such as login would do).

    pam_setcred() should be called with the PAM_REFRESH_CRED flag if the user session is the renewal of an existing session (such as re-authentication unlocking an existing session).

    pam_setcred() should be called with the PAM_REINITIALIZE_CRED flag if the session is changing the credentials (such as su or role assumption). 

  • Session Establishment

    pam_open_session() should be called if a new user session is being established (such as login would do). 

  • Environment Establishment

    pam_getenvlist() should be called and the returned environment merged with the environment being established if a new environment is being established (such as login would do).

  • Termination

    pam_end() should be called to cleanup the storage associated with the PAM session when the entire process is complete.

    For a successful process, the PAM_SUCCESS status should be passed.

    For an unsuccessful process, the status returned by the failed PAM interface should be passed.

  Password Change

  The interfaces necessary to use when changing a user's password (such as passwd(1) would do) are:

  pam_start()

  pam_set_item() - as needed

  pam_authenticate() - to authenticate the old password

  pam_acct_mgmt() - to validate the account

  Only PAM_SUCCESS and PAM_NEW_AUTHTOK_REQD are valid return codes to continue with password change. Any other value, should be treated as an authentication failure and the application should terminate the PAM session and take action consistent with an authentication failure.

  pam_chauthtok() - to change the new password

  A return code of PAM_SUCCESS indicates a successful password change.

  Return codes PAM_AUTHTOK_LOCK_BUSY and PAM_TRY_AGAIN indicates temporary conditions that are not a password change error and pam_chauthtok() should be retried later.

  A return code of PAM_AUTHTOK_ERR indicates a user error that should count against the number of tries the user is given before the password change is considered a password change failure.

  All other return codes indicate a fatal failure and the application should terminate the PAM session and take action consistent with a password change failure.

  pam_end()

  Exported Interfaces

  The service name(s) that pam_start() is invoked with are part of the exported interfaces of programs calling PAM and must be included in ARC review. They are an administrative interface consumed by pam.conf(4). It is suggested that the service name represent the program or function name (e.g., "login" for login(1), "su" for su(1M), "dtlogin" for CDE login, "xlock" for X display xlock(1), "ftp" for in.ftpd(1M)). 

  Documentation

  It is required that the PAM service name(s) and the service module types that are used be documented on the program manual page. Service module types are: authentication, account management, session management, and password management.

Advice

A Word on Auditing

Though not directly part of user identification, authentication, or password change, auditing successful and failed authentication and password change is a requirement of Solaris. See  Solaris Auditing Policy.

Appeals

Discuss during your ARC review.

CaseHistory

ManPages

References

 Code sample of a tty based PAM conversation function

PolicyChangeLog