add manpage for the module

diff --git a/.gitignore b/.gitignore
index a316a6690be8d560b0a5fb0449d8e9f371f83086..0fb01935af17389b9409de6201805b3e4c45d655 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@
 *.log
 *.trs
 *.tar.xz
 *.log
 *.trs
 *.tar.xz

+*.html

 .deps/
 .libs/
 Makefile
 .deps/
 .libs/
 Makefile

diff --git a/pam_cr_setup.8 b/pam_cr_setup.8
index 24170646e787ddbbd1f42c0d2661c7c5e9a028b4..d09f4452e6ab17f1952afbac2681b28cd838c645 100644 (file)
--- a/pam_cr_setup.8
+++ b/pam_cr_setup.8
@@ -38,7 +38,7 @@ necessary.
 .SH OPTIONS
 .B \-h
 \- show short description and exit.
 .SH OPTIONS
 .B \-h
 \- show short description and exit.

-.sp
+.PP

 .B \-o backend-option
 \- option specific to the crypto-token.
 The format is
 .B \-o backend-option
 \- option specific to the crypto-token.
 The format is


@@ -46,14 +46,14 @@ The format is
 At present, only Yubikey Neo
 crypto-token is supported, and the only option is
 .B ykneo:slot=[1|2].
 At present, only Yubikey Neo
 crypto-token is supported, and the only option is
 .B ykneo:slot=[1|2].

-.sp
+.PP

 .B \-f template
 \- template for the auth file path. It may contain one character
 .B '~'
 which, if in the first position, is replaced with the userid's
 home directory path, and if in any other position - with the userid
 itself.
 .B \-f template
 \- template for the auth file path. It may contain one character
 .B '~'
 which, if in the first position, is replaced with the userid's
 home directory path, and if in any other position - with the userid
 itself.

-.sp
+.PP

 .B \-a secret
 or
 .B \-A file-with-secret
 .B \-a secret
 or
 .B \-A file-with-secret


@@ -65,12 +65,12 @@ the payload in the absense of the crypto-token.
 .B \-A -
 means that the 40-character string is read from
 .B stdin.
 .B \-A -
 means that the 40-character string is read from
 .B stdin.

-.sp
+.PP

 .B \-n nonce
 \- initial nonce. Currently this must be a decimal representation of an
 integer. It is subsequently incremented by one on every successful
 authentication session.
 .B \-n nonce
 \- initial nonce. Currently this must be a decimal representation of an
 integer. It is subsequently incremented by one on every successful
 authentication session.

-.sp
+.PP

 .B \-l payload
 \- a string that will be injected into the PAM framework as
 .B AUTH_TOKEN
 .B \-l payload
 \- a string that will be injected into the PAM framework as
 .B AUTH_TOKEN


@@ -78,7 +78,7 @@ upon successful authentication. It is useful to have the keyring
 unlock password there. The payload is encrypted in the file, and only
 exists in memory in decrypted form for a short period (unless leaked
 by other PAM modules).
 unlock password there. The payload is encrypted in the file, and only
 exists in memory in decrypted form for a short period (unless leaked
 by other PAM modules).

-.sp
+.PP

 .B \-p password
 \- login password that is used to create the challenge (not the one
 from
 .B \-p password
 \- login password that is used to create the challenge (not the one
 from


@@ -89,15 +89,15 @@ module uses when invoked with
 .B noaskpass
 argument. With empty password, login process requires only the presence
 of the crypto-token, and does not involve any input from the user.
 .B noaskpass
 argument. With empty password, login process requires only the presence
 of the crypto-token, and does not involve any input from the user.

-.sp
+.PP

 .B \-v
 \- output the userid and payload from the auth file. Note that displaying
 the payload on screen to be seen by passers by may not be a good idea.
 .B \-v
 \- output the userid and payload from the auth file. Note that displaying
 the payload on screen to be seen by passers by may not be a good idea.

-.sp
+.PP

 
 .SH COPYRIGHT
 2013 Eugene G. Crosser
 .br
 Released under zlib Open Source license.
 .SH SEE ALSO
 
 .SH COPYRIGHT
 2013 Eugene G. Crosser
 .br
 Released under zlib Open Source license.
 .SH SEE ALSO

-.BR pam "(3), "ykpersonalize "(1)
+.BR pam "(3), "ykpersonalize "(1), "pam_pcsc_cr "(8)

diff --git a/pam_pcsc_cr.8 b/pam_pcsc_cr.8
new file mode 100644 (file)
index 0000000..431e2a2
--- /dev/null
+++ b/pam_pcsc_cr.8
@@ -0,0 +1,67 @@
+.\"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.
+.\"
+.TH PAM_PCSC_CR 8 "18 Dec 2013" PAM_PCSC_CR PAM_PCSC_CR
+.SH NAME
+pam_pcsc_cr \- Module for challenge-response authentication
+.SH SYNOPSYS
+.B pam_pcsc_cr.so [options]
+.SH DESCRIPTION
+This is a PAM module for crypto-token based authentication.
+It only provides authentication component, the rest are stubs.
+The module uses the contents of the auth file created with the
+.B pam_cr_setup
+command and optionally a password provided by the user to construct
+challenge that is sent to the crypto-token over
+.B pcsclite
+framework. The token's response is used to decipher the encrypted part
+of the file. If decryption is successful, then the extracted shared
+secret is used to produce ithe expected response to the future
+(different) challenge, encrypted again with the expected response,
+and stowed into the file. Additional payload that was decrypted on
+the way is optionally injected into the PAM framework as AUTH_TOKEN
+to be later used by keyring-unlocking module.
+.SH OPTIONS
+.B verbose
+\- write more error messages to syslog.
+.PP
+.B noaskpass
+\- do not try to ask the user for the challenge password, use empty
+string for the password.
+.PP
+.B injectauth
+\- inject payload as PAM_AUTHTOK for the benefit of subsequent PAM modules.
+.PP
+.B path=<string>
+\- template used to find the file.
+.PP
+.B backend:key=value
+\- option specific to the crypto-token. At present, only Yubikey Neo
+crypto-token is supported, and the only option is
+.B ykneo:slot=[1|2].
+.PP
+
+.SH COPYRIGHT
+2013 Eugene G. Crosser
+.br
+Released under zlib Open Source license.
+.SH SEE ALSO
+.BR pam "(3), "ykpersonalize "(1), "pam_cr_setup "(8)