                           pam-webauth-otp 1.0
          (OTP PAM module for WebAuth user information service)

                Written by Russ Allbery <rra@stanford.edu>

  Copyright 2013 The Board of Trustees of the Leland Stanford Junior
  University.  This software is distributed under a BSD-style license.
  See the LICENSE file, included in this distribution, for copyright and
  redistribution information.

BLURB

  The WebAuth web authentication system defines a user information service
  protocol that's used to determine what factors a given user has access
  to and to validate OTP codes used for authentication to the central
  WebLogin server.  This PAM module uses the same protocol to talk to the
  same WebAuth user information service when validating OTP codes for
  interactive PAM-based logins.  Currently, SMS is not supported, only OTP
  methods that don't require a multi-step user interaction.

DESCRIPTION

  WebAuth is a site-wide web authentication system that uses a central
  login server.  That login server supports multifactor authentication
  (and other features) via a user information service provided by the
  local site.  OTP-based multifactor authentication is validated by
  WebAuth via calls to the validate function in that user information
  service.

  pam-webauth-otp is a PAM module that performs the same API calls as the
  WebAuth login server, allowing the same infrastructure and OTP database
  to be used to secure authentications that use PAM.  The user is prompted
  for an OTP code, which is then validated by a call to the validate
  function of a WebAuth user information service.  Any middleware that
  speaks the WebAuth user information service protocol can be used,
  whether or not it is also used for a WebAuth deployment.

  This module currently only supports OTP mechanisms where the user can
  supply a code without any further interaction.  SMS, which requires a
  call to send the SMS message before prompting the user, is not currently
  supported.

REQUIREMENTS

  The PAM implementations on Linux, Solaris, Mac OS X, HP-UX, and AIX
  should theoretically work, although the module is only tested on Linux.
  Use on platforms with other PAM implementations, such as IRIX or the
  *BSDs, will require more porting and will not currently work.  Patches
  are welcome.

  The module is written in C and should hopefully build on any system with
  an adequate PAM library that Libtool supports.

  pam-webauth-otp requires libwebauth from WebAuth 4.5 or later.  WebAuth
  must be built with remctl support.

  pam-webauth-otp can optionally read configuration from krb5.conf as well
  as PAM options; for this, Kerberos libraries are also required.  This
  functionality should work with either MIT Kerberos or Heimdal, but will
  probably not work on Mac OS X since the krb5_appdefault* APIs are
  crippled on that platform.

  Running the complete test suite requires the remctld program be
  installed in /usr/sbin, /usr/local/sbin, or a directory on the builder's
  PATH.  In addition, Perl 5.6 or later plus the following Perl modules
  are required for some tests:

      Test::More (included with Perl 5.8 and later)
      Test::Pod
      Test::Spelling

  All are available on CPAN.  Those tests will be skipped if the modules
  are not available.

  To enable tests that may be sensitive to the local environment or that
  produce a lot of false positives without uncovering many problems, set
  RRA_MAINTAINER_TESTS to a true value.

COMPILING AND INSTALLING

  To build the module, just run:

      ./configure
      make

  Kerberos support is enabled by default if configure can find Kerberos
  libraries.  If your Kerberos libraries aren't installed in a location
  found by your compiler by default and krb5-config isn't on your PATH,
  use the --with-krb5=PATH option to configure.  The Kerberos libraries
  will then be expected in PATH/lib and the headers in PATH/include.

  To specify a particular krb5-config script to use, either set the
  KRB5_CONFIG environment variable or pass it to configure like:

      ./configure KRB5_CONFIG=/path/to/krb5-config

  To not use krb5-config and force library probing even if there is a
  krb5-config script on your path, set KRB5_CONFIG to a nonexistent path:

      ./configure KRB5_CONFIG=/nonexistent

  To disable Kerberos support, even if you have Kerberos libraries
  available, pass --without-krb5 to configure.

  To install the module into /usr/local/lib/security and the man page into
  /usr/local/share/man/man5, run:

      make install

  You can change the installation locations with the --prefix, --mandir,
  and --libdir options to configure.  The module will normally be
  installed in a subdirectory of $libdir named security, but if --prefix
  is set to /usr (rather than /usr/local, the default), the module will be
  installed in /lib/security (or /lib32/security or /lib64/security if
  they exist) to match the default PAM configuration.  Alternately, you
  can simply copy pam_webauth_otp.so to whatever directory you use for PAM
  modules.  On Solaris, you will need to make the module executable.

