1 \input texinfo @c -*- texinfo -*-
4 @setfilename hx509.info
9 @c some sensible characters, please?
24 * hx509: (hx509). The X.509 distribution from KTH
31 @subtitle X.509 distribution from KTH
32 @subtitle Edition @value{EDITION}, for version @value{VERSION}
34 @author Love Hörnquist Åstrand
35 @author last updated @value{UPDATED}
37 @def@copynext{@vskip 20pt plus 1fil@penalty-1000}
42 Copyright (c) 1994-2008 Kungliga Tekniska Högskolan
43 (Royal Institute of Technology, Stockholm, Sweden).
46 Redistribution and use in source and binary forms, with or without
47 modification, are permitted provided that the following conditions
50 1. Redistributions of source code must retain the above copyright
51 notice, this list of conditions and the following disclaimer.
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.
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.
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
75 Copyright (C) 1990 by the Massachusetts Institute of Technology
77 Export of this software from the United States of America may
78 require a specific license from the United States Government.
79 It is the responsibility of any person or organization contemplating
80 export to obtain such a license before exporting.
82 WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
83 distribute this software and its documentation for any purpose and
84 without fee is hereby granted, provided that the above copyright
85 notice appear in all copies and that both that copyright notice and
86 this permission notice appear in supporting documentation, and that
87 the name of M.I.T. not be used in advertising or publicity pertaining
88 to distribution of the software without specific, written prior
89 permission. M.I.T. makes no representations about the suitability of
90 this software for any purpose. It is provided "as is" without express
95 Copyright (c) 1988, 1990, 1993
96 The Regents of the University of California. All rights reserved.
98 Redistribution and use in source and binary forms, with or without
99 modification, are permitted provided that the following conditions
102 1. Redistributions of source code must retain the above copyright
103 notice, this list of conditions and the following disclaimer.
105 2. Redistributions in binary form must reproduce the above copyright
106 notice, this list of conditions and the following disclaimer in the
107 documentation and/or other materials provided with the distribution.
109 3. Neither the name of the University nor the names of its contributors
110 may be used to endorse or promote products derived from this software
111 without specific prior written permission.
113 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
114 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
115 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
116 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
117 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
118 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
119 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
120 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
121 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
122 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
127 Copyright 1992 Simmule Turner and Rich Salz. All rights reserved.
129 This software is not subject to any license of the American Telephone
130 and Telegraph Company or of the Regents of the University of California.
132 Permission is granted to anyone to use this software for any purpose on
133 any computer system, and to alter it and redistribute it freely, subject
134 to the following restrictions:
136 1. The authors are not responsible for the consequences of use of this
137 software, no matter how awful, even if they arise from flaws in it.
139 2. The origin of this software must not be misrepresented, either by
140 explicit claim or by omission. Since few users ever read sources,
141 credits must appear in the documentation.
143 3. Altered versions must be plainly marked as such, and must not be
144 misrepresented as being the original software. Since few users
145 ever read sources, credits must appear in the documentation.
147 4. This notice may not be removed or altered.
151 IMath is Copyright 2002-2005 Michael J. Fromberger
152 You may use it subject to the following Licensing Terms:
154 Permission is hereby granted, free of charge, to any person obtaining
155 a copy of this software and associated documentation files (the
156 "Software"), to deal in the Software without restriction, including
157 without limitation the rights to use, copy, modify, merge, publish,
158 distribute, sublicense, and/or sell copies of the Software, and to
159 permit persons to whom the Software is furnished to do so, subject to
160 the following conditions:
162 The above copyright notice and this permission notice shall be
163 included in all copies or substantial portions of the Software.
165 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
166 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
167 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
168 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
169 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
170 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
171 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
176 @macro manpage{man, section}
177 @cite{\man\(\section\)}
180 @c Less filling! Tastes great!
183 @global@parskip 6pt plus 1pt
184 @global@chapheadingskip = 15pt plus 4pt minus 2pt
185 @global@secheadingskip = 12pt plus 3pt minus 2pt
186 @global@subsecheadingskip = 9pt plus 2pt minus 2pt
193 @node Top, Introduction, (dir), (dir)
197 This manual is last updated @value{UPDATED} for version
198 @value{VERSION} of hx509.
204 * CMS signing and encryption::
205 * Certificate matching::
208 --- The Detailed Node Listing ---
212 @c * Issuing certificates::
213 * Creating a CA certificate::
214 * Issuing certificates::
216 @c * Issuing a proxy certificate::
217 @c * Creating a user certificate::
218 @c * Validating a certificate::
219 @c * Validating a certificate path::
220 * Application requirements::
222 CMS signing and encryption
233 @node Introduction, What is X.509 ?, Top, Top
234 @chapter Introduction
236 hx509 is a somewhat complete X.509 stack that can handle CMS messages
237 (crypto system used in S/MIME and Kerberos PK-INIT) and basic
238 certificate processing tasks, path construction, path validation, OCSP
239 and CRL validation, PKCS10 message construction, CMS Encrypted (shared
240 secret encrypted), CMS SignedData (certificate signed), and CMS
241 EnvelopedData (certificate encrypted).
243 hx509 can use PKCS11 tokens, PKCS12 files, PEM files, DER encoded files.
245 @node What is X.509 ?, Setting up a CA, Introduction, Top
246 @chapter What is X.509, PKIX, PKCS7 and CMS ?
248 X.509 is from the beginning created by CCITT (later ITU) for the X.500
249 directory service. But today when people are talking about X.509 they
250 are commonly referring to IETF's PKIX Certificate and CRL Profile of the
251 X.509 v3 certificate standard, as specified in RFC 3280.
253 ITU continues to develop the X.509 standard together in a complicated
256 X.509 is public key based security system that have associated data
257 stored within a so called certificate. From the beginning X.509 was a
258 strict hierarchical system with one root. This didn't not work so over
259 time X.509 got support for multiple policy roots, bridges, and mesh
260 solutions. You can even use it as a peer to peer system, but this is not
263 @section Type of certificates
265 There are several flavors of certificate in X.509.
271 Trust anchors are strictly not certificate, but commonly stored in
272 certificate since they are easier to handle then. Trust anchor are the
273 keys that you trust to validate other certificate. This is done by
274 building a path from the certificate you wan to validate to to any of
275 the trust anchors you have.
277 @item End Entity (EE) certificates
279 End entity certificates is the most common type of certificate. End
280 entity certificates can't issue certificate them-self and is used to
281 authenticate and authorize user and services.
283 @item Certification Authority (CA) certificates
285 Certificate authority are certificates that have the right to issue
286 other certificate, they may be End entity certificates or Certificate
287 Authority certificates. There is no limit to how many certificates a CA
288 may issue, but there might other restrictions, like the maximum path
291 @item Proxy certificates
293 Remember that End Entity can't issue certificates by them own, it's not
294 really true. There there is an extension called proxy certificates,
295 defined in RFC3820, that allows certificates to be issued by end entity
296 certificates. The service that receives the proxy certificates must have
297 explicitly turned on support for proxy certificates, so their use is
300 Proxy certificates can be limited by policy stored in the certificate to
301 what they can be used for. This allows users to delegate the proxy
302 certificate to services (by sending over the certificate and private
303 key) so the service can access services on behalf of the user.
305 One example of this would be a print service. The user wants to print a
306 large job in the middle of the night when the printer isn't used that
307 much, so the user creates a proxy certificate with the policy that it
308 can only be used to access files related to this print job, creates the
309 print job description and send both the description and proxy
310 certificate with key over to print service. Later at night will the
311 print service, without the help of the user, access the files for the
312 the print job using the proxy certificate and print the job. Because of
313 the policy (limitation) in the proxy certificate, it can't be used for
318 @section Building a path
320 Before validating a path the path must be constructed. Given a
321 certificate (EE, CA, Proxy, or any other type), the path construction
322 algorithm will try to find a path to one of the trust anchors.
324 It start with looking at whom issued the certificate, by name or Key
325 Identifier, and tries to find that certificate while at the same time
326 evaluates the policy.
328 @node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top
329 @chapter Setting up a CA
331 Do not let this chapter scare you off, it's just to give you an idea how
332 to complicated setting up a CA can be. If you are just playing around,
333 skip all this and go to the next chapter, @pxref{Creating a CA
336 Creating a CA certificate should be more the just creating a
337 certificate, there is the policy of the CA. If it's just you and your
338 friend that is playing around then it probably doesn't matter what the
339 policy is. But then it comes to trust in an organisation, it will
340 probably matter more whom your users and sysadmins will find it
343 At the same time, try to keep thing simple, it's not very hard to run a
344 Certificate authority and the process to get new certificates should
347 Fill all this in later.
349 How do you trust your CA.
351 What is the CA responsibility.
353 Review of CA activity.
355 How much process should it be to issue certificate.
357 Who is allowed to issue certificates.
359 Who is allowed to requests certificates.
361 How to handle certificate revocation, issuing CRLs and maintain OCSP
364 @node Creating a CA certificate, Issuing certificates, Setting up a CA, Top
365 @section Creating a CA certificate
367 This section describes how to create a CA certificate and what to think
370 @subsection Lifetime CA certificate
372 You probably want to create a CA certificate with a long lifetime, 10
373 years at the shortest. This because you don't want to push out the
374 certificate (as a trust anchor) to all you users once again when the old
375 one just expired. A trust anchor can't really expire, but not all
376 software works that way.
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.
383 @subsection Create a CA certificate
385 This command below will create a CA certificate in the file ca.pem.
388 hxtool issue-certificate \
392 --subject="CN=CertificateAuthority,DC=test,DC=h5l,DC=se" \
394 --certificate="FILE:ca.pem"
397 @subsection Extending lifetime of a CA certificate
399 You just realised that your CA certificate is going to expire soon and
400 that you need replace it with something else, the easiest way to do that
401 is to extend the lifetime of your CA certificate.
403 The example below will extend the CA certificate 10 years into the
404 future. You should compare this new certificate if it contains all the
405 special tweaks as the old certificate had.
408 hxtool issue-certificate \
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"
418 @subsection Subordinate CA
420 This example create a new subordinate certificate authority.
423 hxtool issue-certificate \
424 --ca-certificate=FILE:ca.pem \
427 --subject="CN=CertificateAuthority,DC=dev,DC=test,DC=h5l,DC=se" \
428 --certificate="FILE:dev-ca.pem"
432 @node Issuing certificates, Issuing CRLs, Creating a CA certificate, Top
433 @section Issuing certificates
435 First you'll create a CA certificate, after that you have to deal with
436 your users and servers and issue certificate to them.
438 CA can generate the key for the user.
440 Can receive PKCS10 certificate requests from the users. PKCS10 is a
441 request for a certificate. The user can specified what DN the user wants
442 and what public key. To prove the user have the key, the whole request
443 is signed by the private key of the user.
445 @subsection Name space management
447 What people might want to see.
449 Re-issue certificates just because people moved within the organization.
451 Expose privacy information.
453 Using Sub-component name (+ notation).
455 @subsection Certificate Revocation, CRL and OCSP
457 Sonetimes people loose smartcard or computers and certificates have to
458 be make not valid any more, this is called revoking certificates. There
459 are two main protocols for doing this Certificate Revocations Lists
460 (CRL) and Online Certificate Status Protocol (OCSP).
462 If you know that the certificate is destroyed then there is no need to
463 revoke the certificate because it can not be used by someone else.
465 The main reason you as a CA administrator have to deal with CRLs however
466 will be that some software require there to be CRLs. Example of this is
467 Windows, so you have to deal with this somehow.
469 @node Issuing CRLs, Application requirements, Issuing certificates, Top
470 @section Issuing CRLs
472 Create an empty CRL with not certificates revoked. Default expiration
473 value is one year from now.
481 Create a CRL with all certificates in the directory
482 @file{/path/to/revoked/dir} included in the CRL as revoked. Also make
483 it expire one month from now.
488 --signer=FILE:ca.pem \
489 --lifetime='1 month' \
490 DIR:/path/to/revoked/dir
493 @node Application requirements, CMS signing and encryption, Issuing CRLs, Top
494 @section Application requirements
496 Application have different requirements on certificates. This section
497 tries to expand what they are and how to use hxtool to generate
498 certificates for those services.
500 @subsection HTTPS - server
503 hxtool issue-certificate \
504 --subject="CN=www.test.h5l.se,DC=test,DC=h5l,DC=se" \
505 --type="https-server" \
506 --hostname="www.test.h5l.se" \
507 --hostname="www2.test.h5l.se" \
511 @subsection HTTPS - client
514 hxtool issue-certificate \
515 --subject="UID=testus,DC=test,DC=h5l,DC=se" \
516 --type="https-client" \
520 @subsection S/MIME - email
522 There are two things that should be set in S/MIME certificates, one or
523 more email addresses and an extended eku usage (EKU), emailProtection.
525 The email address format used in S/MIME certificates is defined in
526 RFC2822, section 3.4.1 and it should be an ``addr-spec''.
528 There are two ways to specifify email address in certificates. The old
529 ways is in the subject distinguished name, this should not be used. The
530 new way is using a Subject Alternative Name (SAN).
532 But even though email address is stored in certificates, they don't need
533 to, email reader programs are required to accept certificates that
534 doesn't have either of the two methods of storing email in certificates.
535 In that case, they try to protect the user by printing the name of the
538 S/MIME certificate can be used in another special way. They can be
539 issued with a NULL subject distinguished name plus the email in SAN,
540 this is a valid certificate. This is used when you wont want to share
541 more information then you need to.
543 hx509 issue-certificate supports adding the email SAN to certificate by
544 using the --email option, --email also gives an implicit emailProtection
545 eku. If you want to create an certificate without an email address, the
546 option --type=email will add the emailProtection EKU.
549 hxtool issue-certificate \
550 --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \
552 --email="testus@@test.h5l.se" \
556 An example of an certificate without and subject distinguished name with
557 an email address in a SAN.
560 hxtool issue-certificate \
563 --email="testus@@test.h5l.se" \
569 How to create a certificate for a KDC.
572 hxtool issue-certificate \
573 --type="pkinit-kdc" \
574 --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
575 --hostname kerberos.test.h5l.se \
576 --hostname pal.test.h5l.se \
580 How to create a certificate for a user.
583 hxtool issue-certificate \
584 --type="pkinit-client" \
585 --pk-init-principal="user@@TEST.H5L.SE" \
589 @subsection XMPP/Jabber
591 The jabber server certificate should have a dNSname that is the same as
592 the user entered into the application, not the same as the host name of
596 hxtool issue-certificate \
597 --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \
598 --hostname="xmpp1.test.h5l.se" \
599 --hostname="test.h5l.se" \
603 The certificate may also contain a jabber identifier (JID) that, if the
604 receiver allows it, authorises the server or client to use that JID.
606 When storing a JID inside the certificate, both for server and client,
607 it's stored inside a UTF8String within an otherName entity inside the
608 subjectAltName, using the OID id-on-xmppAddr (1.3.6.1.5.5.7.8.5).
610 To read more about the requirements, see RFC3920, Extensible Messaging
611 and Presence Protocol (XMPP): Core.
613 hxtool issue-certificate have support to add jid to the certificate
614 using the option @kbd{--jid}.
617 hxtool issue-certificate \
618 --subject="CN=Love,DC=test,DC=h5l,DC=se" \
619 --jid="lha@@test.h5l.se" \
624 @node CMS signing and encryption, CMS background, Application requirements, Top
625 @chapter CMS signing and encryption
627 CMS is the Cryptographic Message System that among other, is used by
628 S/MIME (secure email) and Kerberos PK-INIT. It's an extended version of
629 the RSA, Inc standard PKCS7.
631 @node CMS background, Certificate matching, CMS signing and encryption, Top
632 @section CMS background
635 @node Certificate matching, Matching syntax, CMS background, Top
636 @section Certificate matching
638 To match certificates hx509 have a special query language to match
639 certifictes in queries and ACLs.
641 @node Matching syntax, , Certificate matching, Top
642 @section Matching syntax
644 This is the language definitions somewhat slopply descriped:
659 word IN ( word [, word ...])
660 word IN %@{variable.subvariable@}