← Back to branch summary

~ubuntu-branches/ubuntu/trusty/heimdal/trusty-proposed

« back to all changes in this revision

Viewing changes to .pc/texinfo_b_5.1/doc/hx509.texi

  • Committer: Package Import Robot
  • Author(s): Brian May
  • Date: 2013-06-03 12:06:56 UTC
  • Revision ID: package-import@ubuntu.com-20130603120656-s8cd5igpolk3c6h3
Tags: 1.6~git20120403+dfsg1-3
http://bugs.debian.org/710731
http://bugs.debian.org/711221
* Move /usr/share/doc/heimdal-kdc/examples to
  /usr/share/heimdal-kdc. Closes: #710731.
* Fix textinfo build errors. Closes: #711221.

Show diffs side-by-side

added added

removed removed

Lines of Context:
.pc/texinfo_b_5.1/doc/hx509.texi
 
1
\input texinfo @c -*- texinfo -*-
 
2
@c %**start of header
 
3
@c $Id$
 
4
@setfilename hx509.info
 
5
@settitle HX509
 
6
@iftex
 
7
@afourpaper
 
8
@end iftex
 
9
@c some sensible characters, please?
 
10
@tex
 
11
\input latin1.tex
 
12
@end tex
 
13
@setchapternewpage on
 
14
@syncodeindex pg cp
 
15
@c %**end of header
 
16
 
 
17
@include vars.texi
 
18
 
 
19
@set VERSION @value{PACKAGE_VERSION}
 
20
@set EDITION 1.0
 
21
 
 
22
@ifinfo
 
23
@dircategory Security
 
24
@direntry
 
25
* hx509: (hx509).               The X.509 distribution from KTH
 
26
@end direntry
 
27
@end ifinfo
 
28
 
 
29
@c title page
 
30
@titlepage
 
31
@title HX509
 
32
@subtitle X.509 distribution from KTH
 
33
@subtitle Edition @value{EDITION}, for version @value{VERSION}
 
34
@subtitle 2008
 
35
@author Love Hörnquist Åstrand
 
36
 
 
37
@def@copynext{@vskip 20pt plus 1fil}
 
38
@def@copyrightstart{}
 
39
@def@copyrightend{}
 
40
@page
 
41
@copyrightstart
 
42
Copyright (c) 1994-2008 Kungliga Tekniska Högskolan
 
43
(Royal Institute of Technology, Stockholm, Sweden).
 
44
All rights reserved.
 
45
 
 
46
Redistribution and use in source and binary forms, with or without
 
47
modification, are permitted provided that the following conditions
 
48
are met:
 
49
 
 
50
1. Redistributions of source code must retain the above copyright
 
51
   notice, this list of conditions and the following disclaimer.
 
52
 
 
53
2. Redistributions in binary form must reproduce the above copyright
 
54
   notice, this list of conditions and the following disclaimer in the
 
55
   documentation and/or other materials provided with the distribution.
 
56
 
 
57
3. Neither the name of the Institute nor the names of its contributors
 
58
   may be used to endorse or promote products derived from this software
 
59
   without specific prior written permission.
 
60
 
 
61
THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
 
62
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 
63
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 
64
ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
 
65
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 
66
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 
67
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 
68
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 
69
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 
70
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 
71
SUCH DAMAGE.
 
72
 
 
73
@copynext
 
74
 
 
75
Copyright (c) 1988, 1990, 1993
 
76
     The Regents of the University of California.  All rights reserved.
 
77
 
 
78
Redistribution and use in source and binary forms, with or without
 
79
modification, are permitted provided that the following conditions
 
80
are met:
 
81
 
 
82
1. Redistributions of source code must retain the above copyright
 
83
   notice, this list of conditions and the following disclaimer.
 
84
 
 
85
2. Redistributions in binary form must reproduce the above copyright
 
86
   notice, this list of conditions and the following disclaimer in the
 
87
   documentation and/or other materials provided with the distribution.
 
88
 
 
89
3. Neither the name of the University nor the names of its contributors
 
90
   may be used to endorse or promote products derived from this software
 
91
   without specific prior written permission.
 
92
 
 
93
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 
94
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 
95
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 
96
ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 
97
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 
98
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 
99
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 
100
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 
101
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 
102
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 
103
SUCH DAMAGE.
 
104
 
 
105
@copynext
 
106
 
 
107
Copyright 1992 Simmule Turner and Rich Salz.  All rights reserved.
 
