NAME

pam_ocra — RFC6287 OCRA: OATH Challenge-Response Algorithm PAM module

SYNOPSIS

[service-name] module-type control-flag pam_ocra [options]

DESCRIPTION

The OCRA service module for PAM, pam_ocra provides functionality for only one PAM category: authentication. In terms of the module-type parameter, this is the “auth” feature. It also provides null functions for the remaining module types.

OCRA Authentication Module

The OCRA authentication component (pam_sm_authenticate()) obtains OCRA credentials from the the per-user file ~/.ocra. If the dir parameter is set, directory/USERNAME will be used. It then provides the user with an OCRA challenge and verifies the response.

The following options may be passed to the authentication module:

dir=directory

Specifies the additional directory to search for OCRA credentials.

nodata=action

Determines how the module handles the situation where there is no OCRA data file associated with the user. Use this option when some accounts use OCRA authentication but other accounts do not. The action value must be one of the following:

‘fail’: In the absence of this option, or if the action is set to ‘fail’, an error message will be logged via syslog() and PAM_AUTHINFO_UNAVAIL will be returned. (But see fake_prompt, below.)
‘succeed’: PAM_SUCCESS will be returned.
‘ignore’: PAM_IGNORE will be returned.

Which option to use will depend on the control flag used in PAM configuration file.

fake_prompt=suite_string

Use suite_string to generate fake challenges for users who do not have OCRA credentials. Note that if this option is not set, no fake challenges will be generated which can leak information to a hypothetical attacker about who uses OCRA and who does not.

If this option is specified, then the handling of the nodata option changes somewhat. If the nodata option is absent, or the action is set to ‘fail’, then the module will return PAM_AUTH_ERR instead of PAM_AUTHINFO_UNAVAIL.

cmsg=challenge_prompt rmsg=response_prompt

Change the challenge and/or the response prompts. The cmsg option changes the challenge prompt, and the rmsg option changes the response prompt. If the cmsg prompt is specified, a newline will be appended to it. There will be no newline appended to the rmsg prompt. If spaces are included for either prompt, the prompt must be in placed in double quotes. For either prompt, the following formatting directives may be used:

‘%c’: Insert the challenge question.
‘%Nc’: The challenge question with a spaces inserted after every N-th character
(N>=1, N=<9).
‘%u’: Insert a UTC timestamp in ISO-8601 format. This information can be useful when the OCRA suite string contains a time specification but the clock on the system is unreliable. Many SSH clients don't give visibility to any system output prior to login, so this may be the only way to indicate that a time discrepancy exists. Note that the timezone abbreviation is appended to the timestamp for readability purposes. This timezone abbreviation should be stripped off before parsing the timestamp.
‘%l’: Insert a local-time timestamp in ISO-8601 format. (Which may still be UTC, depending on how the system is configured.) In addition to the date and time, the timezone offset is appended to the local timestamp. Like its UTC counterpart, a readable timezone abbreviation is appended to the timestamp.
‘%%’: Insert a literal % character.

The default challenge prompt is "OCRA Challenge: %4c" and the default response prompt is "OCRA Response: "

FILES

~/.ocra

OCRA credential file

NOTES

LinuxPAM does not handle quoted strings in pam module options. When Linux PAM is uses instead of OpenPAM, options that contain spaces must be surrounded by square brackets instead of quoting the option value.

EXAMPLES

Note that in the following examples, the pam_ocra.so entry in the PAM configuration file is shown on multiple lines for readability purposes. In the actual configuration file, the module and its options must be on one line.

A PAM config file with the following entries:

auth required pam_unix.so no_warn null_ok
auth required pam_ocra.so \
        nodata=succeed fake_prompt=OCRA-1:HOTP-SHA1-6:QN06-PSHA1

Would ask for both a normal login password and an OCRA response from all users. If there is OCRA data associated with the user, then both authentication methods must succeed. A non-OCRA user only has to successfully enter the normal login password.

A PAM config file with the following entries:

auth requisite pam_unix.so no_warn null_ok
auth required pam_ocra.so nodata=fail

Would ask for a normal login password from all users, but only ask for an OCRA response if the normal login succeeded and there was OCRA data associated with the user. For users without OCRA data, the login would immediately fail.

For both of the above examples, the prompts would appear similar to the following:

OCRA Challenge: 123456
OCRA Response:

If the options included the following prompt changes:

cmsg="%u" rmsg="OTP Response to %c: "

or in case LinuxPAM is used:

cmsg=%u [rmsg=OTP Response to %c: ]

Then the prompts would look similar to:

2017-07-20T21:26:43Z UTC OTP Response to 123456:

Similarly if the options included the following prompt changes:

cmsg="%l - Challenge: %3c" rmsg="Response: " LinuxPAM version:

[cmsg=%l - Challenge: %3c] [rmsg=Response: ]

Then the prompts would look similar to:

2017-07-20T16:26:43-0500 CDT - Challenge: 123 456 Response:

STANDARDS

RFC6287: OCRA: OATH Challenge-Response Algorithm

AUTHORS

The pam_ocra module and this manual page were developed by Stefan Grundmann