-
-
Notifications
You must be signed in to change notification settings - Fork 3
pam multi.8
pam-multi - PAM module supporting multiple configurable methods
For auth or account methods only
args -m sql_query -u MySQL User -p MySQL Pass -D database -H host -P port args -c command [-d]
args -c command [-d]
args -s shared_library_path [-d]
pam-multi is a system to handle the authentication tasks of applications (services) on systems which use PAM, against any proprietary databases. The system provides a stable general interface, that privilege granting programs (such as authpam(7), login(1) and su(1)) can defer to, to perform standard authentication tasks. The primary goal of pam-multi was to allow authentication of IMAP/POP3 servers like courier-imap, dovecot against IndiMail(5)'s MySQL database. It can be used for any application which can authenticate using pam(8) to authenticate against any proprietary database that you have.
pam-multi supports four methods for password hashing schemes. crypt (DES), MD5, SHA256, SHA512.
To use pam-multi for any application (which currently uses PAM), you need to modify the PAM configuration file for that application.
Simply put, pam-multi extends an existing pam module to authenticate against any database using any one of the three methods described below.
For the 'auth' method, pam-multi supports any one of the three methods at a time. All that is needed is for you to configure the appropriate command which will return an encrypted password for the user. pam-multi will encrypt the plain text password given by the user and compare it with the result fetched by one of the three configured method. If the encrypted password match, access will be granted. The comparision will utilize one of the four hashing schemes.
?? .. DES
$5$ .. SHA256
$6$ .. SHA512
The following three methods are supported in configuration file in /etc/pam.d
-m sql_statement
MySQL mode. You will need to specify -u, -p, -D, -H and -P options. When pam-multi is used for authentication, it is expected that the sql_statement will return a row containing the encrypted password for the user. When pam-multi is used for account management, it is expected that the sql_statement will return the expiry date (as a long data type) for the account. The password expiry can be returned along with the account expiry separated by a ',' comma sign.
-c command
Command mode. pam-multi will do sh -c "command". When pam-multi is used for authentication, it is expected that the output of the command will be an encrypted password. When pam-multi is used for account management, it is expected that the output of the command will be the expiry date for the account. The password expiry can be returned along with the account expiry separated by a ',' comma sign.
-s shared_library
Library Mode. pam-multi will dynamically load the shared library. It is expected for the library to provide the function
char *iauth(char *email, char *service, 0|1, int *size, int *nitems, int debug)
The function iauth() will be passed a username and a token service denoting the name of service. The service argument will be used only for identification purpose. It is expected for the function to return the data. The third argument is either 0 or 1 denoting authentication or account management respectively. size denotes the size of the result returned. nitems denotes the number of items that will be returned. The function should return 0 for successful authentication.
The other options supported are
-i service Token identifier denotiing the name of service.
The service can also be set by setting the environment variable
AUTHSERVICE
-d Turn on debug mode
The following tokens if present in command string or the sql string (-m
or -c options), will be replaced as follows
%u - Username (the username will be escaped using mysql_real_escape_string() function).
%U - Username
%d - Domain (the domain supplied will be escaped using mysql_real_escape_string() function).
%D - Domain
pam-multi cannot be used for applications which do not use the PAM interface.
If you want an existing application on your system which uses PAM to use pam-multi, you will neeed to modify the configuration file which your application uses to have any one of the three options below.
auth optional pam-multi.so args -m [select pw_passwd from indimail where pw_name='%u' and pw_domain='%d'] -u indimail -p ssh-1.5- -D indimail -H localhost -P 3306
[step]
auth optional pam-multi.so args -c [grep "^%u:" /etc/passwd | awk -F:
'{print $2}']
[step]
auth optional pam-multi.so args -s /usr/lib/indimail/modules/iauth.so
/etc/pam.d/imap
auth optional pam-multi.so args -m [select pw_passwd from indimail where pw_name='%u' and pw_domain='%d'] -u indimail -p ssh-1.5- -D indimail -H localhost -P 3306
auth include system-auth
account required pam_nologin.so
account include system-auth
password include system-auth
# pam_selinux.so close should be the first session rule
session required pam_selinux.so close
session include system-auth
session required pam_loginuid.so
# pam_selinux.so open should only be followed by sessions to be executed in the user context
session required pam_selinux.so open env_params
session optional pam_keyinit.so force revoke
When a server initiates a PAM transaction, the PAM library tries to load a policy for the service specified in the pam_start(3) call. The policy specifies how authentication requests should be processed, and is defined in a configuration file. This is the other central concept in PAM: the possibility for the admin to tune the system security policy (in the wider sense of the word) simply by editing a text file. A policy consists of four chains, one for each of the four PAM facilities. Each chain is a sequence of configuration statements, each specifying a module to invoke, some (optional) parameters to pass to the module, and a control flag that describes how to interpret the return code from the module. Understanding the control flags is essential to understanding PAM configuration files. There are a number of different control flags:
binding
If the module succeeds and no earlier module in the chain has failed, the chain is immediately terminated and the request is granted. If the module fails, the rest of the chain is executed, but the request is ultimately denied. This control flag was introduced by Sun in Solaris™ 9 (SunOS™ 5.9), and is also supported by OpenPAM.
required
If the module succeeds, the rest of the chain is executed, and the request is granted unless some other module fails. If the module fails, the rest of the chain is also executed, but the request is ultimately denied.
requisite
If the module succeeds, the rest of the chain is executed, and the request is granted unless some other module fails. If the module fails, the chain is immediately terminated and the request is denied.
sufficient
If the module succeeds and no earlier module in the chain has failed, the chain is immediately terminated and the request is granted. If the module fails, the module is ignored and the rest of the chain is executed. As the semantics of this flag may be somewhat confusing, especially when it is used for the last module in a chain, it is recommended that the binding control flag be used instead if the implementation supports it.
optional
The module is executed, but its result is ignored. If all modules in a chain are marked optional, all requests will always be granted. When a server invokes one of the six PAM primitives, PAM retrieves the chain for the facility the primitive belongs to, and invokes each of the modules listed in the chain, in the order they are listed, until it reaches the end, or determines that no further processing is necessary (either because a binding or sufficient module succeeded, or because a requisite module failed.) The request is granted if and only if at least one module was invoked, and all non-optional modules succeeded.
Note that it is possible, though not very common, to have the same module listed several times in the same chain. For instance, a module that looks up user names and passwords in a directory server could be invoked multiple times with different parameters specifying different directory servers to contact. PAM treat different occurrences of the same module in the same chain as different, unrelated modules.
To configure PAM correctly, it is essential to understand how policies are interpreted.
When an application calls pam_start(3), the PAM library loads the policy for the specified service and constructs four module chains (one for each facility.) If one or more of these chains are empty, the corresponding chains from the policy for the other service are substituted.
When the application later calls one of the six PAM primitives, the PAM library retrieves the chain for the corresponding facility and calls the appropriate service function in each module listed in the chain, in the order in which they were listed in the configuration. After each call to a service function, the module type and the error code returned by the service function are used to determine what happens next. With a few exceptions, which we discuss below, the following table applies:
Table PAM chain execution summary
PAM_SUCCESS PAM_IGNORE other
binding if (!fail) break; - fail = true;
required - - fail = true;
requisite - - fail = true; break;
sufficient if (!fail) break; - -
optional - - -
If fail is true at the end of a chain, or when a “break” is reached, the dispatcher returns the error code returned by the first module that failed. Otherwise, it returns PAM_SUCCESS.
The first exception of note is that the error code PAM_NEW_AUTHTOK_REQD is treated like a success, except that if no module failed, and at least one module returned PAM_NEW_AUTHTOK_REQD, the dispatcher will return PAM_NEW_AUTHTOK_REQD.
The second exception is that pam_setcred(3) treats binding and sufficient modules as if they were required.
The third and final exception is that pam_chauthtok(3) runs the entire chain twice (once for preliminary checks and once to actually set the password), and in the preliminary phase it treats binding and sufficient modules as if they were required.
/etc/pam.d
the Linux-PAM configuration directory.
/lib64/security
the Linux-PAM module directory.
Typically errors generated by the pam-multi will be written to syslog(3).
pam(3) pam(8) IndiMail(5) pam-checkpwd(8)
AUTHOR Manvendra Bhangui (mbhangui@gmail.com)