KerbNet Windows Installation Guide

Copyright © 1993, 1994, 1995, 1996, 1997 Cygnus Solutions.

KerbNet includes software and documentation developed at the Massachusetts Institute of Technology, which includes this copyright information:

Copyright © 1995, 1997 by the Massachusetts Institute of Technology.

Export of software employing encryption from the United States of America is assumed to require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.

WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.


KerbNet includes software and documentation developed by OpenVision Technologies, Inc., which includes this copyright notice:

The following copyright and permission notice applies to the OpenVision Kerberos Administration system located in kadmin/create, kadmin/dbutil, kadmin/server, lib/kadm, and portions of lib/rpc:

Copyright, OpenVision Technologies, Inc., 1996, All Rights Reserved WARNING: Retrieving the OpenVision Kerberos Administration system source code, as described below, indicates your acceptance of the following terms. If you do not agree to the following terms, do not retrieve the OpenVision Kerberos administration system. You may freely use and distribute the Source Code and Object Code compiled from it, but this Source Code is provided to you "AS IS" EXCLUSIVE OF ANY WARRANTY, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR ANY OTHER WARRANTY, WHETHER EXPRESS OR IMPLIED. IN NO EVENT WILL OPENVISION HAVE ANY LIABILITY FOR ANY LOST PROFITS, LOSS OF DATA OR COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, INCLUDING, WITHOUT LIMITATION, THOSE RESULTING FROM THE USE OF THE SOURCE CODE, OR THE FAILURE OF THE SOURCE CODE TO PERFORM, OR FOR ANY OTHER REASON.

OpenVision retains all rights, title, and interest in the donated Source Code. With respect to OpenVision's copyrights in the donated Source Code, OpenVision also retains rights to derivative works of the Source Code whether created by OpenVision or a third party. OpenVision Technologies, Inc. has donated this Kerberos Administration system to MIT for inclusion in the standard Kerberos 5 distribution. This donation underscores our commitment to continuing Kerberos technology development and our gratitude for the valuable work which has been performed by MIT and the Kerberos community.


KerbNet includes software and documentation developed at the University of California at Berkeley, which includes this copyright notice:

Copyright © 1983 Regents of the University of California.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. All advertising materials mentioning features or use of this software must display the following acknowledgement:
    This product includes software developed by the University of California, Berkeley and its contributors.
  4. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.


Permission is granted to make and distribute verbatim copies of this manual provided the copyright notices and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

Introduction

With this release, KerbNet can run on Windows NT as well as UNIX. Windows NT servers can be used as Key Distribution Centers (KDCs), both as master and slaves. Windows NT servers can be integrated into an existing Kerberos 5 network, and can synchronise principal databases with UNIX servers. In addition, a special service, PasswordSync, may be run on a Windows NT Primary Domain Controller to synchronise Windows 95 and Windows NT Domain password changes with a Kerberos principal password database.

You should NOT install the KerbNet authentication system on a Windows NT system filesystem using the FAT format filesystem. Such a filesystem has no security and is not supported. Install the KerbNet application only on an NTFS filesystem.

KerbNet Directories

When you install the KerbNet software on an NT system, the install program puts the KerbNet files in the directory C:\CYGNUS\KERBNET. This directory has the following subdirectories:

\ETC
Configuration files that may be read by all users. The main files are krb5.conf and kdc.conf.

\BIN
Standard KerbNet utilities such as kinit and kdestroy.

\LIB
Cygwin32 format library files used for creating your own programs.

\KRB5KDC
Private directory used to store principal databases, access control lists, keytabs and other sensitive data. This must be readable only by the Administrators group and the SYSTEM user.

\SBIN
Server utilities. KerbNet system services are stored here.

\LOG
Log files for the KerbNet system services are stored here. This should be readable only by the Administrators group and the SYSTEM user.

\CCACHE
Credentials cache. This directory stores the cached credentials for currently logged on users. It must have special permissions set to prevent users from reading each others credential files. These are "Administrators: Full Access", "SYSTEM: Full Access", "Creator Owner: Full Access".

Using This Manual

In this manual, we will represent your command line prompt as "shell%". So an instruction to type the "ls" command would be represented as follows:

shell% ls

When a line of sample text is supposed to be continuous, but is too long to fit on a single line in this manual, we will indicate the continuation of the line with the symbol => . So, for example, if we ask you to type:


kadmin.local: ktadd -k WRFILE:C:\CYGNUS\KERBNET\LIB\KRB5KDC\KADM5.KEYTAB
=> kadmin/admin kadmin/changepw

you should type the entire text on the same line and then hit Return.

In the rest of this manual, it is assumed that you have logged onto your Windows NT server as the user Administrator. You must use Administrator privillages to install the KerbNet product.

Loading the KerbNet Software

You must install the KerbNet software onto any NT machine that you want to server as a KerbNet Key Distribution Center, Application Server, Development machine or Client.

To install the software:

  1. Click on the SETUP.EXE icon displayed in the folder of the first installation disk.

    The InstallSheild installation process begins.

  2. When InstalllSheild asks where you want to install the software, select the default option or choose another location.

  3. InstallSheild offers you three choices of installation type. Typical andCompact are identical; select these choices only if you intend to install cliens but not KDCs or application servers. If you want to install KerbNet servers or development libraries, choose the Custom install option.

  4. The Custom installation offers you a list of items to install. By default all are selected. The client files and the sample files make up a client only installation. The "Server Binaries" allow you to make the machine a KDC or KerbNet server and "Libraries and Headers" are what is necessary for a development installation. Deselect either "Server Binaries" or "Libraries and Headers" to save space as appropriate.

  5. Choose a folder. Again you may use the default or enter your own choice.

  6. Confirm your choices.

    InstallSheild installs the KerbNet software. You can now set up your machine to use KerbNet authentication.

  7. Check the Clock and Time Zone.

    Make sure the clock and time zone are set correctly, and that the time is within the maximum clock skew of the KDC. The default maximum clock skew is five minutes. You may need to have the TZ variable set automatically at boot time to get the time zone information passed to correctly.

Installing a Windows NT server as a Master KDC.

Realm and Host Names

First choose a name for your Kerberos realm. A realm's name is often the name of the corresponding Internet domain. By convention, realm names are usually written in UPPER CASE letters.

To determine your Internet domain name:

  1. Open the Network applet in the Control Panel and examine the DNS properties on your TCP/IP protocol.

    The Internet domain name is in the Domain field and will be something like `mydomain.com'.

You also need to know the TCP/IP hostname of your NT server:

  1. Look at the Host Name field in the same dialog you used to determine the Internet domain name.

    For the purposes of the following examples we will call this name `myhost'.

In the following examples, replace `MYREALM.COM' with your Internet domain name capitalized and `myrealm.com' with your Internet domain name in lower case.

Editing the Configuration Files

The KerbNet configuration files contain information that the KDC needs to run successfully. Before you set up a KDC, you need to edit the configuration files.

  1. Edit the file C:\CYGNUS\KERBNET\ETC\KRB5.CONF using NOTEPAD or a similar text editor. Replace all occurences of the string `SAMPLE.REALM.COM' with `MYREALM.COM', and all occurences of the string `sample.realm.com' with `myrealm.com'.

  2. In the [realms] section of the file, replace the entries

    
    	kdc = host.sample.realm.com
    	admin_server = host.sample.realm.com
    
    

    with

    
    	kdc = myhost.myrealm.com
    	admin_server = myhost.myrealm.com
    
    

  3. Next, edit the file C:\CYGNUS\KERBNET\ETC\KDC.CONF. Replace all occurences of the string `SAMPLE.REALM.COM' with `MYREALM.COM', and all occurences of the string `sample.realm.com' with `myrealm.com'.

  4. If you have changed the default location where KerbNet is installed, you need to change all occurences of the string `C:\CYGNUS' in both of these files to `<your base location>' where <your base location> is the directory into which you have installed KerbNet.

The other lines in the KerbNet configuration files are acceptable defaults to start a KDC with. Once you have read and understood all the other KerbNet documentation then you may customize the configuration files for your site.

If you installed KerbNet in a location other than C:\CYGNUS then you must now set two environment variables in the command prompt to enable the KerbNet binaries to find the configuration files.

  1. Start an MS-DOS command prompt.

  2. Type:

    
    set KRB5_CONFIG=<your base location>\KERBNET\ETC\KRB5.CONF 
    set KRB5_KDC_PRFILE=<your base location>\KERBNET\ETC\KDC.CONF
    
    

    replacing <your base location> with the directory into which you have installed KerbNet.

Creating the Principal Database

Now you need to create the initial principal database and the stash file that allows the KDC to read the database when it starts automatically. The principal database and stash file are the heart of the Kerberos security system, so you must place them in a directory with no access to non-system users. By default this directory is C:\CYGNUS\KERBNET\LIB\KRB5KDC which, as noted above, has permissions only for the Administrators group and the SYSTEM user.

  1. From inside the C:\CYGNUS\KERBNET\SBIN directory, type the following command:

    
    shell% kdb5_util create -r MYREALM.COM -s
    
    

  2. Enter a password at the prompt that asks for the database master key. Re-enter the same password at the second prompt.

The key you type here will be used to secure your entire Kerberos principal database, so it is important to pick a good one. A good key is one that you can remember, but that no one else can guess.

