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

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). 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.

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