CONTENTS
==========
I. INTRO
II. IMPLEMENTATION DETAILS
III. REQUIREMENTS
IV. INSTALLATION
V. CONFIGURATION
VI. LDAP CONFIGURATION
VII. SSHD CONFIGURATION FOR 2 FACTOR AUTHENTICATION
VIII. THE mobileCarrier OBJECT CLASS
IX. CAVEATS
I. INTRO
--------
pam_otpw is a PAM module that generates random 6 digit string, sends
it as a SMS text message to a user's mobile device, and prompts the
user to input the string for verification. The 6 digit string will
never be reused - it is valid only once for the lifetime of the user
on that host.
The pam_otpw module was written specifically to work together with the
OpenSSH server daemon, sshd(8), to provide 2-factor authentication for
host logins. It can also be used by other PAM-aware applications,
though it has only been tested with sshd(8).
The SMS text message is sent using the mobile carrier's SMS Gateway
domain and the SMTP protocol. Users' SMS Gateway addresses must be
stored in their LDAP directory entries. This repo includes a file
that defines an LDAP object class which may be used for this purpose.
pam_otpw is compiled as a shared library, pam_otpw.so, that is placed
into the PAM framework's `auth' stack.
II. IMPLEMENTATION DETAILS
---------------------------
The 6-digit string is derived from a randomly generated number. This
constrains the range of possible values to be between 0 and 999999. If
the number generated has fewer than 6-digits, then leading zeros will be
prepended to the value until it becomes a string of 6 numbers (e.g., the
number `75' becomes the string `000075').
Since each value can never be used more than once, the module must
maintain a record of values previously sent to the user.
For each user attempting to authenticate the module creates a file with
a length of 125000 bytes under /var/lib/pam_otpw/. This file is used as
a bit-map, where the offset of each bit records numbers previously used
(e.g., if the bit at offset `n' is set, then the number `n' has already
been used). The module will generate random numbers until it has a
value that maps to a bit that isn't already set.
The requisite information for sending users an SMS message must be
included in their LDAP directory entry. The entry is expected to have
the attribute `smsGateAddr' which contains the email address identifying
the particular mobile device and its SMS gateway domain. This repo
includes the file mobileCarrier.schema that defines the
mobileCarrierData object class with `smsGateAddr' as one of its
attributes.
Information on LDAP servers and LDAP query options are expected to be in
the file /etc/pam_ldap.conf. This file must exist on the target system.
See section III. `REQUIREMENTS' and section IV. `CONFIGURATION' for
more information.
The user is allowed 3 attempts to input the 6 digit string correctly.
On failure, the error PAM_AUTH_ERR is returned to the calling
function/application.
When used in conjunction with SSH, the sshd(8) daemon controls the
timeout for both input operations (user password and 6-digit string).
III. REQUIREMENTS
------------------
1. The pam_otpw module requires libldap and related libraries from the
OpenLDAP project (http://www.openldap.org). Your system most likely
has a package that installs these libraries.
2. The arc4random_uniform(3) function, used for random number generation,
requires libbsd on Linux systems (https://libbsd.freedesktop.org/wiki/).
3. To compile the module, gcc and GNU make are required. Also,
the following header files must exist on your system:
ldap.h
pam_appl.h
pam_modules.h
pam_ext.h
bsd/stdlib.h (Linux only)
3. pam_otpw requires the file /etc/pam_ldap.conf. This file is
normally used by (and installed together with) the PAM module
`pam_ldap'. The pam_ldap module itself is not required. See
section V. `CONFIGURATION'.
IV. INSTALLATION
------------------
1. cd to the src/ directory and run:
make mod
and as a privileged user
make install
(on BSDs, use gmake);
If all goes well, the shared library pam_otpw.so will be created in the
directory /lib/x86_64-linux-gnu/security/ (Debian) or
/usr/lib64/security/ (Centos).
The directory /var/lib/pam_otpw will also be created.
V. CONFIGURATION
------------------
The pam configuration file(s) must be modified to use the pam_otpw.so
library. The module should use the 'auth' type management group. See
pam.conf(5). The repo includes the PAM config file `sshd' which has
been used successfully on a Centos 7.1 system for SSH authentication.
The config file pam_ldap.conf(5) must exist on the system. At this
time, pam_otpw only uses these settings:
timelimit (default is 10 seconds)
bind_timelimit (default is 10 seconds)
tls_cacertfile (required for TLS)
uri (required)
base (required)
scope (required)
ssl (default is `no')
See the manpage for pam_ldap.conf(5) for the meaning of these settings.
VI. LDAP CONFIGURATION
----------------------
The pam_otpw module searches the LDAP directory for a DN with the uid
attribute that matches the username being authenticated. This typically
requires LDAP entries to use either the posixAccount or inetOrgPerson
object class.
The user's SMS Gateway is expected to be a value assigned to the
smsGateway attribute in a user's LDAP entry. The file
mobileCarrier.schema defines the mobileCarrierData object class with the
smsGateway attribute.
To use the mobileCarrier object class with OpenLDAP's slapd server,
copy the file mobileCarrierData.schema to OpenLDAP's schema directory
and configure slapd to include the new object class (see
slapd.conf(5)).
See the section VIII for more information on the mobileCarrer object
class.
VII. SSHD CONFIGURATION FOR 2-FACTOR AUTHENTICATION
----------------------------------------------------
The following options should be set in sshd_config(5).
ChallengeResponseAuthentication yes (the default)
PasswordAuthentication no
UsePAM yes (the default) )
The setting for PasswordAuthentication is not required, but a
recommendation. See the manpage for sshd_config(5).
VIII. The mobileCarrier Object Class
-------------------------------------
The mobileCarrier object class provided with this repo defines 4
attributes:
smsGateAddr The SMS Gateway: an email address consisting of the user's
mobile number and their mobile carrier's SMS Gate Domain.
E.g., 1234567890@txt.att.net
msisdn The user's mobile phone number. Conforms to rfc4517,
Section 3.3.31
mobileCarrier The mobile carrier (e.g., at&t, tmobile, etc)
smsGateDomain Email domain for mobile carriers SMS gateway
(e.g., txt.att.net, vtext.com)
IX. CAVEATS
-------------
1. The NIST is no longer recommends using SMS for 2 factor
authentication:
"Out-of-band authentication using the PSTN (SMS or voice) is discouraged
and is being considered for removal in future editions of this
guideline."
See https://pages.nist.gov/800-63-3/sp800-63b.html, Section 5
2. The format of the SMS text message is largely beyond control of the
PAM module. Different carriers will format the messages differently.
3. SMS messages sent via SMTP may not be received immediately. Delays
can occur. This can be a problem if applications expect confirmation
of authentication within a time interval less than the time required
to deliver the SMS message.