1 \input texinfo @c -*- texinfo -*-
4 @setfilename hx509.info
9 @c some sensible characters, please?
20 @set VERSION @value{PACKAGE_VERSION}
26 * hx509: (hx509). The X.509 distribution from KTH
33 @subtitle X.509 distribution from KTH
34 @subtitle Edition @value{EDITION}, for version @value{VERSION}
36 @author Love Hörnquist Åstrand
37 @author last updated @value{UPDATED}
39 @def@copynext{@vskip 20pt plus 1fil@penalty-1000}
44 Copyright (c) 1994-2008 Kungliga Tekniska Högskolan
45 (Royal Institute of Technology, Stockholm, Sweden).
48 Redistribution and use in source and binary forms, with or without
49 modification, are permitted provided that the following conditions
52 1. Redistributions of source code must retain the above copyright
53 notice, this list of conditions and the following disclaimer.
55 2. Redistributions in binary form must reproduce the above copyright
56 notice, this list of conditions and the following disclaimer in the
57 documentation and/or other materials provided with the distribution.
59 3. Neither the name of the Institute nor the names of its contributors
60 may be used to endorse or promote products derived from this software
61 without specific prior written permission.
63 THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
64 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
65 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
66 ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
67 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
68 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
69 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
70 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
71 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
72 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
77 Copyright (c) 1988, 1990, 1993
78 The Regents of the University of California. All rights reserved.
80 Redistribution and use in source and binary forms, with or without
81 modification, are permitted provided that the following conditions
84 1. Redistributions of source code must retain the above copyright
85 notice, this list of conditions and the following disclaimer.
87 2. Redistributions in binary form must reproduce the above copyright
88 notice, this list of conditions and the following disclaimer in the
89 documentation and/or other materials provided with the distribution.
91 3. Neither the name of the University nor the names of its contributors
92 may be used to endorse or promote products derived from this software
93 without specific prior written permission.
95 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
96 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
97 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
98 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
99 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
100 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
101 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
102 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
103 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
104 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
109 Copyright 1992 Simmule Turner and Rich Salz. All rights reserved.
111 This software is not subject to any license of the American Telephone
112 and Telegraph Company or of the Regents of the University of California.
114 Permission is granted to anyone to use this software for any purpose on
115 any computer system, and to alter it and redistribute it freely, subject
116 to the following restrictions:
118 1. The authors are not responsible for the consequences of use of this
119 software, no matter how awful, even if they arise from flaws in it.
121 2. The origin of this software must not be misrepresented, either by
122 explicit claim or by omission. Since few users ever read sources,
123 credits must appear in the documentation.
125 3. Altered versions must be plainly marked as such, and must not be
126 misrepresented as being the original software. Since few users
127 ever read sources, credits must appear in the documentation.
129 4. This notice may not be removed or altered.
133 IMath is Copyright 2002-2005 Michael J. Fromberger
134 You may use it subject to the following Licensing Terms:
136 Permission is hereby granted, free of charge, to any person obtaining
137 a copy of this software and associated documentation files (the
138 "Software"), to deal in the Software without restriction, including
139 without limitation the rights to use, copy, modify, merge, publish,
140 distribute, sublicense, and/or sell copies of the Software, and to
141 permit persons to whom the Software is furnished to do so, subject to
142 the following conditions:
144 The above copyright notice and this permission notice shall be
145 included in all copies or substantial portions of the Software.
147 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
148 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
149 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
150 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
151 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
152 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
153 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
158 @macro manpage{man, section}
159 @cite{\man\(\section\)}
162 @c Less filling! Tastes great!
165 @global@parskip 6pt plus 1pt
166 @global@chapheadingskip = 15pt plus 4pt minus 2pt
167 @global@secheadingskip = 12pt plus 3pt minus 2pt
168 @global@subsecheadingskip = 9pt plus 2pt minus 2pt
175 @node Top, Introduction, (dir), (dir)
179 This manual is last updated @value{UPDATED} for version
180 @value{VERSION} of hx509.
186 * CMS signing and encryption::
187 * Certificate matching::
188 * Software PKCS 11 module::
191 --- The Detailed Node Listing ---
195 @c * Issuing certificates::
196 * Creating a CA certificate::
197 * Issuing certificates::
199 @c * Issuing a proxy certificate::
200 @c * Creating a user certificate::
201 @c * Validating a certificate::
202 @c * Validating a certificate path::
203 * Application requirements::
205 CMS signing and encryption
213 Software PKCS 11 module
215 * How to use the PKCS11 module::
220 @node Introduction, What is X.509 ?, Top, Top
221 @chapter Introduction
223 The goals of a PKI infrastructure (as defined in
224 <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280</a>) is to meet
225 @emph{the needs of deterministic, automated identification, authentication, access control, and authorization}.
228 The administrator should be aware of certain terminologies as explained by the aforementioned
229 RFC before attemping to put in place a PKI infrastructure. Briefly, these are:
233 Certificate Authority
235 Registration Authority, i.e., an optional system to which a CA delegates certain management functions.
237 An optional system to which a CA delegates the publication of certificate revocation lists.
239 A system or collection of distributed systems that stores certificates and CRLs
240 and serves as a means of distributing these certificates and CRLs to end entities
243 hx509 (Heimdal x509 support) is a near complete X.509 stack that can
244 handle CMS messages (crypto system used in S/MIME and Kerberos PK-INIT)
245 and basic certificate processing tasks, path construction, path
246 validation, OCSP and CRL validation, PKCS10 message construction, CMS
247 Encrypted (shared secret encrypted), CMS SignedData (certificate
248 signed), and CMS EnvelopedData (certificate encrypted).
250 hx509 can use PKCS11 tokens, PKCS12 files, PEM files, and/or DER encoded
253 @node What is X.509 ?, Setting up a CA, Introduction, Top
254 @chapter What is X.509, PKIX, PKCS7 and CMS ?
256 X.509 was created by CCITT (later ITU) for the X.500 directory
257 service. Today, X.509 discussions and implementations commonly reference
258 the IETF's PKIX Certificate and CRL Profile of the X.509 v3 certificate
259 standard, as specified in RFC 3280.
261 ITU continues to develop the X.509 standard together with the IETF in a
262 rather complicated dance.
264 X.509 is a public key based security system that has associated data
265 stored within a so called certificate. Initially, X.509 was a strict
266 hierarchical system with one root. However, ever evolving requiments and
267 technology advancements saw the inclusion of multiple policy roots,
268 bridges and mesh solutions.
270 x.509 can also be used as a peer to peer system, though often seen as a
273 @section Type of certificates
275 There are several flavors of certificate in X.509.
281 Trust anchors are strictly not certificates, but commonly stored in a
282 certificate format as they become easier to manage. Trust anchors are
283 the keys that an end entity would trust to validate other certificates.
284 This is done by building a path from the certificate you want to
285 validate to to any of the trust anchors you have.
287 @item End Entity (EE) certificates
289 End entity certificates are the most common types of certificates. End
290 entity certificates cannot issue (sign) certificate themselves and are generally
291 used to authenticate and authorize users and services.
293 @item Certification Authority (CA) certificates
295 Certificate authority certificates have the right to issue additional
296 certificates (be it sub-ordinate CA certificates to build an trust anchors
297 or end entity certificates). There is no limit to how many certificates a CA
298 may issue, but there might other restrictions, like the maximum path
301 @item Proxy certificates
303 Remember the statement "End Entity certificates cannot issue
304 certificates"? Well that statement is not entirely true. There is an
305 extension called proxy certificates defined in RFC3820, that allows
306 certificates to be issued by end entity certificates. The service that
307 receives the proxy certificates must have explicitly turned on support
308 for proxy certificates, so their use is somewhat limited.
310 Proxy certificates can be limited by policies stored in the certificate to
311 what they can be used for. This allows users to delegate the proxy
312 certificate to services (by sending over the certificate and private
313 key) so the service can access services on behalf of the user.
315 One example of this would be a print service. The user wants to print a
316 large job in the middle of the night when the printer isn't used that
317 much, so the user creates a proxy certificate with the policy that it
318 can only be used to access files related to this print job, creates the
319 print job description and send both the description and proxy
320 certificate with key over to print service. Later at night when the
321 print service initializes (without any user intervention), access to the files
322 for the print job is granted via the proxy certificate. As a result of (in-place)
323 policy limitations, the certificate cannot be used for any other purposes.
327 @section Building a path
329 Before validating a certificate path (or chain), the path needs to be
330 constructed. Given a certificate (EE, CA, Proxy, or any other type),
331 the path construction algorithm will try to find a path to one of the
334 The process starts by looking at the issuing CA of the certificate, by
335 Name or Key Identifier, and tries to find that certificate while at the
336 same time evaluting any policies in-place.
338 @node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top
339 @chapter Setting up a CA
341 Do not let information overload scare you off! If you are simply testing
342 or getting started with a PKI infrastructure, skip all this and go to
343 the next chapter (see: @pxref{Creating a CA certificate}).
345 Creating a CA certificate should be more the just creating a
346 certificate, CA's should define a policy. Again, if you are simply
347 testing a PKI, policies do not matter so much. However, when it comes to
348 trust in an organisation, it will probably matter more whom your users
349 and sysadmins will find it acceptable to trust.
351 At the same time, try to keep things simple, it's not very hard to run a
352 Certificate authority and the process to get new certificates should be simple.
354 You may find it helpful to answer the following policy questions for
355 your organization at a later stage:
358 @item How do you trust your CA.
359 @item What is the CA responsibility.
360 @item Review of CA activity.
361 @item How much process should it be to issue certificate.
362 @item Who is allowed to issue certificates.
363 @item Who is allowed to requests certificates.
364 @item How to handle certificate revocation, issuing CRLs and maintain OCSP services.
367 @node Creating a CA certificate, Issuing certificates, Setting up a CA, Top
368 @section Creating a CA certificate
370 This section describes how to create a CA certificate and what to think
373 @subsection Lifetime CA certificate
375 You probably want to create a CA certificate with a long lifetime, 10
376 years at the very minimum. This is because you don't want to push out the
377 certificate (as a trust anchor) to all you users again when the old
378 CA certificate expires. Although a trust anchor can't really expire, not all
379 software works in accordance with published standards.
381 Keep in mind the security requirements might be different 10-20 years
382 into the future. For example, SHA1 is going to be withdrawn in 2010, so
383 make sure you have enough buffering in your choice of digest/hash
384 algorithms, signature algorithms and key lengths.
386 @subsection Create a CA certificate
388 This command below can be used to generate a self-signed CA certificate.
391 hxtool issue-certificate \
395 --subject="CN=CertificateAuthority,DC=test,DC=h5l,DC=se" \
397 --certificate="FILE:ca.pem"
400 @subsection Extending the lifetime of a CA certificate
402 You just realised that your CA certificate is going to expire soon and
403 that you need replace it with a new CA. The easiest way to do that
404 is to extend the lifetime of your existing CA certificate.
406 The example below will extend the CA certificate's lifetime by 10 years.
407 You should compare this new certificate if it contains all the
408 special tweaks as the old certificate had.
411 hxtool issue-certificate \
414 --lifetime="10years" \
415 --template-certificate="FILE:ca.pem" \
416 --template-fields="serialNumber,notBefore,subject,SPKI" \
417 --ca-private-key=FILE:ca.pem \
418 --certificate="FILE:new-ca.pem"
421 @subsection Subordinate CA
423 This example below creates a new subordinate certificate authority.
426 hxtool issue-certificate \
427 --ca-certificate=FILE:ca.pem \
430 --subject="CN=CertificateAuthority,DC=dev,DC=test,DC=h5l,DC=se" \
431 --certificate="FILE:dev-ca.pem"
435 @node Issuing certificates, Issuing CRLs, Creating a CA certificate, Top
436 @section Issuing certificates
438 First you'll create a CA certificate, after that you have to deal with
439 your users and servers and issue certificates to them.
441 @c I think this section needs a bit of clarity. Can I add a separate
442 @c section which explains CSRs as well?
447 @item Do all the work themself
449 Generate the key for the user. This has the problme that the the CA
450 knows the private key of the user. For a paranoid user this might leave
451 feeling of disconfort.
453 @item Have the user do part of the work
455 Receive PKCS10 certificate requests fromusers. PKCS10 is a request for a
456 certificate. The user may specify what DN they want as well as provide
457 a certificate signing request (CSR). To prove the user have the key,
458 the whole request is signed by the private key of the user.
462 @subsection Name space management
464 @c The explanation given below is slightly unclear. I will re-read the
465 @c RFC and document accordingly
467 What people might want to see.
469 Re-issue certificates just because people moved within the organization.
471 Expose privacy information.
473 Using Sub-component name (+ notation).
475 @subsection Certificate Revocation, CRL and OCSP
477 Certificates that a CA issues may need to be revoked at some stage. As
478 an example, an employee leaves the organization and does not bother
479 handing in his smart card (or even if the smart card is handed back --
480 the certificate on it must no longer be acceptable to services; the
483 You may also want to revoke a certificate for a service which is no
484 longer being offered on your network. Overlooking these scenarios can
485 lead to security holes which will quickly become a nightmare to deal
488 There are two primary protocols for dealing with certificate
492 @item Certificate Revocation List (CRL)
493 @item Online Certificate Status Protocol (OCSP)
496 If however the certificate in qeustion has been destroyed, there is no
497 need to revoke the certificate because it can not be used by someone
498 else. This matter since for each certificate you add to CRL, the
499 download time and processing time for clients are longer.
501 CRLs and OCSP responders however greatly help manage compatible services
502 which may authenticate and authorize users (or services) on an on-going
503 basis. As an example, VPN connectivity established via certificates for
504 connecting clients would require your VPN software to make use of a CRL
505 or an OCSP service to ensure revoked certificates belonging to former
506 clients are not allowed access to (formerly subscribed) network
510 @node Issuing CRLs, Application requirements, Issuing certificates, Top
511 @section Issuing CRLs
513 Create an empty CRL with no certificates revoked. Default expiration
514 value is one year from now.
522 Create a CRL with all certificates in the directory
523 @file{/path/to/revoked/dir} included in the CRL as revoked. Also make
524 it expire one month from now.
529 --signer=FILE:ca.pem \
530 --lifetime='1 month' \
531 DIR:/path/to/revoked/dir
534 @node Application requirements, CMS signing and encryption, Issuing CRLs, Top
535 @section Application requirements
537 Application place different requirements on certificates. This section
538 tries to expand what they are and how to use hxtool to generate
539 certificates for those services.
541 @subsection HTTPS - server
544 hxtool issue-certificate \
545 --subject="CN=www.test.h5l.se,DC=test,DC=h5l,DC=se" \
546 --type="https-server" \
547 --hostname="www.test.h5l.se" \
548 --hostname="www2.test.h5l.se" \
552 @subsection HTTPS - client
555 hxtool issue-certificate \
556 --subject="UID=testus,DC=test,DC=h5l,DC=se" \
557 --type="https-client" \
561 @subsection S/MIME - email
563 There are two things that should be set in S/MIME certificates, one or
564 more email addresses and an extended eku usage (EKU), emailProtection.
566 The email address format used in S/MIME certificates is defined in
567 RFC2822, section 3.4.1 and it should be an ``addr-spec''.
569 There are two ways to specifify email address in certificates. The old
570 way is in the subject distinguished name, @emph{this should not be used}. The
571 new way is using a Subject Alternative Name (SAN).
573 Even though the email address is stored in certificates, they don't need
574 to be, email reader programs are required to accept certificates that
575 doesn't have either of the two methods of storing email in certificates
576 -- in which case, the email client will try to protect the user by
577 printing the name of the certificate instead.
579 S/MIME certificate can be used in another special way. They can be
580 issued with a NULL subject distinguished name plus the email in SAN,
581 this is a valid certificate. This is used when you wont want to share
582 more information then you need to.
584 hx509 issue-certificate supports adding the email SAN to certificate by
585 using the --email option, --email also gives an implicit emailProtection
586 eku. If you want to create an certificate without an email address, the
587 option --type=email will add the emailProtection EKU.
590 hxtool issue-certificate \
591 --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \
593 --email="testus@@test.h5l.se" \
597 An example of an certificate without and subject distinguished name with
598 an email address in a SAN.
601 hxtool issue-certificate \
604 --email="testus@@test.h5l.se" \
610 A PK-INIT infrastructure allows users and services to pick up kerberos
611 credentials (tickets) based on their certificate. This, for example,
612 allows users to authenticate to their desktops using smartcards while
613 acquiring kerberos tickets in the process.
615 As an example, an office network which offers centrally controlled
616 desktop logins, mail, messaging (xmpp) and openafs would give users
617 single sign-on facilities via smartcard based logins. Once the kerberos
618 ticket has been acquired, all kerberized services would immediately
619 become accessible based on deployed security policies.
621 Let's go over the process of initializing a demo PK-INIT framework:
624 hxtool issue-certificate \
625 --type="pkinit-kdc" \
626 --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
627 --hostname=kerberos.test.h5l.se \
628 --ca-certificate="FILE:ca.pem,ca.key" \
630 --certificate="FILE:kdc.pem" \
634 How to create a certificate for a user.
637 hxtool issue-certificate \
638 --type="pkinit-client" \
639 --pk-init-principal="user@@TEST.H5L.SE" \
640 --ca-certificate="FILE:ca.pem,ca.key" \
642 --subject="cn=Test User" \
643 --certificate="FILE:user.pem"
646 The --type field can be specified multiple times. The same certificate
647 can hence house extensions for both pkinit-client as well as S/MIME.
649 To use the PKCS11 module, please see the section:
650 @pxref{How to use the PKCS11 module}.
652 More about how to configure the KDC, see the documentation in the
653 Heimdal manual to set up the KDC.
655 @subsection XMPP/Jabber
657 The jabber server certificate should have a dNSname that is the same as
658 the user entered into the application, not the same as the host name of
662 hxtool issue-certificate \
663 --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \
664 --hostname="xmpp1.test.h5l.se" \
665 --hostname="test.h5l.se" \
669 The certificate may also contain a jabber identifier (JID) that, if the
670 receiver allows it, authorises the server or client to use that JID.
672 When storing a JID inside the certificate, both for server and client,
673 it's stored inside a UTF8String within an otherName entity inside the
674 subjectAltName, using the OID id-on-xmppAddr (1.3.6.1.5.5.7.8.5).
676 To read more about the requirements, see RFC3920, Extensible Messaging
677 and Presence Protocol (XMPP): Core.
679 hxtool issue-certificate have support to add jid to the certificate
680 using the option @kbd{--jid}.
683 hxtool issue-certificate \
684 --subject="CN=Love,DC=test,DC=h5l,DC=se" \
685 --jid="lha@@test.h5l.se" \
690 @node CMS signing and encryption, CMS background, Application requirements, Top
691 @chapter CMS signing and encryption
693 CMS is the Cryptographic Message System that among other, is used by
694 S/MIME (secure email) and Kerberos PK-INIT. It's an extended version of
695 the RSA, Inc standard PKCS7.
697 @node CMS background, Certificate matching, CMS signing and encryption, Top
698 @section CMS background
701 @node Certificate matching, Matching syntax, CMS background, Top
702 @chapter Certificate matching
704 To match certificates hx509 have a special query language to match
705 certifictes in queries and ACLs.
707 @node Matching syntax, Software PKCS 11 module, Certificate matching, Top
708 @section Matching syntax
710 This is the language definitions somewhat slopply descriped:
725 word IN ( word [, word ...])
726 word IN %@{variable.subvariable@}
734 @node Software PKCS 11 module, How to use the PKCS11 module, Matching syntax, Top
735 @chapter Software PKCS 11 module
737 PKCS11 is a standard created by RSA, Inc to support hardware and
738 software encryption modules. It can be used by smartcard to expose the
739 crypto primitives inside without exposing the crypto keys.
741 Hx509 includes a software implementation of PKCS11 that runs within the
742 memory space of the process and thus exposes the keys to the
745 @node How to use the PKCS11 module, , Software PKCS 11 module, Top
746 @section How to use the PKCS11 module
749 $ cat > ~/.soft-pkcs11.rc <<EOF
750 mycert cert User certificate FILE:/Users/lha/Private/pkinit.pem
753 $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG