java kerberos version 1 - technical university of denmark · 2008-10-28 · java kerberos system...

Java Kerberos System User Guide

1

Java Kerberos version 1.1

Installing, Configuring and Running Java Kerberos System

Bojan Pajkovski Autumn 2005

Contents 1 Introduction 2 2 Java Kerberos System 2 3 Getting Started 3 4 Configuring the KDC 3 4.1 KDC Configuration File (kdc.conf) 3 4.2 Java Security Policy File (.java.policy) 4 5 Configuring the Kerberos Clients and Application Servers 4 6 Configuring the Kerberos Database 5 6.1 Configuring and Running the Admin Server 6 7 Running the Java Kerberos System 8 7.1 Run KDC Services 8 7.2 Run Demo Application Servers 8 7.3 Run Kerberos Clients 9 7.3.1 Communicating with the KDC 10 7.3.2 Communicating with the Application Servers 13 8 Developer’s Guide 15


2

1. Introduction This document describes a step-by-step guide to software installation of the Java Kerberos System in both Linux and Windows environments. It is assumed that the reader has basic knowledge of Kerberos, including what it is and what is its purpose.

2. Java Kerberos System The Java Kerberos System consists of three different components: a Key Distribution Center (KDC), Kerberos Client(s) and Application Server(s). The KDC represents the heart of the Kerberos system. It maintains a database of Kerberos Clients and Application Servers within its realm, as well as it issues Kerberos Ticket Granting Tickets (TGT) to its clients. It consists of an Authentication Server (AS) and a Ticket Granting Server (TGS), which are both running on the same machine, whereas the Kerberos Client(s) and the Application Server(s) could be distributed across the network. The architecture of the Java Kerberos System is presented on Figure 1.


3

3. Getting Started Download the Kerberos ZIP-file from: http://www.imm.dtu.dk/~cdj/JavaKerberos/krb5-1.1.zip Unzip the files into the destination directory, normally your home directory. Example (UNIX): cd $HOME wget http://www.imm.dtu.dk/~cdj/krb5-1.1.zip unzip krb5-1.1.zip Example (Windows 2000/XP):

cd C:\Documents and Settings\user name start http://www.imm.dtu.dk/~cdj/krb5-1.1.zip unzip krb5-1.1.zip

The released kerberos package contains the following files:

4. Configuring the KDC Before starting the KDC, you need edit the kdc.conf. This configuration file is only used by the machine where the KDC is to be started.

4.1. KDC Configuration File (kdc.conf) The kdc.conf file contains two stanzas. The first stanza, called kdcdefaults, contains information about the default realm the KDC controls as well as the port numbers on which the Authentication Server (AS) and the Ticket Granting Server (TGS) are listening for requests. An example for such a stanza is the following: [kdcdefaults]

default_realm = DTU.DK as_port = 8081 tgs_port = 8081

krb5-1.1.jar − Kerberos core libraries krb5db.xml − Kerberos database file krb5db.dtd − Kerberos database file admin.pwd − Kerberos database administrator password kdc.conf − Kerberos Distribution Center configuration file krb5.conf − Kerberos Client configuration file server.keytab − Kerberos Application Server file .java.policy − Java security policy policy.socket − Java security policy LICENSE − Software license


4

The default_realm field is required so that the KDC works properly, whereas the as port and tgs port are optional. In case the as_port or tgs_port fields are omitted, port number 88 will be used as default. The second stanza is known as realms, and it contains information about the realms administered by the KDC. This includes information about the attributes of the tickets issued to kerberos clients as well as the possible encryption types. Most of the information has reasonable defaults. However, in case you want to modify the maximum lifetime and/or renew the lifetime of a ticket, you could write the stanza as follows: [realms] DTU.DK = {

max_life = 28800 max_rlife = 86400

} The values of max_life and max_rlife are presented in seconds. Thus, in this example, the realm’s maximum life of a ticket is set to 8 hours. In this implementation of the KDC, only the DES_CBC-MD5 encryption algorithm is supported, since it is the only symmetric password-based encryption supported by the JDK 1.5. Thus, any modification to the encryption type in this stanza will be omitted.

