1Principal names and DNS 2======================= 3 4Kerberos clients can do DNS lookups to canonicalize service principal 5names. This can cause difficulties when setting up Kerberos 6application servers, especially when the client's name for the service 7is different from what the service thinks its name is. 8 9 10Service principal names 11----------------------- 12 13A frequently used kind of principal name is the host-based service 14principal name. This kind of principal name has two components: a 15service name and a hostname. For example, ``imap/imap.example.com`` 16is the principal name of the "imap" service on the host 17"imap.example.com". Other possible service names for the first 18component include "host" (remote login services such as ssh), "HTTP", 19and "nfs" (Network File System). 20 21Service administrators often publish well-known hostname aliases that 22they would prefer users to use instead of the canonical name of the 23service host. This gives service administrators more flexibility in 24deploying services. For example, a shell login server might be named 25"long-vanity-hostname.example.com", but users will naturally prefer to 26type something like "login.example.com". Hostname aliases also allow 27for administrators to set up load balancing for some sorts of services 28based on rotating ``CNAME`` records in DNS. 29 30 31Service principal canonicalization 32---------------------------------- 33 34In the MIT krb5 client library, canonicalization of host-based service 35principals is controlled by the **dns_canonicalize_hostname**, 36**rnds**, and **qualify_shortname** variables in :ref:`libdefaults`. 37 38If **dns_canonicalize_hostname** is set to ``true`` (the default 39value), the client performs forward resolution by looking up the IPv4 40and/or IPv6 addresses of the hostname using ``getaddrinfo()``. This 41process will typically add a domain suffix to the hostname if needed, 42and follow CNAME records in the DNS. If **rdns** is also set to 43``true`` (the default), the client will then perform a reverse lookup 44of the first returned Internet address using ``getnameinfo()``, 45finding the name associated with the PTR record. 46 47If **dns_canonicalize_hostname** is set to ``false``, the hostname is 48not canonicalized using DNS. If the hostname has only one component 49(i.e. it contains no "." characters), the host's primary DNS search 50domain will be appended, if there is one. The **qualify_shortname** 51variable can be used to override or disable this suffix. 52 53If **dns_canonicalize_hostname** is set to ``fallback`` (added in 54release 1.18), the hostname is initially treated according to the 55rules for ``dns_canonicalize_hostname=false``. If a ticket request 56fails because the service principal is unknown, the hostname will be 57canonicalized according to the rules for 58``dns_canonicalize_hostname=true`` and the request will be retried. 59 60In all cases, the hostname is converted to lowercase, and any trailing 61dot is removed. 62 63 64 65Reverse DNS mismatches 66---------------------- 67 68Sometimes, an enterprise will have control over its forward DNS but 69not its reverse DNS. The reverse DNS is sometimes under the control 70of the Internet service provider of the enterprise, and the enterprise 71may not have much influence in setting up reverse DNS records for its 72address space. If there are difficulties with getting forward and 73reverse DNS to match, it is best to set ``rdns = false`` on client 74machines. 75 76 77Overriding application behavior 78------------------------------- 79 80Applications can choose to use a default hostname component in their 81service principal name when accepting authentication, which avoids 82some sorts of hostname mismatches. Because not all relevant 83applications do this yet, using the :ref:`krb5.conf(5)` setting:: 84 85 [libdefaults] 86 ignore_acceptor_hostname = true 87 88will allow the Kerberos library to override the application's choice 89of service principal hostname and will allow a server program to 90accept incoming authentications using any key in its keytab that 91matches the service name and realm name (if given). This setting 92defaults to "false" and is available in releases krb5-1.10 and later. 93 94 95Provisioning keytabs 96-------------------- 97 98One service principal entry that should be in the keytab is a 99principal whose hostname component is the canonical hostname that 100``getaddrinfo()`` reports for all known aliases for the host. If the 101reverse DNS information does not match this canonical hostname, an 102additional service principal entry should be in the keytab for this 103different hostname. 104 105 106Specific application advice 107--------------------------- 108 109Secure shell (ssh) 110~~~~~~~~~~~~~~~~~~ 111 112Setting ``GSSAPIStrictAcceptorCheck = no`` in the configuration file 113of modern versions of the openssh daemon will allow the daemon to try 114any key in its keytab when accepting a connection, rather than looking 115for the keytab entry that matches the host's own idea of its name 116(typically the name that ``gethostname()`` returns). This requires 117krb5-1.10 or later. 118 119OpenLDAP (ldapsearch, etc.) 120~~~~~~~~~~~~~~~~~~~~~~~~~~~ 121 122OpenLDAP's SASL implementation performs reverse DNS lookup in order to 123canonicalize service principal names, even if **rdns** is set to 124``false`` in the Kerberos configuration. To disable this behavior, 125add ``SASL_NOCANON on`` to ``ldap.conf``, or set the 126``LDAPSASL_NOCANON`` environment variable. 127