Macintosh Development

[Home] [About Us] [People] [Information Systems]
[Kerberos for Macintosh] [Applications] [Miscellaneous Documentation]

Kerberos Preferences on Mac OS X 10.1 Documentation

This web page discusses the edu.mit.Kerberos (Kerberos preferences) file: what's in it, where it goes, and how to configure it for distribution at your site.

The information on this page applies to Kerberos for Macintosh 4.0.x and Mac OS X 10.1 Kerberos only. For links to preferences documentation for other Mac OS versions, click here.

About the edu.mit.Kerberos File

Setting up a Preferences File Quick Guide

edu.mit.Kerberos File Locations (or, "Why are there two edu.mit.Kerberos files?")

What to Install Where

About Kerberos Configuration Information

Creating the Default Kerberos Configuration for Your Site

About the edu.mit.Kerberos File

The edu.mit.Kerberos file is where the Kerberos v4 and v5 configuration, Kerberos Login Library, and Kerberos management application preferences are stored on Mac OS X.

The edu.mit.Kerberos file stores this information in both its data and resource forks. The data fork contains the realm and server configuration information (the info that would be found in the krb5.conf file on Unix). See the Kerberos Configuration section for more information.

The resource fork may contain the following resources (but not every edu.mit.Kerberos file will have all of these - if the user has not changed preferences from the default, the resources will not be created):

'KrbL' - the preferences for the Kerberos Login Library, such as the saved username and realms listed in the pop-up menu of the Kerberos Login dialog;

'ktmP' - preferences for the Kerberos management application, such as whether ticket list entries should be expanded and window positioning;

On most systems there will be two edu.mit.Kerberos files. See the edu.mit.Kerberos File Locations section for more information about why this is so.

Setting up a Preferences File Quick Guide

We recommend that you read this entire page. However, if you are in a hurry to get Kerberos for Macintosh 4.0 or Mac OS X Kerberos up and working:

You need to create an edu.mit.Kerberos file in the /Library/Preferences directory which contains the realm and server configuration information for your site.

If you've run the Kerberos for Macintosh 4.0 installer or the Mac OS X Kerberos Extras installer, you may already have a file in the correct place, but which contains MIT configuration information (which is provided as a guideline).

If you have a functioning Mac OS 9.x Kerberos installation, you can simply copy the Kerberos Preferences file from the Kerberos folder in Application Support from your Mac OS 9 volume to the /Library/Preferences on your Mac OS X volume, and rename it to edu.mit.Kerberos.

Otherwise:

Create a file named edu.mit.Kerberos in /Library/Preferences, using BBEdit, or Codewarrior (it must be a plain text file);

Place Kerberos realm and server configuration in the data fork of this file. See the Kerberos Configuration section for the proper format.

Note - while there may also be an edu.mit.Kerberos file in your /Users/username/Library/Preferences directory, you should place your configuration information in the /Library/Preferences location. (See edu.mit.Kerberos File Locations for more details.)

edu.mit.Kerberos File Locations (or, "Why are there two edu.mit.Kerberos files?")

Kerberos for Macintosh supports and looks for two copies of the edu.mit.Kerberos file - a "user" edu.mit.Kerberos file, containing the preferences for an individual user, and a "system" edu.mit.Kerberos file that contains the defaults to be used by all users of the computer. (Defaults for creating a preferences file when none exists are also stored in other locations.)

On Mac OS X, the Kerberos preferences file is named edu.mit.Kerberos, to better match Mac OS X preference naming conventions. The user edu.mit.Kerberos is located in /Users/username/Library/Preferences (where "username" is the name of the user), and the system edu.mit.Kerberos is located in /Library/Preferences .

(Note: in releases prior to KfM 4.0a18, the Mac OS X preferences name was Kerberos Preferences and the system location was /System/Library/Preferences . This name and location are no longer supported as of KfM 4.0a18.)

When KfM reads preferences, it first looks for the preferences in the user Kerberos preferences file, and if it doesn't find them, then looks for them in the system Kerberos preferences. Since there are different sets of preferences, some may be read from the user preferences and others from the system preferences if they aren't in the user preferences.

If no preferences file exist when KfM attempts to read preferences, KfM creates a preferences file from the stored defaults. (See the Creating the Default Kerberos Configuration for Your Site section.)

