Projects/Host-realm pluggable interface

This is an early stage project for MIT Kerberos. It is being fleshed out by its proponents. Feel free to help flesh out the details of this project. After the project is ready, it will be presented for review and approval.

Description

This project adds a pluggable interface for host-to-realm mapping.

Background

The krb5_get_host_realm() function attempts to map a hostname to one or more realm names. We never return more than one answer, and all existing in-tree consumers of this function use only the first answer. One of the possible answers is an empty realm, which means referrals should be used if the consumer is making a TGS request. krb5_get_host_realm() is used by krb5_sname_to_principal(), and also by the KDC in order to produce host referrals.

The krb5_get_fallback_realm() function attempts to map a hostname to one or more realms as well, using more heuristic or insecure approaches than krb5_get_host_realm(). We never return or consume more than one answer. krb5_get_fallback_realm() is used by the libkrb5 TGS request code path if we get an error from trying referrals.

The krb5_get_default_realm() function returns a default realm for the local host (although it may be overridden for a particular context using krb5_set_default_realm()). It is used chiefly by krb5_parse_name() when the string form of the principal contains no realm, but is also used in many other ways.

The currently supported mechanisms for these functions are:

• krb5_get_host_realm() only uses the profile [domain_realm] section. If it cannot get a mapping that way, it returns the referral realm.

• krb5_get_fallback_realm() has several heuristics:
  • With explicit configuration, we can use a TXT record lookup of the hostname.
  • With explicit configuration, we can try to resolve the uppercased parent domains as realms, to a specified depth.
  • We can use the uppercased parent domain.
  • We can use the default realm.

• krb5_get_default_realm() only uses the profile default_realm value.

krb5_get_host_realm() and krb5_get_fallback_realm() "clean" their input hostname by converting it to lower-case and removing any trailing period.

krb5_sname_to_principal() canonicalizes its input hostname using a forward getaddrinfo() lookup and usually a reverse getnameinfo() lookup, before calling krb5_get_host_realm().

The behavior of these functions has changed over time. Prior to the introduction of TGS referral support in 1.6, we did not have krb5_get_fallback_host_realm(), and krb5_get_host_realm() applied most of the heuristics currently applied by that function.

Scope questions

krb5_get_host_realm() and krb5_get_default_realm() are clearly in scope.

• Should krb5_get_default_realm() be in scope?
• Should hostname canonicalization be in scope?
• Should hostname cleaning be in scope?
• Should plugin modules be able to return multiple answers?

Plugin module ordering

This is the fourth pluggable interface (after locate, ccselect, and localauth) which have no natural way to order modules, and whose accumulator behavior is order-dependent for some operations. We can improve the predictability of these interfaces by providing a well-defined order for plugin modules. This project proposes the following ordering constraints, which do not require the addition of any new user-visible options or internal APIs:

• The default order is the dynamic modules in the order they were registered in the profile, followed by the built-in modules in the order they were registered by the code.

• If any modules are disabled, they are removed without affecting the order of the remaining modules.

• If modules are explicitly enabled with enable_only, the order of the enable_only list determines the order of the modules.