doc/html/_sources/admin/enctypes.rst.txt

   1 .. _enctypes:
   2
   3 Encryption types
   4 ================
   5
   6 Kerberos can use a variety of cipher algorithms to protect data.  A
   7 Kerberos **encryption type** (also known as an **enctype**) is a
   8 specific combination of a cipher algorithm with an integrity algorithm
   9 to provide both confidentiality and integrity to data.
  10
  11
  12 Enctypes in requests
  13 --------------------
  14
  15 Clients make two types of requests (KDC-REQ) to the KDC: AS-REQs and
  16 TGS-REQs.  The client uses the AS-REQ to obtain initial tickets
  17 (typically a Ticket-Granting Ticket (TGT)), and uses the TGS-REQ to
  18 obtain service tickets.
  19
  20 The KDC uses three different keys when issuing a ticket to a client:
  21
  22 * The long-term key of the service: the KDC uses this to encrypt the
  23   actual service ticket.  The KDC only uses the first long-term key in
  24   the most recent kvno for this purpose.
  25
  26 * The session key: the KDC randomly chooses this key and places one
  27   copy inside the ticket and the other copy inside the encrypted part
  28   of the reply.
  29
  30 * The reply-encrypting key: the KDC uses this to encrypt the reply it
  31   sends to the client.  For AS replies, this is a long-term key of the
  32   client principal.  For TGS replies, this is either the session key of the
  33   authenticating ticket, or a subsession key.
  34
  35 Each of these keys is of a specific enctype.
  36
  37 Each request type allows the client to submit a list of enctypes that
  38 it is willing to accept.  For the AS-REQ, this list affects both the
  39 session key selection and the reply-encrypting key selection.  For the
  40 TGS-REQ, this list only affects the session key selection.
  41
  42
  43 .. _session_key_selection:
  44
  45 Session key selection
  46 ---------------------
  47
  48 The KDC chooses the session key enctype by taking the intersection of
  49 its **permitted_enctypes** list, the list of long-term keys for the
  50 most recent kvno of the service, and the client's requested list of
  51 enctypes.
  52
  53 Starting in krb5-1.11, it is possible to set a string attribute on a
  54 service principal to control what session key enctypes the KDC may
  55 issue for service tickets for that principal.  See :ref:`set_string`
  56 in :ref:`kadmin(1)` for details.
  57
  58
  59 Choosing enctypes for a service
  60 -------------------------------
  61
  62 Generally, a service should have a key of the strongest
  63 enctype that both it and the KDC support.  If the KDC is running a
  64 release earlier than krb5-1.11, it is also useful to generate an
  65 additional key for each enctype that the service can support.  The KDC
  66 will only use the first key in the list of long-term keys for encrypting
  67 the service ticket, but the additional long-term keys indicate the
  68 other enctypes that the service supports.
  69
  70 As noted above, starting with release krb5-1.11, there are additional
  71 configuration settings that control session key enctype selection
  72 independently of the set of long-term keys that the KDC has stored for
  73 a service principal.
  74
  75
  76 Configuration variables
  77 -----------------------
  78
  79 The following ``[libdefaults]`` settings in :ref:`krb5.conf(5)` will
  80 affect how enctypes are chosen.
  81
  82 **allow_weak_crypto**
  83     defaults to *false* starting with krb5-1.8.  When *false*, removes
  84     weak enctypes from **permitted_enctypes**,
  85     **default_tkt_enctypes**, and **default_tgs_enctypes**.  Do not
  86     set this to *true* unless the use of weak enctypes is an
  87     acceptable risk for your environment and the weak enctypes are
  88     required for backward compatibility.
  89
  90 **permitted_enctypes**
  91     controls the set of enctypes that a service will permit for
  92     session keys and for ticket and authenticator encryption.  The KDC
  93     and other programs that access the Kerberos database will ignore
  94     keys of non-permitted enctypes.  Starting in release 1.18, this
  95     setting also acts as the default for **default_tkt_enctypes** and
  96     **default_tgs_enctypes**.
  97
  98 **default_tkt_enctypes**
  99     controls the default set of enctypes that the Kerberos client
 100     library requests when making an AS-REQ.  Do not set this unless
 101     required for specific backward compatibility purposes; stale
 102     values of this setting can prevent clients from taking advantage
 103     of new stronger enctypes when the libraries are upgraded.
 104
 105 **default_tgs_enctypes**
 106     controls the default set of enctypes that the Kerberos client
 107     library requests when making a TGS-REQ.  Do not set this unless
 108     required for specific backward compatibility purposes; stale
 109     values of this setting can prevent clients from taking advantage
 110     of new stronger enctypes when the libraries are upgraded.
 111
 112 The following per-realm setting in :ref:`kdc.conf(5)` affects the
 113 generation of long-term keys.
 114
 115 **supported_enctypes**
 116     controls the default set of enctype-salttype pairs that :ref:`kadmind(8)`
 117     will use for generating long-term keys, either randomly or from
 118     passwords
 119
 120
 121 Enctype compatibility
 122 ---------------------
 123
 124 See :ref:`Encryption_types` for additional information about enctypes.
 125
 126 ========================== ========== ======== =======
 127 enctype                    weak?      krb5     Windows
 128 ========================== ========== ======== =======
 129 des-cbc-crc                weak       <1.18    >=2000
 130 des-cbc-md4                weak       <1.18    ?
 131 des-cbc-md5                weak       <1.18    >=2000
 132 des3-cbc-sha1              deprecated >=1.1    none
 133 arcfour-hmac               deprecated >=1.3    >=2000
 134 arcfour-hmac-exp           weak       >=1.3    >=2000
 135 aes128-cts-hmac-sha1-96               >=1.3    >=Vista
 136 aes256-cts-hmac-sha1-96               >=1.3    >=Vista
 137 aes128-cts-hmac-sha256-128            >=1.15   none
 138 aes256-cts-hmac-sha384-192            >=1.15   none
 139 camellia128-cts-cmac                  >=1.9    none
 140 camellia256-cts-cmac                  >=1.9    none
 141 ========================== ========== ======== =======
 142
 143 krb5 releases 1.18 and later do not support single-DES.  krb5 releases
 144 1.8 and later disable the single-DES enctypes by default.  Microsoft
 145 Windows releases Windows 7 and later disable single-DES enctypes by
 146 default.
 147
 148 krb5 releases 1.17 and later flag deprecated encryption types
 149 (including ``des3-cbc-sha1`` and ``arcfour-hmac``) in KDC logs and
 150 kadmin output.  krb5 release 1.19 issues a warning during initial
 151 authentication if ``des3-cbc-sha1`` is used.  Future releases will
 152 disable ``des3-cbc-sha1`` by default and eventually remove support for
 153 it.
 154
 155
 156 Migrating away from older encryption types
 157 ------------------------------------------
 158
 159 Administrator intervention may be required to migrate a realm away
 160 from legacy encryption types, especially if the realm was created
 161 using krb5 release 1.2 or earlier.  This migration should be performed
 162 before upgrading to krb5 versions which disable or remove support for
 163 legacy encryption types.
 164
 165 If there is a **supported_enctypes** setting in :ref:`kdc.conf(5)` on
 166 the KDC, make sure that it does not include weak or deprecated
 167 encryption types.  This will ensure that newly created keys do not use
 168 those encryption types by default.
 169
 170 Check the ``krbtgt/REALM`` principal using the :ref:`kadmin(1)`
 171 **getprinc** command.  If it lists a weak or deprecated encryption
 172 type as the first key, it must be migrated using the procedure in
 173 :ref:`changing_krbtgt_key`.
 174
 175 Check the ``kadmin/history`` principal, which should have only one key
 176 entry.  If it uses a weak or deprecated encryption type, it should be
 177 upgraded following the notes in :ref:`updating_history_key`.
 178
 179 Check the other kadmin principals: kadmin/changepw, kadmin/admin, and
 180 any kadmin/hostname principals that may exist.  These principals can
 181 be upgraded with **change_password -randkey** in kadmin.
 182
 183 Check the ``K/M`` entry.  If it uses a weak or deprecated encryption
 184 type, it should be upgraded following the procedure in
 185 :ref:`updating_master_key`.
 186
 187 User and service principals using legacy encryption types can be
 188 enumerated with the :ref:`kdb5_util(8)` **tabdump keyinfo** command.
 189
 190 Service principals can be migrated with a keytab rotation on the
 191 service host, which can be accomplished using the :ref:`k5srvutil(1)`
 192 **change** and **delold** commands.  Allow enough time for existing
 193 tickets to expire between the change and delold operations.
 194
 195 User principals with password-based keys can be migrated with a
 196 password change.  The realm administrator can set a password
 197 expiration date using the :ref:`kadmin(1)` **modify_principal
 198 -pwexpire** command to force a password change.
 199
 200 If a legacy encryption type has not yet been disabled by default in
 201 the version of krb5 running on the KDC, it can be disabled
 202 administratively with the **permitted_enctypes** variable.  For
 203 example, setting **permitted_enctypes** to ``DEFAULT -des3 -rc4`` will
 204 cause any database keys of the triple-DES and RC4 encryption types to
 205 be ignored.