Revision as of 13:30, 11 December 2008

General Requirements

• Kerbereos 5
• Time synchronization
  • Kerberos requires client and server system times be synchronized. This can be done manually, or through ntpdate or ntpd.
  • The strictness of can be adjusted by 'clockscew' in /etc/krb5.conf, but there does need to be some time consistency between machines.
• DNS
  • Forward and reverse resolution for all hosts involved in the demonstration
  • simple test: dig -x `dig host.example.com +short` = host.example.com

• Realms: A kerberos 'realm' is necessary.
  • A 'realm' is just a unique text name.
  • The realm usually matches a DNS domain, but this is not required (it can be easier)
  • Realms are usually written in upper case to distinguish them (from DNS domain names).
  • examples on this page will use:
    • DNS: example.com
    • realm: EXAMPLE.COM

Kerberos Server

F9 Kerberos Server Packages

Install the required packages

# yum install krb5-server krb5-libs krb5-devel

Kerberos Configuration

Verify host name is set

You must make sure that you machine has a hostname (not 'localhost.localdomain') and that the localhost (127.0.0.1) line in /etc/hosts does not contain the hostname. This will confuse kerberos. The host name can be set in /etc/sysconfig/network, and should be the full host name (e.g. 'sefos.example.com').

NETWORKING=yes
HOSTNAME=sefos.example.com

The top of /etc/hosts should look something like

# Do not remove the following line, or various programs
# that require network functionality will fail.
127.0.0.1               localhost.localdomain localhost
::1             localhost6.localdomain6 localhost6

Edit /etc/krb5.conf

• The stock version of this file uses the 'EXAMPLE.COM' realm and the 'example.com' domain everywhere. Replace these with the desired realm and domain names for the configured network.
• The four sections that require changes are libdefaults, realms, domain_realm, and appdefaults. The other sections do not need to be changed.
  • libdefaults section
    • Change EXAMPLE.COM to the local kerberos realm name.
    • Clock skew can be adjusted here
  • realms section
    • Contains the settings for each realm. Change the realm and domain name to the local names
    • Make sure that the default_domain value gets mapped to a realm in the domain_realm section below.
    • Put the correct fully qualified domain name of the KDC and Kerberos admin server (this may be the same machine).
    • Note There should be a 'kdc' line for each Kerberos Domain Controller. While this example has only one KDC, most networks should have at least two.
  • domain_realm section
    • This is the mapping between the DNS domains and your Kerberos realm.
    • If you are serving multiple DNS domains, put them all here.
    • At a minimum, the default_domain should be mapped to a realm here.
  • appdefaults section
    • You may want to tweak the application defaults
      • For example, changing the renew lifetime.

/etc/krb5.conf:

[libdefaults]
 default_realm = EXAMPLE.COM
 dns_lookup_realm = false
 dns_lookup_kdc = false
 clockskew = 120

[realms]
 EXAMPLE.COM = {
  kdc = sefos.example.com:88
  admin_server = sefos.example.com:749
  default_domain = example.com
 }

[domain_realm]
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM
deeperdomain.example.com = EXAMPLE.COM
.deeperdomain.example.com = EXAMPLE.COM

[appdefaults]
 pam = {
   debug = false
   ticket_lifetime = 36000
   renew_lifetime = 36000
   forwardable = true
   krb4_convert = false
 }
 kinit = {
   ticket_lifetime = 36000
   renew_lifetime = 36000
   forwardable = true
 }

/var/kerberos/krb5kdc/kdc.conf

Only the realms section needs to be configured in this file. Most of the defaults should just work.

• change the realm to the correct value: ' EXAMPLE.COM = {'
• possibly add/adjust max_life. This is the maximum life of a ticket issued by the KDC (absolute max is 25 hours).
• possibly add/adjust max_renewable_life. This is the maximum length a ticket can be renewed (absolute max is 4 weeks).

