hx509.texi revision 178825
1178825Sdfr\input texinfo @c -*- texinfo -*- 2178825Sdfr@c %**start of header 3178825Sdfr@c $Id: hx509.texi 22071 2007-11-14 20:04:50Z lha $ 4178825Sdfr@setfilename hx509.info 5178825Sdfr@settitle HX509 6178825Sdfr@iftex 7178825Sdfr@afourpaper 8178825Sdfr@end iftex 9178825Sdfr@c some sensible characters, please? 10178825Sdfr@tex 11178825Sdfr\input latin1.tex 12178825Sdfr@end tex 13178825Sdfr@setchapternewpage on 14178825Sdfr@syncodeindex pg cp 15178825Sdfr@c %**end of header 16178825Sdfr 17178825Sdfr@set UPDATED $Date: 2007-11-14 12:04:50 -0800 (Ons, 14 Nov 2007) $ 18178825Sdfr@set VERSION 1.0 19178825Sdfr@set EDITION 1.0 20178825Sdfr 21178825Sdfr@ifinfo 22178825Sdfr@dircategory Security 23178825Sdfr@direntry 24178825Sdfr* hx509: (hx509). The X.509 distribution from KTH 25178825Sdfr@end direntry 26178825Sdfr@end ifinfo 27178825Sdfr 28178825Sdfr@c title page 29178825Sdfr@titlepage 30178825Sdfr@title HX509 31178825Sdfr@subtitle X.509 distribution from KTH 32178825Sdfr@subtitle Edition @value{EDITION}, for version @value{VERSION} 33178825Sdfr@subtitle 2007 34178825Sdfr@author Love H�rnquist �strand 35178825Sdfr@author last updated @value{UPDATED} 36178825Sdfr 37178825Sdfr@def@copynext{@vskip 20pt plus 1fil@penalty-1000} 38178825Sdfr@def@copyrightstart{} 39178825Sdfr@def@copyrightend{} 40178825Sdfr@page 41178825Sdfr@copyrightstart 42178825SdfrCopyright (c) 1994-2007 Kungliga Tekniska H�gskolan 43178825Sdfr(Royal Institute of Technology, Stockholm, Sweden). 44178825SdfrAll rights reserved. 45178825Sdfr 46178825SdfrRedistribution and use in source and binary forms, with or without 47178825Sdfrmodification, are permitted provided that the following conditions 48178825Sdfrare met: 49178825Sdfr 50178825Sdfr1. Redistributions of source code must retain the above copyright 51178825Sdfr notice, this list of conditions and the following disclaimer. 52178825Sdfr 53178825Sdfr2. Redistributions in binary form must reproduce the above copyright 54178825Sdfr notice, this list of conditions and the following disclaimer in the 55178825Sdfr documentation and/or other materials provided with the distribution. 56178825Sdfr 57178825Sdfr3. Neither the name of the Institute nor the names of its contributors 58178825Sdfr may be used to endorse or promote products derived from this software 59178825Sdfr without specific prior written permission. 60178825Sdfr 61178825SdfrTHIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 62178825SdfrANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 63178825SdfrIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 64178825SdfrARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 65178825SdfrFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 66178825SdfrDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 67178825SdfrOR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 68178825SdfrHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 69178825SdfrLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 70178825SdfrOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 71178825SdfrSUCH DAMAGE. 72178825Sdfr 73178825Sdfr@copynext 74178825Sdfr 75178825SdfrCopyright (C) 1990 by the Massachusetts Institute of Technology 76178825Sdfr 77178825SdfrExport of this software from the United States of America may 78178825Sdfrrequire a specific license from the United States Government. 79178825SdfrIt is the responsibility of any person or organization contemplating 80178825Sdfrexport to obtain such a license before exporting. 81178825Sdfr 82178825SdfrWITHIN THAT CONSTRAINT, permission to use, copy, modify, and 83178825Sdfrdistribute this software and its documentation for any purpose and 84178825Sdfrwithout fee is hereby granted, provided that the above copyright 85178825Sdfrnotice appear in all copies and that both that copyright notice and 86178825Sdfrthis permission notice appear in supporting documentation, and that 87178825Sdfrthe name of M.I.T. not be used in advertising or publicity pertaining 88178825Sdfrto distribution of the software without specific, written prior 89178825Sdfrpermission. M.I.T. makes no representations about the suitability of 90178825Sdfrthis software for any purpose. It is provided "as is" without express 91178825Sdfror implied warranty. 92178825Sdfr 93178825Sdfr@copynext 94178825Sdfr 95178825SdfrCopyright (c) 1988, 1990, 1993 96178825Sdfr The Regents of the University of California. All rights reserved. 97178825Sdfr 98178825SdfrRedistribution and use in source and binary forms, with or without 99178825Sdfrmodification, are permitted provided that the following conditions 100178825Sdfrare met: 101178825Sdfr 102178825Sdfr1. Redistributions of source code must retain the above copyright 103178825Sdfr notice, this list of conditions and the following disclaimer. 104178825Sdfr 105178825Sdfr2. Redistributions in binary form must reproduce the above copyright 106178825Sdfr notice, this list of conditions and the following disclaimer in the 107178825Sdfr documentation and/or other materials provided with the distribution. 108178825Sdfr 109178825Sdfr3. Neither the name of the University nor the names of its contributors 110178825Sdfr may be used to endorse or promote products derived from this software 111178825Sdfr without specific prior written permission. 112178825Sdfr 113178825SdfrTHIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 114178825SdfrANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 115178825SdfrIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 116178825SdfrARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 117178825SdfrFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 118178825SdfrDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 119178825SdfrOR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 120178825SdfrHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 121178825SdfrLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 122178825SdfrOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 123178825SdfrSUCH DAMAGE. 124178825Sdfr 125178825Sdfr@copynext 126178825Sdfr 127178825SdfrCopyright 1992 Simmule Turner and Rich Salz. All rights reserved. 128178825Sdfr 129178825SdfrThis software is not subject to any license of the American Telephone 130178825Sdfrand Telegraph Company or of the Regents of the University of California. 131178825Sdfr 132178825SdfrPermission is granted to anyone to use this software for any purpose on 133178825Sdfrany computer system, and to alter it and redistribute it freely, subject 134178825Sdfrto the following restrictions: 135178825Sdfr 136178825Sdfr1. The authors are not responsible for the consequences of use of this 137178825Sdfr software, no matter how awful, even if they arise from flaws in it. 138178825Sdfr 139178825Sdfr2. The origin of this software must not be misrepresented, either by 140178825Sdfr explicit claim or by omission. Since few users ever read sources, 141178825Sdfr credits must appear in the documentation. 142178825Sdfr 143178825Sdfr3. Altered versions must be plainly marked as such, and must not be 144178825Sdfr misrepresented as being the original software. Since few users 145178825Sdfr ever read sources, credits must appear in the documentation. 146178825Sdfr 147178825Sdfr4. This notice may not be removed or altered. 148178825Sdfr 149178825Sdfr@copynext 150178825Sdfr 151178825SdfrIMath is Copyright 2002-2005 Michael J. Fromberger 152178825SdfrYou may use it subject to the following Licensing Terms: 153178825Sdfr 154178825SdfrPermission is hereby granted, free of charge, to any person obtaining 155178825Sdfra copy of this software and associated documentation files (the 156178825Sdfr"Software"), to deal in the Software without restriction, including 157178825Sdfrwithout limitation the rights to use, copy, modify, merge, publish, 158178825Sdfrdistribute, sublicense, and/or sell copies of the Software, and to 159178825Sdfrpermit persons to whom the Software is furnished to do so, subject to 160178825Sdfrthe following conditions: 161178825Sdfr 162178825SdfrThe above copyright notice and this permission notice shall be 163178825Sdfrincluded in all copies or substantial portions of the Software. 164178825Sdfr 165178825SdfrTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 166178825SdfrEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 167178825SdfrMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 168178825SdfrIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 169178825SdfrCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 170178825SdfrTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 171178825SdfrSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 172178825Sdfr 173178825Sdfr@copyrightend 174178825Sdfr@end titlepage 175178825Sdfr 176178825Sdfr@macro manpage{man, section} 177178825Sdfr@cite{\man\(\section\)} 178178825Sdfr@end macro 179178825Sdfr 180178825Sdfr@c Less filling! Tastes great! 181178825Sdfr@iftex 182178825Sdfr@parindent=0pt 183178825Sdfr@global@parskip 6pt plus 1pt 184178825Sdfr@global@chapheadingskip = 15pt plus 4pt minus 2pt 185178825Sdfr@global@secheadingskip = 12pt plus 3pt minus 2pt 186178825Sdfr@global@subsecheadingskip = 9pt plus 2pt minus 2pt 187178825Sdfr@end iftex 188178825Sdfr@ifinfo 189178825Sdfr@paragraphindent 0 190178825Sdfr@end ifinfo 191178825Sdfr 192178825Sdfr@ifnottex 193178825Sdfr@node Top, Introduction, (dir), (dir) 194178825Sdfr@top Heimdal 195178825Sdfr@end ifnottex 196178825Sdfr 197178825SdfrThis manual is last updated @value{UPDATED} for version 198178825Sdfr@value{VERSION} of hx509. 199178825Sdfr 200178825Sdfr@menu 201178825Sdfr* Introduction:: 202178825Sdfr* What is X.509 ?:: 203178825Sdfr* Setting up a CA:: 204178825Sdfr* CMS signing and encryption:: 205178825Sdfr 206178825Sdfr@detailmenu 207178825Sdfr --- The Detailed Node Listing --- 208178825Sdfr 209178825SdfrSetting up a CA 210178825Sdfr 211178825Sdfr@c * Issuing certificates:: 212178825Sdfr* Creating a CA certificate:: 213178825Sdfr* Issuing certificates:: 214178825Sdfr* Issuing CRLs:: 215178825Sdfr@c * Issuing a proxy certificate:: 216178825Sdfr@c * Creating a user certificate:: 217178825Sdfr@c * Validating a certificate:: 218178825Sdfr@c * Validating a certificate path:: 219178825Sdfr* Application requirements:: 220178825Sdfr 221178825SdfrCMS signing and encryption 222178825Sdfr 223178825Sdfr* CMS background:: 224178825Sdfr 225178825Sdfr@end detailmenu 226178825Sdfr@end menu 227178825Sdfr 228178825Sdfr@node Introduction, What is X.509 ?, Top, Top 229178825Sdfr@chapter Introduction 230178825Sdfr 231178825Sdfrhx509 is a somewhat complete X.509 stack that can handle CMS messages 232178825Sdfr(crypto system used in S/MIME and Kerberos PK-INIT) and basic 233178825Sdfrcertificate processing tasks, path construction, path validation, OCSP 234178825Sdfrand CRL validation, PKCS10 message construction, CMS Encrypted (shared 235178825Sdfrsecret encrypted), CMS SignedData (certificate signed), and CMS 236178825SdfrEnvelopedData (certificate encrypted). 237178825Sdfr 238178825Sdfrhx509 can use PKCS11 tokens, PKCS12 files, PEM files, DER encoded files. 239178825Sdfr 240178825Sdfr@node What is X.509 ?, Setting up a CA, Introduction, Top 241178825Sdfr@chapter What is X.509, PKIX, PKCS7 and CMS ? 242178825Sdfr 243178825SdfrX.509 is from the beginning created by CCITT (later ITU) for the X.500 244178825Sdfrdirectory service. But today when people are talking about X.509 they 245178825Sdfrare commonly referring to IETF's PKIX Certificate and CRL Profile of the 246178825SdfrX.509 v3 certificate standard, as specified in RFC 3280. 247178825Sdfr 248178825SdfrITU continues to develop the X.509 standard together in a complicated 249178825Sdfrdance with IETF. 250178825Sdfr 251178825SdfrX.509 is public key based security system that have associated data 252178825Sdfrstored within a so called certificate. From the beginning X.509 was a 253178825Sdfrstrict hierarchical system with one root. This didn't not work so over 254178825Sdfrtime X.509 got support for multiple policy roots, bridges, and mesh 255178825Sdfrsolutions. You can even use it as a peer to peer system, but this is not 256178825Sdfrvery common. 257178825Sdfr 258178825Sdfr@section Type of certificates 259178825Sdfr 260178825SdfrThere are several flavors of certificate in X.509. 261178825Sdfr 262178825Sdfr@itemize @bullet 263178825Sdfr 264178825Sdfr@item Trust anchors 265178825Sdfr 266178825SdfrTrust anchors are strictly not certificate, but commonly stored in 267178825Sdfrcertificate since they are easier to handle then. Trust anchor are the 268178825Sdfrkeys that you trust to validate other certificate. This is done by 269178825Sdfrbuilding a path from the certificate you wan to validate to to any of 270178825Sdfrthe trust anchors you have. 271178825Sdfr 272178825Sdfr@item End Entity (EE) certificates 273178825Sdfr 274178825SdfrEnd entity certificates is the most common type of certificate. End 275178825Sdfrentity certificates can't issue certificate them-self and is used to 276178825Sdfrauthenticate and authorize user and services. 277178825Sdfr 278178825Sdfr@item Certification Authority (CA) certificates 279178825Sdfr 280178825SdfrCertificate authority are certificates that have the right to issue 281178825Sdfrother certificate, they may be End entity certificates or Certificate 282178825SdfrAuthority certificates. There is no limit to how many certificates a CA 283178825Sdfrmay issue, but there might other restrictions, like the maximum path 284178825Sdfrdepth. 285178825Sdfr 286178825Sdfr@item Proxy certificates 287178825Sdfr 288178825SdfrRemember that End Entity can't issue certificates by them own, it's not 289178825Sdfrreally true. There there is an extension called proxy certificates, 290178825Sdfrdefined in RFC3820, that allows certificates to be issued by end entity 291178825Sdfrcertificates. The service that receives the proxy certificates must have 292178825Sdfrexplicitly turned on support for proxy certificates, so their use is 293178825Sdfrsomewhat limited. 294178825Sdfr 295178825SdfrProxy certificates can be limited by policy stored in the certificate to 296178825Sdfrwhat they can be used for. This allows users to delegate the proxy 297178825Sdfrcertificate to services (by sending over the certificate and private 298178825Sdfrkey) so the service can access services on behalf of the user. 299178825Sdfr 300178825SdfrOne example of this would be a print service. The user wants to print a 301178825Sdfrlarge job in the middle of the night when the printer isn't used that 302178825Sdfrmuch, so the user creates a proxy certificate with the policy that it 303178825Sdfrcan only be used to access files related to this print job, creates the 304178825Sdfrprint job description and send both the description and proxy 305178825Sdfrcertificate with key over to print service. Later at night will the 306178825Sdfrprint service, without the help of the user, access the files for the 307178825Sdfrthe print job using the proxy certificate and print the job. Because of 308178825Sdfrthe policy (limitation) in the proxy certificate, it can't be used for 309178825Sdfrany other purposes. 310178825Sdfr 311178825Sdfr@end itemize 312178825Sdfr 313178825Sdfr@section Building a path 314178825Sdfr 315178825SdfrBefore validating a path the path must be constructed. Given a 316178825Sdfrcertificate (EE, CA, Proxy, or any other type), the path construction 317178825Sdfralgorithm will try to find a path to one of the trust anchors. 318178825Sdfr 319178825SdfrIt start with looking at whom issued the certificate, by name or Key 320178825SdfrIdentifier, and tries to find that certificate while at the same time 321178825Sdfrevaluates the policy. 322178825Sdfr 323178825Sdfr@node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top 324178825Sdfr@chapter Setting up a CA 325178825Sdfr 326178825SdfrDo not let this chapter scare you off, it's just to give you an idea how 327178825Sdfrto complicated setting up a CA can be. If you are just playing around, 328178825Sdfrskip all this and go to the next chapter, @pxref{Creating a CA 329178825Sdfrcertificate}. 330178825Sdfr 331178825SdfrCreating a CA certificate should be more the just creating a 332178825Sdfrcertificate, there is the policy of the CA. If it's just you and your 333178825Sdfrfriend that is playing around then it probably doesn't matter what the 334178825Sdfrpolicy is. But then it comes to trust in an organisation, it will 335178825Sdfrprobably matter more whom your users and sysadmins will find it 336178825Sdfracceptable to trust. 337178825Sdfr 338178825SdfrAt the same time, try to keep thing simple, it's not very hard to run a 339178825SdfrCertificate authority and the process to get new certificates should 340178825Sdfrsimple. 341178825Sdfr 342178825SdfrFill all this in later. 343178825Sdfr 344178825SdfrHow do you trust your CA. 345178825Sdfr 346178825SdfrWhat is the CA responsibility. 347178825Sdfr 348178825SdfrReview of CA activity. 349178825Sdfr 350178825SdfrHow much process should it be to issue certificate. 351178825Sdfr 352178825SdfrWho is allowed to issue certificates. 353178825Sdfr 354178825SdfrWho is allowed to requests certificates. 355178825Sdfr 356178825SdfrHow to handle certificate revocation, issuing CRLs and maintain OCSP 357178825Sdfrservices. 358178825Sdfr 359178825Sdfr@node Creating a CA certificate, Issuing certificates, Setting up a CA, Top 360178825Sdfr@section Creating a CA certificate 361178825Sdfr 362178825SdfrThis section describes how to create a CA certificate and what to think 363178825Sdfrabout. 364178825Sdfr 365178825Sdfr@subsection Lifetime CA certificate 366178825Sdfr 367178825SdfrYou probably want to create a CA certificate with a long lifetime, 10 368178825Sdfryears at the shortest. This because you don't want to push out the 369178825Sdfrcertificate (as a trust anchor) to all you users once again when the old 370178825Sdfrone just expired. A trust anchor can't really expire, but not all 371178825Sdfrsoftware works that way. 372178825Sdfr 373178825SdfrKeep in mind the security requirements might be different 10-20 years 374178825Sdfrinto the future. For example, SHA1 is going to be withdrawn in 2010, so 375178825Sdfrmake sure you have enough buffering in your choice of digest/hash 376178825Sdfralgorithms, signature algorithms and key lengths. 377178825Sdfr 378178825Sdfr@subsection Create a CA certificate 379178825Sdfr 380178825SdfrThis command below will create a CA certificate in the file ca.pem. 381178825Sdfr 382178825Sdfr@example 383178825Sdfrhxtool issue-certificate \ 384178825Sdfr --self-signed \ 385178825Sdfr --issue-ca \ 386178825Sdfr --generate-key=rsa \ 387178825Sdfr --subject="CN=CertificateAuthority,DC=test,DC=h5l,DC=se" \ 388178825Sdfr --lifetime=10years \ 389178825Sdfr --certificate="FILE:ca.pem" 390178825Sdfr@end example 391178825Sdfr 392178825Sdfr@subsection Extending lifetime of a CA certificate 393178825Sdfr 394178825SdfrYou just realised that your CA certificate is going to expire soon and 395178825Sdfrthat you need replace it with something else, the easiest way to do that 396178825Sdfris to extend the lifetime of your CA certificate. 397178825Sdfr 398178825SdfrThe example below will extend the CA certificate 10 years into the 399178825Sdfrfuture. You should compare this new certificate if it contains all the 400178825Sdfrspecial tweaks as the old certificate had. 401178825Sdfr 402178825Sdfr@example 403178825Sdfrhxtool issue-certificate \ 404178825Sdfr --self-signed \ 405178825Sdfr --issue-ca \ 406178825Sdfr --lifetime="10years" \ 407178825Sdfr --template-certificate="FILE:ca.pem" \ 408178825Sdfr --template-fields="serialNumber,notBefore,subject,SPKI" \ 409178825Sdfr --ca-private-key=FILE:ca.pem \ 410178825Sdfr --certificate="FILE:new-ca.pem" 411178825Sdfr@end example 412178825Sdfr 413178825Sdfr@subsection Subordinate CA 414178825Sdfr 415178825SdfrThis example create a new subordinate certificate authority. 416178825Sdfr 417178825Sdfr@example 418178825Sdfrhxtool issue-certificate \ 419178825Sdfr --ca-certificate=FILE:ca.pem \ 420178825Sdfr --issue-ca \ 421178825Sdfr --generate-key=rsa \ 422178825Sdfr --subject="CN=CertificateAuthority,DC=dev,DC=test,DC=h5l,DC=se" \ 423178825Sdfr --certificate="FILE:dev-ca.pem" 424178825Sdfr@end example 425178825Sdfr 426178825Sdfr 427178825Sdfr@node Issuing certificates, Issuing CRLs, Creating a CA certificate, Top 428178825Sdfr@section Issuing certificates 429178825Sdfr 430178825SdfrFirst you'll create a CA certificate, after that you have to deal with 431178825Sdfryour users and servers and issue certificate to them. 432178825Sdfr 433178825SdfrCA can generate the key for the user. 434178825Sdfr 435178825SdfrCan receive PKCS10 certificate requests from the users. PKCS10 is a 436178825Sdfrrequest for a certificate. The user can specified what DN the user wants 437178825Sdfrand what public key. To prove the user have the key, the whole request 438178825Sdfris signed by the private key of the user. 439178825Sdfr 440178825Sdfr@subsection Name space management 441178825Sdfr 442178825SdfrWhat people might want to see. 443178825Sdfr 444178825SdfrRe-issue certificates just because people moved within the organization. 445178825Sdfr 446178825SdfrExpose privacy information. 447178825Sdfr 448178825SdfrUsing Sub-component name (+ notation). 449178825Sdfr 450178825Sdfr@subsection Certificate Revocation, CRL and OCSP 451178825Sdfr 452178825SdfrSonetimes people loose smartcard or computers and certificates have to 453178825Sdfrbe make not valid any more, this is called revoking certificates. There 454178825Sdfrare two main protocols for doing this Certificate Revocations Lists 455178825Sdfr(CRL) and Online Certificate Status Protocol (OCSP). 456178825Sdfr 457178825SdfrIf you know that the certificate is destroyed then there is no need to 458178825Sdfrrevoke the certificate because it can not be used by someone else. 459178825Sdfr 460178825SdfrThe main reason you as a CA administrator have to deal with CRLs however 461178825Sdfrwill be that some software require there to be CRLs. Example of this is 462178825SdfrWindows, so you have to deal with this somehow. 463178825Sdfr 464178825Sdfr@node Issuing CRLs, Application requirements, Issuing certificates, Top 465178825Sdfr@section Issuing CRLs 466178825Sdfr 467178825SdfrCreate an empty CRL with not certificates revoked. Default expiration 468178825Sdfrvalue is one year from now. 469178825Sdfr 470178825Sdfr@example 471178825Sdfrhxtool crl-sign \ 472178825Sdfr --crl-file=crl.der \ 473178825Sdfr --signer=FILE:ca.pem 474178825Sdfr@end example 475178825Sdfr 476178825SdfrCreate a CRL with all certificates in the directory 477178825Sdfr@file{/path/to/revoked/dir} included in the CRL as revoked. Also make 478178825Sdfrit expire one month from now. 479178825Sdfr 480178825Sdfr@example 481178825Sdfrhxtool crl-sign \ 482178825Sdfr --crl-file=crl.der \ 483178825Sdfr --signer=FILE:ca.pem \ 484178825Sdfr --lifetime='1 month' \ 485178825Sdfr DIR:/path/to/revoked/dir 486178825Sdfr@end example 487178825Sdfr 488178825Sdfr@node Application requirements, CMS signing and encryption, Issuing CRLs, Top 489178825Sdfr@section Application requirements 490178825Sdfr 491178825SdfrApplication have different requirements on certificates. This section 492178825Sdfrtries to expand what they are and how to use hxtool to generate 493178825Sdfrcertificates for those services. 494178825Sdfr 495178825Sdfr@subsection HTTPS - server 496178825Sdfr 497178825Sdfr@example 498178825Sdfrhxtool issue-certificate \ 499178825Sdfr --subject="CN=www.test.h5l.se,DC=test,DC=h5l,DC=se" \ 500178825Sdfr --type="https-server" \ 501178825Sdfr --hostname="www.test.h5l.se" \ 502178825Sdfr --hostname="www2.test.h5l.se" \ 503178825Sdfr ... 504178825Sdfr@end example 505178825Sdfr 506178825Sdfr@subsection HTTPS - client 507178825Sdfr 508178825Sdfr@example 509178825Sdfrhxtool issue-certificate \ 510178825Sdfr --subject="UID=testus,DC=test,DC=h5l,DC=se" \ 511178825Sdfr --type="https-client" \ 512178825Sdfr ... 513178825Sdfr@end example 514178825Sdfr 515178825Sdfr@subsection S/MIME - email 516178825Sdfr 517178825SdfrThere are two things that should be set in S/MIME certificates, one or 518178825Sdfrmore email addresses and an extended eku usage (EKU), emailProtection. 519178825Sdfr 520178825SdfrThe email address format used in S/MIME certificates is defined in 521178825SdfrRFC2822, section 3.4.1 and it should be an ``addr-spec''. 522178825Sdfr 523178825SdfrThere are two ways to specifify email address in certificates. The old 524178825Sdfrways is in the subject distinguished name, this should not be used. The 525178825Sdfrnew way is using a Subject Alternative Name (SAN). 526178825Sdfr 527178825SdfrBut even though email address is stored in certificates, they don't need 528178825Sdfrto, email reader programs are required to accept certificates that 529178825Sdfrdoesn't have either of the two methods of storing email in certificates. 530178825SdfrIn that case, they try to protect the user by printing the name of the 531178825Sdfrcertificate instead. 532178825Sdfr 533178825SdfrS/MIME certificate can be used in another special way. They can be 534178825Sdfrissued with a NULL subject distinguished name plus the email in SAN, 535178825Sdfrthis is a valid certificate. This is used when you wont want to share 536178825Sdfrmore information then you need to. 537178825Sdfr 538178825Sdfrhx509 issue-certificate supports adding the email SAN to certificate by 539178825Sdfrusing the --email option, --email also gives an implicit emailProtection 540178825Sdfreku. If you want to create an certificate without an email address, the 541178825Sdfroption --type=email will add the emailProtection EKU. 542178825Sdfr 543178825Sdfr@example 544178825Sdfrhxtool issue-certificate \ 545178825Sdfr --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \ 546178825Sdfr --type=email \ 547178825Sdfr --email="testus@@test.h5l.se" \ 548178825Sdfr ... 549178825Sdfr@end example 550178825Sdfr 551178825SdfrAn example of an certificate without and subject distinguished name with 552178825Sdfran email address in a SAN. 553178825Sdfr 554178825Sdfr@example 555178825Sdfrhxtool issue-certificate \ 556178825Sdfr --subject="" \ 557178825Sdfr --type=email \ 558178825Sdfr --email="testus@@test.h5l.se" \ 559178825Sdfr ... 560178825Sdfr@end example 561178825Sdfr 562178825Sdfr@subsection PK-INIT 563178825Sdfr 564178825SdfrHow to create a certificate for a KDC. 565178825Sdfr 566178825Sdfr@example 567178825Sdfrhxtool issue-certificate \ 568178825Sdfr --type="pkinit-kdc" \ 569178825Sdfr --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \ 570178825Sdfr --hostname kerberos.test.h5l.se \ 571178825Sdfr --hostname pal.test.h5l.se \ 572178825Sdfr ... 573178825Sdfr@end example 574178825Sdfr 575178825SdfrHow to create a certificate for a user. 576178825Sdfr 577178825Sdfr@example 578178825Sdfrhxtool issue-certificate \ 579178825Sdfr --type="pkinit-client" \ 580178825Sdfr --pk-init-principal="user@@TEST.H5L.SE" \ 581178825Sdfr ... 582178825Sdfr@end example 583178825Sdfr 584178825Sdfr@subsection XMPP/Jabber 585178825Sdfr 586178825SdfrThe jabber server certificate should have a dNSname that is the same as 587178825Sdfrthe user entered into the application, not the same as the host name of 588178825Sdfrthe machine. 589178825Sdfr 590178825Sdfr@example 591178825Sdfrhxtool issue-certificate \ 592178825Sdfr --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \ 593178825Sdfr --hostname="xmpp1.test.h5l.se" \ 594178825Sdfr --hostname="test.h5l.se" \ 595178825Sdfr ... 596178825Sdfr@end example 597178825Sdfr 598178825SdfrThe certificate may also contain a jabber identifier (JID) that, if the 599178825Sdfrreceiver allows it, authorises the server or client to use that JID. 600178825Sdfr 601178825SdfrWhen storing a JID inside the certificate, both for server and client, 602178825Sdfrit's stored inside a UTF8String within an otherName entity inside the 603178825SdfrsubjectAltName, using the OID id-on-xmppAddr (1.3.6.1.5.5.7.8.5). 604178825Sdfr 605178825SdfrTo read more about the requirements, see RFC3920, Extensible Messaging 606178825Sdfrand Presence Protocol (XMPP): Core. 607178825Sdfr 608178825Sdfrhxtool issue-certificate have support to add jid to the certificate 609178825Sdfrusing the option @kbd{--jid}. 610178825Sdfr 611178825Sdfr@example 612178825Sdfrhxtool issue-certificate \ 613178825Sdfr --subject="CN=Love,DC=test,DC=h5l,DC=se" \ 614178825Sdfr --jid="lha@@test.h5l.se" \ 615178825Sdfr ... 616178825Sdfr@end example 617178825Sdfr 618178825Sdfr 619178825Sdfr@node CMS signing and encryption, CMS background, Application requirements, Top 620178825Sdfr@chapter CMS signing and encryption 621178825Sdfr 622178825SdfrCMS is the Cryptographic Message System that among other, is used by 623178825SdfrS/MIME (secure email) and Kerberos PK-INIT. It's an extended version of 624178825Sdfrthe RSA, Inc standard PKCS7. 625178825Sdfr 626178825Sdfr@node CMS background, , CMS signing and encryption, Top 627178825Sdfr@section CMS background 628178825Sdfr 629178825Sdfr 630178825Sdfr@c @shortcontents 631178825Sdfr@contents 632178825Sdfr 633178825Sdfr@bye 634