(kerberos-encryption-types)= # Kerberos encryption types 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](https://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/kdc_conf.html#encryption-types), and the salt types can be seen [in the MIT keysalt lists](https://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/kdc_conf.html#keysalt-lists). Here is an example showing the default values (other settings removed for brevity): ```text [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 {ref}`how to install a Kerberos server ` for details). You can check the master key type with either of these commands on the KDC server: ```bash $ 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): ```bash $ 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](https://web.mit.edu/kerberos/krb5-latest/doc/admin/database.html#add-principal). 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: ```text 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: ```text [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](https://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/kdc_conf.html#encryption-types) (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](https://web.mit.edu/kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html#libdefaults) 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: ```text 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: ```text 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: ```bash $ 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: ```text 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](https://web.mit.edu/kerberos/krb5-latest/doc/admin/enctypes.html#migrating-away-from-older-encryption-types) that covers many scenarios, including deployments with multiple replicating servers: ## References * [Encryption types in MIT Kerberos](https://web.mit.edu/kerberos/krb5-latest/doc/admin/enctypes.html) * [`krb5.conf` encryption related configurations options](https://web.mit.edu/kerberos/krb5-latest/doc/admin/enctypes.html#configuration-variables) * [Migrating away from older encryption types](https://web.mit.edu/kerberos/krb5-latest/doc/admin/enctypes.html#migrating-away-from-older-encryption-types) * [`kdc.conf` manpage](https://manpages.ubuntu.com/manpages/jammy/man5/kdc.conf.5.html) * [`krb5.conf` manpage](https://manpages.ubuntu.com/manpages/jammy/man5/krb5.conf.5.html) * [Kerberos V5 concepts](https://web.mit.edu/kerberos/krb5-latest/doc/basic/index.html)