7.3. AUTH

The AUTH context allows trusted SMTP clients. The SASL mechanisms LOGIN and PLAIN are implemented in the SMTP engine and will populate the $saslusername and $saslpassword. If you add support for custom authentication mechanisms you will need to use the $saslmechanism, $saslstate and $saslresponse variables to do so.

7.3.1. Pre-defined variables

These are the read-only pre-defined variables available for each AUTH command.

7.3.1.1. Connection

Variable Type Example Description
$senderip string “192.168.1.11” IP address of the connected client
$senderport number 41666 TCP port of connected client
$serverip string “10.0.0.1” IP address of the mailserver
$serverport number 25 TCP port of the mailserver
$serverid string “mailserver:1” ID of the mailserver profile
$senderhelo string “mail.example.com” HELO message of sender
$tlsstarted boolean false Whether or not the SMTP session is using TLS

These are the writable pre-defined variables available.

Variable Type Description
$context any Connection-bound variable

7.3.1.2. Transaction

Variable Type Example Description
$messageid string “18c190a3-93f-47d7-bd...” ID of the message

7.3.1.3. Arguments

Variable Type Example Description
$saslusername string “mailuser” SASL username
$saslpassword string “secret” SASL password
$saslmechanism string “PLAIN” SASL mechanism (always in uppercase)
$saslstate number 0 SASL state (incremeted per Reply)
$saslresponse string none SASL response (not used with LOGIN or PLAIN)

7.3.2. Functions

auth.Accept([options])

Authorize the login request.

Parameters:options (array) – an options array
Returns:doesn’t return, script is terminated

The following options are available in the options array.

  • username (string) set the username. The default is $saslusername (if available).
auth.Reject([reason[, options]])

Reject the login request.

Parameters:
  • reason (string or array) – reject message with reason
  • options (array) – an options array
Returns:

doesn’t return, script is terminated

The following options are available in the options array.

  • disconnect (boolean) disconnect the client. The default is false.
  • reply_codes (array) The array may contain code (number) and enhanced (array of three numbers). The default is pre-defined.
auth.Defer([reason[, options]])

Defer the login request with a temporary (454) error.

Parameters:
  • reason (string or array) – defer message with reason
  • options (array) – an options array
Returns:

doesn’t return, script is terminated

The following options are available in the options array.

  • disconnect (boolean) disconnect the client. The default is false.
  • reply_codes (array) The array may contain code (number) and enhanced (array of three numbers). The default is pre-defined.
auth.Reply([reply[, options]])

Send a reply (334) message. The reply will be base64 encoded before sent to the client. This function is used to implement custom authentication mechanisms.

Parameters:
  • reply (string) – the reply message
  • options (array) – an options array
Returns:

doesn’t return, script is terminated
Updates:

$saslstate

The following options are available in the options array.

  • disconnect (boolean) disconnect the client. The default is false.
  • reply_codes (array) The array may contain code (number) and enhanced (array of three numbers). The default is pre-defined.
auth.GetTLS([options])

Get the TLS information for a connection.

Parameters:options (array) – options array
Return type:array

The following options are available in the options array.

  • fingerprint (string) Generate the fingerprint of the certificate using one of the following hash function (md5, sha1, sha256 or sha512). The default no hashing.

The following items are available in the result.

  • started (boolean) If STARTTLS was issued.
  • protocol (string) The protocol used (eg. TLSv1.2)
  • ciphers (string) The cipher used (eg. ECDHE-RSA-AES256-SHA384).
  • keysize (number) The keysize used (eg. 256).
  • peer_cert (array) The peer certificate (if provided by the client). Same format as TLSSocket.getpeercert().
  • peer_cert_error (number) The peer certificate validation error (see OpenSSLs SSL_get_verify_result(3)).

7.3.3. On script error

On script error Defer() is called.

7.3.4. On implicit termination

If not explicitly terminated then Reject() is called.

7.3.5. Authentication diagram

A flow chart diagram of how custom authentication is implemented:

             +--------------+
             | AUTH request |
             +--------------+
                    |
                    |
                    v
+---------------------------------------+
|   $saslstate = 0                      |
+---------------------------------------+      Accept()      +-------------------+
| > AUTH $saslmechanism [$saslresponse] | ---- Reject() ---> | AUTH request done |
+---------------------------------------+      Defer()       +-------------------+
                    |                             ^
                    |                             |
                  Reply() <------------------+    |
                    |                        |    |
                    |                        |    |
                    v                        |    |
+---------------------------------------+    |    |
|   $saslstate += 1                     |    |    |
+---------------------------------------+    |    |
| > $saslresponse                       | ---+----+
+---------------------------------------+    |
                    |                        |
                    |                        |
                    +------------------------+