Krb5_Admin Tutorial

Getting Started

Building and Installing

As we have not announced an official release of krb5_admin, it will need to be built from the current sources at the head of the git repository. Before building krb5_admin, the following must be installed:

Required software	Minimum version
Perl	5.10
Swig	1.3.36
Kharon	current srcs
MIT Kerberos	1.4
Heimdal	1.6

Note: you only need one of MIT Kerberos or Heimdal.

Note: Heimdal 1.6 has not been release, use the current development sources instead.

Note: krb5_admin has not been tested on MIT Kerberos in quite a long time, YMMV.

To build and install the software:

        $ git clone http://imrryr.org/git/krb5_admin
        $ cd krb5_admin
        $ perl Makefile.PL
        $ make
        $ make test
        $ make install

When running “perl Makefile.PL” a number of environment variables can be set to influence the build:

KRB5DIR: the directory to find Kerberos. If not specified, we will look for libgssapi{,_krb5}.so in /usr, /usr/pkg, and /usr/local.
KRB5TYPE: either mit or heimdal. We’ll try to figure it out if not specified.

Creating a Realm

For the rest of this document, we shall assume that Heimdal is in use. If using MIT Kerberos, the administrative commands will be slightly different but the krb5_admin procedures will be exactly the same.

First, get Heimdal up and running using the Heimdal documentation. Another guide to installing Heimdal Kerberos is here. If the reader is new to Kerberos or Heimdal Kerberos then cross referencing both guides can be useful.

Be sure to setup PK-INIT as it is required to use all of krb5_admin’s features. Client certificates are not needed but a KDC certificate is required.

Starting krb5_admind

krb5_admin requires that the “krb5_admin” service be defined in /etc/services so that it can be located appropriately. The entry should look roughly like this:

        krb5_admin      5999/tcp

We also need a keytab for krb5_admin/<hostname> on the KDC. We can install this using krb5_keytab’s -Z option which tells it to operate directly against a local Kerberos database rather than talking over the network to a remote krb5_admind.

        # krb5_keytab -Z krb5_admin

Note: Only use the -Z option on the master KDC, if you have multiple KDCs as it directly manipulates the local Kerberos database.

Now, we are ready to start krb5_admind. Initially, we can start it directly from the command line, later we will cover how to start krb5_admind properly.

        # knc -l krb5_admin /path/to/krb5_admind -M

And you are running it with a very basic configuration. To test it, try using krb5_admin preferably from another machine:

        $ krb5_admin list
        default@TEST.REALM
        kadmin/admin@TEST.REALM
        kadmin/hprop@TEST.REALM
        kadmin/changepw@TEST.REALM
        krbtgt/TEST.REALM@TEST.REALM
        changepw/kerberos@TEST.REALM
        WELLKNOWN/ANONYMOUS@TEST.REALM

Advanced Topics

Overriding ACLs and Commands, Adding Commands

In /etc/krb5/krb5_admind.conf, the variable $kmdb_class specifies a class to use to construct the Krb5Admin::KerberosDB object that krb5_admind will use to manipulate the Kerberos database and run the protocol which it speaks. It is expected that this class will inherit from and override methods from Krb5Admin::KerberosDB.

In this object, the commands are represented by methods of the same name. If these methods are overridden then the command in question will behave differently.

Example 1. Overriding Administrative Password Reset

Say one wants to define a administrative password reset workflow which doesn’t let the admin know the entire password that has been assigned to the user. We could, e.g., send the user an SMS message with part the password and present the other part of the password to the administrator who could then communicate it to the user. To do this, and still allow the administrator to use the krb5_admin(1) user interface, we could override the “reset_passwd” command as follows in /etc/krb5/krb5_admind.conf:

$kmdb_class = 'MyKrb5Admin::KerberosDB';


package MyKrb5Admin::KerberosDB;
use base qw(Krb5Admin::KerberosDB);

use SiteLocal::PhoneBook;
use SMS_Software;

sub reset_passwd {
        my ($self, $name) = @_;

        my $phonebook = SiteLocal::PhoneBook->new();
        my $sms = SMS_Software->new();

        my $phonenumber = $phonebook->get_mobile_number($name);

        my $passwd = $self->SUPER::reset_passwd($name);

        $passwd =~ /(.....)(.*)/;
        my $firstpart  = $1;
        my $secondpart = $2;

        $sms->send_text_msg($phonenumber, $firstpart);
        return $secondpart;
}

1;

The ACLs are defined by the functions KHARON_COMMON_ACL and KHARON_ACL_<command_name>. These functions will return 1 for allowed, 0 for permission denied, a string for permission denied with an error message, or undef which passes the ACL process to the next method. KHARON_COMMON_ACL is called first for all commands that are received, if it returns undef then KHARON_ACL_<command_name> is called. If KHARON_ACL_<command_name> returns undef then krb5_admind will use the defined sacls for file based ACLs on the system.

Example 2. Overriding ACLs

To override the ACLs for placing prestashed tickets to use a Perl object AppID::AppIDDB and its method is_appid_owner, one could:

$kmdb_class = 'MyKrb5Admin::KerberosDB';


package MyKrb5Admin::KerberosDB;
use base qw(Krb5Admin::KerberosDB);

use AppID::AppIDDB;

sub KHARON_ACL_remove_ticket { KHARON_ACL_insert_ticket(@_) }
sub KHARON_ACL_insert_ticket {
        my ($self, $verb, $princ, @hosts) = @_;

        my $pdb = AppID::AppIDDB->new(local=>1, dbh=>$self->{dbh});

        my $ret;
        eval { $ret = $pdb->is_appid_owner($self->{client}, $princ); };
        return 1 if $ret eq '1';
        return "Permission denied: $@" if $@;
        return 0;
}

1;

Finally, there are a set of four variables which tell Kharon what commands an object exports:

@KHARON_RO_SC_EXPORT: Read-only commands that are called in a scalar context.
@KHARON_RW_SC_EXPORT: Read/write commands that are called in a scalar context.
@KHARON_RO_AC_EXPORT: Read-only commands that are called in a array context.
@KHARON_RW_AC_EXPORT: Read/write commands that are called in a array context.

To add a command, the appropriate method must be added on the server side and the appropriate variable must be set.

Kharon will look for these arrays in the entire class hierarchy of the object that it is presenting and use the union of all of the command names found. This means that when extending Krb5Admin::KerberosDB, only the new command needs to be defined as seen in the example below. Note that the client side must also know about these variables and so adding commands requires an update to both the server and the client software at this time.