From 65a0dee37ea64df2f3092b46a1fc2e71859790c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Love=20H=C3=B6rnquist=20=C3=85strand?= Date: Sun, 23 Apr 2006 19:52:14 +0000 Subject: [PATCH] Add text about pk-init git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@17175 ec53bebd-3082-4978-b11e-865c3cabbd6b --- doc/setup.texi | 223 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 222 insertions(+), 1 deletion(-) diff --git a/doc/setup.texi b/doc/setup.texi index 7bc7236c1..84ebea44a 100644 --- a/doc/setup.texi +++ b/doc/setup.texi @@ -28,6 +28,7 @@ doing so. It will make life easier for you and everyone else. * Setting up DNS:: * Using LDAP to store the database:: * Providing Kerberos credentials to servers and programs:: +* Setting up PK-INIT:: @end menu @node Configuration file, Creating the database, Setting up a realm, Setting up a realm @@ -986,7 +987,7 @@ Now you can proceed as in @xref{Using LDAP to store the database}. Heimdal will pick up the Samba LDAP entries if they are in the same search space as the Kerberos entries. -@node Providing Kerberos credentials to servers and programs, , Using LDAP to store the database, Setting up a realm +@node Providing Kerberos credentials to servers and programs, Setting up PK-INIT, Using LDAP to store the database, Setting up a realm @section Providing Kerberos credentials to servers and programs Some services require Kerberos credentials when they start to make @@ -1032,3 +1033,223 @@ service@@host$ kinit --cache=/var/run/service_krb5_cache \ script-to-start-service argument1 argument2 @end example + +@node Setting up PK-INIT, , Providing Kerberos credentials to servers and programs, Setting up a realm +@section Setting up PK-INIT + +PK-INIT is levering the existing PKI infrastructure to use +certificates to get the initial ticket, that is usually the krbtgt. + +To use PK-INIT you must first have a PKI, so if you don't have one, +now its time to create it. Note that you should read the whole chapter +of the document to see the requirements on the CA sortware. + +There needs to exist a mapping between the certificate and what +principals that certificate is allowed to use. There are several ways +to do this. The administrator can use a configuration file, storing +the principal in SubjectAltName in extensions of certificate, or store +the mapping in the principals entry in the kerberos database. + +@section Certificates + +This section document the requirements on the KDC and client +certificates and the format used in the id-pkinit-san OtherName +extention. + +@subsection KDC certificate + +The certificate for the KDC have serveral requirements. + +First the certificate should have a Extended Key Usage (EKU) +id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second there must be a +subjectAltName otherName using oid id-pkinit-san (1.3.6.1.5.2.2) in +the type field and and DER encoded KRB5PrincipalName that matches the +name of the TGS of the target realm. + +Both of these two requirements are not required by the standard to be +checked by the client if it have external information what the +certificate the KDC is supposed to be used. So its in the interst of +minium amount of configuration on the clients they should be included. + +Remember that if client would accept any certificate as the KDC's +certificate, the client could be fooled into trusting something that +isn't a KDC and thus expose the user to giving away information (like +password or other private information) that it is supposed to secret. + +Also, if the extension certificate have a nameConstraints extention +with a Generalname with dNSName or iPAdress it must match the hostname +or adress of the KDC. + +@subsection Client certificate + +The client certificate may need to have a EKU id-pkekuoid +(1.3.6.1.5.2.3.4) depending on set on the certifiate on the KDC. + +It possible to store the principal (if allowed by the KDC) in the +certificate and thus delegate responsibility to do the mapping between +certificates and principals to the CA. + +@subsubsection Using KRB5PrincipalName in id-pkinit-san + +OtherName extenetion in the GeneralName is used is used to do the +mapping between certifiate and principal in the certifiate or storing +the krbtgt principal in the KDC certificate. + +The principal is stored in a SubjectAltName in the certificate using +OtherName. The oid in the type is id-pkinit-san. + +@example +id-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6) +internet (1) security (5) kerberosv5 (2) 2 @} +@end example + +In the data part of the OtherName is filled with the following DER +encoded ASN.1 structure: + +@example +KRB5PrincipalName ::= SEQUENCE @{ + realm [0] Realm, + principalName [1] PrincipalName +@} +@end example + +where Realm and PrincipalName is defined by Kerberos ASN.1 specification. + +@section Naming certificate using hx509 + +hx509 is the X.509 software used in Heimdal to handle +certificates. hx509 use diffrent syntaxs to specify the diffrent +format the certificate is stored and in what format they exist in. + +There are several format that can be used, PEM, embeded into PKCS12 +files, embeded into PKCS11 devices and raw DER encoded certificates. +Below is a list of types to use. + + +@table @asis + +@item DIR: + +@c Create a directory where all the trusted anchors are stored +@c ca-trusted-anchors and copy all certificate you are going to trust as +@c anchors into that directory. Make sure there are no other files then +@c trust anchors in that directory, if there are, it will not work. In +@c the krb5.conf, this is refear to as DIR:/dir + +Syntax is: + +@example +DIR:/path/to/der/files +@end example + +@item FILE: + +FILE: is used to have the lib pick up a certificate chain and a +private key. + +Syntax is: + +@example +FILE:certificate-file.pem,private-key-file.key,other-cert.pem,.... +@end example + +@item PKCS11: + +PKCS11: is used handle smartcards via PKCS11 drivers +(soft-token,opensc,muscle) files. + +Syntax is: + +@example +PKCS11:shared-object.so:slot=:otherattribute= +@end example + +@item PKCS12: + +PKCS12: is used handle PKCS12 (.pfx/.p12) files. + +Syntax is: + +@example +PKCS12:/path/to/file.pfx +@end example + +@end table + +@section Configuring the kerberos software + +Add configuration options to krb5.conf + +kinit + +kdc + +@section Configuring the client + +@example +[appdefaults] + pkinit-anchors = DIR:/dir-to-client-trusted-ca-hashes +@end example + +@section Configuring the KDC + +@example +[kdc] + enable-pkinit = yes + pki-identity = FILE:/secure/kdc.crt,/secure/kdc.key + pki-anchors = FILE:/path/to/trust-anchors.pem + pki-pool = PKCS12:/path/to/useful-intermediate-certs.pfx + pki-pool = FILE:/path/to/other-useful-intermediate-certs.pem +@end example + +@subsection Using pki-mapping file + +@subsection Using Kerberos database + +@section Use OpenSSL to create certificates + +@subsection Using OpenSSL to create certificate with krb5PrincipalName + +To make OpenSSL create certificate with krb5PrincipalName use the following + +@file{openssl.cnf}. + +@example + +[user_certificate] +subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name + +[princ_name] +realm = EXP:0, GeneralString:MY.REALM +principal_name = EXP:1, SEQUENCE:principal_seq + +[principal_seq] +name_type = EXP:0, INTEGER:1 +name_string = EXP:1, SEQUENCE:principals + +[principals] +princ1 = GeneralString:userid + +@end example + +Command usage + +@example +openssl x509 -extensions user_certificate +@end example + + +@c --- ms certificate +@c +@c [ new_oids ] +@c msCertificateTemplateName = 1.3.6.1.4.1.311.20.2 +@c +@c +@c [ req_smartcard ] +@c keyUsage = digitalSignature, keyEncipherment +@c extendedKeyUsage = msSmartcardLogin, clientAuth +@c msCertificateTemplateName = ASN1:BMP:SmartcardLogon +@c subjectAltName = otherName:msUPN;UTF8:lukeh@dsg.padl.com +@c #subjectAltName = email:copy + +