README.md

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