( Setting up PK-INIT

Info Catalog ( Providing Kerberos credentials to servers and programs ( Setting up a realm
 4.18 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, it
 is time to create it. Note that you should read the whole chapter of
 the document to see the requirements on the CA software.
 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 the SubjectAltName extension of the certificate, or store
 the mapping in the principals entry in the kerberos database.
 4.19 Certificates
 This section documents the requirements on the KDC and client
 certificates and the format used in the id-pkinit-san OtherName
 4.19.1 KDC certificate
 The certificate for the KDC have serveral requirements.
 First the certificate should have an Extended Key Usage (EKU)
 id-pkkdcekuoid ( set. Second there must be a
 subjectAltName otherName using oid id-pkinit-san ( in the
 type field and a 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 it's in the interest of
 minimum amount of configuration on the clients they should be included.
 Remember that if the 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 certificate has a nameConstraints extention with a
 Generalname with dNSName or iPAdress it must match the hostname or
 adress of the KDC.
 4.19.2 Client certificate
 The client certificate may need to have a EKU id-pkekuoid
 ( set depending 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. Using KRB5PrincipalName in id-pkinit-san
 OtherName extention in the GeneralName 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.
      id-pkinit-san OBJECT IDENTIFIER ::= { iso (1) org (3) dod (6)
      internet (1) security (5) kerberosv5 (2) 2 }
 The data part of the OtherName is filled with the following DER encoded
 ASN.1 structure:
      KRB5PrincipalName ::= SEQUENCE {
      	realm [0] Realm,
      	principalName [1] PrincipalName
 where Realm and PrincipalName is defined by the Kerberos ASN.1
 4.20 Naming certificate using hx509
 hx509 is the X.509 software used in Heimdal to handle certificates.
 hx509 uses different syntaxes to specify the different formats the
 certificates are stored in and what formats they exist in.
 There are several formats that can be used, PEM, embedded into PKCS12
 files, embedded into PKCS11 devices and raw DER encoded certificates.
 Below is a list of types to use.
      DIR is reading all certificates in a directory that is DER or PEM
      The main feature of DIR is that the directory is read on demand
      when iterating over certificates, that way applictions can for
      some cases avoid to store all certificates in memory. It's very
      useful for tests that iterate over larger amount of certificates.
      Syntax is:
      FILE: is used to have the lib pick up a certificate chain and a
      private key. The file can be either a PEM (openssl) file or a raw
      DER encoded certificate. If it's a PEM file it can contain several
      keys and certificates and the code will try to match the private
      key and certificate together.
      Its useful to have one PEM file that contains all the trust
      Syntax is:
      PKCS11: is used to handle smartcards via PKCS11 drivers, for
      example soft-token, opensc, or muscle. The default is to use all
      slots on the device/token.
      Syntax is:
      PKCS12: is used to handle PKCS12 files. PKCS12 files commonly have
      the extension pfx or p12.
      Syntax is:
 4.21 Configure the Kerberos software
 First configure the client's trust anchors and what parameters to
 verify, see subsection below how to do that. Now you can use kinit to
 get yourself tickets. One example how that can look like is:
      $ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@EXAMPLE.ORG
      Enter your private key passphrase:
      : lha@nutcracker ; klist
      Credentials cache: FILE:/tmp/krb5cc_19100a
              Principal: lha@EXAMPLE.ORG
        Issued           Expires          Principal
      Apr 20 02:08:08  Apr 20 12:08:08  krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
 Using PKCS11 it can look like this instead:
      $ kinit -C PKCS11:/usr/heimdal/lib/ lha@EXAMPLE.ORG
      PIN code for SoftToken (slot):
      $ klist
      Credentials cache: API:4
              Principal: lha@EXAMPLE.ORG
        Issued           Expires          Principal
      Mar 26 23:40:10  Mar 27 09:40:10  krbtgt/EXAMPLE.ORG@EXAMPLE.ORG
 Write about the kdc.
 4.22 Configure the client
      	pkinit_anchors = FILE:/path/to/trust-anchors.pem
              EXAMPLE.COM = {
      		pkinit_require_eku = true
      		pkinit_require_krbtgt_otherName = true
      		pkinit_win2k = no
      		pkinit_win2k_require_binding = yes
 4.23 Configure the KDC
      	enable-pkinit = yes
      	pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key
      	pkinit_anchors = FILE:/path/to/trust-anchors.pem
      	pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx
      	pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem
      	pkinit_allow_proxy_certificate = false
      	pkinit_win2k_require_binding = yes
 4.23.1 Using pki-mapping file
 Note that the file name is space sensitive.
      # cat /var/heimdal/pki-mapping
      # comments starts with #
      lha@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha
 4.23.2 Using the Kerberos database
 4.24 Use hxtool to create certificates
 4.24.1 Generate certificates
 First you need to generate a CA certificate, change the -subject to
 something appropriate, the CA certificate will be valid for 10 years.
 You need to change -subject in the command below.
      hxtool issue-certificate \
          --self-signed \
          --issue-ca \
          --generate-key=rsa \
          --subject="CN=CA,DC=test,DC=h5l,DC=se" \
          --lifetime=10years \
 The KDC needs to have a certificate, so generate a certificate of the
 type "pkinit-kdc" and set the PK-INIT specifial SubjectAltName to the
 name of the krbtgt of the realm.
 You need to change -subject and -pk-init-principal in the command below.
      hxtool issue-certificate \
          --ca-certificate=FILE:ca.pem \
          --generate-key=rsa \
          --type="pkinit-kdc" \
          --pk-init-principal="krbtgt/TEST.H5L.SE@TEST.H5L.SE" \
          --subject="uid=kdc,DC=test,DC=h5l,DC=se" \
 The users also needs to have a certificate, so generate a certificate
 of the type "pkinit-client". The client doesn't need to have the PK-INIT
 SubjectAltName set, you can have the Subject DN in the ACL file
 (pki-mapping) instead.
 You need to change -subject and -pk-init-principal in the command below.
      hxtool issue-certificate \
          --ca-certificate=FILE:ca.pem \
          --generate-key=rsa \
          --type="pkinit-client" \
          --pk-init-principal="lha@TEST.H5L.SE" \
          --subject="uid=lha,DC=test,DC=h5l,DC=se" \
 4.24.2 Validate the certificate
 hxtool also contains a tool that will validate certificates according to
 rules from the PKIX document. These checks are not complete, but a good
 test to check if you got all of the basic bits right in your
      hxtool validate FILE:user.pem
 4.25 Use OpenSSL to create certificates
 This section tries to give the CA owners hints how to create
 certificates using OpenSSL (or CA software based on OpenSSL).
 4.25.1 Using OpenSSL to create certificates with krb5PrincipalName
 To make OpenSSL create certificates with krb5PrincipalName use
 `openssl.cnf' as described below. To see a complete example of creating
 client and KDC certificates, see the test-data generation script
 `lib/hx509/data/' in the source-tree. The certicates it
 creates are used to test the PK-INIT functionality in
 To use this example you have to use OpenSSL 0.9.8a or later.
      realm = EXP:0, GeneralString:MY.REALM
      principal_name = EXP:1, SEQUENCE:principal_seq
      name_type = EXP:0, INTEGER:1
      name_string = EXP:1, SEQUENCE:principals
      princ1 = GeneralString:userid
 Command usage
      openssl x509 -extensions user_certificate
      openssl ca -extensions user_certificate
 4.26 Using PK-INIT with Windows
 4.26.1 Client configration
 Clients using a Windows KDC with PK-INIT need configuration since
 windows uses pre-standard format and this can't be autodetected.
 The pkinit_win2k_require_binding option requires the reply for the KDC
 to be of the new, secure, type that binds the request to reply. Before
 clients should fake the reply from the KDC. To use this option you have
 to apply a fix from Microsoft.
              MY.MS.REALM = {
                      pkinit_win2k = yes
                      pkinit_win2k_require_binding = no
 4.26.2 Certificates
 The client certificates need to have the extended keyusage "Microsoft
 Smartcardlogin" (openssl have the oid shortname msSmartcardLogin).
 See Microsoft Knowledge Base Article - 281245 "Guidelines for Enabling
 Smart Card Logon with Third-Party Certification Authorities" for a more
 extensive description of how set setup an external CA to it includes
 all information that will make a Windows KDC happy.
 4.26.3 Configure Windows 2000 CA
 To enable Microsoft Smartcardlogin> for certificates in your Windows
 2000 CA, you want to look at Microsoft Knowledge Base Article - 313274
 "HOW TO: Configure a Certification Authority to Issue Smart Card
 Certificates in Windows".
Info Catalog ( Providing Kerberos credentials to servers and programs ( Setting up a realm
automatically generated byinfo2html