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
id	string	“18c190a3-93f-47d7-bd…”	ID of the connection
priority	number	1	The connection priority
remoteip	string	“192.168.1.11”	IP address of the connected client
remoteport	number	41666	TCP port of connected client
remoteptr	string	“mail.example.org”	Reverse DNS (FCrDNS) for remoteip (not always available)
remoteuid	number	106	UNIX socket remote user id (not always available)
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
sni	string	“example.com”	The SNI hostname (not always available)
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 or array) 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). To remove the enhanced code set it to [0,0,0]. The default code is 235 and enhanced is [2,7,0].

priority (number) Change the connection priority (0 normal, 1 high).

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). To remove the enhanced code set it to [0,0,0]. The default code is 535 and enhanced is [5,7,8].

priority (number) Change the connection priority (0 normal, 1 high).

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). To remove the enhanced code set it to [0,0,0]. The default code is 454 and enhanced is [4,7,0].

priority (number) Change the connection priority (0 normal, 1 high).

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). To remove the enhanced code set it to [0,0,0]. The default code is 334 and enhanced is not used.

priority (number) Change the connection priority (0 normal, 1 high).

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                            | ---+----+
+---------------------------------------+    |
                    |                        |
                    |                        |
                    +------------------------+