4.2. Java Security Policy File (.java.policy) The user who runs the KDC on his/hers machine must add the .java.policy file to his/hers home directory. In addition, the typical contents in this file should include the following lines: grant {

permission java.security.AllPermission; permission java.net.SocketPermission "*:1024-65535", "accept, connect, listen, resolve";

};

5. Configuring the Kerberos Clients and Application Servers The krb5.conf configuration file applies to all programs that use Kerberos, both clients and application servers, and thus, it should be accessible from any host/machine where Kerberos users might reside. This file contains information about the default realm as well as the location of the KDC service. The former stanza is knows as libdefaults, and it contains general Kerberos defaults. In this implementation version of Kerberos, all recommended values are set by default except for the default realm. Therefore, you need specify the default_realm value in a similar way as it is shown in the following example: [libdefaults]

default_realm = DTU.DK


5

This stanza sets the default realm to DTU.DK. One should be aware that the realm name is case-sensitive. Hence, DTU.DK is different from dtu.dk. The later stanza in the krb5.conf file is realms, which gives information about how to connect to the AS and TGS respectively for each realm. An example of a configuration file containing the realms stanza is the following: [realms]

DTU.DK = { kdc = ebar032.ebar.dtu.dk as_port = 8081 tgs_port = 8081

} MYREALM.COM = {

kdc = 192.38.79.229 as_port = 8022 tgs_port = 8022

} EXAMPLE.COM = {

kdc = kerberos.example.com } The kdc field is very important for a Kerberos client and/or an application server, who wants to communicate with the host/machine on which the KDC is running. As it is shown in the above example, the value of the kdc filed could be either a host name (if the KDC is running in the local area network), or an IP address (if the KDC is running in a wide area network). Thus, it is essential for you to make sure that the value in the kdc field is correct, before you start any KDC services. NOTE: Strictly speaking, the kdc name is not a formal Kerberos KDC name. Normally, it should be of the form:

kdc = ebar032.dtu.dk provided that there exist a host ebar032.dtu.dk, on which the KDC is running. However, for the sake of simplicity, and due to limited experiment conditions for this project, it is assumed that the all specified hosts on the realm DTU.DK do exist.

6. Configuring the Kerberos Database Before you configure the Kerberos database, you need to make sure that the two database files, krb5db.xml and krb5db.dtd (included in the kerberos software package), are located in the user_home\krb5 directory. After doing this, you should use the Kerberos administration server in order to manage your Kerberos database.


6

6.1. Configuring and Running the Admin Server Before actually running the Kerberos Admin Server, you need to make sure that the file containing the administrator server password for the database, admin.pwd (included in the kerberos software package), is located in the user_home\krb5 directory. The initial password is ”admin”. It is suggested that you change it to your own private password once you run the admin GUI. To run the Admin Server GUI, please input following java command under the directory where the krb5-1.1.jar package is installed:

> java -classpath krb5-1.1.jar StartAdminUI

The KDC admin window will be presented:

From the Logon menu in the toolbar, select the Log on menu item. The following Logon dialog should pop-up:


7

After entering the correct admin password, you should see a list of all principals that currently exist in the Kerberos database on the admin window:

As this example shows, a principal can be a kerberos client or an application server. A principal name is defined as Name + Realm. Conventionally, a principal name is formatted as Name@Realm. Furthermore, any principal name must be unique in the database. The max life column shows the principal’s preferred maximum lifetime of a ticket. However, this does not mean that the granted lifetime of the ticket will be the same as the one requested. More precisely, the lifetime of a ticket is the minimum of:

• requested life-time in AS request message or TGS request message, • maximum realm life-time, which is defined by the second stanza of the

kdc.conf file, • principal preferred life-time.

The maximum lifetime is not a mandatory field, i.e., you can leave it empty. This means that the admin server is configured in such a way that the maximum lifetime of a ticket is configured automatically. The max rlife column specifies the principal’s preferred ticket renewable ticket time. A renewable ticket is normally interpreted only by the TGS, and it can usually be ignored by the end servers. In general, a renewable ticket is used to obtain a replacement ticket that expires at a later date. Similar to the max lifetime, the max rlife is not a mandatory field. Thus, if left unmodified, a default value will be set automatically by the admin server.


8

