Identification and Authentication Control

Identification ensures that a user is who they claim to be (for example, a unique username). Authentication proves the identity of the user (for example, with a password or keys).

Using the PAM framework

A pluggable authentication module (PAM) environment consists of the following:

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

Systems needing authentication must use a configurable standard library (the PAM library) developed for this purpose. PAM provides a framework for you to use within a system; for example, you can use PAM to prompt for credentials such as username and password if that is the information that you need to authenticate users.

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), 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 indicate that the PAM library should invoke a different shared object file, you can change how your system authenticates users without changing its code.

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.

Note: The PAM library explicitly checks permissions when loading the modules.

Adding PAM modules

PAM modules (pam_*.so) may be located in /usr/lib, /usr/local/lib, or /proc/boot. Ensure permissions for all of /usr, /usr/lib, /usr/local, /usr/local/lib, /proc, /proc/boot and the modules are set to exclude write permissions for group and other.

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 may read configuration files from /etc/pam.d or /usr/local/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 no filename matches the service name (binary name) that the application registered, the service looks for /etc/pam.d/other or /usr/local/etc/pam.d/other.

Configuration commands are stacked in the PAM configuration file to create a chain. They are processed in top-down order by libpam. A configuration command takes the following syntax:

facility control_flag module arguments

A PAM password configuration file supports the following four facilities:

Task Facility Functions
Account management account pam_acct_mgmt
Password management password pam_chauthtok
Authentication auth pam_authenticate and pam_setcred
Session management session 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.

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

The syntax of the configuration file is based on facilities, control flags, modules (shared object files) and optional arguments; for example:

auth required pam_qnx.so
auth required pam_radius.so
account required pam_permit.so                    

The control flags are words that describe what should happen if a function of the indicated type succeeds or fails; 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_mac.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_mac.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_radius.so Authenticate on RADIUS protocol. Authenticate the SSH server request from the RADIUS server:
/etc/pam.d/sshd:
auth sufficient pam_radius.so
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 matched 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:

Note: The racoon and sshd utilities parse their configuration files before PAM does and require additional configuration to enable PAM.

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:

        # apply additional groups as specified in groups.conf
        auth optional pam_group.so
        # use standard un*x validation, allow blank passwords
        auth required pam_qnx.so nullok
        # deny on failure
        auth requisite pam_deny.so
        password required pam_qnx.so nullok
        password requisite pam_deny.so
        account required pam_qnx.so nullok
        account requisite pam_deny.so
        session required pam_qnx.so nullok
        session requisite pam_deny.so

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

        # root can su with no auth
        auth sufficient pam_rootok.so
        # use standard un*x validation, allow blank passwords
        auth required pam_qnx.so nullok
        # deny on failure
        auth requisite pam_deny.so
        account required pam_qnx.so nullok
        account requisite pam_deny.so
        session required pam_qnx.so nullok
        session requisite pam_deny.so
        # no password facility

Using syslogd for debugging

Since OpenPAM and the PAM modules use syslogd to log errors, you can use syslogd for debugging as follows:

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

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

Troubleshooting

Use this section to troubleshoot your PAM configuration.

Invalid password database

To troubleshoot an invalid password database, check:

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:

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:

A valid set up looks like this:

Filepath User Group Permissions
/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 /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:

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

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_radius.so
ls -ld /usr/lib/pam_rootok.so
ls -ld /usr/lib/pam_self.so