diff options
Diffstat (limited to 'crypto/heimdal/doc/hx509.texi')
| -rw-r--r-- | crypto/heimdal/doc/hx509.texi | 633 |
1 files changed, 633 insertions, 0 deletions
diff --git a/crypto/heimdal/doc/hx509.texi b/crypto/heimdal/doc/hx509.texi new file mode 100644 index 000000000000..dbb5261ef938 --- /dev/null +++ b/crypto/heimdal/doc/hx509.texi @@ -0,0 +1,633 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@c $Id: hx509.texi 22071 2007-11-14 20:04:50Z lha $ +@setfilename hx509.info +@settitle HX509 +@iftex +@afourpaper +@end iftex +@c some sensible characters, please? +@tex +\input latin1.tex +@end tex +@setchapternewpage on +@syncodeindex pg cp +@c %**end of header + +@set UPDATED $Date: 2007-11-14 12:04:50 -0800 (Ons, 14 Nov 2007) $ +@set VERSION 1.0 +@set EDITION 1.0 + +@ifinfo +@dircategory Security +@direntry +* hx509: (hx509). The X.509 distribution from KTH +@end direntry +@end ifinfo + +@c title page +@titlepage +@title HX509 +@subtitle X.509 distribution from KTH +@subtitle Edition @value{EDITION}, for version @value{VERSION} +@subtitle 2007 +@author Love Hörnquist Åstrand +@author last updated @value{UPDATED} + +@def@copynext{@vskip 20pt plus 1fil@penalty-1000} +@def@copyrightstart{} +@def@copyrightend{} +@page +@copyrightstart +Copyright (c) 1994-2007 Kungliga Tekniska Högskolan +(Royal Institute of Technology, Stockholm, Sweden). +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. Neither the name of the Institute nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. + +@copynext + +Copyright (C) 1990 by the Massachusetts Institute of Technology + +Export of this software from the United States of America may +require a specific license from the United States Government. +It is the responsibility of any person or organization contemplating +export to obtain such a license before exporting. + +WITHIN THAT CONSTRAINT, permission to use, copy, modify, and +distribute this software and its documentation for any purpose and +without fee is hereby granted, provided that the above copyright +notice appear in all copies and that both that copyright notice and +this permission notice appear in supporting documentation, and that +the name of M.I.T. not be used in advertising or publicity pertaining +to distribution of the software without specific, written prior +permission. M.I.T. makes no representations about the suitability of +this software for any purpose. It is provided "as is" without express +or implied warranty. + +@copynext + +Copyright (c) 1988, 1990, 1993 + The Regents of the University of California. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. Neither the name of the University nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. + +@copynext + +Copyright 1992 Simmule Turner and Rich Salz. All rights reserved. + +This software is not subject to any license of the American Telephone +and Telegraph Company or of the Regents of the University of California. + +Permission is granted to anyone to use this software for any purpose on +any computer system, and to alter it and redistribute it freely, subject +to the following restrictions: + +1. The authors are not responsible for the consequences of use of this + software, no matter how awful, even if they arise from flaws in it. + +2. The origin of this software must not be misrepresented, either by + explicit claim or by omission. Since few users ever read sources, + credits must appear in the documentation. + +3. Altered versions must be plainly marked as such, and must not be + misrepresented as being the original software. Since few users + ever read sources, credits must appear in the documentation. + +4. This notice may not be removed or altered. + +@copynext + +IMath is Copyright 2002-2005 Michael J. Fromberger +You may use it subject to the following Licensing Terms: + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +@copyrightend +@end titlepage + +@macro manpage{man, section} +@cite{\man\(\section\)} +@end macro + +@c Less filling! Tastes great! +@iftex +@parindent=0pt +@global@parskip 6pt plus 1pt +@global@chapheadingskip = 15pt plus 4pt minus 2pt +@global@secheadingskip = 12pt plus 3pt minus 2pt +@global@subsecheadingskip = 9pt plus 2pt minus 2pt +@end iftex +@ifinfo +@paragraphindent 0 +@end ifinfo + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top Heimdal +@end ifnottex + +This manual is last updated @value{UPDATED} for version +@value{VERSION} of hx509. + +@menu +* Introduction:: +* What is X.509 ?:: +* Setting up a CA:: +* CMS signing and encryption:: + +@detailmenu + --- The Detailed Node Listing --- + +Setting up a CA + +@c * Issuing certificates:: +* Creating a CA certificate:: +* Issuing certificates:: +* Issuing CRLs:: +@c * Issuing a proxy certificate:: +@c * Creating a user certificate:: +@c * Validating a certificate:: +@c * Validating a certificate path:: +* Application requirements:: + +CMS signing and encryption + +* CMS background:: + +@end detailmenu +@end menu + +@node Introduction, What is X.509 ?, Top, Top +@chapter Introduction + +hx509 is a somewhat complete X.509 stack that can handle CMS messages +(crypto system used in S/MIME and Kerberos PK-INIT) and basic +certificate processing tasks, path construction, path validation, OCSP +and CRL validation, PKCS10 message construction, CMS Encrypted (shared +secret encrypted), CMS SignedData (certificate signed), and CMS +EnvelopedData (certificate encrypted). + +hx509 can use PKCS11 tokens, PKCS12 files, PEM files, DER encoded files. + +@node What is X.509 ?, Setting up a CA, Introduction, Top +@chapter What is X.509, PKIX, PKCS7 and CMS ? + +X.509 is from the beginning created by CCITT (later ITU) for the X.500 +directory service. But today when people are talking about X.509 they +are commonly referring to IETF's PKIX Certificate and CRL Profile of the +X.509 v3 certificate standard, as specified in RFC 3280. + +ITU continues to develop the X.509 standard together in a complicated +dance with IETF. + +X.509 is public key based security system that have associated data +stored within a so called certificate. From the beginning X.509 was a +strict hierarchical system with one root. This didn't not work so over +time X.509 got support for multiple policy roots, bridges, and mesh +solutions. You can even use it as a peer to peer system, but this is not +very common. + +@section Type of certificates + +There are several flavors of certificate in X.509. + +@itemize @bullet + +@item Trust anchors + +Trust anchors are strictly not certificate, but commonly stored in +certificate since they are easier to handle then. Trust anchor are the +keys that you trust to validate other certificate. This is done by +building a path from the certificate you wan to validate to to any of +the trust anchors you have. + +@item End Entity (EE) certificates + +End entity certificates is the most common type of certificate. End +entity certificates can't issue certificate them-self and is used to +authenticate and authorize user and services. + +@item Certification Authority (CA) certificates + +Certificate authority are certificates that have the right to issue +other certificate, they may be End entity certificates or Certificate +Authority certificates. There is no limit to how many certificates a CA +may issue, but there might other restrictions, like the maximum path +depth. + +@item Proxy certificates + +Remember that End Entity can't issue certificates by them own, it's not +really true. There there is an extension called proxy certificates, +defined in RFC3820, that allows certificates to be issued by end entity +certificates. The service that receives the proxy certificates must have +explicitly turned on support for proxy certificates, so their use is +somewhat limited. + +Proxy certificates can be limited by policy stored in the certificate to +what they can be used for. This allows users to delegate the proxy +certificate to services (by sending over the certificate and private +key) so the service can access services on behalf of the user. + +One example of this would be a print service. The user wants to print a +large job in the middle of the night when the printer isn't used that +much, so the user creates a proxy certificate with the policy that it +can only be used to access files related to this print job, creates the +print job description and send both the description and proxy +certificate with key over to print service. Later at night will the +print service, without the help of the user, access the files for the +the print job using the proxy certificate and print the job. Because of +the policy (limitation) in the proxy certificate, it can't be used for +any other purposes. + +@end itemize + +@section Building a path + +Before validating a path the path must be constructed. Given a +certificate (EE, CA, Proxy, or any other type), the path construction +algorithm will try to find a path to one of the trust anchors. + +It start with looking at whom issued the certificate, by name or Key +Identifier, and tries to find that certificate while at the same time +evaluates the policy. + +@node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top +@chapter Setting up a CA + +Do not let this chapter scare you off, it's just to give you an idea how +to complicated setting up a CA can be. If you are just playing around, +skip all this and go to the next chapter, @pxref{Creating a CA +certificate}. + +Creating a CA certificate should be more the just creating a +certificate, there is the policy of the CA. If it's just you and your +friend that is playing around then it probably doesn't matter what the +policy is. But then it comes to trust in an organisation, it will +probably matter more whom your users and sysadmins will find it +acceptable to trust. + +At the same time, try to keep thing simple, it's not very hard to run a +Certificate authority and the process to get new certificates should +simple. + +Fill all this in later. + +How do you trust your CA. + +What is the CA responsibility. + +Review of CA activity. + +How much process should it be to issue certificate. + +Who is allowed to issue certificates. + +Who is allowed to requests certificates. + +How to handle certificate revocation, issuing CRLs and maintain OCSP +services. + +@node Creating a CA certificate, Issuing certificates, Setting up a CA, Top +@section Creating a CA certificate + +This section describes how to create a CA certificate and what to think +about. + +@subsection Lifetime CA certificate + +You probably want to create a CA certificate with a long lifetime, 10 +years at the shortest. This because you don't want to push out the +certificate (as a trust anchor) to all you users once again when the old +one just expired. A trust anchor can't really expire, but not all +software works that way. + +Keep in mind the security requirements might be different 10-20 years +into the future. For example, SHA1 is going to be withdrawn in 2010, so +make sure you have enough buffering in your choice of digest/hash +algorithms, signature algorithms and key lengths. + +@subsection Create a CA certificate + +This command below will create a CA certificate in the file ca.pem. + +@example +hxtool issue-certificate \ + --self-signed \ + --issue-ca \ + --generate-key=rsa \ + --subject="CN=CertificateAuthority,DC=test,DC=h5l,DC=se" \ + --lifetime=10years \ + --certificate="FILE:ca.pem" +@end example + +@subsection Extending lifetime of a CA certificate + +You just realised that your CA certificate is going to expire soon and +that you need replace it with something else, the easiest way to do that +is to extend the lifetime of your CA certificate. + +The example below will extend the CA certificate 10 years into the +future. You should compare this new certificate if it contains all the +special tweaks as the old certificate had. + +@example +hxtool issue-certificate \ + --self-signed \ + --issue-ca \ + --lifetime="10years" \ + --template-certificate="FILE:ca.pem" \ + --template-fields="serialNumber,notBefore,subject,SPKI" \ + --ca-private-key=FILE:ca.pem \ + --certificate="FILE:new-ca.pem" +@end example + +@subsection Subordinate CA + +This example create a new subordinate certificate authority. + +@example +hxtool issue-certificate \ + --ca-certificate=FILE:ca.pem \ + --issue-ca \ + --generate-key=rsa \ + --subject="CN=CertificateAuthority,DC=dev,DC=test,DC=h5l,DC=se" \ + --certificate="FILE:dev-ca.pem" +@end example + + +@node Issuing certificates, Issuing CRLs, Creating a CA certificate, Top +@section Issuing certificates + +First you'll create a CA certificate, after that you have to deal with +your users and servers and issue certificate to them. + +CA can generate the key for the user. + +Can receive PKCS10 certificate requests from the users. PKCS10 is a +request for a certificate. The user can specified what DN the user wants +and what public key. To prove the user have the key, the whole request +is signed by the private key of the user. + +@subsection Name space management + +What people might want to see. + +Re-issue certificates just because people moved within the organization. + +Expose privacy information. + +Using Sub-component name (+ notation). + +@subsection Certificate Revocation, CRL and OCSP + +Sonetimes people loose smartcard or computers and certificates have to +be make not valid any more, this is called revoking certificates. There +are two main protocols for doing this Certificate Revocations Lists +(CRL) and Online Certificate Status Protocol (OCSP). + +If you know that the certificate is destroyed then there is no need to +revoke the certificate because it can not be used by someone else. + +The main reason you as a CA administrator have to deal with CRLs however +will be that some software require there to be CRLs. Example of this is +Windows, so you have to deal with this somehow. + +@node Issuing CRLs, Application requirements, Issuing certificates, Top +@section Issuing CRLs + +Create an empty CRL with not certificates revoked. Default expiration +value is one year from now. + +@example +hxtool crl-sign \ + --crl-file=crl.der \ + --signer=FILE:ca.pem +@end example + +Create a CRL with all certificates in the directory +@file{/path/to/revoked/dir} included in the CRL as revoked. Also make +it expire one month from now. + +@example +hxtool crl-sign \ + --crl-file=crl.der \ + --signer=FILE:ca.pem \ + --lifetime='1 month' \ + DIR:/path/to/revoked/dir +@end example + +@node Application requirements, CMS signing and encryption, Issuing CRLs, Top +@section Application requirements + +Application have different requirements on certificates. This section +tries to expand what they are and how to use hxtool to generate +certificates for those services. + +@subsection HTTPS - server + +@example +hxtool issue-certificate \ + --subject="CN=www.test.h5l.se,DC=test,DC=h5l,DC=se" \ + --type="https-server" \ + --hostname="www.test.h5l.se" \ + --hostname="www2.test.h5l.se" \ + ... +@end example + +@subsection HTTPS - client + +@example +hxtool issue-certificate \ + --subject="UID=testus,DC=test,DC=h5l,DC=se" \ + --type="https-client" \ + ... +@end example + +@subsection S/MIME - email + +There are two things that should be set in S/MIME certificates, one or +more email addresses and an extended eku usage (EKU), emailProtection. + +The email address format used in S/MIME certificates is defined in +RFC2822, section 3.4.1 and it should be an ``addr-spec''. + +There are two ways to specifify email address in certificates. The old +ways is in the subject distinguished name, this should not be used. The +new way is using a Subject Alternative Name (SAN). + +But even though email address is stored in certificates, they don't need +to, email reader programs are required to accept certificates that +doesn't have either of the two methods of storing email in certificates. +In that case, they try to protect the user by printing the name of the +certificate instead. + +S/MIME certificate can be used in another special way. They can be +issued with a NULL subject distinguished name plus the email in SAN, +this is a valid certificate. This is used when you wont want to share +more information then you need to. + +hx509 issue-certificate supports adding the email SAN to certificate by +using the --email option, --email also gives an implicit emailProtection +eku. If you want to create an certificate without an email address, the +option --type=email will add the emailProtection EKU. + +@example +hxtool issue-certificate \ + --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \ + --type=email \ + --email="testus@@test.h5l.se" \ + ... +@end example + +An example of an certificate without and subject distinguished name with +an email address in a SAN. + +@example +hxtool issue-certificate \ + --subject="" \ + --type=email \ + --email="testus@@test.h5l.se" \ + ... +@end example + +@subsection PK-INIT + +How to create a certificate for a KDC. + +@example +hxtool issue-certificate \ + --type="pkinit-kdc" \ + --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \ + --hostname kerberos.test.h5l.se \ + --hostname pal.test.h5l.se \ + ... +@end example + +How to create a certificate for a user. + +@example +hxtool issue-certificate \ + --type="pkinit-client" \ + --pk-init-principal="user@@TEST.H5L.SE" \ + ... +@end example + +@subsection XMPP/Jabber + +The jabber server certificate should have a dNSname that is the same as +the user entered into the application, not the same as the host name of +the machine. + +@example +hxtool issue-certificate \ + --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \ + --hostname="xmpp1.test.h5l.se" \ + --hostname="test.h5l.se" \ + ... +@end example + +The certificate may also contain a jabber identifier (JID) that, if the +receiver allows it, authorises the server or client to use that JID. + +When storing a JID inside the certificate, both for server and client, +it's stored inside a UTF8String within an otherName entity inside the +subjectAltName, using the OID id-on-xmppAddr (1.3.6.1.5.5.7.8.5). + +To read more about the requirements, see RFC3920, Extensible Messaging +and Presence Protocol (XMPP): Core. + +hxtool issue-certificate have support to add jid to the certificate +using the option @kbd{--jid}. + +@example +hxtool issue-certificate \ + --subject="CN=Love,DC=test,DC=h5l,DC=se" \ + --jid="lha@@test.h5l.se" \ + ... +@end example + + +@node CMS signing and encryption, CMS background, Application requirements, Top +@chapter CMS signing and encryption + +CMS is the Cryptographic Message System that among other, is used by +S/MIME (secure email) and Kerberos PK-INIT. It's an extended version of +the RSA, Inc standard PKCS7. + +@node CMS background, , CMS signing and encryption, Top +@section CMS background + + +@c @shortcontents +@contents + +@bye |