Loading...spinner

PAM_OTPASSWD

 

NAME

pam_otpasswd - Module for OTPasswd one-time password authentication  

SYNOPSIS

pam_otpasswd.so [options]  

DESCRIPTION

This 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).

 

OPTIONS

debug
Maximize module syslog(3) logging output. While this is useful for developers, it is not typically what you want.
audit
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.
silent
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.
use_first_pass
This option is ignored.

Invalid arguments are logged with syslog(3), but are otherwise ignored.  

MODULE SERVICES PROVIDED

PAM(7) supports four independent management groups, which are implemented as follows:

Authentication
Supported, except pam_setcred(3)
Session
Fully supported
Account
Not supported
Password
Not supported
 

RETURN VALUES

PAM_SUCCESS
User one-time passcode authentication was successful. pam_open_session(3) will always return this value.
PAM_IGNORE
Returned by pam_sm_setcred(3) when any attempt is made to alter the user's credentials.
PAM_AUTH_ERR
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
PAM_USER_UNKNOWN
The following conditions will result in this error:
System configuration file otpasswd.conf(5) is unreadable
The PAM(7) system is unable to provide pam_otpasswd with the name of the user for whom authentication has been requested. See pam_get_user(3) for details.
PAM_SERVICE_ERR
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.  

FILES

/etc/otpasswd
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 state data.

Name of this directory can only be configured during compilation.

/etc/otpasswd/otpasswd.conf
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.

/etc/otpasswd/otshadow
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.
$HOME/.otpasswd
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.

/etc/pam.d/otpasswd_login
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.
 

NOTES

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

EXAMPLE

A 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 ALSO

pam(7), pam.conf(5), otpasswd(7), otpasswd(1), otpasswd.conf(5), otshadow(5), otpasswd(5)  

LICENSE

Copyright (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.

You should have received a copy of the GNU General Public License along with this program in a LICENSE file.  

AVAILABILITY

The latest version of the OTPasswd package is available in source form at the project website https://savannah.nongnu.org/projects/otpasswd


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
MODULE SERVICES PROVIDED
RETURN VALUES
FILES
NOTES
EXAMPLE
SEE ALSO
LICENSE
AVAILABILITY

This document was created by man2html, using the manual pages.
Time: 22:17:25 GMT, November 02, 2013