HP Open Source Security for OpenVMS Volume 3:...

Kerberos Client Programs

User Client Programs

Kerberos Programming Concepts

Administrative Client Programs 

kadmin and kadmin_local 

The kadmin program allows the Kerberos administrator to make changes to the Kerberos database. The kadmin program provides for the maintenance of Kerberos principals, policies, and service key tables (keytabs). It exists as both a Kerberos client (kadmin), using Kerberos authentication and an RPC to operate securely from anywhere on the network, and as a local client (kadmin_local), intended to run directly on the KDC without Kerberos authentication.

SYNOPSIS

kadmin		[-r realm] [-p principal] [-w password] [-q query][-s admin_server[:port]] [[-c credentials_cache] |[-k keytab]]
kadmin_local
		[-d dbname] [-e "enc:salt …"] [-m]

Options

-r realm		Use realm as the default Kerberos realm for the database.
-p principal		Use the Kerberos principal principal to authenticate to Kerberos. If this option is not given, kadmin will append admin to either the primary principal name or to the username of the current process.
-w password		Use password as the password instead of prompting for one. Caution: Placing the password for a Kerberos principal with administrative access into a command file can be dangerous if unauthorized users gain read access to the file.
-q query		Pass the string query directly to kadmin. This is useful for writing command procedures that pass specific queries to kadmin.
-s admin_server[:port]		Use admin_server as the KDC to contact. Optionally specify the TCP/IP port to use for communication.
-c credentials_cache		Use credentials_cache as the credentials cache. The credentials cache should contain a service ticket for the kadmin/admin service, which can be acquired with the kinit program. If this option is not specified, kadmin requests a new service ticket from the KDC and stores it in its own temporary cache.
-k keytab		Use the keytab keytab to decrypt the KDC response instead of prompting for a password on the terminal. In this case, the principal will be host/hostname.
-d dbname		This option is valid for kadmin_local only. Specify the filename of the KDC database.
-e "enc:salt..."		This option is valid for kadmin_local only. It sets the list of cryptosystem and salt types to be used for any new keys created. Available types include des3-cbc-sha1:normal, des-cbc-crc:normal, and des-cbc-crc:v4.
-m		This option is valid for kadmin_local only. Specify the KDC database master key.

kdb5_util 

The kdb5_util program provides a way for the Kerberos administrator to create, delete, load, or dump a Kerberos database. It also includes a command to stash a copy of the master database key in a file on a KDC, so that the KDC can authenticate itself to the kadmind and krb5kdc daemons at boot time.

SYNOPSIS

kdb5_util

[-r realm] [-d dbname] [-k mkeytype] [-M mkeyname][-sf stashfilename] [-m] command [command_options]

OPTIONS

-r realm		Use realm as the default Kerberos realm for the database.
-d dbname		Specify the filename of the KDC database.
-k mkeytype		Specify the encryption type to use from the list of supported mtypes in KDC.CONF.
-M mkeyname		Specify the master key name.
-sf stashfilename		Specify the file that stores the master key. If you specify this file, you are not prompted for the master key.
-m		Specify the KDC database master key.

command

The kdb5_util command can be one of the following:

ark [-e etype_list] principal



Add a random key for a Kerberos 5 database entry principal. This assumes the max key version number. As a side effect, all old keys older than the maximum key version number are deleted.



-e etype_list



Specify the key salt to use for the random key.



create [-s]



Create a new Kerberos database. If you specify the -s option, kdb5_util stashes a copy of the master key in a stash file.



destroy [-f]



Destroy the existing Kerberos database. If you do not specify the -f option, you are prompted with "are you sure?" before the database is destroyed.



dump [-old] [-b6] [-ov] [-verbose] [-mkey_convert] [-new_mkey_file mkey_file] [-rev] [-recurse] [filename [princs…]]



Dump a Kerberos database to a file.



-old



Cause the dump file to be Kerberos 5 Beta 5 and earlier dump format (kdb5_edit load_dump version 2.0).



-b6



Cause the dump file to be Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").



-ov



Cause the dump to be in ovsec_adm_export format.



-verbose



Cause the name of each principal and policy to be printed as it is loaded.



-mkey_convert



Change master key as part of dump.



-new_mkey_file mkey file



Get master key from file mkey_file.



-rev



Dump in reverse order.



-recurse



Do recursive descent tree traversal of database instead of using previous/next pointers.



filename



File name of the dump file to be output.



[princs]



Principal name to be dumped.



dump_v4 filename



Dump a Kerberos database to a file in Kerberos V4 format.



filename



File name of the dump file to be output.



load [-old] [-b6] [-ov] [-verbose] [-update] filename



Restore a Kerberos database dump from a file, specified by filename.



-old



Requires the dump to be in the Kerberos 5 Beta 5 and earlier dump format (kdb5_edit load_dump v2.0).