The pa enc required column is a flag that determines whether pre-authentication data is required in the AS request message. If it is true, the AS will pre-authenticate the client before it issues any initial ticket. A service principal can omit this flag since it does not apply for an initial ticket. NOTE: Both Name and Realm fields are case-sensitive. You have to make sure that all principals you add in the database have the correct name.

7. Running the Java Kerberos System This section describes how to individually run every component within the Java Kerberos System.

7.1. Run KDC Services When you are finished configuring and adding new principals into the database, you are ready to run your KDC services. To run the KDC services, please input following java command under the directory where the krb5-1.1.jar package is installed:

> java -Djava.security.policy=policy.socket -classpath krb5-1.1.jar StartKDCServices KDC started successfully

7.2. Run Demo Application Servers For this version of the Java Kerberos System, a demo application server program is provided to show how Kerberos is used in practice. Before running the server, you must create a server.keytab file, which is required for the service principals, that is, principals not associated with a user but a server. When the server receives a request along with a Kerberos ticket, the service must decrypt the ticket with a key. Since no human is available to input a password for that key, the service instead reads the key from a keytab file. Similarly to the above configuration files, the keytab file should be placed in the user_home\krb5 directory. An example of a server keytab file is the following:

[email protected] = eBar-032 [email protected] = ebar012 [email protected] = datasec [email protected] = bojan [email protected] = hJH.k1Ls [email protected] = myserver

In the first line in the above presented example, [email protected] represents the Name and Realm respectively, whereas eBar-032 represents the key/password of the service. In order for everything to run smoothly, you have to make sure that the correct principal name (in this case ebar032.ebar.dtu.dk) already exists in the Kerberos database on the host/machine where the KDC is running, and its key value (in this case eBar-032) is the same as the one stored in the Kerberos database.


9

When you are finished configuring and adding new principals into the database, and your KDC services are already running, you are ready to run your Application Server. Type the following java command under the directory where the krb5-1.1.jar package is installed:

> java -classpath krb5-1.1.jar SecureServerDemo This host name: ebar032.ebar.dtu.dk The principal name: [email protected] Please make sure you have TGT for this principal ! listening...

The output received in this example, is a result from running the application server on host ebar032.ebar.dtu.dk.

7.3. Run Kerberos Clients In order to run a kerberos client, you have to type the following command under the directory where the krb5-1.1.jar package is installed:

> java -classpath krb5-1.1.jar StartKrbClient

Correspondingly, the following dialog is presented to the principal:

It is essential for the principal to authenticate with the Kerberos system, before actually using the kerberos client program. This is done by providing his/hers user name and password in the login dialog as presented on Figure 5. The User Name field accepts two types of names: full principal name and realm (e.g., [email protected]) or just name (e.g., ebar032.ebar.dtu.dk). In the later case the default realm will be used. Thus, if the default realm field, as defined in the kdc.conf file, is DTU.DK, these two user names are actually the same. NOTE: You should note that the inputted user name and password will not be verified with the KDC at the log-in time. This means that the authentication between the principal and the kerberos system happens only when the client program issues a request to the KDC. Therefore, even if the principal inputs a wrong user name or a password, he/she would not be aware until the Kinit command is executed. After specifying a user name and a password, and pressing the OK button, the principal should see a Kerberos client console window, as shown on figure 6. This console window contains two tabs: a KDC Service and a KrbApplication Service tab. The former one is


10

responsible for the communication established between the kerberos client and the KDC, whereas the later one is between the kerberos client and the application server(s).

7.3.1. Communicating with the KDC It presents a list of all available tickets (both TGT and service tickets) for the current principal, as well as with three buttons: Kinit, Kdestroy and Apply TGT. Their functions are defined as follows: Kinit – is used to authenticate the principal with the KDC, and as result return a Kerberos

Ticket Granting Ticket (TGT). The TGT is issued from the AS (see figure 1), and it is mandatory in case you want to request for a Service Ticket at a later stage. This process is shown on Figure 7.


11

Kdestroy – is used to remove any TGTs you have previously obtained. Both Kdestroy and Apply TGT buttons are disabled if the principal has not successfully authenticated with the KDC, as shown on Figure 6. They are activated once a TGT is obtained.

Apply TGT – is used to authenticate the principal (using the principal’s TGT) with the

KDC, in order to obtain a Service Ticket for a specific application server. Therefore, it requires the principal to provide information about the application server he/she wants to connect to, such as an application server name and realm.

