7.4. AUTH

The AUTH script allows trusted SMTP clients. The SASL mechanisms LOGIN and PLAIN are implemented in the SMTP engine and will populate the username and password argument. If you add support for custom authentication mechanisms you will need to use the mechanism, state and response arguments instead.

7.4.1. Variables

These are the pre-defined variables available.

Variable Type Read-only Description
$arguments array yes Context/hook arguments
$connection array yes Connection/session bound
$transaction array yes Transaction bound
$context any no Connection bound user-defined (default none)

7.4.1.1. Arguments

Array item Type Example Description
username string “mailuser” SASL username (only available with LOGIN or PLAIN)
password string “secret” SASL password (only available with LOGIN or PLAIN)
mechanism string “PLAIN” SASL mechanism (always in uppercase)
state number 0 SASL state, incremeted per Reply (not available with LOGIN or PLAIN)
response string none SASL response (not available with LOGIN or PLAIN)

7.4.1.2. Connection

Array item Type Example Description
remoteip string “192.168.1.11” IP address of the connected client
remoteport number 41666 TCP port of connected client
localip string “10.0.0.1” IP address of the server
localport number 25 TCP port of the server
serverid string “inbound” ID of the server
helo array   HELO information (not always available)
tls array   TLS information (if TLS was started)

7.4.1.2.1. HELO

Array item Type Example Description
verb string “EHLO” HELO or EHLO command
host string “mail.example.com” HELO hostname

7.4.1.2.2. TLS

Array item Type Example Description
protocol string “TLSv1.3” The protocol
cipher string “ECDHE-RSA-AES256-SHA384” The cipher
keysize number 256 The keysize
peercert array   The peer certificate (if provided by the client)
7.4.1.2.2.1. Peercert
Array item Type Example Description
x509 X509Resource   An X509Resource to be used with the X509 class
error number 18 The peer certificate validation error (see OpenSSLs SSL_get_verify_result(3))

7.4.1.3. Transaction

Array item Type Example Description
id string “18c190a3-93f-47d7-bd...” ID of the transaction

7.4.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 or change the username. The default is the username argument (if available).
  • reason (string) The reason to report. The default is a system generated message.
  • reply_codes (array) The array may contain code (number) and enhanced (array of three numbers). The default is pre-defined.
auth.Reject([reason[, options]])

Reject the login request with a permanent (535) error.

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
Increments:

state argument
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.GetMailQueueMetric([options])

Return metric information about the mail queue, it can be used to enforce quotas.

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

The following options are available in the options array.

  • metric (string) Metric to be returned; count or bytes. The default is count.
  • filter (array) Any of the available filters, see below. The default is no filters.

The following filters are available in the filters array.

Type Example
remoteip $connection[“remoteip”]
saslusername $connection[“auth”][“username”]
sender $transaction[“sender”]
senderdomain $transaction[“senderaddress”][“domain”]
recipient $transaction[“recipients”][0][“recipient”]
recipientdomain $transaction[“recipients”][0][“address”][“domain”]
transportid $transaction[“recipients”][0][“transportid”]
retry 1
metadata.x any metadata 
$queuesize = GetMailQueueMetric(
        [
                "metric" => "bytes",
                "filter" => [
                        "senderdomain" => ["example.com" , "example.net"],
                        "transportid" => "mailtransport:2"
                ]
        ]
) / 1024 / 1024;
if ($queuesize > 500) {
        Defer("Current queue for mailtransport:2 exceeds 500 MiB");
}

Note

If multiple filters of the same type are given using array notation, any of them may match.

7.4.3. On script error

On script error Defer() is called.

7.4.4. On implicit termination

If not explicitly terminated then Reject() is called.

7.4.5. Authentication diagram

A flow chart diagram of how custom authentication is implemented:

             +--------------+
             | AUTH request |
             +--------------+
                    |
                    |
                    v
+---------------------------------------+
|   state = 0                           |
+---------------------------------------+      Accept()      +-------------------+
| > AUTH mechanism [response]           | ---- Reject() ---> | AUTH request done |
+---------------------------------------+      Defer()       +-------------------+
                    |                             ^
                    |                             |
                  Reply() <------------------+    |
                    |                        |    |
                    |                        |    |
                    v                        |    |
+---------------------------------------+    |    |
|   state += 1                          |    |    |
+---------------------------------------+    |    |
| > response                            | ---+----+
+---------------------------------------+    |
                    |                        |
                    |                        |
                    +------------------------+