WARNING: This documentation is for an old version of Exim (latest)
Chapter 38 - The gsasl authenticator
The gsasl authenticator provides server integration for the GNU SASL library and the mechanisms it provides. This is new as of the 4.80 release and there are a few areas where the library does not let Exim smoothly scale to handle future authentication mechanisms, so no guarantee can be made that any particular new authentication mechanism will be supported without code changes in Exim.
| server_channelbinding | Use: gsasl | Type: boolean | Default: false |
Some authentication mechanisms are able to use external context at both ends of the session to bind the authentication to that context, and fail the authentication process if that context differs. Specifically, some TLS ciphersuites can provide identifying information about the cryptographic context.
This means that certificate identity and verification becomes a non-issue, as a man-in-the-middle attack will cause the correct client and server to see different identifiers and authentication will fail.
This is currently only supported when using the GnuTLS library. This is only usable by mechanisms which support "channel binding"; at time of writing, that’s the SCRAM family.
This defaults off to ensure smooth upgrade across Exim releases, in case this option causes some clients to start failing. Some future release of Exim may switch the default to be true.
| server_hostname | Use: gsasl | Type: string† | Default: see below |
This option selects the hostname that is used when communicating with the
library. The default value is $primary_hostname.
Some mechanisms will use this data.
| server_mech | Use: gsasl | Type: string | Default: see below |
This option selects the authentication mechanism this driver should use. The default is the value of the generic public_name option. This option allows you to use a different underlying mechanism from the advertised name. For example:
sasl: driver = gsasl public_name = X-ANYTHING server_mech = CRAM-MD5 server_set_id = $auth1
| server_password | Use: gsasl | Type: string† | Default: unset |
Various mechanisms need access to the cleartext password on the server, so that proof-of-possession can be demonstrated on the wire, without sending the password itself.
The data available for lookup varies per mechanism. In all cases, $auth1 is set to the authentication id. The $auth2 variable will always be the authorization id (authz) if available, else the empty string. The $auth3 variable will always be the realm if available, else the empty string.
A forced failure will cause authentication to defer.
If using this option, it may make sense to set the server_condition option to be simply "true".
| server_realm | Use: gsasl | Type: string† | Default: unset |
This specifies the SASL realm that the server claims to be in. Some mechanisms will use this data.
| server_scram_iter | Use: gsasl | Type: string† | Default: unset |
This option provides data for the SCRAM family of mechanisms. $auth1 is not available at evaluation time. (This may change, as we receive feedback on use)
| server_scram_salt | Use: gsasl | Type: string† | Default: unset |
This option provides data for the SCRAM family of mechanisms. $auth1 is not available at evaluation time. (This may change, as we receive feedback on use)
| server_service | Use: gsasl | Type: string | Default: smtp
|
This is the SASL service that the server claims to implement. Some mechanisms will use this data.
1. gsasl auth variables
These may be set when evaluating specific options, as detailed above. They will also be set when evaluating server_condition.
Unless otherwise stated below, the gsasl integration will use the following meanings for these variables:
-
$auth1: the authentication id
-
$auth2: the authorization id
-
$auth3: the realm
On a per-mechanism basis:
-
EXTERNAL: only $auth1 is set, to the possibly empty authorization id; the server_condition option must be present.
-
ANONYMOUS: only $auth1 is set, to the possibly empty anonymous token; the server_condition option must be present.
-
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.
An anonymous token is something passed along as an unauthenticated identifier; this is analogous to FTP anonymous authentication passing an email address, or software-identifier@, as the "password".
An example showing the password having the realm specified in the callback and demonstrating a Cyrus SASL to GSASL migration approach is:
gsasl_cyrusless_crammd5:
driver = gsasl
public_name = CRAM-MD5
server_realm = imap.example.org
server_password = ${lookup{$auth1:$auth3:userPassword}\
dbmjz{/etc/sasldb2}{$value}fail}
server_set_id = ${quote:$auth1}
server_condition = yes
