hx509.texi revision 178826
1\input texinfo @c -*- texinfo -*- 2@c %**start of header 3@c $Id: hx509.texi 22071 2007-11-14 20:04:50Z lha $ 4@setfilename hx509.info 5@settitle HX509 6@iftex 7@afourpaper 8@end iftex 9@c some sensible characters, please? 10@tex 11\input latin1.tex 12@end tex 13@setchapternewpage on 14@syncodeindex pg cp 15@c %**end of header 16 17@set UPDATED $Date: 2007-11-14 12:04:50 -0800 (Ons, 14 Nov 2007) $ 18@set VERSION 1.0 19@set EDITION 1.0 20 21@ifinfo 22@dircategory Security 23@direntry 24* hx509: (hx509). The X.509 distribution from KTH 25@end direntry 26@end ifinfo 27 28@c title page 29@titlepage 30@title HX509 31@subtitle X.509 distribution from KTH 32@subtitle Edition @value{EDITION}, for version @value{VERSION} 33@subtitle 2007 34@author Love H�rnquist �strand 35@author last updated @value{UPDATED} 36 37@def@copynext{@vskip 20pt plus 1fil@penalty-1000} 38@def@copyrightstart{} 39@def@copyrightend{} 40@page 41@copyrightstart 42Copyright (c) 1994-2007 Kungliga Tekniska H�gskolan 43(Royal Institute of Technology, Stockholm, Sweden). 44All rights reserved. 45 46Redistribution and use in source and binary forms, with or without 47modification, are permitted provided that the following conditions 48are met: 49 501. Redistributions of source code must retain the above copyright 51 notice, this list of conditions and the following disclaimer. 52 532. Redistributions in binary form must reproduce the above copyright 54 notice, this list of conditions and the following disclaimer in the 55 documentation and/or other materials provided with the distribution. 56 573. Neither the name of the Institute nor the names of its contributors 58 may be used to endorse or promote products derived from this software 59 without specific prior written permission. 60 61THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 62ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 63IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 64ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 65FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 66DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 67OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 68HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 69LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 70OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 71SUCH DAMAGE. 72 73@copynext 74 75Copyright (C) 1990 by the Massachusetts Institute of Technology 76 77Export of this software from the United States of America may 78require a specific license from the United States Government. 79It is the responsibility of any person or organization contemplating 80export to obtain such a license before exporting. 81 82WITHIN THAT CONSTRAINT, permission to use, copy, modify, and 83distribute this software and its documentation for any purpose and 84without fee is hereby granted, provided that the above copyright 85notice appear in all copies and that both that copyright notice and 86this permission notice appear in supporting documentation, and that 87the name of M.I.T. not be used in advertising or publicity pertaining 88to distribution of the software without specific, written prior 89permission. M.I.T. makes no representations about the suitability of 90this software for any purpose. It is provided "as is" without express 91or implied warranty. 92 93@copynext 94 95Copyright (c) 1988, 1990, 1993 96 The Regents of the University of California. All rights reserved. 97 98Redistribution and use in source and binary forms, with or without 99modification, are permitted provided that the following conditions 100are met: 101 1021. Redistributions of source code must retain the above copyright 103 notice, this list of conditions and the following disclaimer. 104 1052. Redistributions in binary form must reproduce the above copyright 106 notice, this list of conditions and the following disclaimer in the 107 documentation and/or other materials provided with the distribution. 108 1093. Neither the name of the University nor the names of its contributors 110 may be used to endorse or promote products derived from this software 111 without specific prior written permission. 112 113THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 114ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 115IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 116ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 117FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 118DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 119OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 120HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 121LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 122OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 123SUCH DAMAGE. 124 125@copynext 126 127Copyright 1992 Simmule Turner and Rich Salz. All rights reserved. 128 129This software is not subject to any license of the American Telephone 130and Telegraph Company or of the Regents of the University of California. 131 132Permission is granted to anyone to use this software for any purpose on 133any computer system, and to alter it and redistribute it freely, subject 134to the following restrictions: 135 1361. The authors are not responsible for the consequences of use of this 137 software, no matter how awful, even if they arise from flaws in it. 138 1392. The origin of this software must not be misrepresented, either by 140 explicit claim or by omission. Since few users ever read sources, 141 credits must appear in the documentation. 142 1433. Altered versions must be plainly marked as such, and must not be 144 misrepresented as being the original software. Since few users 145 ever read sources, credits must appear in the documentation. 146 1474. This notice may not be removed or altered. 148 149@copynext 150 151IMath is Copyright 2002-2005 Michael J. Fromberger 152You may use it subject to the following Licensing Terms: 153 154Permission is hereby granted, free of charge, to any person obtaining 155a copy of this software and associated documentation files (the 156"Software"), to deal in the Software without restriction, including 157without limitation the rights to use, copy, modify, merge, publish, 158distribute, sublicense, and/or sell copies of the Software, and to 159permit persons to whom the Software is furnished to do so, subject to 160the following conditions: 161 162The above copyright notice and this permission notice shall be 163included in all copies or substantial portions of the Software. 164 165THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 166EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 167MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 168IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 169CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 170TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 171SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 172 173@copyrightend 174@end titlepage 175 176@macro manpage{man, section} 177@cite{\man\(\section\)} 178@end macro 179 180@c Less filling! Tastes great! 181@iftex 182@parindent=0pt 183@global@parskip 6pt plus 1pt 184@global@chapheadingskip = 15pt plus 4pt minus 2pt 185@global@secheadingskip = 12pt plus 3pt minus 2pt 186@global@subsecheadingskip = 9pt plus 2pt minus 2pt 187@end iftex 188@ifinfo 189@paragraphindent 0 190@end ifinfo 191 192@ifnottex 193@node Top, Introduction, (dir), (dir) 194@top Heimdal 195@end ifnottex 196 197This manual is last updated @value{UPDATED} for version 198@value{VERSION} of hx509. 199 200@menu 201* Introduction:: 202* What is X.509 ?:: 203* Setting up a CA:: 204* CMS signing and encryption:: 205 206@detailmenu 207 --- The Detailed Node Listing --- 208 209Setting up a CA 210 211@c * Issuing certificates:: 212* Creating a CA certificate:: 213* Issuing certificates:: 214* Issuing CRLs:: 215@c * Issuing a proxy certificate:: 216@c * Creating a user certificate:: 217@c * Validating a certificate:: 218@c * Validating a certificate path:: 219* Application requirements:: 220 221CMS signing and encryption 222 223* CMS background:: 224 225@end detailmenu 226@end menu 227 228@node Introduction, What is X.509 ?, Top, Top 229@chapter Introduction 230 231hx509 is a somewhat complete X.509 stack that can handle CMS messages 232(crypto system used in S/MIME and Kerberos PK-INIT) and basic 233certificate processing tasks, path construction, path validation, OCSP 234and CRL validation, PKCS10 message construction, CMS Encrypted (shared 235secret encrypted), CMS SignedData (certificate signed), and CMS 236EnvelopedData (certificate encrypted). 237 238hx509 can use PKCS11 tokens, PKCS12 files, PEM files, DER encoded files. 239 240@node What is X.509 ?, Setting up a CA, Introduction, Top 241@chapter What is X.509, PKIX, PKCS7 and CMS ? 242 243X.509 is from the beginning created by CCITT (later ITU) for the X.500 244directory service. But today when people are talking about X.509 they 245are commonly referring to IETF's PKIX Certificate and CRL Profile of the 246X.509 v3 certificate standard, as specified in RFC 3280. 247 248ITU continues to develop the X.509 standard together in a complicated 249dance with IETF. 250 251X.509 is public key based security system that have associated data 252stored within a so called certificate. From the beginning X.509 was a 253strict hierarchical system with one root. This didn't not work so over 254time X.509 got support for multiple policy roots, bridges, and mesh 255solutions. You can even use it as a peer to peer system, but this is not 256very common. 257 258@section Type of certificates 259 260There are several flavors of certificate in X.509. 261 262@itemize @bullet 263 264@item Trust anchors 265 266Trust anchors are strictly not certificate, but commonly stored in 267certificate since they are easier to handle then. Trust anchor are the 268keys that you trust to validate other certificate. This is done by 269building a path from the certificate you wan to validate to to any of 270the trust anchors you have. 271 272@item End Entity (EE) certificates 273 274End entity certificates is the most common type of certificate. End 275entity certificates can't issue certificate them-self and is used to 276authenticate and authorize user and services. 277 278@item Certification Authority (CA) certificates 279 280Certificate authority are certificates that have the right to issue 281other certificate, they may be End entity certificates or Certificate 282Authority certificates. There is no limit to how many certificates a CA 283may issue, but there might other restrictions, like the maximum path 284depth. 285 286@item Proxy certificates 287 288Remember that End Entity can't issue certificates by them own, it's not 289really true. There there is an extension called proxy certificates, 290defined in RFC3820, that allows certificates to be issued by end entity 291certificates. The service that receives the proxy certificates must have 292explicitly turned on support for proxy certificates, so their use is 293somewhat limited. 294 295Proxy certificates can be limited by policy stored in the certificate to 296what they can be used for. This allows users to delegate the proxy 297certificate to services (by sending over the certificate and private 298key) so the service can access services on behalf of the user. 299 300One example of this would be a print service. The user wants to print a 301large job in the middle of the night when the printer isn't used that 302much, so the user creates a proxy certificate with the policy that it 303can only be used to access files related to this print job, creates the 304print job description and send both the description and proxy 305certificate with key over to print service. Later at night will the 306print service, without the help of the user, access the files for the 307the print job using the proxy certificate and print the job. Because of 308the policy (limitation) in the proxy certificate, it can't be used for 309any other purposes. 310 311@end itemize 312 313@section Building a path 314 315Before validating a path the path must be constructed. Given a 316certificate (EE, CA, Proxy, or any other type), the path construction 317algorithm will try to find a path to one of the trust anchors. 318 319It start with looking at whom issued the certificate, by name or Key 320Identifier, and tries to find that certificate while at the same time 321evaluates the policy. 322 323@node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top 324@chapter Setting up a CA 325 326Do not let this chapter scare you off, it's just to give you an idea how 327to complicated setting up a CA can be. If you are just playing around, 328skip all this and go to the next chapter, @pxref{Creating a CA 329certificate}. 330 331Creating a CA certificate should be more the just creating a 332certificate, there is the policy of the CA. If it's just you and your 333friend that is playing around then it probably doesn't matter what the 334policy is. But then it comes to trust in an organisation, it will 335probably matter more whom your users and sysadmins will find it 336acceptable to trust. 337 338At the same time, try to keep thing simple, it's not very hard to run a 339Certificate authority and the process to get new certificates should 340simple. 341 342Fill all this in later. 343 344How do you trust your CA. 345 346What is the CA responsibility. 347 348Review of CA activity. 349 350How much process should it be to issue certificate. 351 352Who is allowed to issue certificates. 353 354Who is allowed to requests certificates. 355 356How to handle certificate revocation, issuing CRLs and maintain OCSP 357services. 358 359@node Creating a CA certificate, Issuing certificates, Setting up a CA, Top 360@section Creating a CA certificate 361 362This section describes how to create a CA certificate and what to think 363about. 364 365@subsection Lifetime CA certificate 366 367You probably want to create a CA certificate with a long lifetime, 10 368years at the shortest. This because you don't want to push out the 369certificate (as a trust anchor) to all you users once again when the old 370one just expired. A trust anchor can't really expire, but not all 371software works that way. 372 373Keep in mind the security requirements might be different 10-20 years 374into the future. For example, SHA1 is going to be withdrawn in 2010, so 375make sure you have enough buffering in your choice of digest/hash 376algorithms, signature algorithms and key lengths. 377 378@subsection Create a CA certificate 379 380This command below will create a CA certificate in the file ca.pem. 381 382@example 383hxtool issue-certificate \ 384 --self-signed \ 385 --issue-ca \ 386 --generate-key=rsa \ 387 --subject="CN=CertificateAuthority,DC=test,DC=h5l,DC=se" \ 388 --lifetime=10years \ 389 --certificate="FILE:ca.pem" 390@end example 391 392@subsection Extending lifetime of a CA certificate 393 394You just realised that your CA certificate is going to expire soon and 395that you need replace it with something else, the easiest way to do that 396is to extend the lifetime of your CA certificate. 397 398The example below will extend the CA certificate 10 years into the 399future. You should compare this new certificate if it contains all the 400special tweaks as the old certificate had. 401 402@example 403hxtool issue-certificate \ 404 --self-signed \ 405 --issue-ca \ 406 --lifetime="10years" \ 407 --template-certificate="FILE:ca.pem" \ 408 --template-fields="serialNumber,notBefore,subject,SPKI" \ 409 --ca-private-key=FILE:ca.pem \ 410 --certificate="FILE:new-ca.pem" 411@end example 412 413@subsection Subordinate CA 414 415This example create a new subordinate certificate authority. 416 417@example 418hxtool issue-certificate \ 419 --ca-certificate=FILE:ca.pem \ 420 --issue-ca \ 421 --generate-key=rsa \ 422 --subject="CN=CertificateAuthority,DC=dev,DC=test,DC=h5l,DC=se" \ 423 --certificate="FILE:dev-ca.pem" 424@end example 425 426 427@node Issuing certificates, Issuing CRLs, Creating a CA certificate, Top 428@section Issuing certificates 429 430First you'll create a CA certificate, after that you have to deal with 431your users and servers and issue certificate to them. 432 433CA can generate the key for the user. 434 435Can receive PKCS10 certificate requests from the users. PKCS10 is a 436request for a certificate. The user can specified what DN the user wants 437and what public key. To prove the user have the key, the whole request 438is signed by the private key of the user. 439 440@subsection Name space management 441 442What people might want to see. 443 444Re-issue certificates just because people moved within the organization. 445 446Expose privacy information. 447 448Using Sub-component name (+ notation). 449 450@subsection Certificate Revocation, CRL and OCSP 451 452Sonetimes people loose smartcard or computers and certificates have to 453be make not valid any more, this is called revoking certificates. There 454are two main protocols for doing this Certificate Revocations Lists 455(CRL) and Online Certificate Status Protocol (OCSP). 456 457If you know that the certificate is destroyed then there is no need to 458revoke the certificate because it can not be used by someone else. 459 460The main reason you as a CA administrator have to deal with CRLs however 461will be that some software require there to be CRLs. Example of this is 462Windows, so you have to deal with this somehow. 463 464@node Issuing CRLs, Application requirements, Issuing certificates, Top 465@section Issuing CRLs 466 467Create an empty CRL with not certificates revoked. Default expiration 468value is one year from now. 469 470@example 471hxtool crl-sign \ 472 --crl-file=crl.der \ 473 --signer=FILE:ca.pem 474@end example 475 476Create a CRL with all certificates in the directory 477@file{/path/to/revoked/dir} included in the CRL as revoked. Also make 478it expire one month from now. 479 480@example 481hxtool crl-sign \ 482 --crl-file=crl.der \ 483 --signer=FILE:ca.pem \ 484 --lifetime='1 month' \ 485 DIR:/path/to/revoked/dir 486@end example 487 488@node Application requirements, CMS signing and encryption, Issuing CRLs, Top 489@section Application requirements 490 491Application have different requirements on certificates. This section 492tries to expand what they are and how to use hxtool to generate 493certificates for those services. 494 495@subsection HTTPS - server 496 497@example 498hxtool issue-certificate \ 499 --subject="CN=www.test.h5l.se,DC=test,DC=h5l,DC=se" \ 500 --type="https-server" \ 501 --hostname="www.test.h5l.se" \ 502 --hostname="www2.test.h5l.se" \ 503 ... 504@end example 505 506@subsection HTTPS - client 507 508@example 509hxtool issue-certificate \ 510 --subject="UID=testus,DC=test,DC=h5l,DC=se" \ 511 --type="https-client" \ 512 ... 513@end example 514 515@subsection S/MIME - email 516 517There are two things that should be set in S/MIME certificates, one or 518more email addresses and an extended eku usage (EKU), emailProtection. 519 520The email address format used in S/MIME certificates is defined in 521RFC2822, section 3.4.1 and it should be an ``addr-spec''. 522 523There are two ways to specifify email address in certificates. The old 524ways is in the subject distinguished name, this should not be used. The 525new way is using a Subject Alternative Name (SAN). 526 527But even though email address is stored in certificates, they don't need 528to, email reader programs are required to accept certificates that 529doesn't have either of the two methods of storing email in certificates. 530In that case, they try to protect the user by printing the name of the 531certificate instead. 532 533S/MIME certificate can be used in another special way. They can be 534issued with a NULL subject distinguished name plus the email in SAN, 535this is a valid certificate. This is used when you wont want to share 536more information then you need to. 537 538hx509 issue-certificate supports adding the email SAN to certificate by 539using the --email option, --email also gives an implicit emailProtection 540eku. If you want to create an certificate without an email address, the 541option --type=email will add the emailProtection EKU. 542 543@example 544hxtool issue-certificate \ 545 --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \ 546 --type=email \ 547 --email="testus@@test.h5l.se" \ 548 ... 549@end example 550 551An example of an certificate without and subject distinguished name with 552an email address in a SAN. 553 554@example 555hxtool issue-certificate \ 556 --subject="" \ 557 --type=email \ 558 --email="testus@@test.h5l.se" \ 559 ... 560@end example 561 562@subsection PK-INIT 563 564How to create a certificate for a KDC. 565 566@example 567hxtool issue-certificate \ 568 --type="pkinit-kdc" \ 569 --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \ 570 --hostname kerberos.test.h5l.se \ 571 --hostname pal.test.h5l.se \ 572 ... 573@end example 574 575How to create a certificate for a user. 576 577@example 578hxtool issue-certificate \ 579 --type="pkinit-client" \ 580 --pk-init-principal="user@@TEST.H5L.SE" \ 581 ... 582@end example 583 584@subsection XMPP/Jabber 585 586The jabber server certificate should have a dNSname that is the same as 587the user entered into the application, not the same as the host name of 588the machine. 589 590@example 591hxtool issue-certificate \ 592 --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \ 593 --hostname="xmpp1.test.h5l.se" \ 594 --hostname="test.h5l.se" \ 595 ... 596@end example 597 598The certificate may also contain a jabber identifier (JID) that, if the 599receiver allows it, authorises the server or client to use that JID. 600 601When storing a JID inside the certificate, both for server and client, 602it's stored inside a UTF8String within an otherName entity inside the 603subjectAltName, using the OID id-on-xmppAddr (1.3.6.1.5.5.7.8.5). 604 605To read more about the requirements, see RFC3920, Extensible Messaging 606and Presence Protocol (XMPP): Core. 607 608hxtool issue-certificate have support to add jid to the certificate 609using the option @kbd{--jid}. 610 611@example 612hxtool issue-certificate \ 613 --subject="CN=Love,DC=test,DC=h5l,DC=se" \ 614 --jid="lha@@test.h5l.se" \ 615 ... 616@end example 617 618 619@node CMS signing and encryption, CMS background, Application requirements, Top 620@chapter CMS signing and encryption 621 622CMS is the Cryptographic Message System that among other, is used by 623S/MIME (secure email) and Kerberos PK-INIT. It's an extended version of 624the RSA, Inc standard PKCS7. 625 626@node CMS background, , CMS signing and encryption, Top 627@section CMS background 628 629 630@c @shortcontents 631@contents 632 633@bye 634