-b6



Require the dump to be in the Kerberos 5 Beta 6 format (kdb5_edit load_dump v3.0).



-ov



Require the dump to be in ovsec_adm_export format



-verbose



Cause the name of each principal and policy to be printed as it is dumped.



-update



Cause records from the dump file to be updated in or added to the existing database.



filename



File name of the dump file to load.



load_v4 [-t] [-n] [-v] [-K] [-s stashfile] inputfile



Restore a Kerberos database dump from a Kerberos V4 format dump file (specified by inputfile).



-t



Allow modification of an existing database. If you do not specify -t, the load will abort if the database exists.



-n



Read the Kerberos V4 master key from the key file.



-v



Cause the name of each principal and policy to be printed as it is loaded.



-K



Prompt for the Kerberos V5 database master password.



-s stashfile



Specify the location of the Kerberos V4 master key file.



inputfile



Filename of the V4 dump file to load.



stash [-f keyfile]



Create a stash file, which allows a KDC to authenticate itself to the database programs kadmin, kadmind, krb5kdc, and kdb5_util. If the -f option is not specified, kdb5_util stashes the key in the file specified in the KRB$ROOT:[KRB5KDC]KDC.CONF file.

ktutil 

The ktutil program invokes a menu from which an administrator can read, write, or edit entries in a Kerberos V5 keytab or V4 srvtab file.

SYNOPSIS

ktutil

command

The command on the ktutil menu can be one of the following:

clear_list, clear



Clear the current key list.



read_kt, rkt



Read a krb5 keytab into the current keylist.



read_st, rst



Read a krb4 srvtab into the current keylist.



write_kt, wkt



Write the current keylist to a krb5 keytab.



write_st, wst



Write the current keylist to a krb4 srvtab.



add_entry, addent



Add an entry to the current keylist.



delete_entry, delent



Delete an entry from the current keylist.



list, l



List the current keylist.



list_requests, lr, ?



List available requests.



quit, exit, q



Exit program.

kprop 

The kprop program propagates the master KDC database to slave KDCs.

The following sections describe the procedure you should use to propagate your master KDC database. This procedure involves performing steps first on the master system, then the slave system, and back and forth again until finishing with the master system.

In the following procedure, the steps are numbered M1, M2, and so on for the master KDC server, and S1, S2 and so on for the slave KDC server.

Kerberos must be installed on both the master and slave systems.

PROCEDURE

Step 1: Configure the Master KDC Server for Propagation 

M1. On the master KDC server, enter the following command:

$ @SYS$STARTUP:KRB$CONFIGURE

M2. Set up the client.

M3. Set up the server.

M4. Exit the KRB$CONFIGURE.COM file.

M5. If you added additional USER/admin principals during your configuration (other than your first admin principal), add them to KRB$ROOT:[KRB5KDC]KADM5.ACL.

M6. Add your anticipated slave hosts to KRB$ROOT:[ETC]KRB5.CONF under the realms tag using a kdc tag as follows:

USER/admin@REALM

kdc = nodename.domain:88

M7. To create KRB$ROOT:[BIN]KRB$KPROP.DAT from the template file KRB$KPROP_DAT.TEMPLATE, copy KRB$KPROP_DAT.TEMPLATE to KRB$KPROP.DAT, and edit KRB$KPROP.DAT as follows:

1. Comment out the example node name lines with a # sign.
2. Add all of your slave node names either as just the simple node name or as fully qualified node names that include their respective domain names. Be consistent in the naming method you choose. It is safest to use the node name form that is used to define your node names in your local TCP/IP host setting. If you use DNS to manage your local host lookups, you will need to use fully qualified node and domain name strings.
   
   If you specify local host names, know the form of the node name you use, define all propagation node names that way in the local TCP/IP host database, and enter these propagation node names in the form that they are locally defined.
   
   Try to define all propagation nodes in your local TCP/IP hosts database, or leave them all defined in DNS and not in your local database. If you see client not found errors during propagation, review your node name definitions and the form that you have in the local TCP/IP database.
3. The KRB$KPROP.DAT file is simply a data file that is read by the kprop command file to see where database propagation is performed. Make sure you do not include the local server node name in this data file. The propagation server does not need its own data propagated to itself.
4. You need only perform step M7 on those nodes that might act as the master KDC server at some future point, and need to have master database changes propagated to them.

M8. Create the KRB$ROOT:[KRB5KDC]KPROPD.ACL file as follows. There is no template for this file. This file defines the names of the hosts that will be involved in propagation and includes the master server entity. (This step will also have to be performed on each of your slave KDCs.)