108
 
 
109
This software is not subject to any license of the American Telephone
 
110
and Telegraph Company or of the Regents of the University of California.
 
111
 
 
112
Permission is granted to anyone to use this software for any purpose on
 
113
any computer system, and to alter it and redistribute it freely, subject
 
114
to the following restrictions:
 
115
 
 
116
1. The authors are not responsible for the consequences of use of this
 
117
   software, no matter how awful, even if they arise from flaws in it.
 
118
 
 
119
2. The origin of this software must not be misrepresented, either by
 
120
   explicit claim or by omission.  Since few users ever read sources,
 
121
   credits must appear in the documentation.
 
122
 
 
123
3. Altered versions must be plainly marked as such, and must not be
 
124
   misrepresented as being the original software.  Since few users
 
125
   ever read sources, credits must appear in the documentation.
 
126
 
 
127
4. This notice may not be removed or altered.
 
128
 
 
129
@copynext
 
130
 
 
131
IMath is Copyright 2002-2005 Michael J. Fromberger
 
132
You may use it subject to the following Licensing Terms:
 
133
 
 
134
Permission is hereby granted, free of charge, to any person obtaining
 
135
a copy of this software and associated documentation files (the
 
136
"Software"), to deal in the Software without restriction, including
 
137
without limitation the rights to use, copy, modify, merge, publish,
 
138
distribute, sublicense, and/or sell copies of the Software, and to
 
139
permit persons to whom the Software is furnished to do so, subject to
 
140
the following conditions:
 
141
 
 
142
The above copyright notice and this permission notice shall be
 
143
included in all copies or substantial portions of the Software.
 
144
 
 
145
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 
146
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 
147
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 
148
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 
149
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 
150
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 
151
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
152
 
 
153
@copyrightend
 
154
@end titlepage
 
155
 
 
156
@macro manpage{man, section}
 
157
@cite{\man\(\section\)}
 
158
@end macro
 
159
 
 
160
@c Less filling! Tastes great!
 
161
@iftex
 
162
@parindent=0pt
 
163
@global@parskip 6pt plus 1pt
 
164
@global@chapheadingskip = 15pt plus 4pt minus 2pt
 
165
@global@secheadingskip = 12pt plus 3pt minus 2pt
 
166
@global@subsecheadingskip = 9pt plus 2pt minus 2pt
 
167
@end iftex
 
168
@ifinfo
 
169
@paragraphindent 0
 
170
@end ifinfo
 
171
 
 
172
@ifnottex
 
173
@node Top, Introduction, (dir), (dir)
 
174
@top Heimdal
 
175
@end ifnottex
 
176
 
 
177
This manual is for version @value{VERSION} of hx509.
 
178
 
 
179
@menu
 
180
* Introduction::
 
181
* What is X.509 ?::
 
182
* Setting up a CA::
 
183
* CMS signing and encryption::
 
184
* Certificate matching::
 
185
* Software PKCS 11 module::
 
186
 
 
187
@detailmenu
 
188
 --- The Detailed Node Listing ---
 
189
 
 
190
Setting up a CA
 
191
 
 
192
@c * Issuing certificates::
 
193
* Creating a CA certificate::
 
194
* Issuing certificates::
 
195
* Issuing CRLs::
 
196
@c * Issuing a proxy certificate::
 
197
@c * Creating a user certificate::
 
198
@c * Validating a certificate::
 
199
@c * Validating a certificate path::
 
200
* Application requirements::
 
201
 
 
202
CMS signing and encryption
 
203
 
 
204
* CMS background::
 
205
 
 
206
Certificate matching
 
207
 
 
208
* Matching syntax::
 
209
 
 
210
Software PKCS 11 module
 
211
 
 
212
* How to use the PKCS11 module::
 
213
 
 
214
@end detailmenu
 
215
@end menu
 
216
 
 
217
@node Introduction, What is X.509 ?, Top, Top
 
218
@chapter Introduction
 
219
 
 
220
The goals of a PKI infrastructure (as defined in 
 
221
<a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280</a>) is to meet 
 
222
@emph{the needs of deterministic, automated identification, authentication, access control, and authorization}.
 
223
 
 
224
 
 
225
The administrator should be aware of certain terminologies as explained by the aforementioned
 
226
RFC before attemping to put in place a PKI infrastructure. Briefly, these are: 
 
227
 
 
228
@itemize @bullet
 
