[exim-cvs] Document heimdal_gssapi as it works now.

Top Page

Reply to this message
Author: Exim Git Commits Mailing List
Date:  
To: exim-cvs
Subject: [exim-cvs] Document heimdal_gssapi as it works now.
Gitweb: http://git.exim.org/exim.git/commitdiff/9775396084feef071a7c565d6d9b42839ae6098e
Commit:     9775396084feef071a7c565d6d9b42839ae6098e
Parent:     b245b4a5b28e1011655ce3b6ac5051ba6c517299
Author:     Phil Pennock <pdp@???>
AuthorDate: Sat Feb 18 04:56:19 2012 -0500
Committer:  Phil Pennock <pdp@???>
CommitDate: Sat Feb 18 04:56:19 2012 -0500


    Document heimdal_gssapi as it works now.
---
 doc/doc-docbook/spec.xfpt |   75 ++++++++++++++++++++++++++++++++++++++++----
 doc/doc-txt/ChangeLog     |    5 +++
 doc/doc-txt/NewStuff      |    5 +++
 3 files changed, 78 insertions(+), 7 deletions(-)


diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index d7172df..9b59f05 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -23399,6 +23399,7 @@ AUTH_CYRUS_SASL=yes
.new
AUTH_DOVECOT=yes
AUTH_GSASL=yes
+AUTH_HEIMDAL_GSSAPI=yes
.wen
AUTH_PLAINTEXT=yes
AUTH_SPA=yes
@@ -23411,9 +23412,11 @@ The third is an interface to Dovecot's authentication system, delegating the
work via a socket interface.
The fourth provides an interface to the GNU SASL authentication library, which
provides mechanisms but typically not data sources.
-The fifth can be configured to support
+The fifth provides direct access to Heimdal GSSAPI, geared for Kerberos, but
+supporting setting a server keytab.
+The sixth can be configured to support
the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, which is
-not formally documented, but used by several MUAs. The sixth authenticator
+not formally documented, but used by several MUAs. The seventh authenticator
supports Microsoft's &'Secure Password Authentication'& mechanism.
.wen

@@ -23461,7 +23464,9 @@ used to authenticate; servers may have rules to permit one user to act as a
second user, so that after login the session is treated as though that second
user had logged in. That second user is the &'authorization id'&. A robust
configuration might confirm that the &'authz'& field is empty or matches the
-&'authn'& field. Often this is just ignored.
+&'authn'& field. Often this is just ignored. The &'authn'& can be considered
+as verified data, the &'authz'& as an unverified request which the server might
+choose to honour.

A &'realm'& is a text string, typically a domain name, presented by a server
to a client to help it select an account and credentials to use. In some
@@ -24197,14 +24202,16 @@ be set in &_exim.conf_& in your SASL directory. If you are using GSSAPI for
Kerberos, note that because of limitations in the GSSAPI interface,
changing the server keytab might need to be communicated down to the Kerberos
layer independently. The mechanism for doing so is dependent upon the Kerberos
-implementation. For example, for Heimdal, the environment variable KRB5_KTNAME
+implementation.
+.new
+For example, for older releases of Heimdal, the environment variable KRB5_KTNAME
may be set to point to an alternative keytab file. Exim will pass this
variable through from its own inherited environment when started as root or the
Exim user. The keytab file needs to be readable by the Exim user.
-.new
-With some releases of Heimdal, a setuid Exim may cause Heimdal to discard the
+With newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the
environment variable. In practice, for those releases, the Cyrus authenticator
-is not a suitable interface for GSSAPI (Kerberos) support.
+is not a suitable interface for GSSAPI (Kerberos) support. Instead, consider
+the &(heimdal_gssapi)& authenticator, described in chapter &<<CHAPheimdalgss>>&
.wen


@@ -24456,6 +24463,60 @@ email address, or software-identifier@, as the "password".
. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////

+.new
+.chapter "The heimdal_gssapi authenticator" "CHAPheimdalgss"
+.scindex IIDheimdalgssauth1 "&(heimdal_gssapi)& authenticator"
+.scindex IIDheimdalgssauth2 "authenticators" "&(heimdal_gssapi)&"
+.cindex "authentication" "GSSAPI"
+.cindex "authentication" "Kerberos"
+The &(heimdal_gssapi)& authenticator provides server integration for the
+Heimdal GSSAPI/Kerberos library, permitting Exim to set a keytab pathname
+reliably.
+
+.option server_hostname heimdal_gssapi string&!! "see below"
+This option selects the hostname that is used, with &%server_service%&,
+for constructing the GSS server name, as a &'GSS_C_NT_HOSTBASED_SERVICE'&
+identifier. The default value is &`$primary_hostname`&.
+
+.option server_keytab heimdal_gssapi string&!! unset
+If set, then Heimdal will not use the system default keytab (typically
+&_/etc/krb5.keytab_&) but instead the pathname given in this option.
+The value should be a pathname, with no &"file:"& prefix.
+
+.option server_realm heimdal_gssapi string&!! unset
+Er, unused. XXXFIXMEXXX
+
+.option server_service heimdal_gssapi string&!! "smtp"
+This option specifies the service identifier used, in conjunction with
+&%server_hostname%&, for building the identifer for finding credentials
+from the keytab.
+
+
+.section "&(heimdal_gssapi)& auth variables" "SECTheimdalgssauthvar"
+Beware that these variables will typically include a realm, thus will appear
+to be roughly like an email address already. The &'authzid'& in &$auth2$& is
+not verified, so a malicious client can set it to anything.
+
+The &$auth1$& field should be safely trustable as a value from the Key
+Distribution Center. Note that these are not quite email addresses.
+Each identifier is for a role, and so the left-hand-side may include a
+role suffix. For instance, &"joe/admin@???"&.
+
+.vindex "&$auth1$&, &$auth2$&, etc"
+.ilist
+.vindex "&$auth1$&"
+&$auth1$&: the &'authentication id'&, set to the GSS Display Name.
+.next
+.vindex "&$auth2$&"
+&$auth2$&: the &'authorization id'&, sent within SASL encapsulation after
+authentication.
+.endlist
+
+.wen
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
.chapter "The spa authenticator" "CHAPspa"
.scindex IIDspaauth1 "&(spa)& authenticator"
.scindex IIDspaauth2 "authenticators" "&(spa)&"
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index 30cc10e..75d5ccd 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -17,6 +17,11 @@ NM/03 Bugzilla 1169 - primary_hostname spelling was incorrect in docs.

PP/02 Implemented gsasl authenticator.

+PP/03 Implemented heimdal_gssapi authenticator with "server_keytab" option.
+
+PP/04 Local/Makefile support for (AUTH|LOOKUP)_*_PC=foo to use
+      `pkg-config foo` for cflags/libs.
+


 Exim version 4.77
 -----------------
diff --git a/doc/doc-txt/NewStuff b/doc/doc-txt/NewStuff
index 3ca10e8..4521d7d 100644
--- a/doc/doc-txt/NewStuff
+++ b/doc/doc-txt/NewStuff
@@ -18,6 +18,11 @@ Version 4.78
     Exim is currently unable to construct strings with embedded NULs for
     use as keys in lookups against sasldb2.


+ 2. New authenticator driver, "heimdal_gssapi".  Server-only.
+    A replacement for using cyrus_sasl with Heimdal, now that $KRB5_KTNAME
+    is no longer honoured for setuid programs by Heimdal.  Use the
+    "server_keytab" option to point to the keytab.
+


Version 4.77
------------