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.
This section documents the requirements on the KDC and client certificates and the format used in the id-pkinit-san OtherName extention.
The certificate for the KDC have serveral requirements.
First the certificate should have an 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 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.
The client certificate may need to have a EKU id-pkekuoid (1.3.6.1.5.2.3.4) 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:
[kdc] pkinit_principal_in_certificate = yes
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 specification.
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.
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:
DIR:/path/to/der/files
Its useful to have one PEM file that contains all the trust anchors.
Syntax is:
FILE:certificate.pem,private-key.key,other-cert.pem,....
Syntax is:
PKCS11:shared-object.so
Syntax is:
PKCS12:/path/to/file.pfx
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/hx509.so 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.
[appdefaults] pkinit_anchors = FILE:/path/to/trust-anchors.pem [realms] EXAMPLE.COM = { pkinit_require_eku = true pkinit_require_krbtgt_otherName = true pkinit_win2k = no pkinit_win2k_require_binding = yes }
[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
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 lha@EXAMPLE.ORG:CN=Love,UID=lha
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 \ --certificate="FILE:ca.pem"
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" \ --certificate="FILE:kdc.pem"
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" \ --certificate="FILE:user.pem"
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 certificates.
hxtool validate FILE:user.pem
This section tries to give the CA owners hints how to create certificates using OpenSSL (or CA software based on OpenSSL).
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/gen-req.sh in the source-tree. The certicates it creates are used to test the PK-INIT functionality in tests/kdc/check-kdc.in.
To use this example you have to use OpenSSL 0.9.8a or later.
[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
Command usage
openssl x509 -extensions user_certificate openssl ca -extensions user_certificate
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.
[realms] MY.MS.REALM = { pkinit_win2k = yes pkinit_win2k_require_binding = no }
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.
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”.