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