1178825Sdfr\input texinfo @c -*- texinfo -*- 2178825Sdfr@c %**start of header 3233294Sstas@c $Id$ 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 17233294Sstas@include vars.texi 18233294Sstas 19233294Sstas@set VERSION @value{PACKAGE_VERSION} 20178825Sdfr@set EDITION 1.0 21178825Sdfr 22178825Sdfr@ifinfo 23178825Sdfr@dircategory Security 24178825Sdfr@direntry 25233294Sstas* hx509: (hx509). The X.509 distribution from KTH 26178825Sdfr@end direntry 27178825Sdfr@end ifinfo 28178825Sdfr 29178825Sdfr@c title page 30178825Sdfr@titlepage 31178825Sdfr@title HX509 32178825Sdfr@subtitle X.509 distribution from KTH 33178825Sdfr@subtitle Edition @value{EDITION}, for version @value{VERSION} 34233294Sstas@subtitle 2008 35233294Sstas@author Love H��rnquist ��strand 36178825Sdfr 37233294Sstas@def@copynext{@vskip 20pt plus 1fil} 38178825Sdfr@def@copyrightstart{} 39178825Sdfr@def@copyrightend{} 40178825Sdfr@page 41178825Sdfr@copyrightstart 42233294SstasCopyright (c) 1994-2008 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) 1988, 1990, 1993 76178825Sdfr The Regents of the University of California. All rights reserved. 77178825Sdfr 78178825SdfrRedistribution and use in source and binary forms, with or without 79178825Sdfrmodification, are permitted provided that the following conditions 80178825Sdfrare met: 81178825Sdfr 82178825Sdfr1. Redistributions of source code must retain the above copyright 83178825Sdfr notice, this list of conditions and the following disclaimer. 84178825Sdfr 85178825Sdfr2. Redistributions in binary form must reproduce the above copyright 86178825Sdfr notice, this list of conditions and the following disclaimer in the 87178825Sdfr documentation and/or other materials provided with the distribution. 88178825Sdfr 89178825Sdfr3. Neither the name of the University nor the names of its contributors 90178825Sdfr may be used to endorse or promote products derived from this software 91178825Sdfr without specific prior written permission. 92178825Sdfr 93178825SdfrTHIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 94178825SdfrANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 95178825SdfrIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 96178825SdfrARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 97178825SdfrFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 98178825SdfrDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 99178825SdfrOR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 100178825SdfrHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 101178825SdfrLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 102178825SdfrOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 103178825SdfrSUCH DAMAGE. 104178825Sdfr 105178825Sdfr@copynext 106178825Sdfr 107178825SdfrCopyright 1992 Simmule Turner and Rich Salz. All rights reserved. 108178825Sdfr 109178825SdfrThis software is not subject to any license of the American Telephone 110178825Sdfrand Telegraph Company or of the Regents of the University of California. 111178825Sdfr 112178825SdfrPermission is granted to anyone to use this software for any purpose on 113178825Sdfrany computer system, and to alter it and redistribute it freely, subject 114178825Sdfrto the following restrictions: 115178825Sdfr 116178825Sdfr1. The authors are not responsible for the consequences of use of this 117178825Sdfr software, no matter how awful, even if they arise from flaws in it. 118178825Sdfr 119178825Sdfr2. The origin of this software must not be misrepresented, either by 120178825Sdfr explicit claim or by omission. Since few users ever read sources, 121178825Sdfr credits must appear in the documentation. 122178825Sdfr 123178825Sdfr3. Altered versions must be plainly marked as such, and must not be 124178825Sdfr misrepresented as being the original software. Since few users 125178825Sdfr ever read sources, credits must appear in the documentation. 126178825Sdfr 127178825Sdfr4. This notice may not be removed or altered. 128178825Sdfr 129178825Sdfr@copynext 130178825Sdfr 131178825SdfrIMath is Copyright 2002-2005 Michael J. Fromberger 132178825SdfrYou may use it subject to the following Licensing Terms: 133178825Sdfr 134178825SdfrPermission is hereby granted, free of charge, to any person obtaining 135178825Sdfra copy of this software and associated documentation files (the 136178825Sdfr"Software"), to deal in the Software without restriction, including 137178825Sdfrwithout limitation the rights to use, copy, modify, merge, publish, 138178825Sdfrdistribute, sublicense, and/or sell copies of the Software, and to 139178825Sdfrpermit persons to whom the Software is furnished to do so, subject to 140178825Sdfrthe following conditions: 141178825Sdfr 142178825SdfrThe above copyright notice and this permission notice shall be 143178825Sdfrincluded in all copies or substantial portions of the Software. 144178825Sdfr 145178825SdfrTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 146178825SdfrEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 147178825SdfrMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 148178825SdfrIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 149178825SdfrCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 150178825SdfrTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 151178825SdfrSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 152178825Sdfr 153178825Sdfr@copyrightend 154178825Sdfr@end titlepage 155178825Sdfr 156178825Sdfr@macro manpage{man, section} 157178825Sdfr@cite{\man\(\section\)} 158178825Sdfr@end macro 159178825Sdfr 160178825Sdfr@c Less filling! Tastes great! 161178825Sdfr@iftex 162178825Sdfr@parindent=0pt 163178825Sdfr@global@parskip 6pt plus 1pt 164178825Sdfr@global@chapheadingskip = 15pt plus 4pt minus 2pt 165178825Sdfr@global@secheadingskip = 12pt plus 3pt minus 2pt 166178825Sdfr@global@subsecheadingskip = 9pt plus 2pt minus 2pt 167178825Sdfr@end iftex 168178825Sdfr@ifinfo 169178825Sdfr@paragraphindent 0 170178825Sdfr@end ifinfo 171178825Sdfr 172178825Sdfr@ifnottex 173178825Sdfr@node Top, Introduction, (dir), (dir) 174178825Sdfr@top Heimdal 175178825Sdfr@end ifnottex 176178825Sdfr 177233294SstasThis manual is for version @value{VERSION} of hx509. 178178825Sdfr 179178825Sdfr@menu 180178825Sdfr* Introduction:: 181178825Sdfr* What is X.509 ?:: 182178825Sdfr* Setting up a CA:: 183178825Sdfr* CMS signing and encryption:: 184233294Sstas* Certificate matching:: 185233294Sstas* Software PKCS 11 module:: 186178825Sdfr 187178825Sdfr@detailmenu 188178825Sdfr --- The Detailed Node Listing --- 189178825Sdfr 190178825SdfrSetting up a CA 191178825Sdfr 192178825Sdfr@c * Issuing certificates:: 193178825Sdfr* Creating a CA certificate:: 194178825Sdfr* Issuing certificates:: 195178825Sdfr* Issuing CRLs:: 196178825Sdfr@c * Issuing a proxy certificate:: 197178825Sdfr@c * Creating a user certificate:: 198178825Sdfr@c * Validating a certificate:: 199178825Sdfr@c * Validating a certificate path:: 200178825Sdfr* Application requirements:: 201178825Sdfr 202178825SdfrCMS signing and encryption 203178825Sdfr 204178825Sdfr* CMS background:: 205178825Sdfr 206233294SstasCertificate matching 207233294Sstas 208233294Sstas* Matching syntax:: 209233294Sstas 210233294SstasSoftware PKCS 11 module 211233294Sstas 212233294Sstas* How to use the PKCS11 module:: 213233294Sstas 214178825Sdfr@end detailmenu 215178825Sdfr@end menu 216178825Sdfr 217178825Sdfr@node Introduction, What is X.509 ?, Top, Top 218178825Sdfr@chapter Introduction 219178825Sdfr 220233294SstasThe goals of a PKI infrastructure (as defined in 221233294Sstas<a href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280</a>) is to meet 222233294Sstas@emph{the needs of deterministic, automated identification, authentication, access control, and authorization}. 223178825Sdfr 224178825Sdfr 225233294SstasThe administrator should be aware of certain terminologies as explained by the aforementioned 226233294SstasRFC before attemping to put in place a PKI infrastructure. Briefly, these are: 227233294Sstas 228233294Sstas@itemize @bullet 229233294Sstas@item CA 230233294SstasCertificate Authority 231233294Sstas@item RA 232233294SstasRegistration Authority, i.e., an optional system to which a CA delegates certain management functions. 233233294Sstas@item CRL Issuer 234233294SstasAn optional system to which a CA delegates the publication of certificate revocation lists. 235233294Sstas@item Repository 236233294SstasA system or collection of distributed systems that stores certificates and CRLs 237233294Sstasand serves as a means of distributing these certificates and CRLs to end entities 238233294Sstas@end itemize 239233294Sstas 240233294Sstashx509 (Heimdal x509 support) is a near complete X.509 stack that can 241233294Sstashandle CMS messages (crypto system used in S/MIME and Kerberos PK-INIT) 242233294Sstasand basic certificate processing tasks, path construction, path 243233294Sstasvalidation, OCSP and CRL validation, PKCS10 message construction, CMS 244233294SstasEncrypted (shared secret encrypted), CMS SignedData (certificate 245233294Sstassigned), and CMS EnvelopedData (certificate encrypted). 246233294Sstas 247233294Sstashx509 can use PKCS11 tokens, PKCS12 files, PEM files, and/or DER encoded 248233294Sstasfiles. 249233294Sstas 250178825Sdfr@node What is X.509 ?, Setting up a CA, Introduction, Top 251178825Sdfr@chapter What is X.509, PKIX, PKCS7 and CMS ? 252178825Sdfr 253233294SstasX.509 was created by CCITT (later ITU) for the X.500 directory 254233294Sstasservice. Today, X.509 discussions and implementations commonly reference 255233294Sstasthe IETF's PKIX Certificate and CRL Profile of the X.509 v3 certificate 256233294Sstasstandard, as specified in RFC 3280. 257178825Sdfr 258233294SstasITU continues to develop the X.509 standard together with the IETF in a 259233294Sstasrather complicated dance. 260178825Sdfr 261233294SstasX.509 is a public key based security system that has associated data 262233294Sstasstored within a so called certificate. Initially, X.509 was a strict 263233294Sstashierarchical system with one root. However, ever evolving requiments and 264233294Sstastechnology advancements saw the inclusion of multiple policy roots, 265233294Sstasbridges and mesh solutions. 266178825Sdfr 267233294Sstasx.509 can also be used as a peer to peer system, though often seen as a 268233294Sstascommon scenario. 269233294Sstas 270178825Sdfr@section Type of certificates 271178825Sdfr 272178825SdfrThere are several flavors of certificate in X.509. 273178825Sdfr 274178825Sdfr@itemize @bullet 275178825Sdfr 276178825Sdfr@item Trust anchors 277178825Sdfr 278233294SstasTrust anchors are strictly not certificates, but commonly stored in a 279233294Sstascertificate format as they become easier to manage. Trust anchors are 280233294Sstasthe keys that an end entity would trust to validate other certificates. 281233294SstasThis is done by building a path from the certificate you want to 282233294Sstasvalidate to to any of the trust anchors you have. 283178825Sdfr 284178825Sdfr@item End Entity (EE) certificates 285178825Sdfr 286233294SstasEnd entity certificates are the most common types of certificates. End 287233294Sstasentity certificates cannot issue (sign) certificate themselves and are generally 288233294Sstasused to authenticate and authorize users and services. 289178825Sdfr 290178825Sdfr@item Certification Authority (CA) certificates 291178825Sdfr 292233294SstasCertificate authority certificates have the right to issue additional 293233294Sstascertificates (be it sub-ordinate CA certificates to build an trust anchors 294233294Sstasor end entity certificates). There is no limit to how many certificates a CA 295178825Sdfrmay issue, but there might other restrictions, like the maximum path 296178825Sdfrdepth. 297178825Sdfr 298178825Sdfr@item Proxy certificates 299178825Sdfr 300233294SstasRemember the statement "End Entity certificates cannot issue 301233294Sstascertificates"? Well that statement is not entirely true. There is an 302233294Sstasextension called proxy certificates defined in RFC3820, that allows 303233294Sstascertificates to be issued by end entity certificates. The service that 304233294Sstasreceives the proxy certificates must have explicitly turned on support 305233294Sstasfor proxy certificates, so their use is somewhat limited. 306178825Sdfr 307233294SstasProxy certificates can be limited by policies stored in the certificate to 308178825Sdfrwhat they can be used for. This allows users to delegate the proxy 309178825Sdfrcertificate to services (by sending over the certificate and private 310178825Sdfrkey) so the service can access services on behalf of the user. 311178825Sdfr 312178825SdfrOne example of this would be a print service. The user wants to print a 313178825Sdfrlarge job in the middle of the night when the printer isn't used that 314178825Sdfrmuch, so the user creates a proxy certificate with the policy that it 315178825Sdfrcan only be used to access files related to this print job, creates the 316178825Sdfrprint job description and send both the description and proxy 317233294Sstascertificate with key over to print service. Later at night when the 318233294Sstasprint service initializes (without any user intervention), access to the files 319233294Sstasfor the print job is granted via the proxy certificate. As a result of (in-place) 320233294Sstaspolicy limitations, the certificate cannot be used for any other purposes. 321178825Sdfr 322178825Sdfr@end itemize 323178825Sdfr 324178825Sdfr@section Building a path 325178825Sdfr 326233294SstasBefore validating a certificate path (or chain), the path needs to be 327233294Sstasconstructed. Given a certificate (EE, CA, Proxy, or any other type), 328233294Sstasthe path construction algorithm will try to find a path to one of the 329233294Sstastrust anchors. 330178825Sdfr 331233294SstasThe process starts by looking at the issuing CA of the certificate, by 332233294SstasName or Key Identifier, and tries to find that certificate while at the 333233294Sstassame time evaluting any policies in-place. 334178825Sdfr 335178825Sdfr@node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top 336178825Sdfr@chapter Setting up a CA 337178825Sdfr 338233294SstasDo not let information overload scare you off! If you are simply testing 339233294Sstasor getting started with a PKI infrastructure, skip all this and go to 340233294Sstasthe next chapter (see: @pxref{Creating a CA certificate}). 341178825Sdfr 342178825SdfrCreating a CA certificate should be more the just creating a 343233294Sstascertificate, CA's should define a policy. Again, if you are simply 344233294Sstastesting a PKI, policies do not matter so much. However, when it comes to 345233294Sstastrust in an organisation, it will probably matter more whom your users 346233294Sstasand sysadmins will find it acceptable to trust. 347178825Sdfr 348233294SstasAt the same time, try to keep things simple, it's not very hard to run a 349233294SstasCertificate authority and the process to get new certificates should be simple. 350178825Sdfr 351233294SstasYou may find it helpful to answer the following policy questions for 352233294Sstasyour organization at a later stage: 353178825Sdfr 354233294Sstas@itemize @bullet 355233294Sstas@item How do you trust your CA. 356233294Sstas@item What is the CA responsibility. 357233294Sstas@item Review of CA activity. 358233294Sstas@item How much process should it be to issue certificate. 359233294Sstas@item Who is allowed to issue certificates. 360233294Sstas@item Who is allowed to requests certificates. 361233294Sstas@item How to handle certificate revocation, issuing CRLs and maintain OCSP services. 362233294Sstas@end itemize 363178825Sdfr 364178825Sdfr@node Creating a CA certificate, Issuing certificates, Setting up a CA, Top 365178825Sdfr@section Creating a CA certificate 366178825Sdfr 367178825SdfrThis section describes how to create a CA certificate and what to think 368178825Sdfrabout. 369178825Sdfr 370178825Sdfr@subsection Lifetime CA certificate 371178825Sdfr 372178825SdfrYou probably want to create a CA certificate with a long lifetime, 10 373233294Sstasyears at the very minimum. This is because you don't want to push out the 374233294Sstascertificate (as a trust anchor) to all you users again when the old 375233294SstasCA certificate expires. Although a trust anchor can't really expire, not all 376233294Sstassoftware works in accordance with published standards. 377178825Sdfr 378178825SdfrKeep in mind the security requirements might be different 10-20 years 379178825Sdfrinto the future. For example, SHA1 is going to be withdrawn in 2010, so 380178825Sdfrmake sure you have enough buffering in your choice of digest/hash 381178825Sdfralgorithms, signature algorithms and key lengths. 382178825Sdfr 383178825Sdfr@subsection Create a CA certificate 384178825Sdfr 385233294SstasThis command below can be used to generate a self-signed CA certificate. 386178825Sdfr 387178825Sdfr@example 388178825Sdfrhxtool issue-certificate \ 389178825Sdfr --self-signed \ 390178825Sdfr --issue-ca \ 391178825Sdfr --generate-key=rsa \ 392178825Sdfr --subject="CN=CertificateAuthority,DC=test,DC=h5l,DC=se" \ 393178825Sdfr --lifetime=10years \ 394178825Sdfr --certificate="FILE:ca.pem" 395178825Sdfr@end example 396178825Sdfr 397233294Sstas@subsection Extending the lifetime of a CA certificate 398178825Sdfr 399178825SdfrYou just realised that your CA certificate is going to expire soon and 400233294Sstasthat you need replace it with a new CA. The easiest way to do that 401233294Sstasis to extend the lifetime of your existing CA certificate. 402178825Sdfr 403233294SstasThe example below will extend the CA certificate's lifetime by 10 years. 404233294SstasYou should compare this new certificate if it contains all the 405178825Sdfrspecial tweaks as the old certificate had. 406178825Sdfr 407178825Sdfr@example 408178825Sdfrhxtool issue-certificate \ 409178825Sdfr --self-signed \ 410178825Sdfr --issue-ca \ 411178825Sdfr --lifetime="10years" \ 412178825Sdfr --template-certificate="FILE:ca.pem" \ 413178825Sdfr --template-fields="serialNumber,notBefore,subject,SPKI" \ 414178825Sdfr --ca-private-key=FILE:ca.pem \ 415178825Sdfr --certificate="FILE:new-ca.pem" 416178825Sdfr@end example 417178825Sdfr 418178825Sdfr@subsection Subordinate CA 419178825Sdfr 420233294SstasThis example below creates a new subordinate certificate authority. 421178825Sdfr 422178825Sdfr@example 423178825Sdfrhxtool issue-certificate \ 424178825Sdfr --ca-certificate=FILE:ca.pem \ 425178825Sdfr --issue-ca \ 426178825Sdfr --generate-key=rsa \ 427178825Sdfr --subject="CN=CertificateAuthority,DC=dev,DC=test,DC=h5l,DC=se" \ 428178825Sdfr --certificate="FILE:dev-ca.pem" 429178825Sdfr@end example 430178825Sdfr 431178825Sdfr 432178825Sdfr@node Issuing certificates, Issuing CRLs, Creating a CA certificate, Top 433178825Sdfr@section Issuing certificates 434178825Sdfr 435178825SdfrFirst you'll create a CA certificate, after that you have to deal with 436233294Sstasyour users and servers and issue certificates to them. 437178825Sdfr 438233294Sstas@c I think this section needs a bit of clarity. Can I add a separate 439233294Sstas@c section which explains CSRs as well? 440178825Sdfr 441178825Sdfr 442233294Sstas@itemize @bullet 443233294Sstas 444233294Sstas@item Do all the work themself 445233294Sstas 446233294SstasGenerate the key for the user. This has the problme that the the CA 447233294Sstasknows the private key of the user. For a paranoid user this might leave 448233294Sstasfeeling of disconfort. 449233294Sstas 450233294Sstas@item Have the user do part of the work 451233294Sstas 452233294SstasReceive PKCS10 certificate requests fromusers. PKCS10 is a request for a 453233294Sstascertificate. The user may specify what DN they want as well as provide 454233294Sstasa certificate signing request (CSR). To prove the user have the key, 455233294Sstasthe whole request is signed by the private key of the user. 456233294Sstas 457233294Sstas@end itemize 458233294Sstas 459178825Sdfr@subsection Name space management 460178825Sdfr 461233294Sstas@c The explanation given below is slightly unclear. I will re-read the 462233294Sstas@c RFC and document accordingly 463233294Sstas 464178825SdfrWhat people might want to see. 465178825Sdfr 466178825SdfrRe-issue certificates just because people moved within the organization. 467178825Sdfr 468178825SdfrExpose privacy information. 469178825Sdfr 470178825SdfrUsing Sub-component name (+ notation). 471178825Sdfr 472178825Sdfr@subsection Certificate Revocation, CRL and OCSP 473178825Sdfr 474233294SstasCertificates that a CA issues may need to be revoked at some stage. As 475233294Sstasan example, an employee leaves the organization and does not bother 476233294Sstashanding in his smart card (or even if the smart card is handed back -- 477233294Sstasthe certificate on it must no longer be acceptable to services; the 478233294Sstasemployee has left). 479178825Sdfr 480233294SstasYou may also want to revoke a certificate for a service which is no 481233294Sstaslonger being offered on your network. Overlooking these scenarios can 482233294Sstaslead to security holes which will quickly become a nightmare to deal 483233294Sstaswith. 484178825Sdfr 485233294SstasThere are two primary protocols for dealing with certificate 486233294Sstasrevokation. Namely: 487178825Sdfr 488233294Sstas@itemize @bullet 489233294Sstas@item Certificate Revocation List (CRL) 490233294Sstas@item Online Certificate Status Protocol (OCSP) 491233294Sstas@end itemize 492233294Sstas 493233294SstasIf however the certificate in qeustion has been destroyed, there is no 494233294Sstasneed to revoke the certificate because it can not be used by someone 495233294Sstaselse. This matter since for each certificate you add to CRL, the 496233294Sstasdownload time and processing time for clients are longer. 497233294Sstas 498233294SstasCRLs and OCSP responders however greatly help manage compatible services 499233294Sstaswhich may authenticate and authorize users (or services) on an on-going 500233294Sstasbasis. As an example, VPN connectivity established via certificates for 501233294Sstasconnecting clients would require your VPN software to make use of a CRL 502233294Sstasor an OCSP service to ensure revoked certificates belonging to former 503233294Sstasclients are not allowed access to (formerly subscribed) network 504233294Sstasservices. 505233294Sstas 506233294Sstas 507178825Sdfr@node Issuing CRLs, Application requirements, Issuing certificates, Top 508178825Sdfr@section Issuing CRLs 509178825Sdfr 510233294SstasCreate an empty CRL with no certificates revoked. Default expiration 511178825Sdfrvalue is one year from now. 512178825Sdfr 513178825Sdfr@example 514178825Sdfrhxtool crl-sign \ 515178825Sdfr --crl-file=crl.der \ 516178825Sdfr --signer=FILE:ca.pem 517178825Sdfr@end example 518178825Sdfr 519178825SdfrCreate a CRL with all certificates in the directory 520178825Sdfr@file{/path/to/revoked/dir} included in the CRL as revoked. Also make 521178825Sdfrit expire one month from now. 522178825Sdfr 523178825Sdfr@example 524178825Sdfrhxtool crl-sign \ 525178825Sdfr --crl-file=crl.der \ 526178825Sdfr --signer=FILE:ca.pem \ 527178825Sdfr --lifetime='1 month' \ 528178825Sdfr DIR:/path/to/revoked/dir 529178825Sdfr@end example 530178825Sdfr 531178825Sdfr@node Application requirements, CMS signing and encryption, Issuing CRLs, Top 532178825Sdfr@section Application requirements 533178825Sdfr 534233294SstasApplication place different requirements on certificates. This section 535178825Sdfrtries to expand what they are and how to use hxtool to generate 536178825Sdfrcertificates for those services. 537178825Sdfr 538178825Sdfr@subsection HTTPS - server 539178825Sdfr 540178825Sdfr@example 541178825Sdfrhxtool issue-certificate \ 542178825Sdfr --subject="CN=www.test.h5l.se,DC=test,DC=h5l,DC=se" \ 543178825Sdfr --type="https-server" \ 544178825Sdfr --hostname="www.test.h5l.se" \ 545178825Sdfr --hostname="www2.test.h5l.se" \ 546178825Sdfr ... 547178825Sdfr@end example 548178825Sdfr 549178825Sdfr@subsection HTTPS - client 550178825Sdfr 551178825Sdfr@example 552178825Sdfrhxtool issue-certificate \ 553178825Sdfr --subject="UID=testus,DC=test,DC=h5l,DC=se" \ 554178825Sdfr --type="https-client" \ 555178825Sdfr ... 556178825Sdfr@end example 557178825Sdfr 558178825Sdfr@subsection S/MIME - email 559178825Sdfr 560178825SdfrThere are two things that should be set in S/MIME certificates, one or 561178825Sdfrmore email addresses and an extended eku usage (EKU), emailProtection. 562178825Sdfr 563178825SdfrThe email address format used in S/MIME certificates is defined in 564178825SdfrRFC2822, section 3.4.1 and it should be an ``addr-spec''. 565178825Sdfr 566178825SdfrThere are two ways to specifify email address in certificates. The old 567233294Sstasway is in the subject distinguished name, @emph{this should not be used}. The 568178825Sdfrnew way is using a Subject Alternative Name (SAN). 569178825Sdfr 570233294SstasEven though the email address is stored in certificates, they don't need 571233294Sstasto be, email reader programs are required to accept certificates that 572233294Sstasdoesn't have either of the two methods of storing email in certificates 573233294Sstas-- in which case, the email client will try to protect the user by 574233294Sstasprinting the name of the certificate instead. 575178825Sdfr 576178825SdfrS/MIME certificate can be used in another special way. They can be 577178825Sdfrissued with a NULL subject distinguished name plus the email in SAN, 578178825Sdfrthis is a valid certificate. This is used when you wont want to share 579178825Sdfrmore information then you need to. 580178825Sdfr 581178825Sdfrhx509 issue-certificate supports adding the email SAN to certificate by 582178825Sdfrusing the --email option, --email also gives an implicit emailProtection 583178825Sdfreku. If you want to create an certificate without an email address, the 584178825Sdfroption --type=email will add the emailProtection EKU. 585178825Sdfr 586178825Sdfr@example 587178825Sdfrhxtool issue-certificate \ 588178825Sdfr --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \ 589178825Sdfr --type=email \ 590178825Sdfr --email="testus@@test.h5l.se" \ 591178825Sdfr ... 592178825Sdfr@end example 593178825Sdfr 594178825SdfrAn example of an certificate without and subject distinguished name with 595178825Sdfran email address in a SAN. 596178825Sdfr 597178825Sdfr@example 598178825Sdfrhxtool issue-certificate \ 599178825Sdfr --subject="" \ 600178825Sdfr --type=email \ 601178825Sdfr --email="testus@@test.h5l.se" \ 602178825Sdfr ... 603178825Sdfr@end example 604178825Sdfr 605178825Sdfr@subsection PK-INIT 606178825Sdfr 607233294SstasA PK-INIT infrastructure allows users and services to pick up kerberos 608233294Sstascredentials (tickets) based on their certificate. This, for example, 609233294Sstasallows users to authenticate to their desktops using smartcards while 610233294Sstasacquiring kerberos tickets in the process. 611178825Sdfr 612233294SstasAs an example, an office network which offers centrally controlled 613233294Sstasdesktop logins, mail, messaging (xmpp) and openafs would give users 614233294Sstassingle sign-on facilities via smartcard based logins. Once the kerberos 615233294Sstasticket has been acquired, all kerberized services would immediately 616233294Sstasbecome accessible based on deployed security policies. 617233294Sstas 618233294SstasLet's go over the process of initializing a demo PK-INIT framework: 619233294Sstas 620178825Sdfr@example 621178825Sdfrhxtool issue-certificate \ 622233294Sstas --type="pkinit-kdc" \ 623233294Sstas --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \ 624233294Sstas --hostname=kerberos.test.h5l.se \ 625233294Sstas --ca-certificate="FILE:ca.pem,ca.key" \ 626233294Sstas --generate-key=rsa \ 627233294Sstas --certificate="FILE:kdc.pem" \ 628233294Sstas --subject="cn=kdc" 629178825Sdfr@end example 630178825Sdfr 631178825SdfrHow to create a certificate for a user. 632178825Sdfr 633178825Sdfr@example 634178825Sdfrhxtool issue-certificate \ 635233294Sstas --type="pkinit-client" \ 636233294Sstas --pk-init-principal="user@@TEST.H5L.SE" \ 637233294Sstas --ca-certificate="FILE:ca.pem,ca.key" \ 638233294Sstas --generate-key=rsa \ 639233294Sstas --subject="cn=Test User" \ 640233294Sstas --certificate="FILE:user.pem" 641178825Sdfr@end example 642178825Sdfr 643233294SstasThe --type field can be specified multiple times. The same certificate 644233294Sstascan hence house extensions for both pkinit-client as well as S/MIME. 645233294Sstas 646233294SstasTo use the PKCS11 module, please see the section: 647233294Sstas@pxref{How to use the PKCS11 module}. 648233294Sstas 649233294SstasMore about how to configure the KDC, see the documentation in the 650233294SstasHeimdal manual to set up the KDC. 651233294Sstas 652178825Sdfr@subsection XMPP/Jabber 653178825Sdfr 654178825SdfrThe jabber server certificate should have a dNSname that is the same as 655178825Sdfrthe user entered into the application, not the same as the host name of 656178825Sdfrthe machine. 657178825Sdfr 658178825Sdfr@example 659178825Sdfrhxtool issue-certificate \ 660178825Sdfr --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \ 661178825Sdfr --hostname="xmpp1.test.h5l.se" \ 662178825Sdfr --hostname="test.h5l.se" \ 663178825Sdfr ... 664178825Sdfr@end example 665178825Sdfr 666178825SdfrThe certificate may also contain a jabber identifier (JID) that, if the 667178825Sdfrreceiver allows it, authorises the server or client to use that JID. 668178825Sdfr 669178825SdfrWhen storing a JID inside the certificate, both for server and client, 670178825Sdfrit's stored inside a UTF8String within an otherName entity inside the 671178825SdfrsubjectAltName, using the OID id-on-xmppAddr (1.3.6.1.5.5.7.8.5). 672178825Sdfr 673178825SdfrTo read more about the requirements, see RFC3920, Extensible Messaging 674178825Sdfrand Presence Protocol (XMPP): Core. 675178825Sdfr 676178825Sdfrhxtool issue-certificate have support to add jid to the certificate 677178825Sdfrusing the option @kbd{--jid}. 678178825Sdfr 679178825Sdfr@example 680178825Sdfrhxtool issue-certificate \ 681178825Sdfr --subject="CN=Love,DC=test,DC=h5l,DC=se" \ 682178825Sdfr --jid="lha@@test.h5l.se" \ 683178825Sdfr ... 684178825Sdfr@end example 685178825Sdfr 686178825Sdfr 687178825Sdfr@node CMS signing and encryption, CMS background, Application requirements, Top 688178825Sdfr@chapter CMS signing and encryption 689178825Sdfr 690178825SdfrCMS is the Cryptographic Message System that among other, is used by 691178825SdfrS/MIME (secure email) and Kerberos PK-INIT. It's an extended version of 692178825Sdfrthe RSA, Inc standard PKCS7. 693178825Sdfr 694233294Sstas@node CMS background, Certificate matching, CMS signing and encryption, Top 695178825Sdfr@section CMS background 696178825Sdfr 697178825Sdfr 698233294Sstas@node Certificate matching, Matching syntax, CMS background, Top 699233294Sstas@chapter Certificate matching 700233294Sstas 701233294SstasTo match certificates hx509 have a special query language to match 702233294Sstascertifictes in queries and ACLs. 703233294Sstas 704233294Sstas@node Matching syntax, Software PKCS 11 module, Certificate matching, Top 705233294Sstas@section Matching syntax 706233294Sstas 707233294SstasThis is the language definitions somewhat slopply descriped: 708233294Sstas 709233294Sstas@example 710233294Sstas 711233294Sstasexpr = TRUE, 712233294Sstas FALSE, 713233294Sstas ! expr, 714233294Sstas expr AND expr, 715233294Sstas expr OR expr, 716233294Sstas ( expr ) 717233294Sstas compare 718233294Sstas 719233294Sstascompare = 720233294Sstas word == word, 721233294Sstas word != word, 722233294Sstas word IN ( word [, word ...]) 723233294Sstas word IN %@{variable.subvariable@} 724233294Sstas 725233294Sstasword = 726233294Sstas STRING, 727233294Sstas %@{variable@} 728233294Sstas 729233294Sstas@end example 730233294Sstas 731233294Sstas@node Software PKCS 11 module, How to use the PKCS11 module, Matching syntax, Top 732233294Sstas@chapter Software PKCS 11 module 733233294Sstas 734233294SstasPKCS11 is a standard created by RSA, Inc to support hardware and 735233294Sstassoftware encryption modules. It can be used by smartcard to expose the 736233294Sstascrypto primitives inside without exposing the crypto keys. 737233294Sstas 738233294SstasHx509 includes a software implementation of PKCS11 that runs within the 739233294Sstasmemory space of the process and thus exposes the keys to the 740233294Sstasapplication. 741233294Sstas 742233294Sstas@node How to use the PKCS11 module, , Software PKCS 11 module, Top 743233294Sstas@section How to use the PKCS11 module 744233294Sstas 745233294Sstas@example 746233294Sstas$ cat > ~/.soft-pkcs11.rc <<EOF 747233294Sstasmycert cert User certificate FILE:/Users/lha/Private/pkinit.pem 748233294Sstasapp-fatal true 749233294SstasEOF 750233294Sstas$ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG 751233294Sstas@end example 752233294Sstas 753233294Sstas 754178825Sdfr@c @shortcontents 755178825Sdfr@contents 756178825Sdfr 757178825Sdfr@bye 758