[realms]
 EXAMPLE.COM = {
  master_key_type = des3-hmac-sha1
  acl_file = /var/kerberos/krb5kdc/kadm5.acl
  dict_file = /usr/share/dict/words
  admin_keytab = /var/kerberos/krb5kdc/kadm5.keytab
  supported_enctypes = des3-hmac-sha1:normal arcfour-hmac:normal des-hmac-sha1:normal des-cbc-md5:normal des-cbc-crc:normal des-cbc-crc:v4 des-cbc-crc:afs3
  max_life=10h
  max_renewable_life = 1w
 }

/var/kerberos/krb5kdc/kadm5.acl

This is a short file. Change the configuration in this file to the correct realm: EXAMPLE.COM in this example.

*/admin@EXAMPLE.COM *

64 bit servers

• on 64 bit servers that function as clients see: 64 bit machines

Kereberos Database

Create the Database

# kdb5_util create -s

This will prompt you for a password.

• This password will likely only be used again when initially configuring a slave KDC.

Add the first Administrative User

• 'root' doesn't have to be an admin, any other name will work.
• The default realm (e.g. EXAMPLE.COM) is appended automatically.
• It will ask for a password.

 [root@sefos ~] kadmin.local -q "addprinc root/admin"

Starting Kereberos

Start the services:

# run_init service kadmin start 
# run_init service krb5kdc start

Test

• run kadmin.
• default principle is the current user appended with ‘/admin’
• Additional principles in the list were added by the software as part of the creation process.

# kadmin
Authenticating as principal root/admin@EXAMPLE.COM with password.
Password for root/admin@EXAMPLE.COM: 
kadmin:  listprincs
K/M@EXAMPLE.COM
kadmin/admin@EXAMPLE.COM
kadmin/changepw@EXAMPLE.COM
kadmin/history@EXAMPLE.COM
krbtgt/EXAMPLE.COM@EXAMPLE.COM
root/admin@EXAMPLE.COM

Note: If any principle in the test lines above includes 'localhost.localdomain', then the /etc/hosts file needs to be checked on the machine (XXX is this server or client or both). Make sure there are no hostnames on the localhost.localdomain line in /etc/hosts.

Create a Host Principal for the KDC

• This is required for replication (see below).
• You also need to add this principal to the local key table.
• This may not be needed for non-replicated setups, but in general, a non-demo setup should have one ore more replicated KDC's.

  [root@sefos ~]# kadmin
  Authenticating as principal root/admin@EXAMPLE.COM with password.
  Password for root/admin@EXAMPLE.COM:
  kadmin: addprinc -randkey host/sefos.example.com
  NOTICE: no policy specified for host/sefos.example.com@EXAMPLE.COM; assigning "default"
  Principal "host/sefos.example.com@EXAMPLE.COM" created.
  kadmin: ktadd host/sefos.example.com

Setup the Default Policy

• All new accounts will have this policy enforced.

# kadmin
Authenticating as principal root/admin@EXAMPLE.COM with password.
Password for root/admin@EXAMPLE.COM: 
kadmin: add_policy -maxlife 180days -minlife 2days -minlength 8 -minclasses 3 -history 10 default

You can also add other policies and apply different policies to different principles. The different flags and their meaning are as follows. Flag Description

• -maxlife The is the maximum period before the password must be changed.
• -minlife This is the minimum time after a password change before it can be changed again. Without a minimum time, users can change their password multiple times and overflow the history (see below) and end up back with the same password.
• -minclasses This is the number of distinct character classes that must appear in the password. Character classes are uppercase letters, lowercase letters, number and symbols. Setting this to 2 for example would mean a password with at least one lowercase letter and a number would be valid.

-history This is the number of previous passwords to keep. A password may not duplicate a prior password.

Changing the Maximum Renewal Time

• Each principal has its own maximum renewal life.
• Each principal must be manually changed from the default to the desired maximum renewal time.
• In addition, the special principal krbtgt/REALM@REALM must be changed to reflect the maximum renewal time that any principal will have.

