pam_pkcs11(5)

1pam_pkcs11(5)         Standards, Environments, and Macros        pam_pkcs11(5)
2
3
4

NAME

6       pam_pkcs11 - PAM Authentication Module for the PKCS#11 token libraries
7

SYNOPSIS

9       pam_pkcs11.so [debug] [config_file=filename]
10
11

DESCRIPTION

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

OPTIONS

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

FILES

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

AUTHORS

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

ATTRIBUTES

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