update README and .svg
authorEugene Crosser <Eugene.Crosser@ru.ibm.com>
Wed, 25 Dec 2013 10:01:58 +0000 (14:01 +0400)
committerEugene Crosser <Eugene.Crosser@ru.ibm.com>
Wed, 25 Dec 2013 10:01:58 +0000 (14:01 +0400)
remove tokenid from the picture, improve style.

README.md
auth-data-structure.svg

index a7d862d91430be431eeee00e9d06ff737fd6cdf9..fbd355ebb5ffcd845aeb490bd968f22bdea43048 100644 (file)
--- a/README.md
+++ b/README.md
@@ -31,33 +31,35 @@ 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
+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
+the library and the 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.
+you put it on the 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
+secret and with pre-produced response. With 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
+future authentication session. The advantage of this approach is that
+the secret is not kept anywhere other than inside the token, so the only
+way to leak the secret is together with the token. The drawback is that
+the response that will be expected in the next session is transferred in
+cleartext in the current session, 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
@@ -66,11 +68,11 @@ 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
+the 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
+hosts, and the secret is leakd from one of them, all the hosts are now
 compromised. This is not the case with the first approach.
 
 The particular data structure is outlined in the picture:
@@ -80,11 +82,11 @@ The particular data structure is outlined in the picture:
 
 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.
+according to template that can be provided both to the 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.
 
 Default template string is `~/.pam_cr/auth`, i.e. the file lives in the
 user's home directory, in the subdirectory `.pam_cr`.
@@ -111,8 +113,8 @@ 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 uses 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
+so this can be used for "one factor" authentication mode (with the 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
index 30214f5b89833eb638e5c8ba8b80a56f61f15772..8b47a45d3cbbdadad8ecded609344b6d9104ee2b 100644 (file)
@@ -13,7 +13,7 @@
    height="464.16547"
    id="svg2985"
    version="1.1"
-   inkscape:version="0.48.4 r9939"
+   inkscape:version="0.48.3.1 r9886"
    sodipodi:docname="auth-data-structure.svg">
   <defs
      id="defs2987" />
      inkscape:label="Layer 1"
      inkscape:groupmode="layer"
      transform="translate(-17.858739,-17.834537)">
-    <text
-       xml:space="preserve"
-       style="font-size:28px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
-       x="39.355469"
-       y="59.660156"
-       id="text3765"
-       sodipodi:linespacing="125%"><tspan
-         sodipodi:role="line"
-         id="tspan3767"
-         x="39.355469"
-         y="59.660156">tokenid</tspan></text>
     <text
        xml:space="preserve"
        style="font-size:28px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
        height="60"
        x="410"
        y="20" />
-    <rect
-       style="fill:none;stroke:#000000;stroke-width:4.28252268;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
-       id="rect3803"
-       width="140"
-       height="60"
-       x="20"
-       y="20" />
     <text
        xml:space="preserve"
        style="font-size:28px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"