diff options
Diffstat (limited to 'doc/hx509.info')
| -rw-r--r-- | doc/hx509.info | 617 |
1 files changed, 617 insertions, 0 deletions
diff --git a/doc/hx509.info b/doc/hx509.info new file mode 100644 index 000000000000..385b63a872ed --- /dev/null +++ b/doc/hx509.info @@ -0,0 +1,617 @@ +Detta är hx509.info, skapad av makeinfo version 4.8 från hx509.texi. + +INFO-DIR-SECTION Security +START-INFO-DIR-ENTRY +* hx509: (hx509). The X.509 distribution from KTH +END-INFO-DIR-ENTRY + + +File: hx509.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +Heimdal +******* + +This manual is for version 1.5 of hx509. + +* Menu: + +* Introduction:: +* What is X.509 ?:: +* Setting up a CA:: +* CMS signing and encryption:: +* Certificate matching:: +* Software PKCS 11 module:: + + --- The Detailed Node Listing --- + +Setting up a CA + +* Creating a CA certificate:: +* Issuing certificates:: +* Issuing CRLs:: +* Application requirements:: + +CMS signing and encryption + +* CMS background:: + +Certificate matching + +* Matching syntax:: + +Software PKCS 11 module + +* How to use the PKCS11 module:: + + +File: hx509.info, Node: Introduction, Next: What is X.509 ?, Prev: Top, Up: Top + +1 Introduction +************** + +The goals of a PKI infrastructure (as defined in <a +href="http://www.ietf.org/rfc/rfc3280.txt">RFC 3280</a>) is to meet +_the needs of deterministic, automated identification, authentication, +access control, and authorization_. + +The administrator should be aware of certain terminologies as explained +by the aforementioned RFC before attemping to put in place a PKI +infrastructure. Briefly, these are: + + * CA Certificate Authority + + * RA Registration Authority, i.e., an optional system to which a CA + delegates certain management functions. + + * CRL Issuer An optional system to which a CA delegates the + publication of certificate revocation lists. + + * Repository A system or collection of distributed systems that + stores certificates and CRLs and serves as a means of distributing + these certificates and CRLs to end entities + +hx509 (Heimdal x509 support) is a near 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, and/or DER encoded +files. + + +File: hx509.info, Node: What is X.509 ?, Next: Setting up a CA, Prev: Introduction, Up: Top + +2 What is X.509, PKIX, PKCS7 and CMS ? +************************************** + +X.509 was created by CCITT (later ITU) for the X.500 directory service. +Today, X.509 discussions and implementations commonly reference the +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 with the IETF in a +rather complicated dance. + +X.509 is a public key based security system that has associated data +stored within a so called certificate. Initially, X.509 was a strict +hierarchical system with one root. However, ever evolving requiments and +technology advancements saw the inclusion of multiple policy roots, +bridges and mesh solutions. + +x.509 can also be used as a peer to peer system, though often seen as a +common scenario. + +2.1 Type of certificates +======================== + +There are several flavors of certificate in X.509. + + * Trust anchors + + Trust anchors are strictly not certificates, but commonly stored + in a certificate format as they become easier to manage. Trust + anchors are the keys that an end entity would trust to validate + other certificates. This is done by building a path from the + certificate you want to validate to to any of the trust anchors + you have. + + * End Entity (EE) certificates + + End entity certificates are the most common types of certificates. + End entity certificates cannot issue (sign) certificate themselves + and are generally used to authenticate and authorize users and + services. + + * Certification Authority (CA) certificates + + Certificate authority certificates have the right to issue + additional certificates (be it sub-ordinate CA certificates to + build an trust anchors or end entity certificates). There is no + limit to how many certificates a CA may issue, but there might + other restrictions, like the maximum path depth. + + * Proxy certificates + + Remember the statement "End Entity certificates cannot issue + certificates"? Well that statement is not entirely true. 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 policies 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 when the print service initializes + (without any user intervention), access to the files for the print + job is granted via the proxy certificate. As a result of (in-place) + policy limitations, the certificate cannot be used for any other + purposes. + + +2.2 Building a path +=================== + +Before validating a certificate path (or chain), the path needs to 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. + +The process starts by looking at the issuing CA of the certificate, by +Name or Key Identifier, and tries to find that certificate while at the +same time evaluting any policies in-place. + + +File: hx509.info, Node: Setting up a CA, Next: Creating a CA certificate, Prev: What is X.509 ?, Up: Top + +3 Setting up a CA +***************** + +Do not let information overload scare you off! If you are simply testing +or getting started with a PKI infrastructure, skip all this and go to +the next chapter (see: *note Creating a CA certificate::). + +Creating a CA certificate should be more the just creating a +certificate, CA's should define a policy. Again, if you are simply +testing a PKI, policies do not matter so much. However, when 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 things simple, it's not very hard to run a +Certificate authority and the process to get new certificates should be +simple. + +You may find it helpful to answer the following policy questions for +your organization at a later stage: + + * 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. + + +File: hx509.info, Node: Creating a CA certificate, Next: Issuing certificates, Prev: Setting up a CA, Up: Top + +3.1 Creating a CA certificate +============================= + +This section describes how to create a CA certificate and what to think +about. + +3.1.1 Lifetime CA certificate +----------------------------- + +You probably want to create a CA certificate with a long lifetime, 10 +years at the very minimum. This is because you don't want to push out +the certificate (as a trust anchor) to all you users again when the old +CA certificate expires. Although a trust anchor can't really expire, +not all software works in accordance with published standards. + +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. + +3.1.2 Create a CA certificate +----------------------------- + +This command below can be used to generate a self-signed CA certificate. + + 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" + +3.1.3 Extending the lifetime of a CA certificate +------------------------------------------------ + +You just realised that your CA certificate is going to expire soon and +that you need replace it with a new CA. The easiest way to do that is +to extend the lifetime of your existing CA certificate. + +The example below will extend the CA certificate's lifetime by 10 years. +You should compare this new certificate if it contains all the special +tweaks as the old certificate had. + + 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" + +3.1.4 Subordinate CA +-------------------- + +This example below creates a new subordinate certificate authority. + + 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" + + +File: hx509.info, Node: Issuing certificates, Next: Issuing CRLs, Prev: Creating a CA certificate, Up: Top + +3.2 Issuing certificates +======================== + +First you'll create a CA certificate, after that you have to deal with +your users and servers and issue certificates to them. + + * Do all the work themself + + Generate the key for the user. This has the problme that the the CA + knows the private key of the user. For a paranoid user this might + leave feeling of disconfort. + + * Have the user do part of the work + + Receive PKCS10 certificate requests fromusers. PKCS10 is a request + for a certificate. The user may specify what DN they want as well + as provide a certificate signing request (CSR). To prove the user + have the key, the whole request is signed by the private key of + the user. + + +3.2.1 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). + +3.2.2 Certificate Revocation, CRL and OCSP +------------------------------------------ + +Certificates that a CA issues may need to be revoked at some stage. As +an example, an employee leaves the organization and does not bother +handing in his smart card (or even if the smart card is handed back - +the certificate on it must no longer be acceptable to services; the +employee has left). + +You may also want to revoke a certificate for a service which is no +longer being offered on your network. Overlooking these scenarios can +lead to security holes which will quickly become a nightmare to deal +with. + +There are two primary protocols for dealing with certificate +revokation. Namely: + + * Certificate Revocation List (CRL) + + * Online Certificate Status Protocol (OCSP) + +If however the certificate in qeustion has been destroyed, there is no +need to revoke the certificate because it can not be used by someone +else. This matter since for each certificate you add to CRL, the +download time and processing time for clients are longer. + +CRLs and OCSP responders however greatly help manage compatible services +which may authenticate and authorize users (or services) on an on-going +basis. As an example, VPN connectivity established via certificates for +connecting clients would require your VPN software to make use of a CRL +or an OCSP service to ensure revoked certificates belonging to former +clients are not allowed access to (formerly subscribed) network +services. + + +File: hx509.info, Node: Issuing CRLs, Next: Application requirements, Prev: Issuing certificates, Up: Top + +3.3 Issuing CRLs +================ + +Create an empty CRL with no certificates revoked. Default expiration +value is one year from now. + + hxtool crl-sign \ + --crl-file=crl.der \ + --signer=FILE:ca.pem + +Create a CRL with all certificates in the directory +`/path/to/revoked/dir' included in the CRL as revoked. Also make it +expire one month from now. + + hxtool crl-sign \ + --crl-file=crl.der \ + --signer=FILE:ca.pem \ + --lifetime='1 month' \ + DIR:/path/to/revoked/dir + + +File: hx509.info, Node: Application requirements, Next: CMS signing and encryption, Prev: Issuing CRLs, Up: Top + +3.4 Application requirements +============================ + +Application place different requirements on certificates. This section +tries to expand what they are and how to use hxtool to generate +certificates for those services. + +3.4.1 HTTPS - server +-------------------- + + 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" \ + ... + +3.4.2 HTTPS - client +-------------------- + + hxtool issue-certificate \ + --subject="UID=testus,DC=test,DC=h5l,DC=se" \ + --type="https-client" \ + ... + +3.4.3 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 +way is in the subject distinguished name, _this should not be used_. The +new way is using a Subject Alternative Name (SAN). + +Even though the email address is stored in certificates, they don't need +to be, email reader programs are required to accept certificates that +doesn't have either of the two methods of storing email in certificates +- in which case, the email client will 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. + + hxtool issue-certificate \ + --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \ + --type=email \ + --email="testus@test.h5l.se" \ + ... + +An example of an certificate without and subject distinguished name with +an email address in a SAN. + + hxtool issue-certificate \ + --subject="" \ + --type=email \ + --email="testus@test.h5l.se" \ + ... + +3.4.4 PK-INIT +------------- + +A PK-INIT infrastructure allows users and services to pick up kerberos +credentials (tickets) based on their certificate. This, for example, +allows users to authenticate to their desktops using smartcards while +acquiring kerberos tickets in the process. + +As an example, an office network which offers centrally controlled +desktop logins, mail, messaging (xmpp) and openafs would give users +single sign-on facilities via smartcard based logins. Once the kerberos +ticket has been acquired, all kerberized services would immediately +become accessible based on deployed security policies. + +Let's go over the process of initializing a demo PK-INIT framework: + + hxtool issue-certificate \ + --type="pkinit-kdc" \ + --pk-init-principal="krbtgt/TEST.H5L.SE@TEST.H5L.SE" \ + --hostname=kerberos.test.h5l.se \ + --ca-certificate="FILE:ca.pem,ca.key" \ + --generate-key=rsa \ + --certificate="FILE:kdc.pem" \ + --subject="cn=kdc" + +How to create a certificate for a user. + + hxtool issue-certificate \ + --type="pkinit-client" \ + --pk-init-principal="user@TEST.H5L.SE" \ + --ca-certificate="FILE:ca.pem,ca.key" \ + --generate-key=rsa \ + --subject="cn=Test User" \ + --certificate="FILE:user.pem" + +The -type field can be specified multiple times. The same certificate +can hence house extensions for both pkinit-client as well as S/MIME. + +To use the PKCS11 module, please see the section: *note How to use the +PKCS11 module::. + +More about how to configure the KDC, see the documentation in the +Heimdal manual to set up the KDC. + +3.4.5 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. + + hxtool issue-certificate \ + --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \ + --hostname="xmpp1.test.h5l.se" \ + --hostname="test.h5l.se" \ + ... + +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 `--jid'. + + hxtool issue-certificate \ + --subject="CN=Love,DC=test,DC=h5l,DC=se" \ + --jid="lha@test.h5l.se" \ + ... + + +File: hx509.info, Node: CMS signing and encryption, Next: CMS background, Prev: Application requirements, Up: Top + +4 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. + + +File: hx509.info, Node: CMS background, Next: Certificate matching, Prev: CMS signing and encryption, Up: Top + +4.1 CMS background +================== + + +File: hx509.info, Node: Certificate matching, Next: Matching syntax, Prev: CMS background, Up: Top + +5 Certificate matching +********************** + +To match certificates hx509 have a special query language to match +certifictes in queries and ACLs. + + +File: hx509.info, Node: Matching syntax, Next: Software PKCS 11 module, Prev: Certificate matching, Up: Top + +5.1 Matching syntax +=================== + +This is the language definitions somewhat slopply descriped: + + + expr = TRUE, + FALSE, + ! expr, + expr AND expr, + expr OR expr, + ( expr ) + compare + + compare = + word == word, + word != word, + word IN ( word [, word ...]) + word IN %{variable.subvariable} + + word = + STRING, + %{variable} + + +File: hx509.info, Node: Software PKCS 11 module, Next: How to use the PKCS11 module, Prev: Matching syntax, Up: Top + +6 Software PKCS 11 module +************************* + +PKCS11 is a standard created by RSA, Inc to support hardware and +software encryption modules. It can be used by smartcard to expose the +crypto primitives inside without exposing the crypto keys. + +Hx509 includes a software implementation of PKCS11 that runs within the +memory space of the process and thus exposes the keys to the +application. + + +File: hx509.info, Node: How to use the PKCS11 module, Prev: Software PKCS 11 module, Up: Top + +6.1 How to use the PKCS11 module +================================ + + $ cat > ~/.soft-pkcs11.rc <<EOF + mycert cert User certificate FILE:/Users/lha/Private/pkinit.pem + app-fatal true + EOF + $ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@EXAMPLE.ORG + + + +Tag Table: +Node: Top203 +Node: Introduction797 +Node: What is X.509 ?2246 +Node: Setting up a CA6204 +Node: Creating a CA certificate7474 +Node: Issuing certificates9915 +Node: Issuing CRLs12458 +Node: Application requirements13085 +Node: CMS signing and encryption18446 +Node: CMS background18797 +Node: Certificate matching18953 +Node: Matching syntax19207 +Node: Software PKCS 11 module19764 +Node: How to use the PKCS11 module20283 + +End Tag Table |