229
@item CA
 
230
Certificate Authority
 
231
@item RA
 
232
Registration Authority, i.e., an optional system to which a CA delegates certain management functions.
 
233
@item CRL Issuer
 
234
An optional system to which a CA delegates the publication of certificate revocation lists.
 
235
@item Repository
 
236
A system or collection of distributed systems that stores certificates and CRLs 
 
237
and serves as a means of distributing these certificates and CRLs to end entities
 
238
@end itemize
 
239
 
 
240
hx509 (Heimdal x509 support) is a near complete X.509 stack that can
 
241
handle CMS messages (crypto system used in S/MIME and Kerberos PK-INIT)
 
242
and basic certificate processing tasks, path construction, path
 
243
validation, OCSP and CRL validation, PKCS10 message construction, CMS
 
244
Encrypted (shared secret encrypted), CMS SignedData (certificate
 
245
signed), and CMS EnvelopedData (certificate encrypted).
 
246
 
 
247
hx509 can use PKCS11 tokens, PKCS12 files, PEM files, and/or DER encoded
 
248
files.
 
249
 
 
250
@node What is X.509 ?, Setting up a CA, Introduction, Top
 
251
@chapter What is X.509, PKIX, PKCS7 and CMS ? 
 
252
 
 
253
X.509 was created by CCITT (later ITU) for the X.500 directory
 
254
service. Today, X.509 discussions and implementations commonly reference
 
255
the IETF's PKIX Certificate and CRL Profile of the X.509 v3 certificate
 
256
standard, as specified in RFC 3280.
 
257
 
 
258
ITU continues to develop the X.509 standard together with the IETF in a 
 
259
rather complicated dance.
 
260
 
 
261
X.509 is a public key based security system that has associated data
 
262
stored within a so called certificate. Initially, X.509 was a strict
 
263
hierarchical system with one root. However, ever evolving requiments and
 
264
technology advancements saw the inclusion of multiple policy roots,
 
265
bridges and mesh solutions.
 
266
 
 
267
x.509 can also be used as a peer to peer system, though often seen as a
 
268
common scenario.
 
269
 
 
270
@section Type of certificates
 
271
 
 
272
There are several flavors of certificate in X.509.
 
273
 
 
274
@itemize @bullet
 
275
 
 
276
@item Trust anchors
 
277
 
 
278
Trust anchors are strictly not certificates, but commonly stored in a
 
279
certificate format as they become easier to manage. Trust anchors are
 
280
the keys that an end entity would trust to validate other certificates.
 
281
This is done by building a path from the certificate you want to
 
282
validate to to any of the trust anchors you have.
 
283
 
 
284
@item End Entity (EE) certificates
 
285
 
 
286
End entity certificates are the most common types of certificates. End
 
287
entity certificates cannot issue (sign) certificate themselves and are generally
 
288
used to authenticate and authorize users and services.
 
289
 
 
290
@item Certification Authority (CA) certificates
 
291
 
 
292
Certificate authority certificates have the right to issue additional
 
293
certificates (be it sub-ordinate CA certificates to build an trust anchors
 
294
or end entity certificates). There is no limit to how many certificates a CA
 
295
may issue, but there might other restrictions, like the maximum path
 
296
depth.
 
297
 
 
298
@item Proxy certificates
 
299
 
 
300
Remember the statement "End Entity certificates cannot issue
 
301
certificates"?  Well that statement is not entirely true. There is an
 
302
extension called proxy certificates defined in RFC3820, that allows
 
303
certificates to be issued by end entity certificates. The service that
 
304
receives the proxy certificates must have explicitly turned on support
 
305
for proxy certificates, so their use is somewhat limited.
 
306
 
 
307
Proxy certificates can be limited by policies stored in the certificate to
 
308
what they can be used for. This allows users to delegate the proxy
 
309
certificate to services (by sending over the certificate and private
 
310
key) so the service can access services on behalf of the user.
 
311
 
 
312
One example of this would be a print service. The user wants to print a
 
313
large job in the middle of the night when the printer isn't used that
 
314
much, so the user creates a proxy certificate with the policy that it
 
315
can only be used to access files related to this print job, creates the
 
316
print job description and send both the description and proxy
 
317
certificate with key over to print service. Later at night when the
 
318
print service initializes (without any user intervention), access to the files 
 
319
for the print job is granted via the proxy certificate. As a result of (in-place) 
 
