1pam_pkcs11(5) Standards, Environments, and Macros pam_pkcs11(5)
2
3
4
6 pam_pkcs11 - PAM Authentication Module for the PKCS#11 token libraries
7
9 pam_pkcs11.so [debug] [config_file=filename]
10
11
13 The pam_pkcs11 module implements pam_sm_authenticate(3PAM), which pro‐
14 vides functionality to the PAM authentication stack. This module allows
15 a user to login a system, using a X.509 certificate and its dedicated
16 private key stored in a PKCS#11 token. This module currently supports
17 the RSA algorithm only.
18
19
20 To verify the dedicated private key is truly associated with the X.509
21 certificate, the following verification procedure is performed in this
22 module by default:
23
24 o Generate 128 random byte data
25
26 o Sign the random data with the private key and get a signa‐
27 ture. This step is done in the PKCS#11 token.
28
29 o Verify the signature using the public key extracted from the
30 certificate.
31
32
33 For the verification of the users' certificates, locally stored CA cer‐
34 tificates as well as either online or locally accessible CRLs are used.
35
36 PAM CONFIGURATION
37 The pam_pkcs11.so service module can be used in the <auth> PAM chain.
38 The program that needs a PAM service should be configured in the
39 /etc/pam.conf file. For details on how to configure PAM services, see
40 pam.conf(4).
41
42
43 The following example uses only pam_pkcs11 for authentication:
44
45 login auth requisite pam_pkcs11.so.1
46 login autho required pam_unix_cred.so.1
47
48
49
50 The following example uses pam_pkcs11 for authentication with fallback
51 to standard UNIX authentication:
52
53 login auth sufficient pam_pkcs11.so.1
54 login auth requisite pam_authtok_get.so.1
55 login auth required pam_dhkeys.so.1
56 login auth required pam_unix_cred.so.1
57 login auth required pam_unix_auth.so.1
58
59
60 PAM_PKCS11 CONFIGURATION
61 To configure the pam_pkcs11 module, you must have the following infor‐
62 mation:
63
64 o Which PKCS #11 token you are going to use
65
66 o Which mapper(s) you need, and if needed, how to create and
67 edit the related mapping files
68
69 o The root Certificate Authority files, and if required, the
70 Certificate Revocation Lists files
71
72 o The list of authorized users to login, and their correspond‐
73 ing certificates
74
75
76 To configure the pam_pkcs11 module, you need to modify the
77 pam_pkcs11.conf configuration file which is in the /etc/secu‐
78 rity/pam_pkcs11 directory by default. For detailed information on how
79 to configure the pam_pkcs11 module, see the PAM-PKCS11 User Manual,
80 available at the http://www.opensc-project.org/ web site, under the PAM
81 PKCS#11 link.
82
83
84 The following example illustrates how to configure the pam_pkcs11 mod‐
85 ule for a user whose certificate and private key are stored in the
86 Solaris pkcs11_softtoken keystore. This example uses the default cer‐
87 tificate verification policy.
88
89 o Set up the PKCS#11 module.
90
91 On Solaris, the PKCS#11 module should be set to
92 /usr/lib/libpkcs11.so.1, the PKCS#11 Cryptographic Framework
93 library.
94
95 o Set up the slot_description entry.
96
97 Specifies the slot to be used. For example, slot_description
98 = "Sun Crypto Softtoken". The default value for this entry
99 is none which means to use the first slot with an available
100 token.
101
102 An administrator can use the cryptoadm list -vcommand to
103 find all the available slots and their slot descriptions.
104 For more information, see libpkcs11(3LIB) and cryptoadm(1M).
105
106 o Install or create user certificates and its dedicated pri‐
107 vate keys in the specific PKCS#11 token.
108
109 o Set up the certificate verification policy (cert_policy). If
110 needed, set up CA certificate and CRL files.
111
112 The certificate verification policy includes:
113
114
115 none Perform no verification
116
117
118 ca Perform CA check
119
120
121 signature Perform a signature check to ensure that pri‐
122 vate and public key matches
123
124
125 crl_xxx Perform various certificate revocation checking
126
127
128 As this example uses the default policy, cert_policy = ca,signa‐
129 ture, an administer needs to set up the CA certificates.
130
131 o Copy the CA certificate to the /etc/secu‐
132 rity/pam_pkcs11/cacerts directory.
133
134 A certificate that is self-signed is its own CA certifi‐
135 cate. Therefore, in this example, the certificate is
136 placed both in the Softtoken keystore and in the CA cer‐
137 tificate directory.
138
139 o Make hash links for CA certificates
140
141 $ /etc/security/pam_pkcs11/make_hash_link.sh \
142 /etc/security/pam_pkcs11/cacerts
143
144
145
146 o Set up the mappers and mapfiles.
147
148 When a X509 certificate is provided, there are no direct
149 ways to map a certificate to a login. The pam_pkcs11 module
150 provides a configurable way with mappers to specify cert-to-
151 user mapping.
152
153 Many mappers are provided by the pam_pkcs11 module, for
154 example, the common name (CN) mapper, the digest mapper, the
155 Email mapper, or the LDAP mapper.
156
157 A user can configure a mapper list in the pam_pkcs11.conf
158 file. The mappers in the list are used sequentially until
159 the certificate is successfully matched with the user.
160
161 The default mapper list is as follows:
162
163 use_mappers = digest, cn, pwent, uid, mail, subject, null;
164
165
166 Some mappers do not require the specification of a mapfile,
167 for example, the common name mapper. Other mappers require
168 mapfiles, for example, the digest mapper. Some sample map‐
169 ping files can be found in the /etc/security/pam_pkcs11
170 directory.
171
173 The following options are supported:
174
175 config_file=filename Specify the configuration file. The default
176 value is /etc/secu‐
177 rity/pam_pkcs11/pam_pkcs11.conf.
178
179
180 debug Enable debugging output.
181
182
184 /usr/lib/security/pam_pkcs11.so
185
186 pam_pkcs11 module
187
188
189 /usr/lib/pam_pkcs11/ldap_mapper.so
190
191 Mapper module.
192
193
194 /usr/lib/pam_pkcs11/opensc_mapper.so
195
196 Mapper module.
197
198
199 /usr/lib/pam_pkcs11/openssh_mapper.so
200
201 Mapper module.
202
203
204 /etc/security/pam_pkcs11/pam_pkcs11.conf
205
206 Configuration file.
207
208
209 /etc/security/pam_pkcs11/cacerts
210
211 Configuration directory. Stores the CA certificates.
212
213
214 /etc/security/pam_pkcs11/crls
215
216 Configuration directory. Stores the CRL files.
217
218
219 /etc/security/pam_pkcs11/digest_mapping.example
220
221 Sample mapfile.
222
223
224 /etc/security/pam_pkcs11/subject_mapping.example
225
226 Sample mapfile.
227
228
229 /etc/security/pam_pkcs11/mail_mapping.example
230
231 Sample mapfile.
232
233
234 /etc/security/pam_pkcs11/make_hash_link.sh
235
236 Sample script.
237
238
240 PAM-pkcs11 was originally written by MarioStrasser , mast@gmx.net.
241
242
243 Newer versions are from Juan Antonio Martinez, jonsito@teleline.es
244
246 See attributes(5) for a description of the following attributes:
247
248
249
250
251 ┌─────────────────────────────┬─────────────────────────────┐
252 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
253 ├─────────────────────────────┼─────────────────────────────┤
254 │Availability │SUNWpampkcs11u, SUNWpamp‐ │
255 │ │kcs11r, SUNWpampkcs11-docs │
256 ├─────────────────────────────┼─────────────────────────────┤
257 │Interface Stability │Uncommitted │
258 └─────────────────────────────┴─────────────────────────────┘
259
261 pkcs11_inspect(1), pklogin_finder(1), cryptoadm(1M), libp‐
262 kcs11(3LIB)libpkcs11(3LIB)pam_sm_authenticate(3PAM), pam.conf(4),
263 attributes(5), pkcs11_softtoken(5)
264
265
266 PAM-PKCS11 User Manual, available at the http://www.opensc-project.org/
267 web site, under the PAM PKCS#11 link.
268
269
270
271SunOS 5.11 21 Jul 2008 pam_pkcs11(5)