7.2. 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.2.1. Pre-defined variables¶
These are the read-only pre-defined variables available for each AUTH command.
7.2.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.2.1.2. Transaction¶
Variable | Type | Example | Description |
---|---|---|---|
$messageid | string | “18c190a3-93f-47d7-bd...” | ID of the message |
7.2.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.2.2. Functions¶
-
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).
- username (string) set the username. The default is
-
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.
-
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.
-
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.
-
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
orsha512
). 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)).
- fingerprint (string) Generate the fingerprint of the certificate using one of the following hash function (
7.2.3. On script error¶
On script error Defer()
is called.
7.2.4. On implicit termination¶
If not explicitly terminated then Reject()
is called.
7.2.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 | ---+----+
+---------------------------------------+ |
| |
| |
+------------------------+