User Authentication via Pluggable Authentication Module (PAM)

Users of Linux and some other unix-like operating systems, including recent versions of Solaris, can use the Pluggable Authentication Module (PAM) system.

PAM allows PAM-compatible applications including the to switch authentication methods without recompiling the application. This allows a system administrator to upgrade to a completely different authentication system without recompiling the application. Changes are made by updating configuration files to specify which authentication method should be used and optionally by adding additional subroutine libraries to add new types of authentication methods. The additional subroutine libraries can be purchased, or you can develope one yourself.

Note: At the time PAM was added to Sybase CEP, PAM was not available on MS-Windows systems.

This document assumes that you already have the PAM modules that you need and therefore we explain only how to configure your to use existing PAM modules. For more information about PAM, including information about how to develop PAM modules of your own, see the PAM documentation on the internet. As of the date that this feature was introduced in Sybase CEP, these documents were located at:

http://www.kernel.org/pub/linux/libs/pam/
    Linux-PAM-html/Linux-PAM_SAG.html
http://www.kernel.org/pub/linux/libs/pam/
    Linux-PAM-html/Linux-PAM_ADG.html

The first of these documents is the System Installation Guide, which explains how to configure a PAM system when you already have the files you need. The second document explains how to write your own pluggable authentication module.

We assume:

