README

   1 Copyright (c) 2013 Eugene Crosser
   2
   3 This software is provided 'as-is', without any express or implied
   4 warranty. In no event will the authors be held liable for any damages
   5 arising from the use of this software.
   6
   7 Permission is granted to anyone to use this software for any purpose,
   8 including commercial applications, and to alter it and redistribute it
   9 freely, subject to the following restrictions:
  10
  11     1. The origin of this software must not be misrepresented; you must
  12     not claim that you wrote the original software. If you use this
  13     software in a product, an acknowledgment in the product documentation
  14     would be appreciated but is not required.
  15
  16     2. Altered source versions must be plainly marked as such, and must
  17     not be misrepresented as being the original software.
  18
  19     3. This notice may not be removed or altered from any source
  20     distribution.
  21
  22 ========================================================================
  23
  24 This package provides a UNIX PAM module and accompanying setup program
  25 implementing HMAC-SHA1 challenge-response user authentication with
  26 hardware crypto token supporting PC/SC (Smartcard) interface.
  27
  28 At the time of writing, I know of just one such hardware token, Yubikey
  29 Neo from Yubico http://www.yubico.com/. Pcsclite infrastructure (i.e.
  30 library and a daemon) is used to communicate with the token over CCID
  31 (i.e. PC/SC over USB) or NFC. It means that it works equally well when
  32 you plug the token in a USB slot and if you put it on an NFC reader.
  33
  34 There are two ways to do challenge-response authentication: with shared
  35 secret and with pre-produced response. In pre-produced response, the
  36 host does not need to store the token's HMAC secret; on every session
  37 conversation with the token is performed twice with different challenges.
  38 The first response is compared with stored expected response, which is
  39 then replaced with the second response to be used on the next session.
  40 The advantage is that the secret is not kept anywhere except the token,
  41 so it's less chance of compromise. The drawback is that the expected
  42 response is transferred in cleartext long before being used, and can
  43 be eavesdropped on and reused in a replay attack. This is of particular
  44 concern when using NFC. This approach is used by the PAM module provided
  45 by Yubico.
  46
  47 My module uses the second approach, under which the HMAC secret is
  48 stored both in the token and on the host. To minimize the danger of
  49 compromise, the host copy of the shared secret is encrypted by the key
  50 which is the expected response from the token. In the process of
  51 authentication, token's response is used to decrypt the secret, then
  52 this secret is used to compute the next expected token's response, and
  53 this expected response is used to encrypt the secret again. This next
  54 expected response is not transferred over the air, and the shared secret
  55 stays in unencrypted form in RAM (unless paged out) for a very short
  56 period. The downside is that if the token is used against multiple
  57 hosts, and one of them leaks the key to an adversary, all hosts are
  58 compromised. This is not the case with the first approach.
  59
  60 Authentication file, containing nonce, encrypted shared secret,
  61 encrypted additional payload, and anciliary information, is named
  62 according to template that can be provided both to PAM module and to the
  63 setup program (and must be the same, obviously). In the template string,
  64 character '~' in the first position is substituted with the userid's
  65 home directory, '~' in a position other than first - with the userid
  66 itself, and character '?' - with the "tokenid". This latter is just an
  67 arbitrary string that is not involved in the authentication process.
  68 But, if the template contains '?' but not '~', login process can start
  69 without the knowlege of the userid. Userid will be picked from the file
  70 and injected into the PAM environment, given that tokenid is known from
  71 the start.
  72
  73 Default template string is "~/.pam_cr/auth", i.e. the file lives in the
  74 user's home directory, in the subdirectory ".pam_cr".
  75
  76 Authentication file must be initially created by the program
  77 'pam_cr_setup' included in this package.
  78
  79 usage: pam_cr_setup [options] [username]
  80     -h                - show this help and exit
  81     -o backend-option - token option "backend:key=val"
  82     -f template       - template for auth state filepath
  83     -a secret | -A file-with-secret | -A -
  84                       - 40-character hexadecimal secret
  85     -s token-serial   - public I.D. of the token
  86     -n nonce          - initial nonce
  87     -l payload        - keyring unlock password
  88     -p password       - login password
  89     -v                - show returned data
  90
  91 The only backend option existing is "ykneo:slot=1" or "ykneo:slot=2".
  92 Slot 2 is the default. Secret must be supplied when creating the file,
  93 and when modifying the file in the absense of the token. Password is
  94 used to construct the challenge. If not supplied empty string is used.
  95 The pam module also used empty string when given "noaskpass" argument,
  96 so this can be used for "one factor" authentication mode with token
  97 only. Payload is a string that can be optionally injected as the PAM
  98 authentication token after successful authentication; subsequent PAM
  99 modules like gnome keyring unlocker module will pick it up. Note that
 100 this keyring unlocker password may be different from the login
 101 password, and it is generally a good idea to make it so. The "returned
 102 data" is the userid as recorded in the file and the aforementioned
 103 payload string.
 104
 105 PAM module has the following parameters:
 106         verbose         write more errors to syslog.
 107         noaskpass       do not try to ask the user for the challenge
 108                         password, use empty string for the password.
 109         injectauth      inject payload as PAM_AUTHTOK for the benefit
 110                         of subsequent PAM modules.
 111         path=<string>   template used to find the file.
 112         backend:key=val backend options.
 113
 114