Examples of bad keys are words that can be found in a dictionary, any common or popular name, especially a famous person (or cartoon character), your username in any form (e.g., forward, backward, repeated twice, etc.), and any of the sample keys that appear in this manual. One example of a key which would be good if it did not appear in this manual is "CSiys4K5!", which represents the sentence "Cygnus Solutions is your source for Kerberos 5!" (It's the first letter of each word, substituting the numeral "4" for the word "for", and includes the punctuation mark at the end.)

This procedure creates five Kerberos database-related files in the directory C:\CYGNUS\KERBNET\LIB\KRB5KDC (or the directory you specified in your kdc.conf file):

principal.db
the Kerberos principal database itself

principal.ok
the database check file

principal.kadm5
the Kerberos administrative database file

principal.kadm5.lock
the administrative database lock file

.k5.MYREALM.COM
the stash file (where MYREALM.COM is the name of your Kerberos realm).

Controlling Access to Your Principal Database

The actions that principals can take when administering the principal database are controlled by an Access Control List (acl) file. By default, the acl file is stored in C:\CYGNUS\KERBNET\LIB\KRB5KDC\KADM5.ACL.

A sample acl file is created during KerbNet installation. This sample file allows any principal with the instance "admin" to have full permissions in administering the principal database. To use the sample file as your acl file, you must change the realm in the acl file to the name of your Kerberos realm.

  1. Open the file C:\CYGNUS\KERBNET\LIB\KRB5KDC\KADM5.ACL with NOTEPAD or a similar text editor.

  2. Change the line:

    
    */admin@SAMPLE.COM     *
    
    

    to read:

    
    */admin@MYREALM.COM     *
    
    

If you wish to set up more sophisticated access control for your principal database, consult the "Administrative Privileges" section of theKerbNet System Administrator's Guide on the format of the KADM5.ACL file.

Adding the Administrative User to the Principal Database

Before you can start the Kerberos KDC service, you need to add a principal who can administrate the database and who has permission to add other users. By convention this principal has the name "admin/admin". As the Kerberos KDC service is not yet running, a utility that can act directly on the principal database files is used. This utility is C:\CYGNUS\KERBNET\SBIN\KADMIN.LOCAL.EXE.

To create the admin/admin principal:

  1. Run kadmin.local.

  2. At the kadmin.local prompt, type:

    
    kadmin.local: addprinc admin/admin@MYREALM.COM 
    
    

    kadmin.local prompts you for the password for the principal admin/admin.

  3. Type a password in and press ENTER. Type the password again when kadmin.local asks you to confirm the password.

    Remember the rules about easy to guess passwords and attempt to pick a secure password.

Leave kadmind.local.exe running, for use in the next operation.

Creating the KAdmin Service Keytab

The KAdmin service must have a Kerberos key to decrypt users' Kerberos tickets to determine if they should be allowed access to the principal database. Since KAdmin is a service program and runs automatically at Windows NT startup, it must have its key stored for it on disk in a keytab. The keytab should be stored in a secure directory, since anyone who can read this file can impersonate the KAdmin service). The default path for the keytab is C:\CYGNUS\KERBNET\LIB\KRB5KDC\KADM5.KEYTAB.

This file should contain the keys for two principals, kadmin/admin and kadmin/changepw.

To create the keytab:

  1. With kadmin.local.exe running, type:

    
    kadmin.local: ktadd -k WRFILE:C:\CYGNUS\KERBNET\LIB\KRB5KDC\KADM5.KEYTAB
    => kadmin/admin kadmin/changepw
    
    

    The arguement after the -k specifies the type of file to create (WRFILE: means writable keytab file) followed by the filename.

  2. To exit from kadmin.local type:

    
    kadmin.local: quit 
    
    

Installing and Starting the KDC Service and the KAdmin Service

You are now ready to install and start the KerbNet KDC service, which is the ticket issuing service that is the heart of the Kerberos system, and the KAdmin service, which allows administrators to modify the principal database (add new users, change passwords, etc.).

  1. In the C:\CYGNUS\KERBNET\SBIN directory type:

    
    krb5kdc /install
    
    

  2. Next, type:

    
    kadmind /install
    
    

The KerbNet KDC service and the KerbNet KAdmin service create the required registry keys automatically. For a full list of the registry entries used by KerbNet and their significance, see section Registry Keys and Values used by KerbNet Server in this document.

The KerbNet KDC service and the KerbNet KAdmin service are set up to start automatically when your Windows NT Server restarts.

To start them now:

  1. Open the Services applet from the Control Panel and click on the line of text titled KerbnetKDC in the Service scrolling list.

  2. Click the Start button.

    After a few seconds the "status" entry for KerbnetKDC should change from blank to "Started".

  3. Click on the line of text titled KerbnetKAdmin in the Service scrolling list.

  4. Click on the start button.

    After a few seconds, the "status" entry for KerbnetKAdmin should change from blank to "Started".

To start the services from the command line instead of the Control Panel:

  1. At the DOS command prompt, type:

    
    net start KerbnetKDC 
    net start KerbnetKAdmin
    
    

    A message appears after each line, informing you that the named service is being started.

If you get an error message with either of these procedures see section Troubleshooting KerbNet on Windows NT at the end of this manual.

To test that you have succesfully installed your master KerbNet KDC and the KAdmin service correctly:

  1. Type the following command:

    
    shell% kadmin -p admin/admin
    
    

  2. At the password prompt, type the password you entered when you created the admin/admin principal (in section Adding the Administrative User to the Principal Database).

  3. At the kadmin: prompt, type:

    
    kadmin: getprincs
    
    

    kadmin should respond with a list of the current principals in the database. A sample list might look like this:

    
    K/M@MYREALM.COM 
    admin/admin@MYREALM.COM 
    kadmin/admin@MYREALM.COM
    kadmin/changepw@MYREALM.COM 
    kadmin/history@MYREALM.COM
    krbtgt/MYREALM.COM@MYREALM.COM
    
    

  4. Exit kadmin by typing:

    
    kadmin: exit
    
    

Congratulations - you have set up your KerbNet master KDC!

Installing Slave KerbNet KDC hosts

KerbNet allows you to replicate the principal databases to other hosts, to allow redundency in your valuable database, and also to spread the network load of issuing Kerberos tickets to several machines across a network. This is especially useful if your Kerberos realm consists of several sites separated by a wide area network. Kerberos realms may be thought of as very similar to Windows NT 3.x and 4.x domains, so the same planning in siting domain controllers should be used in siting KerbNet slave KDC machines. Indeed, if you already have backup domain controllers in your Windows NT domain, then you might consider placing slave KDC servers on these machines.

A slave KDC runs the KerbNet KDC service, to issue tickets to users, but does not run the KerbNet KAdmind service, as all updates to a principal database are done to the master KDC. Instead, slave KDCs run a service called KPropd (which stands for Kerberos Propagation service). This service receives replica copies of the principal database from the master KDC. These copies of the database are encrypted in transit and the replication mechanism is protected by the issuing of Kerberos tickets.

Since KerbNet runs identically on Windows NT and UNIX, you may decide to have your master KDC on either UNIX or Windows NT, and slave KDCs may be hosted on either UNIX or Windows NT. For information on setting up slave KDCs on a UNIX machine, consult the KerbNet UNIX Installation Guide.

Setting Up the KerbNet Software on a Windows NT Slave Host

To set up a machine as a slave KDC host, you must have administrative permissions on the slave host machine.

  1. Log onto your slave Windows NT machine as Administrator.

  2. Install the KerbNet software onto the slave machine.

    The KerbNet software should have the same directory structure and permissions on directories on this machine as it does onthe master KDC machine. As in the master KDC case, the following procedure will be easier if the KerbNet directory is installed into its default directory, C:\CYGNUS.

  3. Using NOTEPAD, edit the files C:\CYGNUS\KERBNET\ETC\KRB5.CONF and C:\CYGNUS\KERBNET\ETC\KDC.CONF so that they are identical to the KRB5.CONF and KDC.CONF file on the master KDC host. Alternatively, just copy over the files from the master KDC.

Now you need to create a principal in the master Kerberos database for this host. This principal is used to secure the transfer of the master principal database. The name of this principal is host/<machinename>.mydomain.com, where <machinename> is the Internet host name of this slave KDC machine, and mydomain.com is the Internet domain name of this slave KDC machine. You can determine the domain and host names using the method described in section Realm and Host Names.

  1. Change into the C:\CYGNUS\KERBNET\SBIN directory and run the command KADMIN.EXE by typing:

    
    shell% kadmin -p admin/admin.
    
    

    You will be prompted for the master administrator password.

  2. Type the password.

    If you typed the correct password you will get a kadmin: prompt.

  3. To create the principal for this host machine, type the command

    
    kadmin: addprinc -randkey host/machinename.mydomain.com
    
    

    where machinename is the Internet host name of this machine, and mydomain.com is the Internet domain name of this machine, as described above.

    The -randkey argument to the command causes kadmin to generate a password for this principal randomly, instead of asking you to provide one. Because the password is stored in a keytab, to which the KDC has direct access, no one needs to know the password.

Now you need to write out the keytab for the principal you have just created. Make sure you store the keytab in a secure place, since anyone gaining access to this file could impersonate the KPropd service and gain a copy of the Kerberos principal database. The default place to store this is in the file C:\CYGNUS\KERBNET\LIB\KRB5KDC\V5SRVTAB, which is secure.

  1. To write out the keytab, type the command:

    
    kadmin: ktadd host/machinename.mydomain.com
    
    

    If you wish to store the keytab in a different place, type:

    
    kadmin: ktadd -k WRFILE:<Path to keytab file> host/machinename
    => .mydomain.com
    
    

    instead.

  2. You may now quit kadmin by typing:

    
    kadmin: quit
    
    

You now need to create an acl file so the the KPropd service can decide who is authorized to send database updates to it. The acl file is called C:\CYGNUS\KERBNET\LIB\KRB5KDC\KPROPD.ACL.

  1. Using NOTEPAD or a similar text editor, open this file and change the line:

    
    host/hostname.sample.com@SAMPLE.COM
    
    

    to:

    
    host/<Internet name of Master KDC>.<Internet domain of 
    =>    MasterKDC>@MYREALM.COM
    
    

    where <Internet name of master KDC> is the Internet hostname of the machine you installed as the master KDC, <Internet domain of Master KDC> is its Internet domain name and MYREALM.COM is the name of your Kerberos realm.

Finally, you need to install the KPropd service on your slave KDC.

  1. To do this, change to the directory C:\CYGNUS\KERBNET\SBIN and type the command:

    
    shell% kpropd /install
    
    

  2. Start the service by typing:

    
    shell% net start KerbnetKPropd
    
    

    or by using the Services applet in the Windows NT control panel as described above in section Installing and Starting the KDC Service and the KAdmin Service.

At this point everything is ready for the master KDC to transfer the principal database to you new slave KDC. Go back to the master KDC before continuing.

Transferring the Principal Database From Master to Slave KDC

Adding a Host Principal

On the master KDC, log on as user Administrator. In order to transfer the principal database from the master KDC to the slave KDC the program that does the transfer (kprop.exe) needs a Kerberos principal to identify it to the receiving KerbnetKPropd service. This principal must match the one you entered in the KPROPD.ACL file in the last section; if you entered something other than host/<master KDC internet name>.<master KDC internet domain> there, make sure you use the same name now.

To create this principal:

  1. Start an MS-DOS command line.

  2. From inside the directory C:\CYGNUS\KERBNET\SBIN, type:

    
    shell% kadmin -p admin/admin
    
    

  3. Type your Kerberos admin password at the prompt and hit ENTER.

  4. Now type:

    
    kadmin: addprinc -randkey host/<master KDC internet name>.<master KDC internet domain>
    
    

In order for the propagation program (kprop) to run unattended to synchronize principal databases on a periodic basis, the password for this principal must be stored in a keytab file. By default this file is C:\CYGNUS\KERBNET\LIB\KRB5KDC\V5SRVTAB. As this is in the secure directory, it is safe.

  1. To store the password for the principal you just created in this file, type:

    
    kadmin: ktadd host/<master KDC internet name>.<master KDC internet domain>
    
    

    kadmin responds with:

    
    Entry for principal host/<master KDC internet name>.<master KDC internet
    domain> with kvno <#>, encryption type DES-CBC-CRC added to keytab
    WRFILE:c:\cygnus\KERBNET\lib\krb5kdc\v5srvtab.
    
    

Testing Database Propagation

You are now ready to test the propagation of the master KDC principal database to the slave KDC. Usually, a script will perform propagation automatically. However, by propagating the database manually now, you can make sure that everything is working correctly, while getting the database onto your slave KDCs right away.

Each slave KDC must have the database before you start the KDC service on the slave. If you are setting up more than one slave KDC, you can manually propagate the database to each one, or you can manually propagate the database onto one slave and then use automatic propagation (see section Automating Database Propagation) to get the database onto the others.

  1. Dump the principal database into a text file format suitable for transmission. To do so, switch to the C:\CYGNUS\KERBNET\SBIN directory, and type:

    
    shell% kdb5_util dump c:\cygnus\KERBNET\lib\krb5kdc\dbdump
    
    

    This command writes the text form of the master principal database into the file C:\CYGNUS\KERBNET\LIB\KRB5KDC\DBDUMP.

  2. To transfer the database dump to your slave kdc, type:

    
    shell% kprop -f c:\cygnus\KERBNET\lib\krb5kdc\dbdump <slave>
    
    

    where <slave> is the Internet host name of your slave KDC.

  3. If you are propagating the database to more than one slave KDC, repeat step 6 for each slave.

    At this point the database principal file has been successfully propagated to the slave KDC machine, and has been loaded into internal format. The copy of the principal database is loaded by default on the slave KDC machine into the secure directory as the files:

    C:\CYGNUS\KERBNET\LIB\KRB5KDC\PRINCIPAL.DB
    C:\CYGNUS\KERBNET\LIB\KRB5KDC\PRINCIPAL.OK
    C:\CYGNUS\KERBNET\LIB\KRB5KDC\PRINCIPAL.KADM5
    C:\CYGNUS\KERBNET\LIB\KRB5KDC\PRINCIPAL.KADM5.LOCK
    

  4. For security, delete the text based dump file on the master KDC you used as a temporary file in order to propagate to the slave. To do so, type the command:

    shell% DEL C:\CYGNUS\KERBNET\LIB\KRB5KDC\DMDUMP

The temporary file that contains the text based dump of the principal database remains on the slave as the file C:\CYGNUS\KerbNet\LIB\KRB5KDC\FROM_MASTER. However, since this file is in a secure directory, its existance isn't a security risk like the existance of the copy on the master KDC.

Starting the Slave KDC Service.

Once each slave machine has a copy of the database, you can set them up to run as KDCs. The following procedure describes how to set up a single slave KDC.

  1. Log on to the slave KDC machine as Administrator.

    You need to create a stash file containing the principal database master key. This allows the slave KerbNet KDC service to decrypt and access the principal database you have just propagated to this machine.

  2. Change to the directory CYGNUS\KERBNET\SBIN, and type:

    
    kdb5_util stash
    
    

    kdb5_util prompts you for the master database key.

  3. Enter the master database key.

    The master key you type in must be the same as the master key you used when you originally created the principal database on the master KDC machine.

    kdb5_util creates the master key stash file within the secure directory in the file C:\CYGNUS\KERBNET\LIB\KRB5KDC\.K5.MYREALM.COM, where MYREALM.COM is your realm name.

  4. Install and start the KerbnetKDC service on the slave KDC machine, by running the command:

    
    krb5kdc /install
    
    

  5. Start the KerbnetKDC service on the slave KDC by using the Services applet from the Control Panel or by using the command line, as described in section Installing and Starting the KDC Service and the KAdmin Service.

Note that you never install a KerbnetKAdmin service on a slave KDC machine. All principal databases changes are made to the principal database on the master KDC via the KerbnetKAdmin service running on that machine. This includes all kerberos password changes as well as the addition and deletion of principals.

    Now you need to add your new slave KDC as a known KDC for clients to contact.

  1. Open C:\CYGNUS\KERBNET\ETC\KRB5.CONF with NOTEPAD or a similar text editor.

  2. Under the line that reads:

    
    kdc = masterkdcname.mydomain.com
    
    

    (where masterkdcname is the Internet name of the machine running as the master KDC), add the line:

    
    kdc = machinename.mydomain.com
    
    

    where machinename is the Internet name of your slave KDC machine, and mydomain.com is its Internet domain name.

Once this is done, clients requesting kerberos tickets will try to obtain them from the first KDC on the list. If the first KDC does not respond, the client will automatically send its request to the next KDC on the list, and so on. When running KerbNet over a wide-area-network, list the local KDC first in KRB%.CONF; this can reduce the time clients spend waiting for Kerberos tickets, since they can talk to a local slave KDC rather than having to talk to the master.

To install multiple slave KDC machines, repeat the steps above for each of the slave KDC machines you wish to install. Note that you can save time by planning ahead and adding all of the slave KDCs to the KRB5.CONF file when you first edit it on the master KDC (as described in section Editing the Configuration Files), rather than performing step 6 separately for each separate slave KDC. Similarly, instead of adding each slave KDC principal to the database separately when you set up the KerbNet software on that slave (steps 3-5, section Setting Up the KerbNet Software on a Windows NT Slave Host), you can add all the principals to the database at once when you first edit it from the master server (as described in section Adding the Administrative User to the Principal Database).

Automating Database Propagation

Once you have all your slave KDC machines set up, you must keep them in sync so that changes to the master principal database are pushed out to them in a timely fashion, so that when a principals password is changed, for example, the change appears in all the slave KDCs with a minimum propagation delay.

First, decide how often you will be replicating the principal database. Replicate as often as you think will be neccessary to keep up with the changes in principal data you expect. For an example, with a 10,000 principal database, you may assume that 10% of the passwords will be changed each day, and thus 1000 changes will be made to the database daily. If you assume that these will be made over an 8 hour working period, then that is approximately 2 changes per minute. You might decide then, that replicating every 60 minutes (thus synchronising 120 changes) would be appropriate.

Create a script on your master KDC machine that replicates the principal database to your list of slave KDC machines:

  1. Using NOTEPAD or a similar text editor, create a file called C:\CYGNUS\KERBNET\LIB\KRB5KDC\SLAVE_REPLICATE.BAT.

  2. Insert the following text into the file:

    
    C:\CYGNUS\KERBNET\SBIN\KPROP -f %1 %2
    
    

    and save it.

  3. Using NOTEPAD or a similar text editor, create a file called C:\CYGNUS\KERBNET\LIB\KRB5KDC\TIMED_REPLICATE.BAT.

  4. Insert the following text into the file:

    
    C:\CYGNUS\KERBNET\SBIN\KDB5_UTIL dump
    => C:\CYGNUS\KERBNET\LIB\KRB5KDC\DBDUMP  
    => >>C:\CYGNUS\KerbNet\LOG\REPLICATE.LOG
    for %%i in ( slave_kdc1 slave_kdc2 ...  ) DO
    => C:\CYGNUS\KERBNET\LIB\KRB5KDC\SLAVE_REPLICATE.BAT
    => C:\CYGNUS\KERBNET\LIB\KRB5KDC\DBDUMP %%i
    =>  >>C:\CYGNUS\KerbNet\LOG\REPLICATE.LOG
    DEL /F C:\CYGNUS\KERBNET\LIB\KRB5KDC\DBDUMP
    
    

    where slave_kdc1, slave_kdc2 and so on are the Internet names of the slave KDC machines you wish to replicate to.

  5. Save the file

To test this script, type the following command:


C:\CYGNUS\KERBNET\LIB\KRB5KDB\TIMED_REPLICATE.BAT

A log of the replication will be created in the file

C:\CYGNUS\KERBNET\LOG\REPLICATE.LOG.

To cause this script to run every 60 minutes, or as desired, you need to start the Scheduler service on your master KDC machine, and use the AT command to schedule this batch file to run. As an example, to set this command to run every 60 minutes you would need to schedule 24 jobs, to go off on every hour. To schedule the 1am job you would type:


AT 01:00 /every:M,T,W,Th,F,S,Su "cmd /c 
C:\CYGNUS\KERBNET\LIB\KRB5KDC\TIMED_REPLICATE.BAT

Setting Up the Password Synchronization Service

KerbNet contains a service that allows all password changes to a Windows NT Primary Domain Controller (PDC) to be replicated automatically into your master principal database.

WARNING: By installing the PasswordSync service described as follows, you will be extending the Kerberos trusted computing base to include your Windows NT PDC. This means that any user with Administrator access to your Windows NT PDC will be able to modify principals in the kerberos master principal database, as well as change the password or attributes of any kerberos principal. If you regard this as too much of a risk then Cygnus Solutions advises that you do not install the PasswordSync service, and you will have to rely on manual methods to keep your Windows NT PDC password database, and your kerberos principal database in sync. Note that if you install the PasswordSync service on your Windows NT PDC, then password synchronization is not an issue.

In order for password synchronisation to work you need to install a special Dynamic Link Library into your SYSTEM32 directory on your Windows NT PDC, and also install a service on your PDC that communicates with the KerbnetKAdmin service on your master KDC. This library is called PWSYNC.DLL and is found in the directory C:\CYGNUS\KERBNET\LIB\PWSYNC.DLL.

In order for the PasswordSync service to be able to get kerberos tickets and communicate securely with the master KDC, KerbNet must be installed on your Windows NT PDC. This installation should involve setting up the C:\CYGNUS\KERBNET\ETC\KRB5.CONF files correctly so that the C:\CYGNUS\KERBNET\SBIN\KADMIN.EXE program can get kerberos tickets and log onto the master KDC KerbnetKAdmin service. The easiest way to do this is to copy the KRB5.CONF files from a machine with an already working KerbNet setup.

  1. To install PWSYNC.DLL log on to your Windows NT PDC as Administrator and change directory to C:\CYGNUS\KERBNET\SBIN.

  2. Run the command:

    
    shell% pwsync /install /syncdll C:\CYGNUS\KERBNET\LIB\PWSYNC.DLL
    
    

    This command copies the PWSYNC.DLL into the SYSTEM32 directory (failing if it already exists there), updates the registry key HKEY_LOCAL_MACHINE\CurrentControlSet\Control\Lsa, and adds the PWSYNC.DLL to the "Notification Packages" value.

    Now you must create a user for the PasswordSync service to conntect to the KerbnetKAdmin service as, and as usual for a service, store that users password in a keytab.

  3. To do this, run the command:

    
    shell% kadmin -p admin/admin
    
    

    kadmin prompts you for the kerberos administrator password.

  4. Type the administrator password.

    The kadmin: prompt appears.

    Now create the password synchronization principal by typing:

    
    kadmin: addprinc -randkey pwsync/pdcname.mydomain.com
    
    

    where pdcname.mydomain.com is the fully qualified Internet hostname of your PDC

  5. Now create the keytab for the PasswordSync service in the secure directory, by typing:

    
    kadmin: ktadd -k WRFILE:C:\CYGNUS\KERBNET\LIB\KRB5KDC\PWSYNC.SRVTAB
    
    

    kadmin responds with:

    
    Entry for principal pwsync/pdcname.mydomain.com with kvno <#>,
    encryption type DES-CBC-CRC added to keytab
    WRFILE:C:\CYGNUS\KERBNET\LIB\KRB5KDC\PWSYNC.SRVTAB
    
    

  6. Quit kadmin by typing:

    
    kadmin: quit
    
    

  7. Install the PasswordSync service by typing:

    
    shell% pwsync /install
    
    

  8. Reboot this machine to allow the password synchronization DLL to be initialized and the PasswordSync service to started.

  9. Log on to your master KDC machine (or this machine, if the Windows NT PDC is the same as the master KDC machine) as Administrator.

    Give the new principal the rights to change passwords in the principal database using the KerbnetKAdmin service.

  10. Using the program NOTEPAD, or a similar text editor, open the file C:\CYGNUS\KERBNET\LIB\KRB5KDC\KADM5.ACL and add the line:

    
    pwsync/pdcname.mydomain.com@MYREALM.COM        c
    
    

    where "pwsync/pdcname.mydomain.com" is the name of the principal you created in the previous step. The 'c' gives this principal password change privillages.

  11. Save this file.

  12. Stop and restart the KerbnetKAdmin service on the master KDC machine, by typing:

    
    net stop KerbnetKAdmin
    net start KerbnetKAdmin
    
    

Now, using the Windows NT Domain User Administrator tool, try changing the password of a user who has the same kerberos principal name as their username in the Windows NT Domain. You should find that their kerberos password has also changed. From now on, all principals you add to the master KDC principal database will be able to have their kerberos passwords changed automatically when their password is changed in the Windows NT Domain environment, whether that change is done by the user themselves, by an Administrator, or even programatically! For this to work, remember to add principals to your master KDC database with the same name as those you have in your Windows NT Domain.

Glossary of Kerberos Terms

authentication
the process of proving the identity of one entity on the internet (a user or service) to another entity.

client
an entity that can obtain a ticket. This entity is usually either a user or a host.

credentials cache
the location where KerbNet stores tickets. The credentials cache is frequently a file, but it may just be a place in memory.

expiration
tickets cease to be valid when they expire. The amount of time tickets have before expiration is chosen by the user when obtaining the tickets; the maximum allowable lifetime for different kinds of tickets is preset by the System Administrator.

forwardable tickets
Kerberos tickets that can be forwarded (copied) to a remote machine; the copies can be used on the remote machine, eliminating the need to obtain new tickets on that machine.

host
a computer that can be accessed over a network. A remote host is one that is accessed electronically through another host, rather than directly.

Kerberos
in Greek mythology, the three-headed dog that guards the entrance to the underworld. In the computing world, Kerberos is a network security package that was developed at MIT.

KDC
Key Distribution Center. A machine that issues Kerberos tickets.

keytab
a key table file containing one or more keys. A host or service uses a keytab file in much the same way as a user uses his/her password.

principal
a string that names a specific entity to which a set of credentials may be assigned. It generally has three parts:

primary
the first part of a Kerberos principal. The primary identifies the individual user (for a user principal) or the type of service (for a service principal). A user's primary is his/her username.

instance
the second part of a Kerberos principal. It gives information that qualifies the primary. If the principal represents a user, the instance is usually null (blank), but can also be used to describe the intended use of the corresponding credentials. If the principal represents a host, the instance is the fully qualified hostname.

realm
the logical network served by a single Kerberos database and a set of Key Distribution Centers. By convention, realm names are generally all uppercase letters, to differentiate the realm from the internet domain.

The typical format of a typical Kerberos principal is primary/instance@REALM.

  • service any program or computer you access over a network. Examples of services include "host" (a host, e.g., when you use telnet and rsh), "ftp" (FTP), "krbtgt" (authentication; cf. ticket-granting ticket), and "pop" (email).

  • single-sign-on system a security system that asks for initial confirmation of the user's identity, but then does all further authenticaton automatically. With a single-sign-on system, a user only needs to type his or her password once, at the beginning of the session.

  • telnet port the "address" that the telnet applications connects to on a computer.

  • ticket a temporary set of electronic credentials that verifies the identity of its to a particular service.

  • TGT Ticket-Granting Ticket. A special Kerberos ticket that permits its owner to obtain additional Kerberos tickets within the same Kerberos realm. A TGT is obtained during the initial authentication process.
  • Registry Keys and Values used by KerbNet Server

    SOFTWARE\Cygnus Solutions\Kerbnet\1
    Base registry key for KerbNet information. Contains two values:

    Name:
    CredentialsCacheDir
    Type:
    REG_SZ
    Description:

    Absolute path to the KerbNet credentials cache directory. Default is C:\CYGNUS\KERBNET\CCACHE

    Name:
    KERBNET_HOME
    Type:
    REG_SZ
    Description:

    Absolute path to the place where the KerbNet software is installed. Default is C:\CYGNUS\KERBNET

  • SOFTWARE\Cygnus Solutions\Kerbnet\1\Gina Base registry key for the KerbNet Windows NT Gina library. Can contain the following values:

    Name:
    ExcludedUsers
    Type:
    REG_MULTI_SZ
    Description:

    This is a list of users (one user per line) who are excluded from getting a kerberos ticket on logon. Each line is of the form:

    DOMAIN\user
    The user in the specified Domain.
    MACHINE\user
    The user logging in on the specified Machine.
    *\user
    The specified user in any Domain or Machine.
    DOMAIN\*
    Any user in the specified Domain.
    MACHINE\*
    Any user on the specified Machine.

    kerbgina.dll will not attempt to get a kerberos ticket for any users that match any name in this list. If this key doesn't exist then the default list is:

        *\Administrator   .
    

    I.e., kerbgina.dll doesn't attempt to get a Kerberos ticket for any Administrator user.

    Name:
    REALMS
    Type:
    REG_MULTI_SZ
    Description:

    This is a mapping between Windows NT Domain names or Machine names into kerberos realms. Each line is of the form:

    DOMAIN=REALM.COM
    Anyone loging on in the specified DOMAIN will attempt to get a Kerberos ticket in REALM.COM

    MACHINE=REALM.COM
    Anyone loging on at the specified MACHINE will attempt to get a Kerberos ticket in REALM.COM

    By default this value is empty, and users logging in will attempt to get a ticket in the default_realm listed in the krb5.conf file in C:\CYGNUS\KERBNET\ETC\KRB5.CONF

    Name:
    RequireKerberosLogon
    Type:
    REG_DWORD
    Description:

    This is a binary value. If non-zero then logins are rejected if the user is unable to get a kerberos ticket. This doesn't affect users who are matched by the 'ExcludedUsers' list.

  • SOFTWARE\Cygnus Solutions\Kerbnet\1\KAdmin Base registry key for the KerbnetKAdmin Service. Can contain one value:

    Name:
    Kadmin args
    Type:
    REG_MULTI_SZ
    Description:

    This is a list of arguments to the KerbnetKAdmin service, one argument per line. This key can be set for the service service by changing to the directory C:\CYGNUS\KERBNET\SBIN and typing:
    kadmind /install /args [ list of args ]
    
    Each argument will be added to this value, one line per argument.

  • SOFTWARE\Cygnus Solutions\Kerbnet\1\Kdc Base registry key for the KerbnetKdc Service. Can contain one value:

    Name:
    Kdc args
    Type:
    REG_MULTI_SZ
    Description:

    This is a list of arguments to the KerbnetKdc service, one argument per line. This key can be set for the service service by changing to the directory C:\CYGNUS\KERBNET\SBIN and typing:
    krb5kdc /install /args [ list of args ]
    
    Each argument will be added to this value, one line per argument.

  • SOFTWARE\Cygnus Solutions\Kerbnet\1\KPropd Base registry key for the KerbnetKPropd Service. Can contain one value:

    Name:
    KPropd args
    Type:
    REG_MULTI_SZ
    Description:

    This is a list of arguments to the KerbnetKPropd service, one argument per line. This key can be set for the service service by changing to the directory C:\CYGNUS\KERBNET\SBIN and typing:
    kpropd /install /args [ list of args ]
    

    Each argument will be added to this value, one line per argument.

  • SOFTWARE\Cygnus Solutions\PasswordSync Base registry key for the PasswordSync Service. Can contain one value:

    Name:
    PasswordSync args
    Type:
    REG_MULTI_SZ
    Description:

    This is a list of arguments to the PasswordSync service, one argument per line. This key can be set for the service service by changing to the directory C:\CYGNUS\KERBNET\SBIN and typing:
    pwsync /install /args [ list of args ]
    
    Each argument will be added to this value, one line per argument.

  • SOFTWARE\Cygnus Solutions\PasswordSync\Dlls Not used in KerbNet PasswordSync service.
  • SOFTWARE\Cygnus Solutions\PasswordSync\DLLToken Used internally by the password sync .DLL to maintain security when connecting to PasswordSync Service. No values specified.
  • SOFTWARE\Cygnus Solutions\PasswordSync\WatchKey Used internally by the password sync .DLL to notice when the the PasswordSync Service starts and stops. No values specified.
  • Troubleshooting KerbNet on Windows NT

    All KerbNet services, as well as the KerbNet GINA.DLL, log startup/shutdown and initialization problems to the Windows NT 'Application' log on the machine they are running on. To examine the Applicatin log, click on the 'Start' button and navigate to 'Programs->Administrative Tools->Event Viewer' and click.

    The Windows NT Event viewer will start up. To view the application log click on the menu 'Log->Application'. The KerbNet services log messages under their program names, for example the KerbnetKPropd service will log messages under the name 'kprop'. Error messages are logged with a red 'stop' symbol, informational messages are logged with a 'i' sign. If any of the above install steps fail it is a good idea to examine the Windows NT event log to determine the failure. The error messages given (there are too many to list here) should give you an idea of what may be going wrong.

    In addition, the KerbNet services will log messages into log files, created (if you use the default KRB5.CONF file) in the directory:

    C:\CYGNUS\KERBNET\LOG
    
    By default, the logs are as follows:
    KerbnetKDC Service logs messages to
    C:\CYGNUS\KERBNET\LOG\KDC
    KerbnetKAdmin Service logs message to
    C:\CYGNUS\KERBNET\LOG\ADMIN_SERVER
    All other services log messages to
    C:\CYGNUS\KERBNET\LOG\DEFAULT

    If the services are misbehaving you may find error messages in these files to be helpful.