TESTING

  pam-webauth-otp comes with a test suite, which you can run after
  building pam-afs-session with:

      make check

  If a test case fails, please run the that individual test case with
  verbose output using:

      tests/runtests -o <name-of-test>

  and send me the output when reporting the problem.

CONFIGURING

  Just installing the module does not enable it or change anything about
  your system authentication configuration.  You have to add the module to
  your PAM configuration in the auth group, and you will also need to
  provide the minimum amount of configuration for it to contact the
  WebAuth user information service.  You will at least need to specify
  the server on which that service runs and the command prefix to use.

  For Linux, this will mean a line like:

      auth required pam_webauth_otp.so server=userinfo.example.com \
          command=webkdc

  in the relevant PAM configuration file (all on one line), replacing the
  server parameter with your WebAuth information server host and the
  command with the remctl command that you use for user information
  service calls.

  To affect every login on the system, Debian uses /etc/pam.d/common-auth
  and Red Hat uses /etc/pam.d/system-auth.  Other distributions may use
  other files.  You can also, obviously, use more complex configurations
  if you want OTP to be optional or requested only in combination with
  other forms of authentication.

  For Solaris, add:

      login auth required /usr/local/lib/security/pam_webauth_otp.so \
          server=userinfo.example.com command=webkdc

  to /etc/pam.conf to affect most services, replacing the server and
  command parameters as above.  As with Linux, you may want a different
  configuration to use the module with specific services other than login
  (ssh for instance).

  On all platforms, options can be put after the module name in the PAM
  configuration file.  This is useful if you don't have Kerberos libraries
  available or if you want different configurations for different
  services.

  If Kerberos support was enabled, configuration options may also be put
  in the krb5.conf file used by your Kerberos libraries (usually
  /etc/krb5.conf or /usr/local/etc/krb5.conf) instead or in addition to
  the PAM configuration.  See the man page for more details.  This is
  recommended for general system configuration, since the krb5.conf
  configuration syntax is a little nicer and more flexible.

  If you are using this module with ssh, be aware that it requires
  ChallengeResponseAuthentication (keyboard-interactive).  It will not
  work with the simpler PasswordAuthentication (password) protocol because
  it is prompting for an OTP code, not a password, and doesn't reuse the
  same password as other PAM modules.  Thankfully, most ssh clients now
  support keyboard-interactive.

SUPPORT

  The pam-webauth-otp web page at:

      http://www.eyrie.org/~eagle/software/pam-webauth-otp/

  will always have the current version of this package, the current
  documentation, and pointers to any additional resources.

  New releases are announced via the low-volume webauth-announce mailing
  list.  To subscribe or see the list archives, go to:

      https://mailman.stanford.edu/mailman/listinfo/webauth-announce

  There is also a separate mailing list for general discussion and
  requests for help with WebAuth, and this PAM module can be discussed
  there.  To subscribe or see the list archives, go to:

      https://mailman.stanford.edu/mailman/listinfo/webauth-info

  For Stanford affiliates, this PAM module is a supported product of the
  ITS Infrastructure Delivery Group.  You can report problems or request
  help with WebAuth by submitting a HelpSU ticket at:

      <https://remedyweb.stanford.edu/helpsu/helpsu>

  For non-Stanford users, please instead subscribe to webauth-info and ask
  your question there.  We cannot provide any formal support for
  non-Stanford users, nor do we make any promises or committments related
  to this software.  Please feel free to use it on an as-is basis, and
  please do feel free to send us any patches or improvements that you wish
  to contribute and we will evaluate them for future releases.  However,
  please be aware that our primary focus is supporting the needs of
  Stanford University and work on features not used by Stanford is mostly
  done on a volunteer basis.

SOURCE REPOSITORY

  pam-webauth-otp is maintained using Git.  You can access the current
  source by cloning the repository at:

      git://git.eyrie.org/kerberos/pam-webauth-otp.git

  or view the repository via the web at:

      http://git.eyrie.org/?p=kerberos/pam-webauth-otp.git

  When contributing modifications, patches (possibly generated by
  git-format-patch) are preferred to Git pull requests.

LICENSE

  The pam-webauth-otp package as a whole covered by the following
  copyright statement and license:

    Copyright 2013
        The Board of Trustees of the Leland Stanford Junior University

    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:

    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

  All individual files without an explicit exception below are released
  under this license.  Some files may have additional copyright holders as
  noted in those files.  There is detailed information about the licensing
  of each file in the LICENSE file in this distribution.

  Some files in this distribution are individually released under
  different licenses, all of which are compatible with the above general
  package license but which may require preservation of additional
  notices.  All required notices are preserved in the LICENSE file.
