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