PAM

Using the PAM framework

A PAM environment consists of the following components:

the PAM library
applications that link against the PAM library
a PAM configuration file for each application
PAM modules (DLLs) that implement the authentication and authorization mechanisms

PAM provides a framework for you to use within a system; for example, if you use username and password to authenticate users, you can use PAM to prompt for those credentials.

PAM simplifies the task of choosing which algorithm or database to use for authentication. To configure a system that has been configured to use PAM (and make use of the PAM framework), you edit a text file to specify what PAM needs to do.

The framework also simplifies the task of changing which algorithm or database to use. By editing the PAM configuration file to change which shared object file the PAM library invokes, you can change how your system authenticates users without changing its code.

The OpenPAM framework is integrated with QNX Neutrino to support authentication and identification for the QNX Neutrino utilities that use it.

The login utility is one example of a QNX Neutrino utility that is PAM-aware and supported by the PAM framework. Under the PAM framework, the login command is dependent on the PAM library and loads libpam.so. The PAM library, in turn, opens the PAM modules explicitly referenced in the PAM configuration file.

Adding PAM modules

PAM modules (pam_*.so) are usually located in one or more of the following directories, but they can be kept elsewhere:

/proc/boot
/usr/local/lib
/usr/lib

Note: By default, these paths are searched for PAM modules in this order.

If you plan to keep the PAM modules in a different directory, use the confstr value _CS_PAMLIB to override the default search paths and indicate where to find them. If you override the default directories, you must specify a single path. Multiple search paths are not permitted.

The following example sets a configuration string to indicate where to find the PAM modules:

setconf _CS_PAMLIB /system/lib/pam

Ensure that the permissions of the PAM module paths and the module files themselves exclude write (w) permission for group and other (PAM checks this). The module files should be owned by root.

Configuring PAM

Without the PAM framework in place, a login sequence typically checks /etc/passwd (and checks the shadow file /etc/shadow, if a password is set) to get a user entry and set credentials.

PAM configuration files are usually located in one or more of the following directories, but they may instead be kept elsewhere:

/usr/local/etc/pam.d/
/etc/pam.d/

Note: By default, these paths are searched for PAM configuration files in this order.

If you plan to keep the PAM configuration files in a different directory, use the confstr value _CS_PAMCONF to override the default search paths and indicate where to find them. If you are overriding the default directories, you must specify a single path; multiple search paths are not permitted.

The following example shows how to set a configuration string to indicate where to find the PAM configuration files. The path that you specify must end in a forward slash (/):

setconf _CS_PAMCONF /system/etc/pam.d/

The directory may contain multiple PAM configuration files to support a range of security policies beyond authentication. For example, the login service would look for the configuration file /etc/pam.d/login or /usr/local/etc/pam.d/login if the default paths are used.

If no filename matches the service name (binary name) that the application registered, the service looks instead for a file named other in the search paths for the PAM configuration files.

Configuration commands are stacked in the PAM configuration file to create a chain. They are processed in top-down order by libpam. The configuration file specifies facilities, control flags, modules (shared object files) and optional arguments using the following syntax:

facility control_flag module arguments

For example, the following commands are specified in the PAM configuration file for su:

# Root is allowed to switch to any account without providing a password
auth sufficient pam_rootok.so no_warn
auth requisite pam_qnx.so

account requisite pam_qnx.so

session requisite pam_qnx.so

password requisite pam_qnx.so

You specify the facility with one of the following values:

Facility	Task	Functions
account	Account management	pam_acct_mgmt
password	Password management	pam_chauthtok
auth	Authentication	pam_authenticate and pam_setcred
session	Session management	pam_open_session and pam_close_session

Note: The configuration file for a service that uses PAM must specify a chain for each of the four facilities (auth, account, session, password), even if the service does not make use of a facility. If a chain is missing, pam_start() fails with PAM_SYSTEM_ERR.

The control flags describe what happens if a function of the indicated type succeeds or fails. The PAM facilities each support the following control flags:

Flag	Purpose
binding	If the module fails and is part of a chain, the chain executes and the request is denied. Success breaks the chain.
required	If the module fails and is part of a chain, the chain executes and the request is denied. Success does not break the chain.
requisite	If the module fails and is part of a chain, the chain is broken. Success does not break the chain.
sufficient	Failure does not break the chain. If the module succeeds with no prior failures in the chain, the chain is broken.
optional	The result is ignored.

For example:

auth sufficient pam_rootok.so
auth optional pam_motd.so nullok
auth requisite pam_qnx.so nullok

or

password requisite pam_qnx.so nullok
account requisite pam_qnx.so nullok

Note: PAM attempts authentication in the order that the modules are listed, until the user is authenticated, the options for authentication are exhausted, or there is a terminal failure.

QNX Neutrino supports the following modules:

Module	Description	Example
pam_deny.so	Always returns failure.	Permit all logins but deny any attempts to change a password: /etc/pam.d/passwd: auth requisite pam_permit.so account requisite pam_permit.so session requisite pam_permit.so password requisite pam_deny.so
pam_echo.so	Displays a message. Fails if the message file does not exist.	Print a message from a file: /etc/pam.d/passwd: password optional pam_echo.so file=/`path`/good-password.txt
pam_exec.so	Runs a command. Fails if the command does not run.	Runs a command after each local password change: /etc/pam.d/passwd: password optional pam_exec.so `/path/command`
pam_secpol.so	Determines the type that should be associated with the user and switches to it if a security policy is loaded.	Configure PAM for `ssh`, making use of the allow_mac_policy option (to avoid having to change any configuration based on whether a security policy is used or not): auth requisite pam_qnx.so account requisite pam_qnx.so session requisite pam_qnx.so session requisite pam_secpol.so allow_no_policy password requisite pam_qnx.so
pam_permit.so	Always returns success.	Log in as any user without being prompted for a password: /etc/pam.d/login: auth requisite pam_permit.so account requisite pam_permit.so session requisite pam_permit.so password requisite pam_permit.so
pam_qnx.so	Behavior is comparable to previous QNX versions.	Provide legacy behavior: /etc/pam.d/login: auth requisite pam_qnx.so nullok account requisite pam_qnx.so nullok session requisite pam_qnx.so nullok password requisite pam_qnx.so nullok
pam_rootok.so	Always returns success for the superuser.	Check for UID 0: auth sufficient pam_rootok.so
pam_self.so	Returns success if the target user's UID matches the current UID.	Self authentication: auth requisite pam_self.so
pam_ftpusers.so	Returns success if the user is listed in /etc/ftpusers.	Account management: account required pam_ftpusers.so
pam_group.so	Accepts or rejects users based on their membership in a particular group.	Permit only members of the admin group to login: auth requisite pam_group.so account required pam_group.so group=admin

Note: For a full list of arguments for each module, see the PAM Reference.

Note: If you are using these examples in a Windows environment, make sure that each line in the text file ends with a carriage return as well as a line feed.

Utilities supported by the PAM framework

The following QNX Neutrino utilities are PAM-aware and supported by the PAM framework:

login
ftpd
pppd
passwd
su
sshd
racoon

Note:

The racoon and sshd utilities parse their configuration files before PAM does and require additional configuration to enable PAM.
If you start sshd via inetd, it changes the default configuration that PAM requires and PAM initialization fails. QNX recommends that you avoid this problem by not using inetd to launch sshd.
Alternatively, you can change references to sshd in the PAM configuration file for sshd to in.sshd, to match the changes generated by using inetd.

Integrating PAM functions

The following pseudocode provides an example of how to integrate PAM functions into your system:

pam_start("service name", ...)
     if returns -1 go to "no PAM")
otherwise:
     auth
     acctmgmt 
          chauthtok
     setcred
     opensession
     ...
     closesession
pam_end

The following code provides an example of how to integrate PAM functions into your system for login:

        auth requisite pam_qnx.so
        account requisite pam_qnx.so
        session requisite pam_qnx.so
        password requisite pam_qnx.so

The following code provides an example of how to integrate PAM functions into your system for su:

        # Root is allowed to switch to any account without providing a password
        auth sufficient pam_rootok.so no_warn
        auth requisite pam_qnx.so
        account requisite pam_qnx.so
        session requisite pam_qnx.so
        password requisite pam_qnx.so

Debugging PAM

Because OpenPAM and the PAM modules use syslogd to log errors and debugging messages (when enabled), you can use the following steps to use syslogd for debugging:

Create the configuration file for syslogd: /etc/syslog.conf and add the following line to it:
```
*.*      /dev/slog
```
Note: Use tabs in this new line, not spaces. The syslogd utility can't handle spaces in the configuration file and fails silently.
Run slogger2 to create /dev/slog.
Run syslogd so that syslogd messages are written into /dev/slog.

Now you should be able to see PAM error messages using slog2info.

Enable PAM debugging messages by using the following command to set the OPENPAM_DEBUG environment variable:

export OPENPAM_DEBUG=1

Use one of the following commands to disable debugging messages:

export OPENPAM_DEBUG=0
unset OPENPAM_DEBUG

Troubleshooting

Use this section to troubleshoot your PAM configuration.

Invalid password database

To troubleshoot an invalid password database, check:

file permissions
file ownership
each user present in /etc/passwd must be in /etc/shadow as well and vice versa
each group present in /etc/passwd must be in /etc/group as well

A valid set up looks like this:

File	User	Group	Permissions
/etc/passwd	root	root	0644
/etc/shadow	root	root	0600
/etc/group	root	root	0644

The following commands may help you find the information you need to change:

ls -ld /etc/passwd
ls -ld /etc/shadow
ls -ld /etc/group
cat /etc/passwd
cat /etc/shadow
cat /etc/group

Incorrect permissions or ownership of utilities

To troubleshoot incorrect permissions or ownership of utilities, check that:

utilities are on the target
utilities are setuid user
utilities are owned by user root and group root

A valid set up looks like this:

Utility	User	Group	Permissions
login	root	root	4755
passwd	root	root	4755
su	root	root	4755
sshd	root	root	0755

The following commands may help you find the information that you need to change:

ls -ld /etc
ls -ld /etc/pam.d
ls -l /etc/pam.d
ls -ld /etc/pam.d/login
ls -ld /etc/pam.d/passwd
ls -ld /etc/pam.d/su
ls -ld /etc/pam.d/sshd
ls -ld /etc/pam.d/ftpd
ls -ld /etc/pam.d/sshd
ls -ld /etc/pam.d/racoon
grep auth /etc/pam.d/*
grep password /etc/pam.d/*
grep account /etc/pam.d/*
grep session /etc/pam.d/*

Incorrect PAM configuration files

To troubleshoot incorrect PAM configuration files, check that:

permissions of directories are set correctly
a PAM configuration file exists for the utility
all four PAM chains are listed in the configuration file for the utility

A valid set up looks like this:

Filepath	User	Group	Permissions
/	root	root	0755
/etc	root	root	0755
/etc/pam.d	root	root	0755
/etc/pam.d/*	root	root	0644

The following commands may help you find the information you need to change:

ls -ld /
ls -ld /etc
ls -ld /etc/pam.d
ls -l /etc/pam.d
ls -ld /etc/pam.d/login
ls -ld /etc/pam.d/passwd
ls -ld /etc/pam.d/su
ls -ld /etc/pam.d/sshd
ls -ld /etc/pam.d/ftpd
ls -ld /etc/pam.d/sshd
ls -ld /etc/pam.d/racoon
grep auth /etc/pam.d/*
grep password /etc/pam.d/*
grep account /etc/pam.d/*
grep session /etc/pam.d/*

Missing PAM modules

To troubleshoot missing PAM modules, check that:

directory and module permissions are set correctly
all PAM modules are present

Directory or module	User	Group	Permissions
/	root	root	755
/usr	root	root	755
/usr/lib	root	root	755
/usr/lib/pam_*.so.2	root	root	755

The following commands may help you find which modules are missing and determine which directory permissions need to change:

ls -ld /
ls -ld /usr
ls -ld /usr/lib
ls -ld /usr/lib/pam_deny.so
ls -ld /usr/lib/pam_echo.so
ls -ld /usr/lib/pam_exec.so
ls -ld /usr/lib/pam_ftpusers.so
ls -ld /usr/lib/pam_group.so
ls -ld /usr/lib/pam_permit.so
ls -ld /usr/lib/pam_qnx.so
ls -ld /usr/lib/pam_rootok.so
ls -ld /usr/lib/pam_self.so

Incorrect ownership or permissions when mounting filesystems

When you mount a filesystem that uses mountpoint permissions, make sure that you specify the appropriate directory and module permissions (as described above). For more information, see the description of the mntperms option in the io-blk.so entry in the Utilities Reference.

PAM generates errors when files or directories are group or world writeable.