1 '\" te |
|
2 .\" Portions Copyright (c) 2008, 2012, Oracle and/or its affiliates. All rights reserved. |
|
3 .\" This manual page is derived from documentation obtained from the OpenSC organization (www.opensc-project.org). This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it is useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
|
4 .TH pam_pkcs11 5 "22 May 2012" "SunOS 5.12" "Standards, Environments, and Macros" |
|
5 .SH NAME |
|
6 pam_pkcs11 \- PAM Authentication Module for the PKCS#11 token libraries |
|
7 .SH SYNOPSIS |
|
8 .LP |
|
9 .nf |
|
10 \fBpam_pkcs11.so\fR [debug] [config_file=\fIfilename\fR] |
|
11 .fi |
|
12 |
|
13 .SH DESCRIPTION |
|
14 .sp |
|
15 .LP |
|
16 The \fBpam_pkcs11\fR module implements \fBpam_sm_authenticate\fR(3PAM), which provides functionality to the PAM authentication stack. This module allows a user to login a system, using a X.509 certificate and its dedicated private key stored in a PKCS#11 token. This module currently supports the RSA algorithm only. |
|
17 .sp |
|
18 .LP |
|
19 To verify the dedicated private key is truly associated with the X.509 certificate, the following verification procedure is performed in this module by default: |
|
20 .RS +4 |
|
21 .TP |
|
22 .ie t \(bu |
|
23 .el o |
|
24 Generate 128 random byte data |
|
25 .RE |
|
26 .RS +4 |
|
27 .TP |
|
28 .ie t \(bu |
|
29 .el o |
|
30 Sign the random data with the private key and get a signature. This step is done in the PKCS#11 token. |
|
31 .RE |
|
32 .RS +4 |
|
33 .TP |
|
34 .ie t \(bu |
|
35 .el o |
|
36 Verify the signature using the public key extracted from the certificate. |
|
37 .RE |
|
38 .sp |
|
39 .LP |
|
40 For the verification of the users' certificates, locally stored CA certificates as well as either online or locally accessible CRLs are used. |
|
41 .SS "PAM CONFIGURATION" |
|
42 .sp |
|
43 .LP |
|
44 The \fBpam_pkcs11.so\fR service module can be used in the \fB<auth>\fR PAM chain. The program that needs a PAM service should be configured in \fB/etc/pam.conf\fR or \fB/etc/pam.d/\fR\fIservice\fR. For details on how to configure PAM services, see \fBpam.conf\fR(4). |
|
45 .sp |
|
46 .LP |
|
47 The following example uses only \fBpam_pkcs11\fR for authentication: |
|
48 .sp |
|
49 .in +2 |
|
50 .nf |
|
51 login auth requisite pam_pkcs11.so.1 |
|
52 login autho required pam_unix_cred.so.1 |
|
53 .fi |
|
54 .in -2 |
|
55 |
|
56 .sp |
|
57 .LP |
|
58 The following example uses \fBpam_pkcs11\fR for authentication with fallback to standard UNIX authentication: |
|
59 .sp |
|
60 .in +2 |
|
61 .nf |
|
62 login auth sufficient pam_pkcs11.so.1 |
|
63 login auth requisite pam_authtok_get.so.1 |
|
64 login auth required pam_dhkeys.so.1 |
|
65 login auth required pam_unix_cred.so.1 |
|
66 login auth required pam_unix_auth.so.1 |
|
67 .fi |
|
68 .in -2 |
|
69 |
|
70 .SS "PAM_PKCS11 CONFIGURATION" |
|
71 .sp |
|
72 .LP |
|
73 To configure the \fBpam_pkcs11\fR module, you must have the following information: |
|
74 .RS +4 |
|
75 .TP |
|
76 .ie t \(bu |
|
77 .el o |
|
78 Which PKCS #11 token you are going to use |
|
79 .RE |
|
80 .RS +4 |
|
81 .TP |
|
82 .ie t \(bu |
|
83 .el o |
|
84 Which mapper(s) you need, and if needed, how to create and edit the related mapping files |
|
85 .RE |
|
86 .RS +4 |
|
87 .TP |
|
88 .ie t \(bu |
|
89 .el o |
|
90 The root Certificate Authority files, and if required, the Certificate Revocation Lists files |
|
91 .RE |
|
92 .RS +4 |
|
93 .TP |
|
94 .ie t \(bu |
|
95 .el o |
|
96 The list of authorized users to login, and their corresponding certificates |
|
97 .RE |
|
98 .sp |
|
99 .LP |
|
100 To configure the \fBpam_pkcs11\fR module, you need to modify the \fBpam_pkcs11.conf\fR configuration file which is in the \fB/etc/security/pam_pkcs11\fR directory by default. For detailed information on how to configure the \fBpam_pkcs11\fR module, see the \fIPAM-PKCS11 User Manual\fR, available at the \fBhttp://www.opensc-project.org/\fR web site, under the \fBPAM PKCS#11\fR link. |
|
101 .sp |
|
102 .LP |
|
103 The following example illustrates how to configure the \fBpam_pkcs11\fR module for a user whose certificate and private key are stored in the Solaris \fBpkcs11_softtoken\fR keystore. This example uses the default certificate verification policy. |
|
104 .RS +4 |
|
105 .TP |
|
106 .ie t \(bu |
|
107 .el o |
|
108 Set up the PKCS#11 module. |
|
109 .sp |
|
110 On Solaris, the PKCS#11 module should be set to \fB/usr/lib/libpkcs11.so.1\fR, the PKCS#11 Cryptographic Framework library. |
|
111 .RE |
|
112 .RS +4 |
|
113 .TP |
|
114 .ie t \(bu |
|
115 .el o |
|
116 Set up the \fBslot_description\fR entry. |
|
117 .sp |
|
118 Specifies the slot to be used. For example, \fBslot_description = "Sun Crypto Softtoken"\fR. The default value for this entry is \fBnone\fR which means to use the first slot with an available token. |
|
119 .sp |
|
120 An administrator can use the \fBcryptoadm list -v\fRcommand to find all the available slots and their slot descriptions. For more information, see \fBlibpkcs11\fR(3LIB) and \fBcryptoadm\fR(1M). |
|
121 .RE |
|
122 .RS +4 |
|
123 .TP |
|
124 .ie t \(bu |
|
125 .el o |
|
126 Install or create user certificates and its dedicated private keys in the specific PKCS#11 token. |
|
127 .RE |
|
128 .RS +4 |
|
129 .TP |
|
130 .ie t \(bu |
|
131 .el o |
|
132 Set up the certificate verification policy (\fBcert_policy\fR). If needed, set up CA certificate and CRL files. |
|
133 .sp |
|
134 The certificate verification policy includes: |
|
135 .RS |
|
136 |
|
137 .sp |
|
138 .ne 2 |
|
139 .mk |
|
140 .na |
|
141 \fB\fBnone\fR\fR |
|
142 .ad |
|
143 .RS 13n |
|
144 .rt |
|
145 Perform no verification |
|
146 .RE |
|
147 |
|
148 .sp |
|
149 .ne 2 |
|
150 .mk |
|
151 .na |
|
152 \fB\fBca\fR\fR |
|
153 .ad |
|
154 .RS 13n |
|
155 .rt |
|
156 Perform CA check |
|
157 .RE |
|
158 |
|
159 .sp |
|
160 .ne 2 |
|
161 .mk |
|
162 .na |
|
163 \fB\fBsignature\fR\fR |
|
164 .ad |
|
165 .RS 13n |
|
166 .rt |
|
167 Perform a signature check to ensure that private and public key matches |
|
168 .RE |
|
169 |
|
170 .sp |
|
171 .ne 2 |
|
172 .mk |
|
173 .na |
|
174 \fB\fBcrl_\fR\fIxxx\fR\fR |
|
175 .ad |
|
176 .RS 13n |
|
177 .rt |
|
178 Perform various certificate revocation checking |
|
179 .RE |
|
180 |
|
181 .RE |
|
182 |
|
183 As this example uses the default policy, \fBcert_policy = ca,signature\fR, an administer needs to set up the CA certificates. |
|
184 .RS +4 |
|
185 .TP |
|
186 .ie t \(bu |
|
187 .el o |
|
188 Copy the CA certificate to the \fB/etc/security/pam_pkcs11/cacerts\fR directory. |
|
189 .sp |
|
190 A certificate that is self-signed is its own CA certificate. Therefore, in this example, the certificate is placed both in the Softtoken keystore and in the CA certificate directory. |
|
191 .RE |
|
192 .RS +4 |
|
193 .TP |
|
194 .ie t \(bu |
|
195 .el o |
|
196 Make hash links for CA certificates |
|
197 .sp |
|
198 .in +2 |
|
199 .nf |
|
200 $ /etc/security/pam_pkcs11/make_hash_link.sh \e |
|
201 /etc/security/pam_pkcs11/cacerts |
|
202 .fi |
|
203 .in -2 |
|
204 .sp |
|
205 |
|
206 .RE |
|
207 .RE |
|
208 .RS +4 |
|
209 .TP |
|
210 .ie t \(bu |
|
211 .el o |
|
212 Set up the mappers and mapfiles. |
|
213 .sp |
|
214 When a X509 certificate is provided, there are no direct ways to map a certificate to a login. The \fBpam_pkcs11\fR module provides a configurable way with mappers to specify \fBcert-to-user\fR mapping. |
|
215 .sp |
|
216 Many mappers are provided by the \fBpam_pkcs11\fR module, for example, the common name (CN) mapper, the digest mapper, the Email mapper, or the LDAP mapper. |
|
217 .sp |
|
218 A user can configure a mapper list in the \fBpam_pkcs11.conf\fR file. The mappers in the list are used sequentially until the certificate is successfully matched with the user. |
|
219 .sp |
|
220 The default mapper list is as follows: |
|
221 .sp |
|
222 .in +2 |
|
223 .nf |
|
224 use_mappers = digest, cn, pwent, uid, mail, subject, null; |
|
225 .fi |
|
226 .in -2 |
|
227 .sp |
|
228 |
|
229 Some mappers do not require the specification of a mapfile, for example, the common name mapper. Other mappers require mapfiles, for example, the digest mapper. Some sample mapping files can be found in the \fB/etc/security/pam_pkcs11\fR directory. |
|
230 .RE |
|
231 .SH OPTIONS |
|
232 .sp |
|
233 .LP |
|
234 The following options are supported: |
|
235 .sp |
|
236 .ne 2 |
|
237 .mk |
|
238 .na |
|
239 \fB\fBconfig_file=\fIfilename\fR\fR\fR |
|
240 .ad |
|
241 .RS 24n |
|
242 .rt |
|
243 Specify the configuration file. The default value is \fB/etc/security/pam_pkcs11/pam_pkcs11.conf\fR. |
|
244 .RE |
|
245 |
|
246 .sp |
|
247 .ne 2 |
|
248 .mk |
|
249 .na |
|
250 \fB\fBdebug\fR\fR |
|
251 .ad |
|
252 .RS 24n |
|
253 .rt |
|
254 Enable debugging output. |
|
255 .RE |
|
256 |
|
257 .SH FILES |
|
258 .sp |
|
259 .ne 2 |
|
260 .mk |
|
261 .na |
|
262 \fB\fB/usr/lib/security/pam_pkcs11.so\fR\fR |
|
263 .ad |
|
264 .sp .6 |
|
265 .RS 4n |
|
266 \fBpam_pkcs11\fR module |
|
267 .RE |
|
268 |
|
269 .sp |
|
270 .ne 2 |
|
271 .mk |
|
272 .na |
|
273 \fB\fB/usr/lib/pam_pkcs11/ldap_mapper.so\fR\fR |
|
274 .ad |
|
275 .sp .6 |
|
276 .RS 4n |
|
277 Mapper module. |
|
278 .RE |
|
279 |
|
280 .sp |
|
281 .ne 2 |
|
282 .mk |
|
283 .na |
|
284 \fB\fB/usr/lib/pam_pkcs11/opensc_mapper.so\fR\fR |
|
285 .ad |
|
286 .sp .6 |
|
287 .RS 4n |
|
288 Mapper module. |
|
289 .RE |
|
290 |
|
291 .sp |
|
292 .ne 2 |
|
293 .mk |
|
294 .na |
|
295 \fB\fB/usr/lib/pam_pkcs11/openssh_mapper.so\fR\fR |
|
296 .ad |
|
297 .sp .6 |
|
298 .RS 4n |
|
299 Mapper module. |
|
300 .RE |
|
301 |
|
302 .sp |
|
303 .ne 2 |
|
304 .mk |
|
305 .na |
|
306 \fB\fB/etc/security/pam_pkcs11/pam_pkcs11.conf\fR\fR |
|
307 .ad |
|
308 .sp .6 |
|
309 .RS 4n |
|
310 Configuration file. |
|
311 .RE |
|
312 |
|
313 .sp |
|
314 .ne 2 |
|
315 .mk |
|
316 .na |
|
317 \fB\fB/etc/security/pam_pkcs11/cacerts\fR\fR |
|
318 .ad |
|
319 .sp .6 |
|
320 .RS 4n |
|
321 Configuration directory. Stores the CA certificates. |
|
322 .RE |
|
323 |
|
324 .sp |
|
325 .ne 2 |
|
326 .mk |
|
327 .na |
|
328 \fB\fB/etc/security/pam_pkcs11/crls\fR\fR |
|
329 .ad |
|
330 .sp .6 |
|
331 .RS 4n |
|
332 Configuration directory. Stores the CRL files. |
|
333 .RE |
|
334 |
|
335 .sp |
|
336 .ne 2 |
|
337 .mk |
|
338 .na |
|
339 \fB\fB/etc/security/pam_pkcs11/digest_mapping.example\fR\fR |
|
340 .ad |
|
341 .sp .6 |
|
342 .RS 4n |
|
343 Sample mapfile. |
|
344 .RE |
|
345 |
|
346 .sp |
|
347 .ne 2 |
|
348 .mk |
|
349 .na |
|
350 \fB\fB/etc/security/pam_pkcs11/subject_mapping.example\fR\fR |
|
351 .ad |
|
352 .sp .6 |
|
353 .RS 4n |
|
354 Sample mapfile. |
|
355 .RE |
|
356 |
|
357 .sp |
|
358 .ne 2 |
|
359 .mk |
|
360 .na |
|
361 \fB\fB/etc/security/pam_pkcs11/mail_mapping.example\fR\fR |
|
362 .ad |
|
363 .sp .6 |
|
364 .RS 4n |
|
365 Sample mapfile. |
|
366 .RE |
|
367 |
|
368 .sp |
|
369 .ne 2 |
|
370 .mk |
|
371 .na |
|
372 \fB\fB/etc/security/pam_pkcs11/make_hash_link.sh\fR\fR |
|
373 .ad |
|
374 .sp .6 |
|
375 .RS 4n |
|
376 Sample script. |
|
377 .RE |
|
378 |
|
379 .SH AUTHORS |
|
380 .sp |
|
381 .LP |
|
382 \fBPAM-pkcs11\fR was originally written by MarioStrasser , \[email protected]\fR. |
|
383 .sp |
|
384 .LP |
|
385 Newer versions are from Juan Antonio Martinez, \[email protected]\fR |
|
386 .SH ATTRIBUTES |
|
387 .sp |
|
388 .LP |
|
389 See \fBattributes\fR(5) for a description of the following attributes: |
|
390 .sp |
|
391 |
|
392 .sp |
|
393 .TS |
|
394 tab() box; |
|
395 cw(2.75i) |cw(2.75i) |
|
396 lw(2.75i) |lw(2.75i) |
|
397 . |
|
398 ATTRIBUTE TYPEATTRIBUTE VALUE |
|
399 _ |
|
400 AvailabilityT{ |
|
401 library/security/pam/module/pam-pkcs11, SUNWpampkcs11r, SUNWpampkcs11-docs |
|
402 T} |
|
403 _ |
|
404 Interface StabilityUncommitted |
|
405 .TE |
|
406 |
|
407 .SH SEE ALSO |
|
408 .sp |
|
409 .LP |
|
410 \fBpkcs11_inspect\fR(1), \fBpklogin_finder\fR(1), \fBcryptoadm\fR(1M), \fBlibpkcs11\fR(3LIB)\fBlibpkcs11\fR(3LIB)\fBpam_sm_authenticate\fR(3PAM), \fBpam.conf\fR(4), \fBattributes\fR(5), \fBpkcs11_softtoken\fR(5) |
|
411 .sp |
|
412 .LP |
|
413 \fIPAM-PKCS11 User Manual\fR, available at the \fBhttp://www.opensc-project.org/\fR web site, under the \fBPAM PKCS#11\fR link. |
|