320
policy limitations, the certificate cannot be used for any other purposes.
 
321
 
 
322
@end itemize
 
323
 
 
324
@section Building a path
 
325
 
 
326
Before validating a certificate path (or chain), the path needs to be
 
327
constructed.  Given a certificate (EE, CA, Proxy, or any other type),
 
328
the path construction algorithm will try to find a path to one of the
 
329
trust anchors.
 
330
 
 
331
The process starts by looking at the issuing CA of the certificate, by
 
332
Name or Key Identifier, and tries to find that certificate while at the
 
333
same time evaluting any policies in-place.
 
334
 
 
335
@node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top
 
336
@chapter Setting up a CA
 
337
 
 
338
Do not let information overload scare you off! If you are simply testing
 
339
or getting started with a PKI infrastructure, skip all this and go to
 
340
the next chapter (see: @pxref{Creating a CA certificate}).
 
341
 
 
342
Creating a CA certificate should be more the just creating a
 
343
certificate, CA's should define a policy. Again, if you are simply
 
344
testing a PKI, policies do not matter so much. However, when it comes to
 
345
trust in an organisation, it will probably matter more whom your users
 
346
and sysadmins will find it acceptable to trust.
 
347
 
 
348
At the same time, try to keep things simple, it's not very hard to run a
 
349
Certificate authority and the process to get new certificates should be simple.
 
350
 
 
351
You may find it helpful to answer the following policy questions for
 
352
your organization at a later stage:
 
353
 
 
354
@itemize @bullet
 
355
@item How do you trust your CA.
 
356
@item What is the CA responsibility.
 
357
@item Review of CA activity.
 
358
@item How much process should it be to issue certificate.
 
359
@item Who is allowed to issue certificates.
 
360
@item Who is allowed to requests certificates.
 
361
@item How to handle certificate revocation, issuing CRLs and maintain OCSP services.
 
362
@end itemize
 
363
 
 
364
@node Creating a CA certificate, Issuing certificates, Setting up a CA, Top
 
365
@section Creating a CA certificate
 
366
 
 
367
This section describes how to create a CA certificate and what to think
 
368
about.
 
369
 
 
370
@subsection Lifetime CA certificate
 
371
 
 
372
You probably want to create a CA certificate with a long lifetime, 10
 
373
years at the very minimum. This is because you don't want to push out the
 
374
certificate (as a trust anchor) to all you users again when the old
 
375
CA certificate expires. Although a trust anchor can't really expire, not all
 
376
software works in accordance with published standards.
 
377
 
 
378
Keep in mind the security requirements might be different 10-20 years
 
379
into the future. For example, SHA1 is going to be withdrawn in 2010, so
 
380
make sure you have enough buffering in your choice of digest/hash
 
381
algorithms, signature algorithms and key lengths.
 
382
 
 
383
@subsection Create a CA certificate
 
384
 
 
385
This command below can be used to generate a self-signed CA certificate.
 
386
 
 
387
@example
 
388
hxtool issue-certificate \
 
389
    --self-signed \
 
390
    --issue-ca \
 
391
    --generate-key=rsa \
 
392
    --subject="CN=CertificateAuthority,DC=test,DC=h5l,DC=se" \
 
393
    --lifetime=10years \
 
394
    --certificate="FILE:ca.pem"
 
395
@end example
 
396
 
 
397
@subsection Extending the lifetime of a CA certificate
 
398
 
 
399
You just realised that your CA certificate is going to expire soon and
 
400
that you need replace it with a new CA. The easiest way to do that
 
401
is to extend the lifetime of your existing CA certificate.
 
402
 
 
403
The example below will extend the CA certificate's lifetime by 10 years. 
 
404
You should compare this new certificate if it contains all the
 
405
special tweaks as the old certificate had.
 
406
 
 
407
@example
 
408
hxtool issue-certificate \
 
409
    --self-signed \
 
410
    --issue-ca \
 
411
    --lifetime="10years" \
 
412
    --template-certificate="FILE:ca.pem" \
 
413
    --template-fields="serialNumber,notBefore,subject,SPKI" \
 
414
    --ca-private-key=FILE:ca.pem \
 
415
    --certificate="FILE:new-ca.pem"
 
416
@end example
 
417
 
 
418
@subsection Subordinate CA
 
419
 
 
420
This example below creates a new subordinate certificate authority.
 
421
 
 
422
@example
 
423
hxtool issue-certificate \
 