However, the user preferences must contain a complete set of Kerberos realm and server configuration information, or none at all - you cannot include partial configuration information in the user file and have other parts read from the system preferences. The typical and preferred case is to have the Kerberos configuration information in the system preferences, and each user has a preferences file that contains their Kerberos Login Library preferences (as set in the Kerberos control panel's Preferences dialog). Having just a user preferences file and no system preferences file to fall back on is permitted, but not recommended. If there is a full set of realm information in both preference locations, KfM will attempt to meld the two sets of information together - you may see realms listed twice.

When KfM writes preferences, it writes them to the user preferences file, not the system preferences file. That way each user gets their customized preferences, but there is a core default Kerberos preferences file for each new user. If there is no existing user Kerberos preferences file, one is created. As a result, the user Kerberos preferences may not have all the resources the system Kerberos preferences has, because the user has not changed all the preferences.

What To Install Where

On Mac OS X, the system Kerberos preferences file edu.mit.Kerberos should be placed in /Library/Preferences .

About Kerberos Configuration Information

The Kerberos v4 and v5 configurations are stored in the data fork of edu.mit.Kerberos. The defaults used to create a preferences file when one does not exist are stored in /System/Library/Frameworks/Kerberos.framework/Frameworks/KerberosPreferences.framework/Resources/DefaultRealmsConfiguration
This text is similar to that of krb5.conf on Unix machines or krb5.ini on Windows machines. The configuration tells Kerberos for Macintosh what realms exist, what Kerberos versions are supported by them, and where to find the servers. You should edit this file for your site by opening the edu.mit.Kerberos file in a text editor that preserves file type/creator codes (ie: BBEdit or CodeWarrior; but not TextEdit or Microsoft Word).

Once you are done editing the edu.mit.Kerberos file, you should reboot or log out, and then you need to use the "Edit Favorite Realms" feature of the Kerberos management application to add your realms to the pop-up menu in the Login dialog.

Here is an example Kerberos configuration:
	[libdefaults]
		default_realm = ATHENA.MIT.EDU
		ticket_lifetime = 600
		default_tkt_enctypes = des-cbc-crc
		default_tgs_enctypes = des-cbc-crc

	[realms]
	        ATHENA.MIT.EDU = {
	                kdc = kerberos.mit.edu:88
	                kdc = kerberos-1.mit.edu:88
	                kdc = kerberos-2.mit.edu:88
	                kdc = kerberos-3.mit.edu:88
	                admin_server = kerberos.mit.edu
	                default_domain = mit.edu
	        }
	        MEDIA-LAB.MIT.EDU = {
	                kdc = kerberos.media.mit.edu
	                admin_server = kerberos.media.mit.edu
	        }

	[domain_realm]
		.mit.edu = ATHENA.MIT.EDU
		mit.edu = ATHENA.MIT.EDU
		.media.mit.edu = MEDIA-LAB.MIT.EDU
		media.mit.edu = MEDIA-LAB.MIT.EDU

	[v4 realms]
	        ATHENA.MIT.EDU = {
	                kdc = kerberos.mit.edu
	                kdc = kerberos-1.mit.edu
	                kdc = kerberos-2.mit.edu
	                kdc = kerberos-3.mit.edu
	                admin_server = kerberos.mit.edu
	                default_domain = mit.edu
	                string_to_key_type = mit_string_to_key
	        }
	        UMICH.EDU = {
	                kdc = kerberos.umich.edu
	                admin_server = kerberos.umich.edu
	                default_domain = umich.edu
	                string_to_key_type = afs_string_to_key
	        }

	[v4 domain_realm]
		.mit.edu = ATHENA.MIT.EDU
		mit.edu = ATHENA.MIT.EDU
		.umich.edu = UMICH.EDU
		umich.edu = UMICH.EDU
The [libdefaults] section describes what the default behavior of the Kerberos libraries should be. You should always fill in the default realm. If you have Kerberos v5 at your site, you should also copy any other [libdefaults] from your site's krb5.conf or krb5.ini.

The [realms] and [domain_realm] sections refer to Kerberos v5 realms. If your site is v4-only you should omit these sections. Otherwise just copy these sections from your site's krb5.conf or krb5.ini.

The [v4 realms] and [v4 domain_realm] sections refer to Kerberos v4 realms. If your site is v5-only you should omit these sections. Otherwise you will need to create entries for each of the Kerberos v4 realms at your site. You must supply a Kerberos v4 string_to_key_type for each realm. Currently the type can be either mit_string_to_key or afs_string_to_key. If your site uses a different string_to_key function, please send us mail at krbdev@mit.edu.

Creating the Default Kerberos Configuration for Your Site

(This section is provided for reference only. In general you should not attempt to distribute a Kerberos.framework at your site; just distribute a correctly configured edu.mit.Kerberos file for placement in /Library/Preferences .)

Once you have created an edu.mit.Kerberos file which contains the defaults for your site and tested it, you should create an DefaultRealmsConfiguration file which can create those defaults when no preferences file already exists.

Open the file named DefaultRealmsConfiguration in /System/Library/Frameworks/Kerberos.framework/Frameworks/KerberosPreferences.framework/Resources, using BBEdit, or Codewarrior (it must be a plain text file);

Place Kerberos realm and server configuration in the data fork of this file. See the Kerberos Configuration section for the proper format.

Questions or comments? Send mail to macdev@mit.edu
Last updated on $Date: 2003/11/18 22:03:39 $
Last modified by $Author: smcguire $