X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/c1e794ba50d0d5a73529412929228ae5c5d09073..f1e05cc79778c693a1a2bad478ced44791922cce:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index d7172df8a..9c39b4aa2 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -1868,6 +1868,14 @@ SUPPORT_TLS=yes TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto TLS_INCLUDE=-I/usr/local/openssl/include/ .endd +.new +.cindex "pkg-config" "OpenSSL" +If you have &'pkg-config'& available, then instead you can just use: +.code +SUPPORT_TLS=yes +USE_OPENSSL_PC=openssl +.endd +.wen .cindex "USE_GNUTLS" If GnuTLS is installed, you should set .code @@ -1883,6 +1891,16 @@ USE_GNUTLS=yes TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt TLS_INCLUDE=-I/usr/gnu/include .endd +.new +.cindex "pkg-config" "GnuTLS" +If you have &'pkg-config'& available, then instead you can just use: +.code +SUPPORT_TLS=yes +USE_GNUTLS=yes +USE_GNUTLS_PC=gnutls +.endd +.wen + You do not need to set TLS_INCLUDE if the relevant directory is already specified in INCLUDE. Details of how to configure Exim to make use of TLS are given in chapter &<>&. @@ -2110,6 +2128,28 @@ files or libraries are required. When a lookup type is not included in the binary, attempts to configure Exim to use it cause run time configuration errors. +.new +.cindex "pkg-config" "lookups" +.cindex "pkg-config" "authenticators" +Many systems now use a tool called &'pkg-config'& to encapsulate information +about how to compile against a library; Exim has some initial support for +being able to use pkg-config for lookups and authenticators. For any given +makefile variable which starts &`LOOKUP_`& or &`AUTH_`&, you can add a new +variable with the &`_PC`& suffix in the name and assign as the value the +name of the package to be queried. The results of querying via the +&'pkg-config'& command will be added to the appropriate Makefile variables +with &`+=`& directives, so your version of &'make'& will need to support that +syntax. For instance: +.code +LOOKUP_SQLITE=yes +LOOKUP_SQLITE_PC=sqlite3 +AUTH_GSASL=yes +AUTH_GSASL_PC=libgsasl +AUTH_HEIMDAL_GSSAPI=yes +AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi +.endd +.wen + .cindex "Perl" "including support for" Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines to be called during string expansion. To enable this facility, @@ -11784,6 +11824,16 @@ command in a filter file. Its use is explained in the description of that command, which can be found in the separate document entitled &'Exim's interfaces to mail filtering'&. +.new +.vitem &$tls_bits$& +.vindex "&$tls_bits$&" +Contains an approximation of the TLS cipher's bit-strength; the meaning of +this depends upon the TLS implementation used. +If TLS has not been negotiated, the value will be 0. +The value of this is automatically fed into the Cyrus SASL authenticator +when acting as a server, to specify the "external SSF" (a SASL term). +.wen + .vitem &$tls_certificate_verified$& .vindex "&$tls_certificate_verified$&" This variable is set to &"1"& if a TLS certificate was verified when the @@ -23399,6 +23449,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 +23462,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 +23514,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 +24252,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 &<>& .wen @@ -24442,8 +24499,8 @@ ANONYMOUS: only &$auth1$& is set, to the possibly empty &'anonymous token'&; the &%server_condition%& option must be present. .next .cindex "authentication" "GSSAPI" -GSSAPI: &$auth1$& will be set to the &'authorization id'&, -&$auth2$& will be set to the &'GSSAPI Display Name'&; +GSSAPI: &$auth1$& will be set to the &'GSSAPI Display Name'&; +&$auth2$& will be set to the &'authorization id'&, the &%server_condition%& option must be present. .endlist @@ -24456,6 +24513,57 @@ 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_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@EXAMPLE.ORG"&. + +.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)&"