You have read an overview of the PAM system (for example, chapters 1-4 of the PAM System Administrator's Guide) and understand how PAM works.
You have downloaded and installed the PAM files (library files, and so on) that you will need. Some unix-like operating systems may already come with PAM installed.
You have acquired system administrator privileges on your computer or have other privileges sufficient to allow you to create or modify files under:

/etc

so that you can create or add to one of the following:
- /etc/pam.d: A directory containing PAM configuration files.
- /etc/pam.conf: A file containing PAM configuration information.
Note: Access to the /etc/pam.d directory or the /etc/pam.conf file should be tightly restricted, otherwise, a malicious user could change the configuration files and weaken security.
You have acquired system administrator privileges on your computer, or other privileges that allow you to create or modify the c8-server.conf file and the c8-acl.xml file.

The location of the server configuration file depends on where you install to, but a typical location is:

<install-dir>/server/conf/c8-server.conf

A Brief Overview of PAM with C8

In the diagram below, you can see the basic components involved when Sybase CEP uses PAM:

contains functions designed to work with PAM, including the initialize, authenticate, and shutdown functions. You will need to configure your c8-server.conf file to specify the name of the library that contains these functions.

The API box indicates what type of information is transmitted from the Sybase CEP Server to the PAM Plugin (which is a library that actually runs as part of the same process as the Server). The Server passes user and password information to the C8 PAM Plugin, and the C8 PAM Plugin returns a set of values that indicate:

Whether the specified user is permitted or denied access.
If the user is permitted access, then which groups the user is a member of.

The C8 PAM Plugin calls appropriate functions in the PAM library, and passes appropriate information to that library.

The PAM library does a variety of things, including:

Reading the /etc/pam.d/c8 file to determine which configuration method (for example password, retina scan, or fingerprint) should be used.
Calling the appropriate functions to authenticate the user (for example, request password or fingerprint info).
Returning a permit/deny value to the C8 PAM Plugin, which, in turn, passes this information back to the Sybase CEP Server.

The PAM library does more than this, but these are the key high-level tasks as far as the is concerned.

The /etc/pam.d/c8 file specifies which authentication method should be used, and other details, which are explained in more detail below. For additional information, see the internet pages that document PAM.

Configuring Sybase CEP Server to Use PAM

As with any plugin, you must update the c8-server.conf configuration file to specify information about the plugin. The default c8-server.conf file included with your contains a commented-out section with PAM-related configuration parameters. The basic parameters are described here:

<!-- Sample PAM authentication plugin configuration -->
<section name="Plugin">
<preference name="LibraryName" value="c8_server_plugins_lib"/>
<preference name="InitializeFunction" value="c8_auth_plugin_pam_initialize"/>
<preference name="AuthenticateFunction" value="c8_auth_plugin_pam_authenticate"/>
<preference name="ShutdownFunction" value="c8_auth_plugin_pam_shutdown"/>
<!--
 Uncomment the following line and change 'value' to 
 set the password prompt that PAM sends to applications.  
 The defaultprompt is "Password: ".  (Note the required 
 space at the end.)  You should only need to do this if 
 you encounter a system that does not use the default, 
 and as such, it failing authentication.
-->
<!-- <preference name="PasswordPrompt" value="Password: "/> -->
</section>

Look carefully at your c8-server.conf file to see the exact parameters for your version of Sybase CEP. See also the .

By default, this section is commented out in the c8-server.conf file. Make sure that you de-comment it.

To use a PAM, you must specify:

The name of the library file that contains the initialize(), authenticate(), and shutdown() functions.
The name of the initialize() function in that library.
The name of the authenticate() function in that library.
The name of the shutdown() function in that library.

Since the C8 PAM library is supplied by Sybase CEP, the names of the library and the functions in it are known, so you can de-comment this section of the c8-server.conf file. You do not need to change the values of the library or function names.

Configuring the PAM Service

Create or edit a PAM configuration file to specify which authentication method (for example, password, or fingerprint) you want to use with . Sybase CEP Server calls the PAM library functions to read this configuration file. The PAM library functions then know which of the many PAM authentication functions to use. Complete documentation about this PAM configuration file can be found as part of the PAM documentation. Key aspects are covered below.

In this document, we assume that you will create

/etc/pam.d/c8

Although PAM allows 4 different types of management group rules (account, auth, password, and session), uses only two: account and auth.

auth: This indicates that the user must be authenticated to prove that they are whom they claim to be, and allows the module to indicate which groups the user is a member of.
account: This allows the system to permit or deny access based on factors other than the user's identity. For example, the module might temporarily deny a user access to a system if the system is already heavily loaded.

The examples below use only a single rule. See the PAM documentation if you need information about how to use a "stack" containing multiple rules.

This sample configuration file will check the user against the system password:

# type     control    module-path    module-arguments
# -------  --------   ------------   -------------------
auth       required   pam_stack.so   service=system-auth
account    required   pam_stack.so   service=system-auth

The type is either auth or account.

In this case, the user must follow the specified authentication rule, so we put required. If you are using a stack that contains multiple rules, you might specify values other than required for some rules. For more information, see the PAM documentation.

The module-path indicates which PAM library we want to use to perform the authentication. The module-path is either the absolute path and filename of the PAM to be used by the application (if the path begins with a '/'), or a relative pathname from the default module location: /lib/security/ or /lib64/security/, depending on the architecture.

The module-arguments are a space-separated list of tokens that can be used to modify the specific behavior of the given PAM. The exact values depend on which PAM library module you are using and can be found in the documentation for that specific module. In this example, we are specifying that we want the normal system-wide authentication method on this computer (typically a user ID and password).

This configuration file allows access to all users. This may be useful for testing but is not secure.

# type    control   module-path    module-arguments
# -----   --------  -------------  ----------------
auth      required  pam_permit.so 
account   required  pam_permit.so

This configuration file denies all access and is useful for testing.

# type    control   module-path  module-arguments
# -----   -------   -----------  ----------------
auth      required  pam_deny.so 
account   required  pam_deny.so

PAM Troubleshooting

This section provides troubleshooting tips for some PAM-related problems.

Specifying the service:

PAM allows two different file formats and locations for configuration files. If you use /etc/pam.conf, then you will must include a service column in the PAM configuration file. If you use /etc/pam.d/c8, then you must omit the service column from the PAM configuration file. For more information, see the documentation for PAM.
PasswordPrompt:

If your system uses a password prompt different from the one shown in the c8-server.conf file's PasswordPrompt preference which may occur if your password prompt has been localized, then you need to change the c8-server.conf file's preference to match your actual prompt.

This is because at a certain point in the authentication process, the PAM library calls the Sybase CEP PAM plugin and passes the system's password prompt. The PAM library expects the to display the prompt, retrieve the password from the user, and then return the password to the PAM library. However, when Sybase CEP's PAM plugin receives the prompt, 's PAM plugin does not actually display the prompt, but instead returns password information that Sybase CEP Server already has. If the system's password prompt does not match the PasswordPrompt preference, then doesn't recognize when to return the password. To prevent this problem, set the PasswordPrompt preference to match your system's actual password prompt. Note that this string must exactly match the actual password prompt, including any blank space in the prompt.
If the password prompt sent by the PAM library does not match the password prompt expected by the Sybase CEP PAM plugin, you do not get a detailed error message. The only symptom you can see is that authentication fails.