424
    --ca-certificate=FILE:ca.pem \
 
425
    --issue-ca \
 
426
    --generate-key=rsa \
 
427
    --subject="CN=CertificateAuthority,DC=dev,DC=test,DC=h5l,DC=se" \
 
428
    --certificate="FILE:dev-ca.pem"
 
429
@end example
 
430
 
 
431
 
 
432
@node Issuing certificates, Issuing CRLs, Creating a CA certificate, Top
 
433
@section Issuing certificates
 
434
 
 
435
First you'll create a CA certificate, after that you have to deal with
 
436
your users and servers and issue certificates to them.
 
437
 
 
438
@c I think this section needs a bit of clarity. Can I add a separate
 
439
@c section which explains CSRs as well?
 
440
 
 
441
 
 
442
@itemize @bullet
 
443
 
 
444
@item Do all the work themself
 
445
 
 
446
Generate the key for the user. This has the problme that the the CA
 
447
knows the private key of the user. For a paranoid user this might leave
 
448
feeling of disconfort.
 
449
 
 
450
@item Have the user do part of the work
 
451
 
 
452
Receive PKCS10 certificate requests fromusers. PKCS10 is a request for a
 
453
certificate.  The user may specify what DN they want as well as provide
 
454
a certificate signing request (CSR).  To prove the user have the key,
 
455
the whole request is signed by the private key of the user.
 
456
 
 
457
@end itemize
 
458
 
 
459
@subsection Name space management
 
460
 
 
461
@c The explanation given below is slightly unclear. I will re-read the
 
462
@c RFC and document accordingly
 
463
 
 
464
What people might want to see.
 
465
 
 
466
Re-issue certificates just because people moved within the organization.
 
467
 
 
468
Expose privacy information.
 
469
 
 
470
Using Sub-component name (+ notation).
 
471
 
 
472
@subsection Certificate Revocation, CRL and OCSP
 
473
 
 
474
Certificates that a CA issues may need to be revoked at some stage. As
 
475
an example, an employee leaves the organization and does not bother
 
476
handing in his smart card (or even if the smart card is handed back --
 
477
the certificate on it must no longer be acceptable to services; the
 
478
employee has left).
 
479
 
 
480
You may also want to revoke a certificate for a service which is no
 
481
longer being offered on your network. Overlooking these scenarios can
 
482
lead to security holes which will quickly become a nightmare to deal
 
483
with.
 
484
 
 
485
There are two primary protocols for dealing with certificate
 
486
revokation. Namely:
 
487
 
 
488
@itemize @bullet
 
489
@item Certificate Revocation List (CRL)
 
490
@item Online Certificate Status Protocol (OCSP)
 
491
@end itemize
 
492
 
 
493
If however the certificate in qeustion has been destroyed, there is no
 
494
need to revoke the certificate because it can not be used by someone
 
495
else. This matter since for each certificate you add to CRL, the
 
496
download time and processing time for clients are longer.
 
497
 
 
498
CRLs and OCSP responders however greatly help manage compatible services
 
499
which may authenticate and authorize users (or services) on an on-going
 
500
basis. As an example, VPN connectivity established via certificates for
 
501
connecting clients would require your VPN software to make use of a CRL
 
502
or an OCSP service to ensure revoked certificates belonging to former
 
503
clients are not allowed access to (formerly subscribed) network
 
504
services.
 
505
 
 
506
 
 
507
@node Issuing CRLs, Application requirements, Issuing certificates, Top
 
508
@section Issuing CRLs
 
509
 
 
510
Create an empty CRL with no certificates revoked. Default expiration
 
511
value is one year from now.
 
512
 
 
513
@example
 
514
hxtool crl-sign \
 
515
        --crl-file=crl.der \
 
516
        --signer=FILE:ca.pem
 
517
@end example
 
518
 
 
519
Create a CRL with all certificates in the directory
 
520
@file{/path/to/revoked/dir} included in the CRL as revoked.  Also make
 
521
it expire one month from now.
 
522
 
 
523
@example
 
524
hxtool crl-sign \
 
525
        --crl-file=crl.der \
 
526
        --signer=FILE:ca.pem \
 
527
        --lifetime='1 month' \
 
528
        DIR:/path/to/revoked/dir
 
529
@end example
 
530
 
 
531
@node Application requirements, CMS signing and encryption, Issuing CRLs, Top
 
532
@section Application requirements
 
