Introduction
In the Kerberos world, entities are 'principals'. Their names take one of the forms 'name@realm' and 'name1/name2@realm'. Names are not restricted to only two parts, but it is seldom necessary to use more than two. In fact, since all DSAs have a name, <server-name>@realm would seem to be sufficient, for example, 'democorp@DIRECTORY'.
For a client to connect to a server using Kerberos, the following steps are to be taken.
- Normally, you would need to run 'kinit' to obtain a ticket-granting ticket and store it in the file system. There is no need for this when running DXgrid or the DUA.
- The client will require access to the krb5.conf file, so this needs to be configured. The corde base we use also requires the server to have access to the krb5.conf file.
- When binding, the client needs to provide the server's principal name. It also needs to provide its own principal name and Kerberos password, for autheticating to the server.
When the server receives the bind request, it has to create a distinguished name as the client's user name. But the server is provided with the client's principal name and it can use one of two methods to construct the distinguished name. The first method involves simply building the distinguished name using a rule. For example, the rule 'cn=$P$,o=democorp' applied to the pricipal name 'client@DIRECTORY' will yield the distinguished name 'cn=client,o=directory'. The server will verify that an entry with this name exists unless 'set sasl-auth-bypass-entry-check' is set.
The second method is to provide a base DN and filter to allow the server to search for a user entry. A base DN of "o=democorp" and a filter of "mail=$P$@$R$" will cause a whole-subtree search to be performed with a base object "o=democorp" and a filter "mail=client@DIRECTORY". Having ascribed a DN to the client, the usual processing now takes place. As Kerberos is a password system, the authentication level assigned is 'clear-password'.
Kerberos, broadly, is configured similarly to SSL.
Configuration (Server)
To configure the general parameters in the server we use the command
set krb = { krb5conf = <str> principal = <str> keytab = <str> [dsa-mapped-dn = <str> ] [ mapped-dn = <str> ] [ base-dn = <str> ] [ filter = <str> ] };
The parameters are:
- krb5conf - the path of the Kerberos configuration file 'krb5.conf' (required).
- principal - this is a substitutable principal name for the server, of the general form name@realm or name1/name2@realm (required). It may contain at most one occurrence of the string '$S$', indicating that the DSA name of the server should be inserted. For example, '$S$@DIRECTORY' would resolve to 'democorp@DIRECTORY' if the server name were 'democorp'.
- keytab - the path of the keytab file containing the server's password (required).
- dsa-mapped-dn - a string indicating how to map a principal name to a DSA name (optional). The DSA creates four variables to assist with this specification, $P$, $P1$, $P2$, $R$. If the principal name were name1/name2@realm, then the values of these variables would be: $P$ - 'name1/name2', $P1$ = 'name1', $P2$ = 'name2', $R$ = 'realm'.
- mapped-dn - a string indicating how to map a principal name to a user entry (optional). Constructed in the same manner as 'dsa-mapped-dn'.
- base-dn - the base DN for a search for the entry of the user having a particular principal (optional).
- filter - The filter to use to search for the user entry corresponding to a principal (optional). It allows substitutions using the variables $P$, $P1$, $P2$, $R$ previously described.
Either 'mapped-dn', or both 'base-dn' and 'filter', must be present.
Example 1: Mapping a principal name to a user entry
set krb = {
krb5conf = "/local/krb5/krb5.conf"
principal = "$S$@DIRECTORY"
keytab = "/local/krb5/krb5kdc/kadm5.keytab"
mapped-dn = "cn=$P1$,o=democorp"
'name@realm' is mapped directly to 'cn=name,o=democorp'.
Example 2: Searching for the user entry corresponding to a principal.
set krb = {
krb5conf = "/local/krb5/krb5.conf"
principal = "$S$@DIRECTORY"
keytab = "/local/krb5/krb5kdc/kadm5.keytab"
base-dn = "o=democorp"
filter = "(mail=$P$@$R$)"
'name@realm' is mapped to the entry returned by the search "o=democorp" "mail=name@realm".
Configuration (Client)
The client does not try try wrangle a distinguished name for a principal name. The only parameter it requires is the path of the krb5.conf file:
set krb = { krb5conf = <str> };
Example 3: A client 'krb' command.
set krb = { krb5conf = "/local/krb5/krb5.conf" };
The Client Bind Request
The keyword 'kerberos' indicates that the connection will be made over a Kerberos link. The required parameters are:
- destination - the principal name of the server.
- source - the principal name of the client.
- password - the password corresponding to the client principal.
There is an optional parameter 'encrypt'. If this keyword is included, the connection will be encrypted.
The client will obtain a ticket-granting ticket itself, there is no need to run 'kinit' for its principal.
Example 4: A client bind request.
bind-req
kerberos
destination = "server@DIRECTORY"
source = "client@DIRECTORY"
password = "secret"
encrypt
remote-addr = { nsap = tcp localhost port 389 };
Configuring DSP to Use Kerberos
There are two link-flags for this purpose, 'krb' and 'krb-encryption', the first provides only integrity protection (signing) while the second provides integrity protection and confidentiality (encryption).
The DSA will automatically obtain a kerberos ticket using the password configured in the knowledge entry.
Configuring Kerberos
Accessing the KDC
Justin has set up a Kerberos KDC (key distribution centre) on 'rosella', so we just need to interface to it. The interface is provided by the 'krb5.conf' file. The standard location for this file is /etc/krb5.conf, but this can be overridden by setting the KRB5_CONFIG environment variable.
A version of this file that should work follows.
[libdefaults]
default_realm = DIRECTORY
default_keytab_name = /local/krb5/keytab
[realms]
DIRECTORY = {
master_kdc = rosella.ca.com
kdc = rosella.ca.com
admin_server = rosella.ca.com
}
[domain_realm]
rosella.com.au = DIRECTORY
[logging]
kdc = STDERR
default = STDERR
I don't think default_realm is really necessary. But you need to specify the keytab file because server keys are stored here.
For the DIRECTORY realm, you need to specify a KDC for obtaining Kerberos tickets. You should only need the 'kdc' entry, though I had some trouble with not having the 'master_kdc' entry. 'admin_server' would only be needed for managing the principal database from another host. On rosella itself you can use kadmind.local.
I don't think we need a mapping from domain to realm.
Interestingly, even though we know now where the KDC is, we don't know its port. This would seem to be a fundamental limitation. Anyway, not my protocol so let me introduce the 'kdc.conf' file, which contains information for the KDC (and not for user programs?!).
[kdcdefaults]
kdc_ports = 88
[realms]
DIRECTORY = {
database_name = /local/krb5/krb5kdc/principal
admin_keytab = FILE:/local/krb5/krb5kdc/kadm5.keytab
acl_file = /local/krb5/krb5kdc/kadm5.acl
key_stash_file = /local/krb5/krb5kdc/.k5.DIRECTORY
kadmind_port = 749
max_life = 10h 0m 0s
max_renewable_life = 7d 0m 0m 0s
}
The only thing needed here is the KDC port. I don't know if we even need this file if the default port (88) is used. The rest of the file relates to stuff the KDC is interested in. If we only run one KDC, this information is not required on other hosts. So one could try to operate without this file. The default location of the kdc.conf file (/etc/kdc.conf) can be overridden with the KRB5_KDC_PROFILE environment variable.
Adding Principals
From rosella, you should be able to run kadmin.local. You will get a ':' prompt which enables you to enter a command. To add a principal, the command is 'addprinc'. For example,
: addprinc client@DIRECTORY
To add a server, we need to add the principal and then copy the data to the keytab.
: addprinc server@DIRECTORY
: ktadd -norandkey server@DIRECTORY
This will only add the server keys to the local keytab file, though. I don't know whether it is better to copy this keytab file to all hosts or to run kadmin on all hosts.
Setting Up The KDC
As there is a KDC already setup on rosella, this information is not required. I'm just adding it for completeness.
1. Set the environment variables, if necessary.<br> 2. Create an 'admin' principal by first allowing access to the principal database. Add the line
admin@DIRECTORY *
to krb5kdc/kadm5.acl (or whatever you named it in the kdc.conf file).<br> 3. Create the DIRECTORY realm. The password you use will be the realm password.
kdb5_util -r DIRECTORY create -s
4. Add the 'admin' principal to the principal database.
kadmin.local
: addprinc admin@DIRECTORY
4. Start the KDC
krb5kdc