From: Eugene Crosser Date: Thu, 5 Dec 2013 13:12:35 +0000 (+0400) Subject: mark down README X-Git-Url: http://www.average.org/gitweb/?p=pam_pcsc_cr.git;a=commitdiff_plain;h=288c17d345dfd026fb9d71976275cdabdbeeaf88 mark down README --- 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 deleted file mode 100644 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= template used to find the file. - backend:key=val backend options. - - diff --git a/README.md b/README.md new file mode 100644 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= 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 \ + + +---