mark down README
authorEugene Crosser <Eugene.Crosser@ru.ibm.com>
Thu, 5 Dec 2013 13:12:35 +0000 (17:12 +0400)
committerEugene Crosser <Eugene.Crosser@ru.ibm.com>
Thu, 5 Dec 2013 13:12:35 +0000 (17:12 +0400)
Makefile.am
README [deleted file]
README.md [new file with mode: 0644]

index d6eeb62c8d38f72119b1bfc80935f92cb42ede06..ab96020824ee1c1ef065750a73e1ef6062893cc5 100644 (file)
@@ -29,7 +29,7 @@ test_serial_LDADD = libpcsc_cr.la
 test_crypto_LDADD = libpcsc_cr.la
 test_chalresp_LDADD = libpcsc_cr.la
 
-EXTRA_DIST = autogen.sh README_CR
+EXTRA_DIST = autogen.sh README.md README_CR
 
 TESTS = test_auth test_serial test_crypto test_chalresp
 XFAIL_TESTS = test_chalresp
diff --git a/README b/README
deleted file mode 100644 (file)
index af0bd75..0000000
--- a/README
+++ /dev/null
@@ -1,114 +0,0 @@
-Copyright (c) 2013 Eugene Crosser
-
-This software is provided 'as-is', without any express or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-    1. The origin of this software must not be misrepresented; you must
-    not claim that you wrote the original software. If you use this
-    software in a product, an acknowledgment in the product documentation
-    would be appreciated but is not required.
-
-    2. Altered source versions must be plainly marked as such, and must
-    not be misrepresented as being the original software.
-
-    3. This notice may not be removed or altered from any source
-    distribution.
-
-========================================================================
-
-This package provides a UNIX PAM module and accompanying setup program
-implementing HMAC-SHA1 challenge-response user authentication with
-hardware crypto token supporting PC/SC (Smartcard) interface.
-
-At the time of writing, I know of just one such hardware token, Yubikey
-Neo from Yubico http://www.yubico.com/. Pcsclite infrastructure (i.e.
-library and a daemon) is used to communicate with the token over CCID
-(i.e. PC/SC over USB) or NFC. It means that it works equally well when
-you plug the token in a USB slot and if you put it on an NFC reader.
-
-There are two ways to do challenge-response authentication: with shared
-secret and with pre-produced response. In pre-produced response, the
-host does not need to store the token's HMAC secret; on every session
-conversation with the token is performed twice with different challenges.
-The first response is compared with stored expected response, which is
-then replaced with the second response to be used on the next session.
-The advantage is that the secret is not kept anywhere except the token,
-so it's less chance of compromise. The drawback is that the expected
-response is transferred in cleartext long before being used, and can
-be eavesdropped on and reused in a replay attack. This is of particular
-concern when using NFC. This approach is used by the PAM module provided
-by Yubico.
-
-My module uses the second approach, under which the HMAC secret is
-stored both in the token and on the host. To minimize the danger of
-compromise, the host copy of the shared secret is encrypted by the key
-which is the expected response from the token. In the process of
-authentication, token's response is used to decrypt the secret, then
-this secret is used to compute the next expected token's response, and
-this expected response is used to encrypt the secret again. This next
-expected response is not transferred over the air, and the shared secret
-stays in unencrypted form in RAM (unless paged out) for a very short
-period. The downside is that if the token is used against multiple
-hosts, and one of them leaks the key to an adversary, all hosts are
-compromised. This is not the case with the first approach.
-
-Authentication file, containing nonce, encrypted shared secret,
-encrypted additional payload, and anciliary information, is named
-according to template that can be provided both to PAM module and to the
-setup program (and must be the same, obviously). In the template string,
-character '~' in the first position is substituted with the userid's
-home directory, '~' in a position other than first - with the userid
-itself, and character '?' - with the "tokenid". This latter is just an
-arbitrary string that is not involved in the authentication process.
-But, if the template contains '?' but not '~', login process can start
-without the knowlege of the userid. Userid will be picked from the file
-and injected into the PAM environment, given that tokenid is known from
-the start.
-
-Default template string is "~/.pam_cr/auth", i.e. the file lives in the
-user's home directory, in the subdirectory ".pam_cr".
-
-Authentication file must be initially created by the program
-'pam_cr_setup' included in this package.
-
-usage: pam_cr_setup [options] [username]
-    -h                - show this help and exit
-    -o backend-option - token option "backend:key=val"
-    -f template       - template for auth state filepath
-    -a secret | -A file-with-secret | -A -
-                      - 40-character hexadecimal secret
-    -s token-serial   - public I.D. of the token
-    -n nonce          - initial nonce
-    -l payload        - keyring unlock password
-    -p password       - login password
-    -v                - show returned data
-
-The only backend option existing is "ykneo:slot=1" or "ykneo:slot=2".
-Slot 2 is the default. Secret must be supplied when creating the file,
-and when modifying the file in the absense of the token. Password is
-used to construct the challenge. If not supplied empty string is used.
-The pam module also used empty string when given "noaskpass" argument,
-so this can be used for "one factor" authentication mode with token
-only. Payload is a string that can be optionally injected as the PAM
-authentication token after successful authentication; subsequent PAM
-modules like gnome keyring unlocker module will pick it up. Note that
-this keyring unlocker password may be different from the login
-password, and it is generally a good idea to make it so. The "returned
-data" is the userid as recorded in the file and the aforementioned
-payload string.
-
-PAM module has the following parameters:
-       verbose         write more errors to syslog.
-       noaskpass       do not try to ask the user for the challenge
-                       password, use empty string for the password.
-       injectauth      inject payload as PAM_AUTHTOK for the benefit
-                       of subsequent PAM modules.
-       path=<string>   template used to find the file.
-       backend:key=val backend options.
-
-
diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..c12a0dc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,147 @@
+
+```
+Copyright (c) 2013 Eugene Crosser
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+    1. The origin of this software must not be misrepresented; you must
+    not claim that you wrote the original software. If you use this
+    software in a product, an acknowledgment in the product documentation
+    would be appreciated but is not required.
+
+    2. Altered source versions must be plainly marked as such, and must
+    not be misrepresented as being the original software.
+
+    3. This notice may not be removed or altered from any source
+    distribution.
+```
+
+------------------------------------------------------------------------
+
+# Challenge-Response PAM Module for HMAC-SHA1 Hardware Token(s)
+
+This package provides a UNIX
+[PAM](http://en.wikipedia.org/wiki/Pluggable_Authentication_Modules)
+module and accompanying setup program implementing
+[HMAC-SHA1](http://en.wikipedia.org/wiki/HMAC-SHA1) challenge-response
+user authentication with hardware crypto token supporting
+[PC/SC](http://en.wikipedia.org/wiki/PC/SC) (Smartcard) interface.
+
+At the time of writing, I know of just one such hardware token, Yubikey
+Neo from [Yubico](http://www.yubico.com/).
+[Pcsclite](http://pcsclite.alioth.debian.org/) infrastructure (i.e.
+library and a daemon) is used to communicate with the token over
+[CCID](http://en.wikipedia.org/wiki/Integrated_Circuit_Card_Interface_Device)
+(i.e. PC/SC over USB) or
+[NFC](http://en.wikipedia.org/wiki/Near_field_communication). It means
+that it works equally well when you plug the token in a USB slot and if
+you put it on an NFC reader.
+
+## Theory of Challenge-Response Authentication
+
+There are two ways to do challenge-response authentication: with shared
+secret and with pre-produced response. In pre-produced response, the
+host does not need to store the token's HMAC secret; on every session
+conversation with the token is performed twice with different challenges.
+The first response is used to decrypt stored encrypted challenge and
+compare it with cleartext challenge. A new challenge is then sent
+to the token, and response is used to encrypt it and store for the
+future authentication session.  The advantage is that the secret is not
+kept anywhere except the token, so it's less chance of compromise. The
+drawback is that the response is transferred in cleartext long before
+being used, and can be eavesdropped on and used in a replay attack. This
+is of particular concern when using NFC. This approach is used by the
+[PAM module provided by Yubico](https://github.com/Yubico/yubico-pam).
+
+My module uses the second approach, under which the HMAC secret is
+stored both in the token and on the host. To minimize the danger of
+compromise, the host copy of the shared secret is encrypted by the key
+which is the expected response from the token. In the process of
+authentication, token's response is used to decrypt the secret, then
+this secret is used to compute the next expected token's response, and
+this expected response is used to encrypt the secret again. This next
+expected response is not transferred over the air, and the shared secret
+stays in unencrypted form in the RAM (unless paged out) for a very short
+period. The downside is that if the token is used against multiple
+hosts, and one of them leaks the secret to an adversary, all hosts are
+compromised. This is not the case with the first approach.
+
+## Module Operation
+
+Authentication file, containing nonce, encrypted shared secret,
+encrypted additional payload, and anciliary information, is named
+according to template that can be provided both to PAM module and to the
+setup program (and must be the same, obviously). In the template string,
+character '~' in the first position is substituted with the userid's
+home directory, '~' in a position other than first - with the userid
+itself, and character '?' - with the "tokenid". This latter is just an
+arbitrary string that is not involved in the authentication process.
+But, if the template contains '?' but not '~', login process can start
+without the knowlege of the userid. Userid will be picked from the file
+and injected into the PAM environment, given that tokenid is known from
+the start.
+
+Default template string is `~/.pam_cr/auth`, i.e. the file lives in the
+user's home directory, in the subdirectory `.pam_cr`.
+
+Authentication file must be initially created by the program
+`pam_cr_setup` included in this package.
+
+```
+usage: pam_cr_setup [options] [username]
+    -h                - show this help and exit
+    -o backend-option - token option "backend:key=val"
+    -f template       - template for auth state filepath
+    -a secret | -A file-with-secret | -A -
+                      - 40-character hexadecimal secret
+    -s token-serial   - public I.D. of the token
+    -n nonce          - initial nonce
+    -l payload        - keyring unlock password
+    -p password       - login password
+    -v                - show returned data
+```
+
+The only backend option existing is "ykneo:slot=1" or "ykneo:slot=2".
+Slot 2 is the default. Secret must be supplied when creating the file,
+and when modifying the file in the absense of the token. Password is
+used to construct the challenge. If not supplied empty string is used.
+The pam module also used empty string when given "noaskpass" argument,
+so this can be used for "one factor" authentication mode with token
+only. Payload is a string that can be optionally injected as the PAM
+authentication token after successful authentication; subsequent PAM
+modules like gnome keyring unlocker module will pick it up. Note that
+this keyring unlocker password may be different from the login
+password, and it is generally a good idea to make it so. The "returned
+data" is the userid as recorded in the file and the aforementioned
+payload string.
+
+PAM module has the following parameters:
+
+```
+        verbose         write more errors to syslog.
+        noaskpass       do not try to ask the user for the challenge
+                        password, use empty string for the password.
+        injectauth      inject payload as PAM_AUTHTOK for the benefit
+                        of subsequent PAM modules.
+        path=<string>   template used to find the file.
+        backend:key=val backend options.
+```
+
+## Getting the Source
+
+[clone](git://git.average.org/git/pam_pcsc_cr.git) or
+[browse](http://www.average.org/gitweb/?p=pam_pcsc_cr.git;a=summary)
+the repo.
+
+## Author
+
+Eugene Crosser \<crosser at average dot org\>   
+<http://www.average.org/~crosser/>
+
+---