Exim Internet Mailer

<-previousnext->

XWARNING: 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.

Exim’s gsasl authenticator does not have client-side support at this time; only the server-side support is implemented. Patches welcome.

server_channelbinding Use: gsasl Type: boolean Default: false

Do not set this true without consulting a cryptographic engineer.

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 should have meant 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 might have switched the default to be true.

However, Channel Binding in TLS has proven to be broken in current versions. Do not plan to rely upon this feature for security, ever, without consulting with a subject matter expert (a cryptographic engineer).

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
<-previousTable of Contentsnext->