NAMEpam_otpasswd - Module for OTPasswd one-time password authentication
DESCRIPTIONThis module allows the authentication of one-time passwords with the OTPasswd system. OTPasswd consists of two primary components, this PAM module and the otpasswd(1) utility. The utility is used to control the operation of the system, and the PAM module essentially makes it happen.
In general, once OTPasswd has been installed, the system administrator must determine where the system will keep the user configuration data (user state). The administrator will likely also configure the system by making various policy choices, such as how long passcodes must be, how complicated the static password should be, which passcode alphabet will be used, etc. Subsequently, users will probably also make some configuration choices - to the degree they are permitted by policy - and then they will generate a key and print some passcards. All of these activities involve the use of the otpasswd(1) utility. Once this initial configuration is complete, the OTPasswd system will operate virtually autonomously. Each time a user attempts to login to the system, or otherwise authenticate with some service which uses this module, the previously configured data is consulted, a one-time passcode challenge will be issued, and the user will have a chance to authenticate.
The PAM(7) authentication system supports four independent management groups, of which this module only supports two: authentication management and session management. The account and password management groups are not supported.
In typical usage, the authentication component of the pam_otpasswd module performs the task of issuing a challenge to the user for a one-time passcode, validating it against the user state information, and advancing the counter to the next passcode for subsequent authentications. Other more advanced tasks involve the validation of the user's static password and accepting some simple authentication-related commands, such as sending a passcode to the user by text message (SMS).
The session component of this module is primarily intended to provide the user with warnings when a user session is initially established. This include some of OTPasswd system conditions user should be aware of like the fact that he is running out of printed passcodes (see otpasswd(1) for more details).
This module's session management functions will never cause a user session to be denied.
The pam_otpasswd module for compatibility with interfaces of other modules may optionally be provided with a series of options in the PAM configuration file (see EXAMPLE section below), each of which may alter the behavior of some components of the module.
This options duplicates functionality of otpasswd.conf, and enabling any of them overrides settings in configuration file.
Any legal options which have no relevance to the specific management context in which this module is called will be silently ignored. Unrecognized options will be logged as warnings through syslog(3).
- Maximize module syslog(3) logging output. While this is useful for developers, it is not typically what you want.
- Increased amount of logging to the system log. This option is appropriate for system administrators who desire to more carefully monitor OTPasswd activity without excessive log spam.
- No unnecessary text or messages are sent to the calling program, and the PAM conversation function is only used to ask for passcode. Passing this option to session stack effectively turns it off. This option causes the module to behave in the same manner as though the PAM_SILENT flag had been passed by the application.
- This option is ignored.
Invalid arguments are logged with syslog(3), but are otherwise ignored.
MODULE SERVICES PROVIDEDPAM(7) supports four independent management groups, which are implemented as follows:
- Supported, except pam_setcred(3)
- Fully supported
- Not supported
- Not supported
- User one-time passcode authentication was successful. pam_open_session(3) will always return this value.
- Returned by pam_sm_setcred(3) when any attempt is made to alter the user's credentials.
One of the following conditions has occurred:
- User failed to properly provide the expected passcode
- OTPasswd use is enforced by policy but user has no configuration
- User state information was not successfully locked
- Passcode counter value could not be incremented
- Passcode prompt could not be generated
- Application provided no user response to a passcode query
- An unforeseen error occurred
- The following conditions will result in this error:
- OTPasswd system configuration error. This value is returned when any function in this PAM module is unable to read the otpasswd.conf(5) system configuration file. (FIXME: How does this return code translate into the success/failure of the auth stack?)
In those situations where an error status was returned to the calling application, the pam_otpasswd module uses the syslog(3) facility to log additional details. Check your system log.
The directory for OTPasswd configuration files.
If OTPasswd is configured to use a global flat-file
database, then this file resides here, and therefore,
the directory should be owned by the special system user
(set in otpasswd.conf, a default value is otpasswd),
and should not be accessible for normal users
(mode 0700 recommended). The otpasswd(1) utility has to be
Set-UID to that user to be able to read and modify configuration and
Name of this directory can only be configured during compilation.
The main OTPasswd system configuration file.
This file contains key-value configuration parameters that
govern the operation of the system.
In particular, it contains the state database configuration,
system-wide defaults, PAM configuration and policy configuration.
When the backend user database is configured to use MySQL or LDAP,
this file will contain privileged information and
must be not be accessible for normal users. This requires utility
to be Set-UID to user who owns /etc/otpasswd/otpasswd.conf.
Name of this file can only be configured during compilation.
- The system-wide user database, used only when the otpasswd.conf(5) configuration file specifies the use of a global database backend. The file contains state information for all users, including keys, flags, etc, and must not be accessible to normal users.
This file is only used when the system configuration file
otpasswd.conf(5) specifies that state information is
to be maintained in user home directories.
This has the same format as the otshadow(5) file above,
except it only contains information for a single user.
As users have full permissions to modify those files, policy can't be enforced in this mode.
- The PAM prototype configuration for OTPasswd. If this file is included in a PAM configuration for any service (like SSH), the pam_otpasswd(8) PAM module will be used to ask the user for a passcode just after the normal pam_unix(8) authentication mechanisms are applied. This stack is prepared to be used instead of previous authentication state.
NOTESSee otpasswd(1) for further information regarding the OTPasswd one-time password authentication system. In particular, the reader is directed to the sections entitled COMPATIBILITY, DOCUMENTATION, and HISTORY.
EXAMPLEA typical PAM auth stack for OTPasswd use would be:
auth required pam_tally.so onerr=succeed auth required pam_shells.so auth required pam_nologin.so auth required pam_env.so auth requisite pam_unix.so try_first_pass likeauth nullok auth required pam_otpasswd.so audit session optional pam_otpasswd.so
In this example, the requisite keyword is used for the pam_unix(8) module, which means that if the user fails to enter the proper system password, the entire auth stack will fail immediately. In particular, this means that the user will never be asked for a passcode by the pam_otpasswd module. To change this behavior, merely replace the requisite keyword, with the required keyword. This forces the entire auth stack to complete first, and the user will be asked for a passcode every time, regardless of whether the user specified the system password correctly.
Note that the audit option was specified in the auth configuration for the pam_otpasswd module above. This will cause an increased number of messages to be placed in the system log, allowing system administrators to more carefully monitor OTPasswd authentication activity.
This example also highlights the typical way in which pam_otpasswd is used in the session management stack. The primary facility provided by this module's session management functions is to provide warnings of unusual OTPasswd system conditions when a user session is initially established (see otpasswd(1) for more details). (FIXME: verify previous) No pam_otpasswd session management function will ever fail.
SEE ALSOpam(7), pam.conf(5), otpasswd(7), otpasswd(1), otpasswd.conf(5), otshadow(5), otpasswd(5)
LICENSECopyright (c) 2009, 2010 Tomasz bla Fortuna
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
AVAILABILITYThe latest version of the OTPasswd package is available in source form at the project website https://savannah.nongnu.org/projects/otpasswd
- MODULE SERVICES PROVIDED
- RETURN VALUES
- SEE ALSO
This document was created by man2html, using the manual pages.
Time: 22:17:25 GMT, November 02, 2013