.su objects to gitignore
[pam_pcsc_cr.git] / pam_cr_setup.8
1 .\"Copyright (c) 2013 Eugene Crosser
2 .\"
3 .\"This software is provided 'as-is', without any express or implied
4 .\"warranty. In no event will the authors be held liable for any damages
5 .\"arising from the use of this software.
6 .\"
7 .\"Permission is granted to anyone to use this software for any purpose,
8 .\"including commercial applications, and to alter it and redistribute it
9 .\"freely, subject to the following restrictions:
10 .\"
11 .\"    1. The origin of this software must not be misrepresented; you must
12 .\"    not claim that you wrote the original software. If you use this
13 .\"    software in a product, an acknowledgment in the product documentation
14 .\"    would be appreciated but is not required.
15 .\"
16 .\"    2. Altered source versions must be plainly marked as such, and must
17 .\"    not be misrepresented as being the original software.
18 .\"
19 .\"    3. This notice may not be removed or altered from any source
20 .\"    distribution.
21 .\"
22 .TH PAM_CR_SETUP 8 "18 Dec 2013" PAM_PCSC_CR PAM_PCSC_CR
23 .SH NAME
24 pam_cr_setup \- manipulate user auth file for pam_pcsc_cr
25 .SH SYNOPSYS
26 .B pam_cr_setup
27 [options] [username]
28 .SH DESCRIPTION
29 .B pam_cr_setup
30 creates and modifies the file with the shared secret that is used by
31 .B pam_pcsc_cr
32 PAM module for crypto-token based authentication. To initially create
33 the file, you must provide the shared secret that is also installed in
34 the token. Later on, the command may be used to update the payload
35 which may be the keyring unlock key. If used in the latter mode, and
36 if the crypto-token is present, specifying the shared secret is not
37 necessary.
38 .SH OPTIONS
39 .B \-h
40 \- show short description and exit.
41 .PP
42 .B \-o backend-option
43 \- option specific to the crypto-token.
44 The format is
45 .B backend:key=value.
46 At present, only Yubikey Neo
47 crypto-token is supported, and the only option is
48 .B ykneo:slot=[1|2].
49 .PP
50 .B \-f template
51 \- template for the auth file path. It may contain one character
52 .B '~'
53 which, if in the first position, is replaced with the userid's
54 home directory path, and if in any other position - with the userid
55 itself.
56 .PP
57 .B \-a secret
58 or
59 .B \-A file-with-secret
60 or
61 .B \-A -
62 \- 40-character hexadecimal representation of the shared secret.
63 It must be provided when first creating the file, and when updating
64 the payload in the absense of the crypto-token.
65 .B \-A -
66 means that the 40-character string is read from
67 .B stdin.
68 .PP
69 .B \-n nonce
70 \- initial nonce. Currently this must be a decimal representation of an
71 integer. It is subsequently incremented by one on every successful
72 authentication session.
73 .PP
74 .B \-l payload
75 \- a string that will be injected into the PAM framework as
76 .B AUTH_TOKEN
77 upon successful authentication. It is useful to have the keyring
78 unlock password there. The payload is encrypted in the file, and only
79 exists in memory in decrypted form for a short period (unless leaked
80 by other PAM modules).
81 .PP
82 .B \-p password
83 \- login password that is used to create the challenge (not the one
84 from
85 .BR /etc/shadow ").
86 If not specified, an empty string is used, which is the same as the
87 .B pam_pcsc_cr
88 module uses when invoked with
89 .B noaskpass
90 argument. With empty password, login process requires only the presence
91 of the crypto-token, and does not involve any input from the user.
92 .PP
93 .B \-v
94 \- output the userid and payload from the auth file. Note that displaying
95 the payload on screen to be seen by passers by may not be a good idea.
96 .PP
97
98 .SH COPYRIGHT
99 2013 Eugene G. Crosser
100 .br
101 Released under zlib Open Source license.
102 .SH SEE ALSO
103 .BR pam "(3), "ykpersonalize "(1), "pam_pcsc_cr "(8)