The Postfix policy delegation protocol is really simple. The
client request is a sequence of name=value attributes separated by
newline, and is terminated by an empty line. The server reply is
one name=value attribute and it, too, is terminated by an empty
line.
Here is an example of all the attributes that the Postfix SMTP
server sends in a delegated SMTPD access policy request:
request=smtpd_access_policy
protocol_state=RCPT
protocol_name=SMTP
helo_name=some.domain.tld
queue_id=8045F2AB23
[email protected]
[email protected]
recipient_count=0
client_address=1.2.3.4
client_name=another.domain.tld
reverse_client_name=another.domain.tld
instance=123.456.7
Postfix version 2.2 and later:
sasl_method=plain
sasl_username=you
sasl_sender=
size=12345
ccert_subject=solaris9.porcupine.org
ccert_issuer=Wietse+20Venema
ccert_fingerprint=C2:9D:F4:87:71:73:73:D9:18:E7:C2:F3:C1:DA:6E:04
Postfix version 2.3 and later:
encryption_protocol=TLSv1/SSLv3
encryption_cipher=DHE-RSA-AES256-SHA
encryption_keysize=256
etrn_domain=
[empty line]
Notes:
-
The "request" attribute is required. In this example
the request type is "smtpd_access_policy".
-
The order of the attributes does not matter. The policy
server should ignore any attributes that it does not care about.
-
When the same attribute name is sent more than once,
the server may keep the first value or the last attribute value.
-
When an attribute value is unavailable, the client
either does not send the attribute, sends the attribute with
an empty value ("name="), or sends a zero value ("name=0") in
the case of a numerical attribute.
-
The "recipient" attribute is available only in the
"RCPT TO" stage, and in the "DATA" and "END-OF-MESSAGE" stages
when Postfix accepted only one recipient for the current message.
-
The "recipient_count" attribute (Postfix 2.3 and later)
is non-zero only in the "DATA" and "END-OF-MESSAGE" stages. It
specifies the number of recipients that Postfix accepted for
the current message.
-
The client address is an IPv4 dotted quad in the form
1.2.3.4 or it is an IPv6 address in the form 1:2:3::4:5:6.
-
For a discussion of the differences between reverse
and verified client_name information, see the
reject_unknown_client_hostname discussion in the
postconf(5)
document.
-
An attribute name must not contain "=", null or newline,
and an attribute value must not contain null or newline.
-
The "instance" attribute value can be used to correlate
different requests regarding the same message delivery.
-
The "size" attribute value specifies the message size
that the client specified in the MAIL FROM command (zero if
none was specified). With Postfix 2.2 and later, it specifies
the actual message size when the client sends the END-OF-DATA
command.
-
The "sasl_*" attributes (Postfix 2.2 and later) specify
information about how the client was authenticated via SASL.
These attributes are empty in case of no SASL authentication.
-
The "ccert_*" attributes (Postfix 2.2 and later) specify
information about how the client was authenticated via TLS.
These attributes are empty in case of no certificate authentication.
As of Postfix 2.2.11 these attribute values are encoded as
xtext: some characters are represented by +XX, where XX is the
two-digit hecadecimal representation of the character value.
-
The "encryption_*" attributes (Postfix 2.3 and later)
specify information about how the connection is encrypted. With
plaintext connections the protocol and cipher attributes are
empty and the keysize is zero.
-
The "etrn_domain" attribute is defined only in the
context of the ETRN command, and specifies the ETRN command
parameter.
The following is specific to SMTPD delegated policy requests:
-
Protocol names are ESMTP or SMTP.
-
Protocol states are CONNECT, EHLO, HELO, MAIL, RCPT,
DATA, END-OF-MESSAGE, VRFY or ETRN; these are the SMTP protocol
states where
the Postfix SMTP server makes an OK/REJECT/HOLD/etc. decision.
The policy server replies with any action that is allowed in a
Postfix SMTPD
access(5) table. Example:
action=
defer_if_permit Service temporarily unavailable
[empty line]
This causes the Postfix SMTP server to reject the request with
a 450 temporary error code and with text "Service temporarily
unavailable", if the Postfix SMTP server finds no reason to reject
the request permanently.
In case of trouble the policy server must not send a reply.
Instead the server must log a warning and disconnect. Postfix will
retry the request at some later time.
