Next: , Previous: Providing Kerberos credentials to servers and programs, Up: Setting up a realm

4.18 Setting up PK-INIT

PK-INIT leverages an existing PKI (public key infrastructure), using certificates to get the initial ticket (usually the krbtgt ticket-granting ticket).

To use PK-INIT you must first have a PKI. If you don't have one, it is time to create it. You should first read the whole chapter of the document to see the requirements imposed on the CA software.

A mapping between the PKI certificate and what principals that certificate is allowed to use must exist. There are several ways to do this. The administrator can use a configuration file, store 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 extention.

4.19.1 KDC certificate

The certificate for the KDC has 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. 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.

The client is not required by the standard to check the server certificate for this information if the client has external information confirming which certificate the KDC is supposed to be using. However, adding this information to the KDC certificate removes the need to specially configure the client to recognize the KDC certificate.

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 a password or other private information) that it is supposed to keep secret.

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.

This behavior is controlled by KDC configuration option:

     	pkinit_principal_in_certificate = yes Using KRB5PrincipalName in id-pkinit-san

The OtherName extention in the GeneralName is used to do the mapping between certificate and principal. For the KDC certificate, this stores the krbtgt principal name for that KDC. For the client certificate, this stores the principal for which that certificate is allowed to get tickets.

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 specification.

4.20 Naming certificate using hx509

hx509 is the X.509 software used in Heimdal to handle certificates. hx509 supports several different syntaxes for specifying certificate files or formats. Several formats may be used: PEM, certificates embedded in PKCS#12 files, certificates embedded in PKCS#11 devices, and raw DER encoded certificates.

Those formats may be specified as follows:

DIR specifies a directory which contains certificates in the DER or PEM format.

The main feature of DIR is that the directory is read on demand when iterating over certificates. This allows applications, in some situations, to avoid having to store all certificates in memory. It's very useful for tests that iterate over large numbers of certificates.

The syntax is:


FILE: specifies a file that contains a certificate or 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. Multiple files may be specified, separated by commas.

It's useful to have one PEM file that contains all the trust anchors.

The syntax is:


PKCS11: is used to handle smartcards via PKCS#11 drivers, such as soft-token, opensc, or muscle. The argument specifies a shared object that implements the PKCS#11 API. The default is to use all slots on the device/token.

The syntax is:


PKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have the extension pfx or p12.

The syntax is:


4.21 Configure the Kerberos software

First configure the client's trust anchors and what parameters to verify. See the subsections below for how to do that. Then, you can use kinit to get yourself tickets. For example:

     $ 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 PKCS#11 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

TODO: 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 = no
     	pkinit_win2k_require_binding = yes
     	pkinit_principal_in_certificate = no

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. This example creates a CA certificate that will be valid for 10 years.

You need to change –subject in the command below to something appropriate for your site.

     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 to something appropriate for your site.

     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 certificates. For your first client, generate a certificate of 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 to something appropriate for your site. You can omit –pk-init-principal if you're going to use the ACL file instead.

     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 they provide a good test of whether you got all of the basic bits right in your certificates.

     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 an 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 tests/kdc/

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 could 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 has 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 so that it includes all the information required to 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”.