1. Edit KRB$ROOT:[KRB5KDC]KPROPD.ACL to add each slave KDC host/name keytab entry that will be created in Step M11.
   
   The form depends on how your node names are defined in TCP/IP. You can use either of the following forms. The @REALM portion is required.

     host/yournode@REALM

     host/yournode.yourdomain@REALM

2. If your local TCP/IP database defines the node names, the form of your node name in Step M8a must match that of your TCP/IP database
3. Be sure to include the host/entry for your master KDC.

M9. Start your master server and run KADMIN.

In steps M10 and M11, it is critical that the node names are in the same form as your local TCP/IP node name. You can use either simple node names or fully qualified DNS node names, as long as you are consistent.

  addprinc -randkey host/yourmasternode

  addprinc -randkey host/yourslavenode

M11. Add/export the host/keytabs with the following commands:

  ktadd host/yourmasternode@REALM

  ktadd host/yourslavenode@REALM

The @REALM part of this file name is important and must match the REALM entered into KPROPD.ACL in step M8.

Step 2: Configure the Slave KDC Servers for Propagation 

After you configure the master server, perform the following steps to configure each slave KDC server.

S1. To configure your slave KDC client, enter the master KDC server name when asked where the master KDC server resides. Do not use your local node name.

S2. Set up your slave KDC server by entering the following command:

  $ @SYS$STARTUP:KRB$CONFIGURE

• Your KDC node name is your local node, not the master KDC node name.



• Specify SLAVE_KDC, if it is not the default.



• Add a local admin principal. (This will not be used.)



• Accept the defaults for the remaining questions.

S3. Exit the configuration file and perform step M7 from the previous section only if, in the future, you may use this slave KDC as a master KDC server. Otherwise, go to step S4.

S4. Perform Step 1, M8 on your slave KDC node. You can copy the file from the server or edit a new file using the same host/entry information. This step is required for propagation.

S5. Export the master server's host/keytabs to the local KDC slave server keytab file. Because the slave server is configured as a client in the master KDC, you can kinit as the master KDC server's admin and run kadmin to extract the server's keytabs as shown in Step 1, M11. This will create your local keytab file with the MASTER KDC server keytab information. Issue a listprincs command and then ktadd the host principals.

S6. Edit KRB$ROOT:[KRB5KDC]KRB$ROLE.DAT. Change the second data line from a zero to a one (0 to 1), and save the file. This tells KRB$CONFIGURE that the KRB$KPROPD.EXE daemon must be started when the slave server is started.

S7. Edit KRB$ROOT:[ETC]KRB5.CONF and add the slave and master KDC nodes under the realms tag, if they do not exist. Here, you can safely specify fully qualified node names with their domain names as follows:

kdc = yourmasternode.yourdomain:88

kdc = yourslavenode.yourdomain:88

Make sure the record format for KRB5.CONF and KPROPD.ACL is STREAM_LF.

Do not start the slave server yet.

Step 3: Complete the Configuration of the Master KDC Server 

Perform the following steps on the master server.

M13. Run kadmin and re-export only the master's host/keytab as in Step 1, M11. Because this keytab was exported on one or more slaves, the key version number is now greater than when this keytab was originally exported, and the slave KDCs will not be able to authenticate to the master KDC with a lower key version number.

M14. In kadmin, enter the following command:

  ktadd host/yourmaster@REALM

You may have to remove the host keytabs and principals and re-add them if the slave and master cannot agree on the key version numbers. This is an issue only with the master KDC keytab after keys are added to the slaves. This step does correct certain authentication problems.

Step 4: Complete the Configuration of the Slave KDC Server 

Perform the following steps on the slave server.

S8. Use kinit to get to your master server's admin account. This will refresh the master's host keytab on the local system and start the slave server in preparation for its first propagation from the master.

Step 5: Propagate the Master KDC Server to Each Configured Slave Server 

Perform the following steps to complete the propagation procedure.

M16. Enter the following command:

  @KRB$ROOT:[BIN]KRB$KPROP.COM

The kprop command procedure causes the following to occur:

1. The master server is stopped, the database dumped, the servers restarted, and a connection to each slave kpropd daemon is made in order to transfer the master database to the slave servers listed in KRB$ROOT:[BIN]KRB$KPROP.DAT.
2. The slave servers are stopped, the master KDC database is loaded, the slave servers are restarted, and a signal is sent to the master server that the propagation has successfully completed.
3. The master server produces a file called SLAVE_DATATRANS_DAT_YOURSLAVENODE.LAST_PROP that indicates that the propagation to the individual slave node has completed.
4. When propagation to each slave server completes, the kpropd.exe daemon exits. The next propagation can be done only after starting the kpropd daemon on each of the KDC slave servers. This is why kpropd should be a TCP/IP service. The TCP/IP system automatically starts the kpropd daemon for each slave server requested by the master server.

User Client Programs

Kerberos Programming Concepts