# kadmin
Authenticating as principal root/admin@EXAMPLE.COM with password.
Password for root/admin@EXAMPLE.COM: 
kadmin:  modprinc -maxrenewlife 2weeks krbtgt/EXAMPLE.COM@EXAMPLE.COM
Principal "krbtgt/EXAMPLE.COM@EXAMPLE.COM" modified.

• when Adding Principals:

# kadmin
Authenticating as principal root/admin@EXAMPLE.COM with password.
Password for root/admin@EXAMPLE.COM: 
kadmin: add_princ -maxrenewlife 7days doug

Firewalls

If there is a firewall on the server, the following default ports should be allowed through to enable Kerberos.

Ports:

• 88 UDP/TCP
• 749 UDP/TCP
• 754 TCP

The following lines should be added to /etc/sysconfig/iptables before the INPUT REJECT rule:

# kerberos kdc/admin
-A INPUT -m tcp -p tcp --dport 88 -j ACCEPT
-A INPUT -m udp -p udp --dport 88 -j ACCEPT
-A INPUT -m tcp -p tcp --dport 749 -j ACCEPT
-A INPUT -m udp -p udp --dport 749 -j ACCEPT
-A INPUT -m tcp -p tcp --dport 754 -j ACCEPT

Then iptables should be restarted:

# service iptables restart

Restart Kereberos

At this point it is necessary to restart the Kerberos services to take advantage of the firewall changes.

 # run_init service kadmin restart 
 # run_init service krb5kdc restart

Enable Start at Boot

Enable the kerberos services to be started after a reboot:

 # chkconfig kadmin on
 # chkconfig krb5kdc on

Kerberos Client

F9 Kerberos Client Packages

# yum install krb5-workstation krb5-libs pam_krb5 cyrus-sasl-gssapi krb5-auth-dialog

Note: on 64 bit processors, must make sure you get the 64 bit version of cyrus-sasl-gssapi.

Copy Files

Copy the following files from the KDC server.

• /etc/krb5.conf

64 bit machines

For Kerberos clients on 64 bit machines the /etc/gssapi_mech.conf file may need to be edited. This file may specify the lib path instead of the lib64 path. This should be corrected.

• Note: untested on current software versions as there is not access to a 64 bit machine. It is quite possibly fixed.

Create Kerberos Principals

Run kadmin on the client.

• Create the client host's principal key.
  • This will add the client host's principal key to the Kerberos server.
  • Replace client.example.com with the fully qualified name of the client machine.
• Add the new host principal key to the clients local keytab file.

# kadmin
Authenticating as principal root/admin@server.example.com with password.
Password for root/admin@server.example.com
kadmin: addprinc -randkey host/seclient.example.com
kadmin: ktadd host/seclient.example.com
kadmin: quit

Note: the following error message can indicate a time syncing issue. If you see this error, the server and client clocks may need to be synchronized.

 kadmin: GSS-API (or Kerberos) error while initializing kadmin interface

Test

Check to see that the client host's principal keys exist on the client machine.

  # klist -k /etc/krb5.keytab
  Keytab name: FILE:/etc/krb5.keytab
  KVNO Principal
  --------------------------------------------------------------------------
    5 host/seclient.example.com@EXAMPLE.COM
    5 host/seclient.example.com@EXAMPLE.COM
    5 host/seclient.example.com@EXAMPLE.COM
    5 host/seclient.example.com@EXAMPLE.COM

Note: The KVNO value will vary and may not match '5' above.

Kerberos References

• Kerberos: The Network Authentication Protocol Kerberos: Home Page
• The Kerberos Network Authentication Service (V5), RFC 4120
• The Kerberos Version 5 Generic Security Service Application Program Interface (GSS-API) Mechanism: Version 2, RFC 4121
• The Kerberos V5 ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism, RFC 4752