Figure 8 shows a principal requesting (applying his TGT) a service ticket for an application server, whose name is EBAR032 and it is running within the DTU.DK realm. Since the Java Kerberos system is a distributed system, the KDC could operate with application servers that are distributed across the network. Thus, a principal could request another service ticket (using the same TGT) from the KDC, for an application server that is running on a different machine or within a different realm, provided that such an application server already exists in the KDC database. An example for such a scenario is presented of Figure 9, where a principal, even though he/she has a service ticket for the EBAR032 server, requests another service ticket for an application server running on 192.38.93.47 within the DTU.DK realm. Assuming that there is an application server running on a host whose IP address is 192.38.93.47, and the principal 192.38.93.47 already exists in the Kerberos database, the principal would be issued another service ticket by the TGS.


12

After obtaining another service ticket by the TGS, the state of the client window console should look like the following figure:

An interesting feature of the Java Kerberos System is cashing. More specifically, the client program will cache the effective tickets automatically. Thus, a principal does not need to reapply for tickets in case he/she restarts the client program. Expired tickets will be automatically removed from cache and the ticket list within the client GUI, once the program is closed or the ticket list has been updated. Furthermore, every principal has its own cache space, which depends on the principal’s name. This is considered to be very useful when one or more principals are running the Kerberos client from the same machine.


13

7.3.2. Communicating with the Application Servers After successfully obtaining a service ticket for a particular application server, the Kerberos client is ready to present the service ticket in order to authenticate with that application server, and afterwards use the services offered by that particular application server. The second tab in the Kerberos client console, KrbApplication Service, is used to communicate with a particular application server. It is composed of two major parts: a field that lets you specify the name of the application server, and a message window that presents the authentication status as well as the information received from the application server (see Figure 11).

As it is shown on the above figure, the Server Name is used by the client program in order to setup a TCP connection with the specified application server. Thus, you should either specify the server’s hostname on the network (refer back to section 7.2), or its IP address. Before you press the Select button, you have to make sure (again) that the application server has been started. For any question about how to start application service, please refer to section 7.2. Now, press the button and then you should see an authentication message received from the application server, as shown on Figure 12.


14

In case of any other dialog prompts or error messages shown in the message area, please check the server name or the printout of the application server program. If everything is alright, the two buttons: Time Service and Server Info should be activated. The former one enquires the server time, whereas the later one demands the information of which operation system the server is working on (see Figure 13).


15

The message transferred between the Kerberos client and application server is encrypted according to the Kerberos protocol. The replied messages from the application server, should be posted in the Message Window area.

8. Developer’s Guide This section is intended for an audience interested in developing Kerberized applications. This requires a certain knowledge about the Kerberos client side API. For this reason, a Java Documentation has been created, and it can be downloaded from:

http://www.imm.dtu.dk/~cdj/JavaKerberos/krb5-api-1.1.zip You should remember that the software produced by this author is covered by a license, which is enclosed with the whole Kerberos package.

9. Known Quirks This user-space implementation of Kerberos in Java has been made by students at DTU Informatics. Most of the developed code is a few years old and things change, so some quirks have developed over time. The following is a short list of known “features” in the current implementation:

• The package should be unpacked into a sub-directory (krb5) in your home directory • Specification of realms has to be in capital letters, LIKE THIS • Specification of all hostnames have to be fully qualified, i.e., include the domain,

this is also true for the hostnames in the keytab file • The implementation relies on RMI internally and some of the integrated development

environments, e.g., Eclipse, deletes the necessary stub files. Generation of these stub files is described below

Java Kerberos is looking for the file krb5/lib/AuthenticationServiceImpl_Stub.class, which is generated by “rmic krb5.lib.AuthenticationServiceImpl” – the rmic compiler is located in the same directory as the javac compiler. Similarly, the file krb5/lib/TicketGrantingServiceImpl.class is generated by rmic compiler like this: “rmic krb5.lib.TicketGrantingServiceImpl”. Finally, if you wish to contribute to the evolution of this package (or want to redevelop it from scratch,) please don’t hesitate to contact [email protected]. We are keen to continue the development of this software and prepared to define bachelor projects (or smaller special courses) to reward students who desire to work on it.