From 288c17d345dfd026fb9d71976275cdabdbeeaf88 Mon Sep 17 00:00:00 2001 From: Eugene Crosser Date: Thu, 5 Dec 2013 17:12:35 +0400 Subject: [PATCH] mark down README --- Makefile.am | 2 +- README => README.md | 89 +++++++++++++++++++++++++++++++-------------- 2 files changed, 62 insertions(+), 29 deletions(-) rename README => README.md (63%) diff --git a/Makefile.am b/Makefile.am index d6eeb62..ab96020 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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.md similarity index 63% rename from README rename to README.md index af0bd75..c12a0dc 100644 --- a/README +++ b/README.md @@ -1,3 +1,5 @@ + +``` Copyright (c) 2013 Eugene Crosser This software is provided 'as-is', without any express or implied @@ -18,31 +20,44 @@ freely, subject to the following restrictions: 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 module and accompanying setup program -implementing HMAC-SHA1 challenge-response user authentication with -hardware crypto token supporting PC/SC (Smartcard) interface. +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 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. +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 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. +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 @@ -52,11 +67,13 @@ 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 +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 key to an adversary, all hosts are +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 @@ -70,12 +87,13 @@ 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". +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. +`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" @@ -87,6 +105,7 @@ usage: pam_cr_setup [options] [username] -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, @@ -103,12 +122,26 @@ 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= template used to find the file. - backend:key=val backend options. +``` + 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= 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 \ + +--- -- 2.39.2