forked from OpenSC/pam_pkcs11
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
184 lines (129 loc) · 6.24 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
This is the README of the PKCS #11 PAM Login Module
======================================================================
Authors: Mario Strasser <[email protected]>
Juan Antonio Martinez <[email protected]>
Ludovic Rouseau <[email protected]>
Frank Morgner <[email protected]>
This Linux-PAM login module allows a X.509 certificate based user
login. The certificate and its dedicated private key are thereby
accessed by means of an appropriate PKCS #11 module. For the
verification of the users' certificates, locally stored CA
certificates as well as either online or locally accessible CRLs are
used.
Detailed information about the Linux-PAM system can be found in [1],
[2] and [3]. The specification of the Cryptographic Token Interface
Standard (PKCS #11) is available at [4].
PKCS #11 Module Requirements
----------------------------------------------------------------------
The PKCS #11 modules must fullfill the requirements given by the RSA
Asymmetric Client Signing Profile, which has been specified in the
PKCS #11 Conformance Profile Specification [5] by RSA Laboratories.
User Matching
----------------------------------------------------------------------
To approve the ownership of a certificate, that is to allow the owner
of a certificate to login as a particular user Several modules
are provided. See README.mappers file in doc directory
[Note: This is still a work in progress, any suggestions for
improvements or alternative matching algorithms are welcome.]
Installation
----------------------------------------------------------------------
bash# tar xvzf pam_pkcs11-X.Y.Z.tar.gz
bash# cd pam_pkcs11-X.Y.Z
bash# ./configure
bash# make
bash# sudo make install
Configuration
1- Create a directory /etc/pam_pkcs11
2- Copy $(base)/etc/pam_pkcs11.conf.example to /etc/pam_pkcs11/ and personalize
3- Create crls and cacerts directories according with configuration file,
and fill them with proper data
4- Choose one or more mappers to install, set up configuration file, and
if needed configure mappers
The file etc/pam_pkcs11.conf is fully auto-documented, to allow you easy
editing
5- setup /etc/pam.d/xxx entries
----------------------------------------------------------------------
To make use of the PKCS #11 login module replace the line
auth requisite pam_unix2.so ...
with
auth requisite pam_pkcs11.so ...
in the pam configuration files.
Some mappers doesn't map to an existing user. To allow correct login,
you may need to install also pam-mkhomedir in session pam stack
See http://www.kernel.org/pub/linux/libs/pam for details
The following options are recognised for pam-pkcs11.so:
debug
Enable debugging support.
config_file
To specify up configuration file ( default /etc/pam_pkcs11/pam_pkcs11.conf )
Next options should be taken from configuration file, but is up to the
user to specify them from command line. If so, it takes precedence over
configuration file
nullok
Allow empty passwords.
use_first_pass
Do not prompt the user for the passwords but take them from the
PAM_ items instead.
try_first_pass
Do not prompt the user for the passwords unless PAM_(OLD)AUTHTOK
is unset.
use_authtok
Like try_first_pass, but fail if the new PAM_AUTHTOK has not been
previously set (intended for stacking password modules only).
card_only
Always try to get the userid from the certificate, don't prompt for the user name if
the card is present, and if the token is present, then we must use it to authenticate.
wait_for_card
This option needs card_only to be set. This will make the system wait for the
token to be inserted on login, or after login it will require the same token be
inserted to unlock the system.
Next options are pkcs11 module specific
pkcs11_module=<file>
Filename of the PKCS #11 module. The default value is
/etc/pam_pkcs11/pkcs11_module.so.
Note that this option takes precedence over "module" entry
in proper pkcs11_module section, but this section is still needed
slot_num=<nr>
Slot-number to use. One for the first, two for the second and so
on. The default value is zero which means to use the first slot
with an available token.
ca_dir=<path>
Path to the directory where the CA certificates are stored. The
directory must contain an openssl hash-link to each certificate.
The default value is /etc/pam_pkcs11/cacerts.
crl_dir=<path>
Path to the directory where the CRLs are stored. The directory
must contain an openssl hash-link to each CRL. The default value
is /etc/pam_pkcs11/crls.
crl_policy={none, online, offline, auto}
Sets the CRL verification policy. None performs no verification
at all, online downloads the CRL form the location given by the
CRL distribution point extension of the certificate and offline
uses the locally stored CRLs. Auto is a combination of online and
offline; it first tries to download the CRL from a possibly
given CRL distribution point and if this fails, uses the local
CRLs. The default setting is none.
Example:
auth sufficient pam_pkcs11.so config_file=/etc/pam_pkcs11/pam_pkcs11.conf
or ( avoid if possible )
auth sufficient pam_pkcs11.so nullok debug try_first_pass \
pkcs11_module=/usr/lib/pkcs11/pkcs11_module.so \
ca_dir=/etc/cacerts/ crl_dir=/etc/cacerts/ crl_policy=auto
Contact
----------------------------------------------------------------------
Any comments, suggestions and bug reports are welcome. Please, mention
the keywords 'pkcs' and 'pam' in the subject.
Mario Strasser <[email protected]>
Juan Antonio Martinez <[email protected]>
References
----------------------------------------------------------------------
[1] The Linux-PAM System Administrators' Guide
http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam.html
[2] The Linux-PAM Module Writers' Guide
http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam_modules.html
[3] The Linux-PAM Application Developers' Guide
http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam_appl.html
[4] PKCS #11 - Cryptographic Token Interface Standard
http://www.rsasecurity.com/rsalabs/pkcs/pkcs-11/
[5] PKCS #11: Conformance Profile Specification
http://www.rsasecurity.com/rsalabs/pkcs/pkcs-11/