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
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
|
Building with pkinit enabled:
=============================
To build the code you will need OpenSSL headers. To build
with smartcard support, OpenSC is required. The code can
currently be built w/o smartcard support by defining
WITHOUT_PKCS11 in the CFLAGS.
Although you will need OpenSC to build the code, at run time you just need a
pkcs11 module. It may be possible to build without having OpenSC installed
by changing the path to the pkcs11 include file and the name of the default
module. We have not tried this.
Running with pkinit enabled:
=============================
In the following descriptions, options specified with "DIR:"
are assumed to point to an OpenSSL-style hashed CA directory
where each CA cert is stored in a file "<hash of CA cert>.0".
We assume that a CRL directory (pkinit_revoke) will contain CRL files
"<hash of CA cert>.r0". We encourage that users have such
infrastructure but we will also allow files that contain
certificates (or crls) in that directory that are not named
in this style. Basically, for a given directory, the code
will read each file in the directory and if the file contains
a certificate (or crl), we will include it.
Configuration for a pkinit-enabled KDC:
---------------------------------------
The following pkinit-specific configuration parameters can be specified
in kdc.conf in either the [kdcdefaults] stanza or the appropriate
realm entry:
"pkinit_identity"
Specifies where to find the KDC's certificate and private key.
It is REQUIRED, and can be defined only once. It takes the form:
FILE:<cert-file-name>[,<key-file-name>]
If <key-file-name> is not specified, the private key is assumed
to be located in the same file with the certificate.
"pkinit_anchors"
Specifies where the KDC will find trusted root CA certficates
to verify client certificates it receives. This parameter is
REQUIRED and may be specified multiple times. It can take the
forms:
FILE:<ca-bundle-file-name>
DIR:<openssl-style-hashed-directory>
"pkinit_pool"
Specifies where the KDC will find other (intermediate) CA
certificates it can use to build trust paths to the trusted
roots defined in "pkinit_anchors", while verifying client
certificates. This parameter is OPTIONAL and may be specified
multiple times. It can take the same forms as "pkinit_anchors".
"pkinit_revoke"
Specifies where CRL information can be found to be used when
verifying client certificates. This parameter is OPTIONAL and
may by specified multiple times. It can take the same forms
as "pkinit_anchors". XXX???XXX
"pkinit_dh_min_bits"
Specifies the minimum number of bits the KDC is willing to accept
for a client's Diffie-Hellman key. This is an OPTIONAL integer
value. The default is 1024.
Configuration for pkinit-enabled client:
----------------------------------------
The following pkinit-specific configuration parameters can be specified
in krb5.conf in the [libdefaults] stanza. They may be specified as
"global" libdefaults or specified by realm within the [libdefaults]
stanza.
i.e.
[libdefaults]
pkinit_anchors = DIR:/etc/ssl/trusted-anchors
pkinit_win2k = false
EXAMPLE.COM = {
pkinit_win2k = true
pkinit_win2k_require_binding = true
pkinit_anchors = FILE:/etc/ssl/example.com.cas
}
"pkinit_identity"
See the discussion for this option in the KDC description above.
For the client, this is OPTIONAL. The client can use either
of the following to specify its certificate and private key
locations:
FILE:<cert-file-name>[,<key-file-name>]
PKCS11:[module_name=]<module-name>[:slotid=<slot-id>]
[:token=<token-label>][:certid=<cert-id>]
[:certlabel=<cert-label>]
"pkinit_anchors"
See the discussion for this option in the KDC description above.
For the client, this option is considered OPTIONAL, however it
is needed in practice to verify a KDC's certificate.
"pkinit_pool"
See the discussion for these options in the KDC descriptions above.
"pkinit_revoke"
See the discussion for these options in the KDC descriptions above.
"pkinit_win2k"
This BOOLEAN option specifies whether the target realm is assumed
to support only the "old" version of the protocol. The default
is false.
"pkinit_win2k_require_binding"
If this BOOLEAN option is set to true, it expects that the target
KDC is patched to return a reply with a checksum rather than a
nonce. The default is false.
"pkinit_require_eku"
This BOOLEAN specifies whether the client insists that the KDC
certificate contain the appropriate Extended Key Usage value.
The default is true.
"pkinit_require_krbtgt_otherName"
This BOOLEAN specifies whether the client insists that the KDC
certificate contain the appropriate SubjectAlternativeName
value. The default is true.
"pkinit_require_hostname_match"
This BOOLEAN specifies whether the client insists that the
hostname within the SubjectAlternativeName must match the
hostname the client believes it is talking to. The default
is false.
Command-line options for kinit:
-------------------------------
Command-line options may be passed via the -X option to kinit.
The following values are currently accepted:
X509_user_identity=<value>
Where <value> has the same format as the "pkinit_identity"
config option described above.
X509_anchors=<value>
Where <value> has the same format as the "pkinit_anchors"
config option described above.
flag_RSA_PROTOCOL
This boolean specifies that the RSA protocol (rather than
the Diffie-Hellman protocol) should be used while authenticating
with the KDC.
For a pkinit-enabled client using smartcards:
---------------------------------------------
1. Install a pkcs11 module (smartcard enabled or otherwise).
We use OpenSC but any module that implements pkcs11 should work.
There are some instructions for setting up OpenSC at
http://www.citi.umich.edu/projects/pkinit/smartcard_setup.html
2. set the location of your trusted cas either by setting the
appropriate configuration file parameter or by specifying
"-X X509_anchors=<value>" on the command line.
3. Select a pkcs11 module. The default is opensc-pkcs11.so. To use a
different one, use the "module_name=" option (see below).
4. Select a pkcs11 slot/token. If you only have one with a token available,
that one will be used. Otherwise use the "slotid=" option. Or you can
specify a token label with the "token=" option and pkinit will attempt to
locate that token.
5. Select a client certificate to use. You can specify a certificate ID
with "certid=" or a certificate label with "certlabel=". If multiple
certs fit the selection criteria, the first one with the appropriate
capabilities will be used.
6. Options can be set either via the "pkcs11_identity" krb5.conf
parameter or via the -X parameter to kinit.
These two examples should produce the same result:
pkinit_identity=PKCS11:module_name=/usr/local/VendorX/lib/libpkcs11.so:slotid=1:certid=4
kinit -X X509_user_identity=PKCS11:module_name=/usr/local/VendorX/lib/libpkcs11.so:slotid=1:certid=4
For a pkinit-enabled client using the filesystem for Cert and Key:
------------------------------------------------------------------
1. verify that the proper krb5.conf options are set
2. Specify the certificate and private key locations either via the
pkinit_identity config option, or via the "-X X509_user_identity="
command line option.
These two examples should produce the same result:
pkinit_identity=FILE:/home/bubba/ssl/foo.crt,/home/bubba/ssl/foo.key
kinit -X X509_user_identity=FILE:/home/bubba/ssl/foo.crt,/home/bubba/ssl/foo.key
Testing
=======
We have tested the client code against our server, Heimdal server,
and Windows 2003 servers, but not yet against a Vista/Longhorn server.
We have not yet been able to test a Windows client against our server.
Most of our smartcard testing has been with Cryptoflex.
Known Issues
============
- The client principal must currently have the REQUIRES_PREAUTH attribute
set to cause the use of pkinit
- Some error reporting is incomplete
Information about using CRLs
============================
N.B. The following describes a "pkinit_require_crl_checking" option
which currently doesn't actually exist. The current behavior is
as if this option were always set to false.
We assume that the user will acquire needed CRLs and place them
in a local directory (using OpenSSL style) or a single file. During
verification of a certificate for each CA, the code looks for a CRL
issued by that CA. If a match is found for the certificate in a CRL,
verification fails. If the certificate being verified is not listed
in a CRL, or there is no CRL present for its issuing CA, and
pkinit_require_crl_checking is false, then verification succeeds.
However, if pkinit_require_crl_checking is true and there is no
CRL for the issuing CA, then verification fails.
Basically, pkinit_require_crl_checking should be set to true if the
policy is such that up-to-date CRLs must be present for every CA.
===============
NOT IMPLEMENTED
===============
The following KDC options allowed by Heimdal are NOT CURRENTLY IMPLEMENTED:
"pkinit_kdc_ocsp"
Specifies where the KDC will find information to use the Online
Certificate Status Protocol while verifying client certificates.
This parameter is OPTIONAL and there is no default.
"pkinit_mappings_file"
Specifies where the KDC will find information to use to map the
DN information in a certificate to a KDC principal. This would
be used when the client certificate does not contain the pkinit-SAN
information defined by RFC 4556.
This parameter is OPTIONAL and there is no default.
"pkinit_allow_proxy_certificate"
Specifies whether the KDC should accept proxy client certificates
for authentication. This is an OPTIONAL boolean parameter. The
default is false.
"pkinit_principal_in_certificate"
Specifies whether the KDC should obtain the client principal name
from the SubjectAlternativeName in the certificate presented
for authentication. This is an OPTIONAL boolean parameter. The
default is true.
pkinit_identity=PKCS11:[module_name=]<module-name>[:slotid=<slot-id>]
[:token=<token-label>][:certid=<cert-id>]
[:certlabel=<cert-label>]
|