533
 
 
534
Application place different requirements on certificates. This section
 
535
tries to expand what they are and how to use hxtool to generate
 
536
certificates for those services.
 
537
 
 
538
@subsection HTTPS - server
 
539
 
 
540
@example
 
541
hxtool issue-certificate \
 
542
          --subject="CN=www.test.h5l.se,DC=test,DC=h5l,DC=se" \
 
543
          --type="https-server" \
 
544
          --hostname="www.test.h5l.se" \
 
545
          --hostname="www2.test.h5l.se" \
 
546
          ...
 
547
@end example
 
548
 
 
549
@subsection HTTPS - client
 
550
 
 
551
@example
 
552
hxtool issue-certificate \
 
553
          --subject="UID=testus,DC=test,DC=h5l,DC=se" \
 
554
          --type="https-client" \
 
555
          ...
 
556
@end example
 
557
 
 
558
@subsection S/MIME - email
 
559
 
 
560
There are two things that should be set in S/MIME certificates, one or
 
561
more email addresses and an extended eku usage (EKU), emailProtection.
 
562
 
 
563
The email address format used in S/MIME certificates is defined in
 
564
RFC2822, section 3.4.1 and it should be an ``addr-spec''.
 
565
 
 
566
There are two ways to specifify email address in certificates. The old
 
567
way is in the subject distinguished name, @emph{this should not be used}. The
 
568
new way is using a Subject Alternative Name (SAN).
 
569
 
 
570
Even though the email address is stored in certificates, they don't need
 
571
to be, email reader programs are required to accept certificates that
 
572
doesn't have either of the two methods of storing email in certificates
 
573
-- in which case, the email client will try to protect the user by
 
574
printing the name of the certificate instead.
 
575
 
 
576
S/MIME certificate can be used in another special way. They can be
 
577
issued with a NULL subject distinguished name plus the email in SAN,
 
578
this is a valid certificate. This is used when you wont want to share
 
579
more information then you need to.
 
580
 
 
581
hx509 issue-certificate supports adding the email SAN to certificate by
 
582
using the --email option, --email also gives an implicit emailProtection
 
583
eku. If you want to create an certificate without an email address, the
 
584
option --type=email will add the emailProtection EKU.
 
585
 
 
586
@example
 
587
hxtool issue-certificate \
 
588
          --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \
 
589
          --type=email \
 
590
          --email="testus@@test.h5l.se" \
 
591
          ...
 
592
@end example
 
593
 
 
594
An example of an certificate without and subject distinguished name with
 
595
an email address in a SAN.
 
596
 
 
597
@example
 
598
hxtool issue-certificate \
 
599
          --subject="" \
 
600
          --type=email \
 
601
          --email="testus@@test.h5l.se" \
 
602
          ...
 
603
@end example
 
604
 
 
605
@subsection PK-INIT
 
606
 
 
607
A PK-INIT infrastructure allows users and services to pick up kerberos
 
608
credentials (tickets) based on their certificate. This, for example,
 
609
allows users to authenticate to their desktops using smartcards while
 
610
acquiring kerberos tickets in the process.
 
611
 
 
612
As an example, an office network which offers centrally controlled
 
613
desktop logins, mail, messaging (xmpp) and openafs would give users
 
614
single sign-on facilities via smartcard based logins.  Once the kerberos
 
615
ticket has been acquired, all kerberized services would immediately
 
616
become accessible based on deployed security policies.
 
617
 
 
618
Let's go over the process of initializing a demo PK-INIT framework:
 
619
 
 
620
@example
 
621
hxtool issue-certificate \
 
622
        --type="pkinit-kdc" \
 
623
        --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
 
624
        --hostname=kerberos.test.h5l.se \
 
625
        --ca-certificate="FILE:ca.pem,ca.key" \
 
626
        --generate-key=rsa \
 
627
        --certificate="FILE:kdc.pem" \
 
628
        --subject="cn=kdc"
 
629
@end example
 
630
 
 
631
How to create a certificate for a user.
 
632
 
 
633
@example
 
634
hxtool issue-certificate \
 
635
        --type="pkinit-client" \
 
636
        --pk-init-principal="user@@TEST.H5L.SE" \
 
637
        --ca-certificate="FILE:ca.pem,ca.key" \
 
638
        --generate-key=rsa \
 
639
        --subject="cn=Test User" \
 
640
        --certificate="FILE:user.pem"
 
