1 \input texinfo @c -*- texinfo -*-
2 @c $NetBSD: hx509.texi,v 1.1.1.3 2014/04/24 12:45:26 pettai Exp $
5 @setfilename hx509.info
10 @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
39 @def@copynext{@vskip 20pt plus 1fil}
52 Copyright (c) 1994-2008 Kungliga Tekniska Högskolan
53 (Royal Institute of Technology, Stockholm, Sweden).
56 Redistribution and use in source and binary forms, with or without
57 modification, are permitted provided that the following conditions
60 1. Redistributions of source code must retain the above copyright
61 notice, this list of conditions and the following disclaimer.
63 2. Redistributions in binary form must reproduce the above copyright
64 notice, this list of conditions and the following disclaimer in the
65 documentation and/or other materials provided with the distribution.
67 3. Neither the name of the Institute nor the names of its contributors
68 may be used to endorse or promote products derived from this software
69 without specific prior written permission.
71 THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
72 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
73 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
74 ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
75 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
76 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
77 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
78 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
79 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
80 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
85 Copyright (c) 1988, 1990, 1993
86 The Regents of the University of California. All rights reserved.
88 Redistribution and use in source and binary forms, with or without
89 modification, are permitted provided that the following conditions
92 1. Redistributions of source code must retain the above copyright
93 notice, this list of conditions and the following disclaimer.
95 2. Redistributions in binary form must reproduce the above copyright
96 notice, this list of conditions and the following disclaimer in the
97 documentation and/or other materials provided with the distribution.
99 3. Neither the name of the University nor the names of its contributors
100 may be used to endorse or promote products derived from this software
101 without specific prior written permission.
103 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
104 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
105 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
106 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
107 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
108 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
109 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
110 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
111 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
112 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
117 Copyright 1992 Simmule Turner and Rich Salz. All rights reserved.
119 This software is not subject to any license of the American Telephone
120 and Telegraph Company or of the Regents of the University of California.
122 Permission is granted to anyone to use this software for any purpose on
123 any computer system, and to alter it and redistribute it freely, subject
124 to the following restrictions:
126 1. The authors are not responsible for the consequences of use of this
127 software, no matter how awful, even if they arise from flaws in it.
129 2. The origin of this software must not be misrepresented, either by
130 explicit claim or by omission. Since few users ever read sources,
131 credits must appear in the documentation.
133 3. Altered versions must be plainly marked as such, and must not be
134 misrepresented as being the original software. Since few users
135 ever read sources, credits must appear in the documentation.
137 4. This notice may not be removed or altered.
141 IMath is Copyright 2002-2005 Michael J. Fromberger
142 You may use it subject to the following Licensing Terms:
144 Permission is hereby granted, free of charge, to any person obtaining
145 a copy of this software and associated documentation files (the
146 "Software"), to deal in the Software without restriction, including
147 without limitation the rights to use, copy, modify, merge, publish,
148 distribute, sublicense, and/or sell copies of the Software, and to
149 permit persons to whom the Software is furnished to do so, subject to
150 the following conditions:
152 The above copyright notice and this permission notice shall be
153 included in all copies or substantial portions of the Software.
155 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
156 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
157 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
158 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
159 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
160 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
161 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
166 @macro manpage{man, section}
167 @cite{\man\(\section\)}
170 @c Less filling! Tastes great!
173 @global@parskip 6pt plus 1pt
174 @global@chapheadingskip = 15pt plus 4pt minus 2pt
175 @global@secheadingskip = 12pt plus 3pt minus 2pt
176 @global@subsecheadingskip = 9pt plus 2pt minus 2pt
183 @node Top, Introduction, (dir), (dir)
187 This manual is for version @value{VERSION} of hx509.
193 * CMS signing and encryption::
194 * Certificate matching::
195 * Software PKCS 11 module::
196 * Creating a CA certificate::
197 * Issuing certificates::
199 * Application requirements::
202 * How to use the PKCS11 module::
205 --- The Detailed Node Listing ---
209 @c * Issuing certificates::
210 * Creating a CA certificate::
211 * Issuing certificates::
213 @c * Issuing a proxy certificate::
214 @c * Creating a user certificate::
215 @c * Validating a certificate::
216 @c * Validating a certificate path::
217 * Application requirements::
219 CMS signing and encryption
227 Software PKCS 11 module
229 * How to use the PKCS11 module::
234 @node Introduction, What is X.509 ?, Top, Top
235 @chapter Introduction
237 The goals of a PKI infrastructure (as defined in
238 <a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280</a>) is to meet
239 @emph{the needs of deterministic, automated identification, authentication, access control, and authorization}.
242 The administrator should be aware of certain terminologies as explained by the aforementioned
243 RFC before attemping to put in place a PKI infrastructure. Briefly, these are:
247 Certificate Authority
249 Registration Authority, i.e., an optional system to which a CA delegates certain management functions.
251 An optional system to which a CA delegates the publication of certificate revocation lists.
253 A system or collection of distributed systems that stores certificates and CRLs
254 and serves as a means of distributing these certificates and CRLs to end entities
257 hx509 (Heimdal x509 support) is a near complete X.509 stack that can
258 handle CMS messages (crypto system used in S/MIME and Kerberos PK-INIT)
259 and basic certificate processing tasks, path construction, path
260 validation, OCSP and CRL validation, PKCS10 message construction, CMS
261 Encrypted (shared secret encrypted), CMS SignedData (certificate
262 signed), and CMS EnvelopedData (certificate encrypted).
264 hx509 can use PKCS11 tokens, PKCS12 files, PEM files, and/or DER encoded
267 @node What is X.509 ?, Setting up a CA, Introduction, Top
268 @chapter What is X.509, PKIX, PKCS7 and CMS ?
270 X.509 was created by CCITT (later ITU) for the X.500 directory
271 service. Today, X.509 discussions and implementations commonly reference
272 the IETF's PKIX Certificate and CRL Profile of the X.509 v3 certificate
273 standard, as specified in RFC 3280.
275 ITU continues to develop the X.509 standard together with the IETF in a
276 rather complicated dance.
278 X.509 is a public key based security system that has associated data
279 stored within a so called certificate. Initially, X.509 was a strict
280 hierarchical system with one root. However, ever evolving requiments and
281 technology advancements saw the inclusion of multiple policy roots,
282 bridges and mesh solutions.
284 x.509 can also be used as a peer to peer system, though often seen as a
287 @section Type of certificates
289 There are several flavors of certificate in X.509.
295 Trust anchors are strictly not certificates, but commonly stored in a
296 certificate format as they become easier to manage. Trust anchors are
297 the keys that an end entity would trust to validate other certificates.
298 This is done by building a path from the certificate you want to
299 validate to to any of the trust anchors you have.
301 @item End Entity (EE) certificates
303 End entity certificates are the most common types of certificates. End
304 entity certificates cannot issue (sign) certificate themselves and are generally
305 used to authenticate and authorize users and services.
307 @item Certification Authority (CA) certificates
309 Certificate authority certificates have the right to issue additional
310 certificates (be it sub-ordinate CA certificates to build an trust anchors
311 or end entity certificates). There is no limit to how many certificates a CA
312 may issue, but there might other restrictions, like the maximum path
315 @item Proxy certificates
317 Remember the statement "End Entity certificates cannot issue
318 certificates"? Well that statement is not entirely true. There is an
319 extension called proxy certificates defined in RFC3820, that allows
320 certificates to be issued by end entity certificates. The service that
321 receives the proxy certificates must have explicitly turned on support
322 for proxy certificates, so their use is somewhat limited.
324 Proxy certificates can be limited by policies stored in the certificate to
325 what they can be used for. This allows users to delegate the proxy
326 certificate to services (by sending over the certificate and private
327 key) so the service can access services on behalf of the user.
329 One example of this would be a print service. The user wants to print a
330 large job in the middle of the night when the printer isn't used that
331 much, so the user creates a proxy certificate with the policy that it
332 can only be used to access files related to this print job, creates the
333 print job description and send both the description and proxy
334 certificate with key over to print service. Later at night when the
335 print service initializes (without any user intervention), access to the files
336 for the print job is granted via the proxy certificate. As a result of (in-place)
337 policy limitations, the certificate cannot be used for any other purposes.
341 @section Building a path
343 Before validating a certificate path (or chain), the path needs to be
344 constructed. Given a certificate (EE, CA, Proxy, or any other type),
345 the path construction algorithm will try to find a path to one of the
348 The process starts by looking at the issuing CA of the certificate, by
349 Name or Key Identifier, and tries to find that certificate while at the
350 same time evaluting any policies in-place.
352 @node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top
353 @chapter Setting up a CA
355 Do not let information overload scare you off! If you are simply testing
356 or getting started with a PKI infrastructure, skip all this and go to
357 the next chapter (see: @pxref{Creating a CA certificate}).
359 Creating a CA certificate should be more the just creating a
360 certificate, CA's should define a policy. Again, if you are simply
361 testing a PKI, policies do not matter so much. However, when it comes to
362 trust in an organisation, it will probably matter more whom your users
363 and sysadmins will find it acceptable to trust.
365 At the same time, try to keep things simple, it's not very hard to run a
366 Certificate authority and the process to get new certificates should be simple.
368 You may find it helpful to answer the following policy questions for
369 your organization at a later stage:
372 @item How do you trust your CA.
373 @item What is the CA responsibility.
374 @item Review of CA activity.
375 @item How much process should it be to issue certificate.
376 @item Who is allowed to issue certificates.
377 @item Who is allowed to requests certificates.
378 @item How to handle certificate revocation, issuing CRLs and maintain OCSP services.
381 @node Creating a CA certificate, Issuing certificates, Setting up a CA, Top
382 @section Creating a CA certificate
384 This section describes how to create a CA certificate and what to think
387 @subsection Lifetime CA certificate
389 You probably want to create a CA certificate with a long lifetime, 10
390 years at the very minimum. This is because you don't want to push out the
391 certificate (as a trust anchor) to all you users again when the old
392 CA certificate expires. Although a trust anchor can't really expire, not all
393 software works in accordance with published standards.
395 Keep in mind the security requirements might be different 10-20 years
396 into the future. For example, SHA1 is going to be withdrawn in 2010, so
397 make sure you have enough buffering in your choice of digest/hash
398 algorithms, signature algorithms and key lengths.
400 @subsection Create a CA certificate
402 This command below can be used to generate a self-signed CA certificate.
405 hxtool issue-certificate \
409 --subject="CN=CertificateAuthority,DC=test,DC=h5l,DC=se" \
411 --certificate="FILE:ca.pem"
414 @subsection Extending the lifetime of a CA certificate
416 You just realised that your CA certificate is going to expire soon and
417 that you need replace it with a new CA. The easiest way to do that
418 is to extend the lifetime of your existing CA certificate.
420 The example below will extend the CA certificate's lifetime by 10 years.
421 You should compare this new certificate if it contains all the
422 special tweaks as the old certificate had.
425 hxtool issue-certificate \
428 --lifetime="10years" \
429 --template-certificate="FILE:ca.pem" \
430 --template-fields="serialNumber,notBefore,subject,SPKI" \
431 --ca-private-key=FILE:ca.pem \
432 --certificate="FILE:new-ca.pem"
435 @subsection Subordinate CA
437 This example below creates a new subordinate certificate authority.
440 hxtool issue-certificate \
441 --ca-certificate=FILE:ca.pem \
444 --subject="CN=CertificateAuthority,DC=dev,DC=test,DC=h5l,DC=se" \
445 --certificate="FILE:dev-ca.pem"
449 @node Issuing certificates, Issuing CRLs, Creating a CA certificate, Top
450 @section Issuing certificates
452 First you'll create a CA certificate, after that you have to deal with
453 your users and servers and issue certificates to them.
455 @c I think this section needs a bit of clarity. Can I add a separate
456 @c section which explains CSRs as well?
461 @item Do all the work themself
463 Generate the key for the user. This has the problme that the the CA
464 knows the private key of the user. For a paranoid user this might leave
465 feeling of disconfort.
467 @item Have the user do part of the work
469 Receive PKCS10 certificate requests fromusers. PKCS10 is a request for a
470 certificate. The user may specify what DN they want as well as provide
471 a certificate signing request (CSR). To prove the user have the key,
472 the whole request is signed by the private key of the user.
476 @subsection Name space management
478 @c The explanation given below is slightly unclear. I will re-read the
479 @c RFC and document accordingly
481 What people might want to see.
483 Re-issue certificates just because people moved within the organization.
485 Expose privacy information.
487 Using Sub-component name (+ notation).
489 @subsection Certificate Revocation, CRL and OCSP
491 Certificates that a CA issues may need to be revoked at some stage. As
492 an example, an employee leaves the organization and does not bother
493 handing in his smart card (or even if the smart card is handed back --
494 the certificate on it must no longer be acceptable to services; the
497 You may also want to revoke a certificate for a service which is no
498 longer being offered on your network. Overlooking these scenarios can
499 lead to security holes which will quickly become a nightmare to deal
502 There are two primary protocols for dealing with certificate
506 @item Certificate Revocation List (CRL)
507 @item Online Certificate Status Protocol (OCSP)
510 If however the certificate in qeustion has been destroyed, there is no
511 need to revoke the certificate because it can not be used by someone
512 else. This matter since for each certificate you add to CRL, the
513 download time and processing time for clients are longer.
515 CRLs and OCSP responders however greatly help manage compatible services
516 which may authenticate and authorize users (or services) on an on-going
517 basis. As an example, VPN connectivity established via certificates for
518 connecting clients would require your VPN software to make use of a CRL
519 or an OCSP service to ensure revoked certificates belonging to former
520 clients are not allowed access to (formerly subscribed) network
524 @node Issuing CRLs, Application requirements, Issuing certificates, Top
525 @section Issuing CRLs
527 Create an empty CRL with no certificates revoked. Default expiration
528 value is one year from now.
536 Create a CRL with all certificates in the directory
537 @file{/path/to/revoked/dir} included in the CRL as revoked. Also make
538 it expire one month from now.
543 --signer=FILE:ca.pem \
544 --lifetime='1 month' \
545 DIR:/path/to/revoked/dir
548 @node Application requirements, CMS signing and encryption, Issuing CRLs, Top
549 @section Application requirements
551 Application place different requirements on certificates. This section
552 tries to expand what they are and how to use hxtool to generate
553 certificates for those services.
555 @subsection HTTPS - server
558 hxtool issue-certificate \
559 --subject="CN=www.test.h5l.se,DC=test,DC=h5l,DC=se" \
560 --type="https-server" \
561 --hostname="www.test.h5l.se" \
562 --hostname="www2.test.h5l.se" \
566 @subsection HTTPS - client
569 hxtool issue-certificate \
570 --subject="UID=testus,DC=test,DC=h5l,DC=se" \
571 --type="https-client" \
575 @subsection S/MIME - email
577 There are two things that should be set in S/MIME certificates, one or
578 more email addresses and an extended eku usage (EKU), emailProtection.
580 The email address format used in S/MIME certificates is defined in
581 RFC2822, section 3.4.1 and it should be an ``addr-spec''.
583 There are two ways to specifify email address in certificates. The old
584 way is in the subject distinguished name, @emph{this should not be used}. The
585 new way is using a Subject Alternative Name (SAN).
587 Even though the email address is stored in certificates, they don't need
588 to be, email reader programs are required to accept certificates that
589 doesn't have either of the two methods of storing email in certificates
590 -- in which case, the email client will try to protect the user by
591 printing the name of the certificate instead.
593 S/MIME certificate can be used in another special way. They can be
594 issued with a NULL subject distinguished name plus the email in SAN,
595 this is a valid certificate. This is used when you wont want to share
596 more information then you need to.
598 hx509 issue-certificate supports adding the email SAN to certificate by
599 using the --email option, --email also gives an implicit emailProtection
600 eku. If you want to create an certificate without an email address, the
601 option --type=email will add the emailProtection EKU.
604 hxtool issue-certificate \
605 --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \
607 --email="testus@@test.h5l.se" \
611 An example of an certificate without and subject distinguished name with
612 an email address in a SAN.
615 hxtool issue-certificate \
618 --email="testus@@test.h5l.se" \
624 A PK-INIT infrastructure allows users and services to pick up kerberos
625 credentials (tickets) based on their certificate. This, for example,
626 allows users to authenticate to their desktops using smartcards while
627 acquiring kerberos tickets in the process.
629 As an example, an office network which offers centrally controlled
630 desktop logins, mail, messaging (xmpp) and openafs would give users
631 single sign-on facilities via smartcard based logins. Once the kerberos
632 ticket has been acquired, all kerberized services would immediately
633 become accessible based on deployed security policies.
635 Let's go over the process of initializing a demo PK-INIT framework:
638 hxtool issue-certificate \
639 --type="pkinit-kdc" \
640 --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
641 --hostname=kerberos.test.h5l.se \
642 --ca-certificate="FILE:ca.pem,ca.key" \
644 --certificate="FILE:kdc.pem" \
648 How to create a certificate for a user.
651 hxtool issue-certificate \
652 --type="pkinit-client" \
653 --pk-init-principal="user@@TEST.H5L.SE" \
654 --ca-certificate="FILE:ca.pem,ca.key" \
656 --subject="cn=Test User" \
657 --certificate="FILE:user.pem"
660 The --type field can be specified multiple times. The same certificate
661 can hence house extensions for both pkinit-client as well as S/MIME.
663 To use the PKCS11 module, please see the section:
664 @pxref{How to use the PKCS11 module}.
666 More about how to configure the KDC, see the documentation in the
667 Heimdal manual to set up the KDC.
669 @subsection XMPP/Jabber
671 The jabber server certificate should have a dNSname that is the same as
672 the user entered into the application, not the same as the host name of
676 hxtool issue-certificate \
677 --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \
678 --hostname="xmpp1.test.h5l.se" \
679 --hostname="test.h5l.se" \
683 The certificate may also contain a jabber identifier (JID) that, if the
684 receiver allows it, authorises the server or client to use that JID.
686 When storing a JID inside the certificate, both for server and client,
687 it's stored inside a UTF8String within an otherName entity inside the
688 subjectAltName, using the OID id-on-xmppAddr (1.3.6.1.5.5.7.8.5).
690 To read more about the requirements, see RFC3920, Extensible Messaging
691 and Presence Protocol (XMPP): Core.
693 hxtool issue-certificate have support to add jid to the certificate
694 using the option @kbd{--jid}.
697 hxtool issue-certificate \
698 --subject="CN=Love,DC=test,DC=h5l,DC=se" \
699 --jid="lha@@test.h5l.se" \
704 @node CMS signing and encryption, CMS background, Application requirements, Top
705 @chapter CMS signing and encryption
707 CMS is the Cryptographic Message System that among other, is used by
708 S/MIME (secure email) and Kerberos PK-INIT. It's an extended version of
709 the RSA, Inc standard PKCS7.
711 @node CMS background, Certificate matching, CMS signing and encryption, Top
712 @section CMS background
715 @node Certificate matching, Matching syntax, CMS background, Top
716 @chapter Certificate matching
718 To match certificates hx509 have a special query language to match
719 certifictes in queries and ACLs.
721 @node Matching syntax, Software PKCS 11 module, Certificate matching, Top
722 @section Matching syntax
724 This is the language definitions somewhat slopply descriped:
739 word IN ( word [, word ...])
740 word IN %@{variable.subvariable@}
748 @node Software PKCS 11 module, How to use the PKCS11 module, Matching syntax, Top
749 @chapter Software PKCS 11 module
751 PKCS11 is a standard created by RSA, Inc to support hardware and
752 software encryption modules. It can be used by smartcard to expose the
753 crypto primitives inside without exposing the crypto keys.
755 Hx509 includes a software implementation of PKCS11 that runs within the
756 memory space of the process and thus exposes the keys to the
759 @node How to use the PKCS11 module, , Software PKCS 11 module, Top
760 @section How to use the PKCS11 module
763 $ cat > ~/.soft-pkcs11.rc <<EOF
764 mycert cert User certificate FILE:/Users/lha/Private/pkinit.pem
767 $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG