Kerberos encryption types

Note:
This documentation has moved to a new home! Please update your bookmarks to the new URL for the up-to-date version of this page.

Encryption is at the heart of Kerberos, and it supports multiple cryptographic algorithms. The default choices are good enough for most deployments, but specific situations might need to tweak these settings.

This document will explain the basic configuration parameters of Kerberos that control the selection of encryption algorithms used in a Kerberos deployment.

Server-side configuration

There are two main server-side configuration parameters that control the encryption types used on the server for its database and its collection or principals. Both exist in /etc/krb5kdc/kdc.conf inside the [realms] section and are as follows:

master_key_type
Specifies the key type of the master key. This is used to encrypt the database, and the default is aes256-cts-hmac-sha1-96.
supported_enctypes
Specifies the default key/salt combinations of principals for this realm. The default is aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal, and the encryption types should be listed in order of preference.

Possible values for the encryption algorithms are listed in the MIT documentation on encryption types, and the salt types can be seen in the MIT keysalt lists.

Here is an example showing the default values (other settings removed for brevity):

[realms]
    EXAMPLE.INTERNAL = {
        (...)
        master_key_type = aes256-cts
        supported_enctypes = aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal
        (...)
}

The master key is created once per realm, when the realm is bootstrapped. That is usually done with the krb5_newrealm tool (see how to install a Kerberos server for details). You can check the master key type with either of these commands on the KDC server:

$ sudo kadmin.local
kadmin.local:  getprinc K/M
Principal: K/M@EXAMPLE.INTERNAL
(...)
Number of keys: 1
Key: vno 1, aes256-cts-hmac-sha1-96
(...)

$ sudo klist -ke /etc/krb5kdc/stash
Keytab name: FILE:/etc/krb5kdc/stash
KVNO Principal
---- --------------------------------------------------------------------------
   1 K/M@EXAMPLE.INTERNAL (aes256-cts-hmac-sha1-96)

When a new Kerberos principal is created through the kadmind service (via the kadmin or kadmin.local utilities), the types of encryption keys it will get are controlled via the supported_enctypes configuration parameter.

For example, let’s create an ubuntu principal, and check the keys that were created for it (output abbreviated):

$ sudo kadmin.local
Authenticating as principal root/admin@EXAMPLE.INTERNAL with password.
kadmin.local:  addprinc ubuntu
No policy specified for ubuntu@EXAMPLE.INTERNAL; defaulting to no policy
Enter password for principal "ubuntu@EXAMPLE.INTERNAL":
Re-enter password for principal "ubuntu@EXAMPLE.INTERNAL":
Principal "ubuntu@EXAMPLE.INTERNAL" created.

kadmin.local:  getprinc ubuntu
Principal: ubuntu@EXAMPLE.INTERNAL
(...)
Number of keys: 2
Key: vno 1, aes256-cts-hmac-sha1-96
Key: vno 1, aes128-cts-hmac-sha1-96
(...)

Two keys were created for the ubuntu principal, following the default setting of supported_enctypes in kdc.conf for this realm.

Note:
The server config supported_enctypes has the default list of key types that are created for a principal. This list applies to the moment when that principal is created by kadmind. Changing that setting after the fact won’t affect the keys that the principal in question has after that event. In particular, principals can be created with specific key types regardless of the supported_enctypes setting. See the -e parameter for the kadmin add_principal command.

If we had supported_enctypes set to aes256-sha2:normal aes128-sha2:normal camellia256-cts:normal in kdc.conf, then the ubuntu principal would get three key types:

kadmin.local:  getprinc ubuntu
Principal: ubuntu@EXAMPLE.INTERNAL
(...)
Number of keys: 3
Key: vno 1, aes256-cts-hmac-sha384-192
Key: vno 1, aes128-cts-hmac-sha256-128
Key: vno 1, camellia256-cts-cmac

Note:
Bootstrapping a new Kerberos realm via the krb5_newrealm command also creates some system principals required by Kerberos, such as kadmin/admin, kadmin/changepw and others. They will all also get the same number of keys each: one per encryption type in supported_enctypes.

Client-side configuration

When we say “client-side”, we really mean “applications linked with the Kerberos libraries”. These live on the server too, so keep that in mind.

The encryption types supported by the Kerberos libraries are defined in the /etc/krb5.conf file, inside the [libdefaults] section, via the permitted_enctypes parameter.

Example:

[libdefaults]
(...)
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96

This parameter contains a space-separated list of encryption type names, in order of preference. Default value: aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 aes256-cts-hmac-sha384-192 aes128-cts-hmac-sha256-128 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac.

Possible values for the encryption algorithms are listed in the MIT documentation (same ones as for the KDC).

Note:
There are more encryption-related parameters in krb5.conf, but most take their defaults from permitted_enctypes. See the MIT libdefaults documentation for more information.

Putting it all together

When a client performs Kerberos authentication and requests a ticket from the KDC, the encryption type used in that ticket is decided by picking the common set of:

The encryption types supported by the server for that principal
The encryption types supported by the client

If there is no common algorithm between what the client accepts, and what the server has to offer for that specific principal, then kinit will fail.

For example, if the principal on the server has:

kadmin.local:  getprinc ubuntu
Principal: ubuntu@EXAMPLE.INTERNAL
(...)
Number of keys: 2
Key: vno 1, aes256-cts-hmac-sha384-192
Key: vno 1, aes128-cts-hmac-sha256-128

And the client’s krb5.conf has:

permitted_enctypes = aes256-sha1 aes128-sha1

Then kinit will fail, because the client only supports sha1 variants, and the server only has sha2 to offer for that particular principal the client is requesting:

$ kinit ubuntu

kinit: Generic error (see e-text) while getting initial credentials

The server log (journalctl -u krb5-admin-server.service) will have more details about the error:

Apr 19 19:31:49 j-kdc krb5kdc[8597]: AS_REQ (2 etypes {aes256-cts-hmac-sha1-96(18), aes128-cts-hmac-sha1-96(17)}) fd42:78f4:b1c4:3964:216:3eff:feda:118c: GET_LOCAL_TGT: ubuntu@EXAMPLE.INTERNAL for krbtgt/EXAMPLE.INTERNAL@EXAMPLE.INTERNAL, No matching key in entry having a permitted enctype

This log says that there was an AS-REQ request which accepted two encryption types, but there was no matching key type on the server database for that principal.

Changing encryption types

Changing encryption types of an existing Kerberos realm is no small task. Just changing the configuration settings won’t recreate existing keys, nor add new ones. The modifications have to be done in incremental steps.

MIT Kerberos has a guide on updating encryption types that covers many scenarios, including deployments with multiple replicating servers:

References

Previous Configure service principals Next Set up secondary KDC

This page was last modified 2 months ago. Help improve this document in the forum.