641
@end example
 
642
 
 
643
The --type field can be specified multiple times. The same certificate
 
644
can hence house extensions for both pkinit-client as well as S/MIME.
 
645
 
 
646
To use the PKCS11 module, please see the section:
 
647
@pxref{How to use the PKCS11 module}.
 
648
 
 
649
More about how to configure the KDC, see the documentation in the
 
650
Heimdal manual to set up the KDC.
 
651
 
 
652
@subsection XMPP/Jabber
 
653
 
 
654
The jabber server certificate should have a dNSname that is the same as
 
655
the user entered into the application, not the same as the host name of
 
656
the machine.
 
657
 
 
658
@example
 
659
hxtool issue-certificate \
 
660
          --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \
 
661
          --hostname="xmpp1.test.h5l.se" \
 
662
          --hostname="test.h5l.se" \
 
663
          ...
 
664
@end example
 
665
 
 
666
The certificate may also contain a jabber identifier (JID) that, if the
 
667
receiver allows it, authorises the server or client to use that JID.
 
668
 
 
669
When storing a JID inside the certificate, both for server and client,
 
670
it's stored inside a UTF8String within an otherName entity inside the
 
671
subjectAltName, using the OID id-on-xmppAddr (1.3.6.1.5.5.7.8.5).
 
672
 
 
673
To read more about the requirements, see RFC3920, Extensible Messaging
 
674
and Presence Protocol (XMPP): Core.
 
675
 
 
676
hxtool issue-certificate have support to add jid to the certificate
 
677
using the option @kbd{--jid}.
 
678
 
 
679
@example
 
680
hxtool issue-certificate \
 
681
          --subject="CN=Love,DC=test,DC=h5l,DC=se" \
 
682
          --jid="lha@@test.h5l.se" \
 
683
          ...
 
684
@end example
 
685
 
 
686
 
 
687
@node CMS signing and encryption, CMS background, Application requirements, Top
 
688
@chapter CMS signing and encryption
 
689
 
 
690
CMS is the Cryptographic Message System that among other, is used by
 
691
S/MIME (secure email) and Kerberos PK-INIT. It's an extended version of
 
692
the RSA, Inc standard PKCS7.
 
693
 
 
694
@node CMS background, Certificate matching, CMS signing and encryption, Top
 
695
@section CMS background
 
696
 
 
697
 
 
698
@node Certificate matching, Matching syntax, CMS background, Top
 
699
@chapter Certificate matching
 
700
 
 
701
To match certificates hx509 have a special query language to match
 
702
certifictes in queries and ACLs.
 
703
 
 
704
@node Matching syntax, Software PKCS 11 module, Certificate matching, Top
 
705
@section Matching syntax
 
706
 
 
707
This is the language definitions somewhat slopply descriped:
 
708
 
 
709
@example
 
710
 
 
711
expr = TRUE, 
 
712
     FALSE,
 
713
     ! expr,
 
714
     expr AND expr,
 
715
     expr OR expr,
 
716
     ( expr )
 
717
     compare
 
718
 
 
719
compare =
 
720
     word == word,
 
721
     word != word,
 
722
     word IN ( word [, word ...])
 
723
     word IN %@{variable.subvariable@}
 
724
 
 
725
word =
 
726
     STRING,
 
727
     %@{variable@}
 
728
 
 
729
@end example
 
730
 
 
731
@node Software PKCS 11 module, How to use the PKCS11 module, Matching syntax, Top
 
732
@chapter Software PKCS 11 module
 
733
 
 
734
PKCS11 is a standard created by RSA, Inc to support hardware and
 
735
software encryption modules. It can be used by smartcard to expose the
 
736
crypto primitives inside without exposing the crypto keys.
 
737
 
 
738
Hx509 includes a software implementation of PKCS11 that runs within the
 
739
memory space of the process and thus exposes the keys to the
 
740
application.
 
741
 
 
742
@node How to use the PKCS11 module, , Software PKCS 11 module, Top
 
743
@section How to use the PKCS11 module
 
744
 
 
745
@example
 
746
$ cat > ~/.soft-pkcs11.rc <<EOF
 
747
mycert  cert    User certificate        FILE:/Users/lha/Private/pkinit.pem
 
748
app-fatal       true
 
749
EOF
 
750
$ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG
 
751
@end example
 
752
 
 
753
 
 
754
@c @shortcontents
 
755
@contents
 
756
 
 
757
@bye