400 lines
15 KiB
HTML
400 lines
15 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"https://www.w3.org/TR/html4/loose.dtd">
|
|
|
|
<html>
|
|
|
|
<head>
|
|
|
|
<title>Postfix SMTPUTF8 support</title>
|
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
|
|
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">
|
|
Postfix SMTPUTF8 support
|
|
</h1>
|
|
|
|
<hr>
|
|
|
|
<h2> Overview </h2>
|
|
|
|
<p> This document describes Postfix support for Email Address
|
|
Internationalization (EAI) as defined in <a href="https://tools.ietf.org/html/rfc6531">RFC 6531</a> (SMTPUTF8 extension),
|
|
<a href="https://tools.ietf.org/html/rfc6532">RFC 6532</a> (Internationalized email headers) and <a href="https://tools.ietf.org/html/rfc6533">RFC 6533</a> (Internationalized
|
|
delivery status notifications). Introduced with Postfix version
|
|
3.0, this fully supports UTF-8 email addresses and UTF-8 message
|
|
header values. </p>
|
|
|
|
<p> Topics covered in this document: </p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#building">Building with/without SMTPUTF8 support</a>
|
|
|
|
<li><a href="#enabling">Enabling Postfix SMTPUTF8 support</a>
|
|
|
|
<li><a href="#using">Using Postfix SMTPUTF8 support</a>
|
|
|
|
<li><a href="#detecting">SMTPUTF8 autodetection</a>
|
|
|
|
<li><a href="#limitations">Limitations of the current implementation</a>
|
|
|
|
<li><a href="#compatibility">Compatibility with pre-SMTPUTF8 environments</a>
|
|
|
|
<li><a href="#idna2003">Compatibility with IDNA2003</a>
|
|
|
|
<li><a href="#credits">Credits</a>
|
|
|
|
</ul>
|
|
|
|
<h2> <a name="building">Building Postfix with/without SMTPUTF8 support</a> </h2>
|
|
|
|
<p> Postfix will build with SMTPUTF8 support if the ICU version
|
|
≥ 46 library and header files are installed on the system. The
|
|
package name varies with the OS distribution. The table shows package
|
|
names for a number of platforms at the time this text was written.
|
|
</p>
|
|
|
|
<blockquote>
|
|
|
|
<table border="1">
|
|
|
|
<tr> <th> OS Distribution </th> <th> Package </th> </tr>
|
|
|
|
<tr> <td> FreeBSD, NetBSD, etc. </td> <td> icu </td> </tr>
|
|
|
|
<tr> <td> Centos, Fedora, RHEL </td> <td> libicu-devel </td> </tr>
|
|
|
|
<tr> <td> Debian, Ubuntu </td> <td> libicu-dev </td> </tr>
|
|
|
|
</table>
|
|
|
|
</blockquote>
|
|
|
|
<p> To force Postfix to build without SMTPUTF8, specify: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
$ <b>make makefiles CCARGS="-DNO_EAI ..."</b>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> See the <a href="INSTALL.html">INSTALL</a> document for more "make makefiles" options. </p>
|
|
|
|
<h2> <a name="enabling">Enabling Postfix SMTPUTF8 support</a> </h2>
|
|
|
|
<p> There is more to SMTPUTF8 than just Postfix itself. The rest
|
|
of your email infrastructure also needs to be able to handle UTF-8
|
|
email addresses and message header values. This includes SMTPUTF8
|
|
protocol support in SMTP-based content filters (Amavisd), LMTP
|
|
servers (Dovecot), and down-stream SMTP servers. </p>
|
|
|
|
<p> Postfix SMTPUTF8 support is enabled by default, but it may be
|
|
disabled as part of a backwards-compatibility safety net (see the
|
|
<a href="COMPATIBILITY_README.html">COMPATIBILITY_README</a> file). </p>
|
|
|
|
<p> SMTPUTF8 support is enabled by setting the <a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a>
|
|
parameter in <a href="postconf.5.html">main.cf</a>:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
# <b>postconf "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes"</b>
|
|
# <b>postfix reload</b>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> (With Postfix ≤ 3.1, you may also need to specify "<b>option_group
|
|
= client</b>" in Postfix MySQL client files, to enable UTF8 support
|
|
in MySQL queries. This setting is the default as of Postfix 3.2.) </p>
|
|
|
|
<p> With SMTPUTF8 support enabled, Postfix changes behavior with
|
|
respect to earlier Postfix releases: </p>
|
|
|
|
<ul>
|
|
|
|
<li> <p> UTF-8 is permitted in the <a href="postconf.5.html#myorigin">myorigin</a> parameter value. However,
|
|
the <a href="postconf.5.html#myhostname">myhostname</a> and <a href="postconf.5.html#mydomain">mydomain</a> parameters must currently specify
|
|
ASCII-only domain names. This limitation may be removed later. </p>
|
|
|
|
<li> <p> UTF-8 is the only form of non-ASCII text that Postfix
|
|
supports in access tables, address rewriting tables, and other
|
|
tables that are indexed with an email address, hostname, or domain
|
|
name. </p>
|
|
|
|
<li> <p> The <a href="postconf.5.html#header_checks">header_checks</a>-like and <a href="postconf.5.html#body_checks">body_checks</a>-like features are
|
|
not UTF-8 enabled, and therefore they do not enforce UTF-8 syntax
|
|
rules on inputs and outputs. The reason is that non-ASCII text may
|
|
be sent in encodings other than UTF-8, and that real email sometimes
|
|
contains malformed headers. Instead of skipping non-UTF-8 content,
|
|
Postfix should be able to filter it. You may try to enable UTF-8
|
|
processing by starting a PCRE pattern with the sequence (*UTF8),
|
|
but this is will result in "message not accepted, try again later"
|
|
errors when the PCRE pattern matcher encounters non-UTF-8 input.
|
|
Other features that are not UTF-8 enabled are <a href="postconf.5.html#smtpd_command_filter">smtpd_command_filter</a>,
|
|
<a href="postconf.5.html#smtp_reply_filter">smtp_reply_filter</a>, the *_delivery_status_filter features, and the
|
|
*_dns_reply_filter features (the latter because DNS is by definition
|
|
an ASCII protocol). </p>
|
|
|
|
<li> <p> The Postfix SMTP server announces SMTPUTF8 support in the
|
|
EHLO response. </p>
|
|
|
|
<pre>
|
|
220 server.example.com ESMTP Postfix
|
|
<b>EHLO client.example.com</b>
|
|
250-server.example.com
|
|
250-PIPELINING
|
|
250-SIZE 10240000
|
|
250-VRFY
|
|
250-ETRN
|
|
250-STARTTLS
|
|
250-AUTH PLAIN LOGIN
|
|
250-ENHANCEDSTATUSCODES
|
|
250-8BITMIME
|
|
250-DSN
|
|
250 SMTPUTF8
|
|
</pre>
|
|
|
|
<li> <p> The Postfix SMTP server accepts the SMTPUTF8 request in
|
|
MAIL FROM and VRFY commands. </p>
|
|
|
|
<pre>
|
|
<b>MAIL FROM:<address> SMTPUTF8 ...</b>
|
|
|
|
<b>VRFY address SMTPUTF8</b>
|
|
</pre>
|
|
|
|
<li> <p> The Postfix SMTP client may issue the SMTPUTF8 request in
|
|
MAIL FROM commands. </p>
|
|
|
|
<li> <p> The Postfix SMTP server accepts UTF-8 in email address
|
|
domains, but only after the remote SMTP client issues the
|
|
SMTPUTF8 request in MAIL FROM or VRFY commands. </p>
|
|
|
|
</ul>
|
|
|
|
<p> Postfix already permitted UTF-8 in message header values
|
|
and in address localparts. This does not change. </p>
|
|
|
|
<h2> <a name="using">Using Postfix SMTPUTF8 support</a> </h2>
|
|
|
|
<p> After Postfix SMTPUTF8 support is turned on, Postfix behavior
|
|
will depend on 1) whether a remote SMTP client requests SMTPUTF8
|
|
support, 2) the presence of UTF-8 content in the message envelope
|
|
and headers, and 3) whether a down-stream SMTP (or LMTP) server
|
|
announces SMTPUTF8 support. </p>
|
|
|
|
<ul>
|
|
|
|
<li> <p> When the Postfix SMTP server receives a message WITHOUT
|
|
the SMTPUTF8 request, Postfix handles the message as it has always
|
|
done (at least that is the default, see autodetection below).
|
|
Specifically, the Postfix SMTP server does not accept UTF-8 in the
|
|
envelope sender domain name or envelope recipient domain name, and
|
|
the Postfix SMTP client does not issue the SMTPUTF8 request when
|
|
delivering that message to an SMTP or LMTP server that announces
|
|
SMTPUTF8 support (again, that is the default). Postfix will accept
|
|
UTF-8 in message header values and in the localpart of envelope
|
|
sender and recipient addresses, because it has always done that.
|
|
</p>
|
|
|
|
<li> <p> When the Postfix SMTP server receives a message WITH the
|
|
SMTPUTF8 request, Postfix will issue the SMTPUTF8 request when
|
|
delivering that message to an SMTP or LMTP server that announces
|
|
SMTPUTF8 support. This is not configurable. </p>
|
|
|
|
<li> <p> When a message is received with the SMTPUTF8 request,
|
|
Postfix will deliver the message to a non-SMTPUTF8 SMTP or LMTP
|
|
server ONLY if: </p>
|
|
|
|
<ul>
|
|
|
|
<li> <p> No message header value contains UTF-8. </p>
|
|
|
|
<li> <p> The envelope sender address contains no UTF-8, </p>
|
|
|
|
<li> <p> No envelope recipient address for that specific
|
|
SMTP/LMTP delivery transaction contains UTF-8. </p>
|
|
|
|
<blockquote> <p> NOTE: Recipients in other email delivery
|
|
transactions for that same message may still contain UTF-8.
|
|
</p> </blockquote>
|
|
|
|
</ul>
|
|
|
|
<p> Otherwise, Postfix will return the recipient(s) for that
|
|
email delivery transaction as undeliverable. The delivery status
|
|
notification message will be an SMTPUTF8 message. It will therefore
|
|
be subject to the same restrictions as email that is received
|
|
with the SMTPUTF8 request. </p>
|
|
|
|
<li> <p> When the Postfix SMTP server receives a message with the
|
|
SMTPUTF8 request, that request also applies after the message is
|
|
forwarded via a virtual or local alias, or $HOME/.forward file.
|
|
</p>
|
|
|
|
</ul>
|
|
|
|
<h2> <a name="detecting">SMTPUTF8 autodetection</a> </h2>
|
|
|
|
<p> This section applies only to systems that have SMTPUTF8 support
|
|
turned on (<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes). </p>
|
|
|
|
<p> For compatibility with pre-SMTPUTF8 environments, Postfix does
|
|
not automatically set the "SMTPUTF8 requested" flag on messages
|
|
from non-SMTPUTF8 clients that contain a UTF-8 header value or
|
|
UTF-8 address localpart. This would make such messages undeliverable
|
|
to non-SMTPUTF8 servers, and could be a barrier to SMTPUTF8 adoption.
|
|
</p>
|
|
|
|
<p> By default, Postfix sets the "SMTPUTF8 requested" flag only on
|
|
address verification probes and on Postfix sendmail submissions
|
|
that contain UTF-8 in the sender address, UTF-8 in a recipient
|
|
address, or UTF-8 in a message header value. </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtputf8_autodetect_classes">smtputf8_autodetect_classes</a> = sendmail, verify
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> However, if you have a non-ASCII <a href="postconf.5.html#myorigin">myorigin</a> or <a href="postconf.5.html#mydomain">mydomain</a> setting,
|
|
or if you have a configuration that introduces UTF-8 addresses with
|
|
virtual aliases, canonical mappings, or BCC mappings, then you may
|
|
have to apply SMTPUTF8 autodetection to all email: </p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#smtputf8_autodetect_classes">smtputf8_autodetect_classes</a> = all
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p> This will, of course, also flag email that was received without
|
|
SMTPUTF8 request, but that contains UTF-8 in a sender address
|
|
localpart, receiver address localpart, or message header value.
|
|
Such email was not standards-compliant, but Postfix would have
|
|
delivered it if SMTPUTF8 support was disabled. </p>
|
|
|
|
<h2> <a name="limitations">Limitations of the current implementation</a>
|
|
</h2>
|
|
|
|
<p> The Postfix implementation is a work in progress; limitations
|
|
are steadily being removed. The text below describes the situation
|
|
at one point in time. </p>
|
|
|
|
<h3> No automatic conversions between ASCII and UTF-8 domain names. </h3>
|
|
|
|
<p> Some background: According to <a href="https://tools.ietf.org/html/rfc6530">RFC 6530</a> and related documents,
|
|
an internationalized domain name can appear in two forms: the UTF-8
|
|
form, and the ASCII (xn--mumble) form. An internationalized address
|
|
localpart must be encoded in UTF-8; the RFCs do not define an ASCII
|
|
alternative form. </p>
|
|
|
|
<p> Postfix currently does not convert internationalized domain
|
|
names from UTF-8 into ASCII (or from ASCII into UTF-8) before using
|
|
domain names in SMTP commands and responses, before looking up
|
|
domain names in lists such as <a href="postconf.5.html#mydestination">mydestination</a>, <a href="postconf.5.html#relay_domains">relay_domains</a> or in
|
|
lookup tables such as access tables, etc., before using domain names
|
|
in a policy daemon or Milter request, or before logging events.
|
|
</p>
|
|
|
|
<p> Postfix does, however, casefold domain names and email addresses
|
|
before matching them against a Postfix configuration parameter or
|
|
lookup table. </p>
|
|
|
|
<p> In order to use Postfix SMTPUTF8 support: </p>
|
|
|
|
<ul>
|
|
|
|
<li> <p> The Postfix parameters <a href="postconf.5.html#myhostname">myhostname</a> and <a href="postconf.5.html#mydomain">mydomain</a> must be in
|
|
ASCII form. One is a substring of the other, and the <a href="postconf.5.html#myhostname">myhostname</a>
|
|
value is used in SMTP commands and responses that require ASCII.
|
|
The parameter <a href="postconf.5.html#myorigin">myorigin</a> (added to local addresses without domain)
|
|
supports UTF-8. </p>
|
|
|
|
<li> <p> You need to configure both the ASCII and UTF-8 forms of
|
|
an Internationalized domain name in Postfix parameters such as
|
|
<a href="postconf.5.html#mydestination">mydestination</a> and <a href="postconf.5.html#relay_domains">relay_domains</a>, as well as lookup table search
|
|
keys. </p>
|
|
|
|
<li> <p> Milters, content filters, policy servers and logfile
|
|
analysis tools need to be able to handle both the ASCII and UTF-8
|
|
forms of Internationalized domain names. </p>
|
|
|
|
</ul>
|
|
|
|
<h2> <a name="compatibility">Compatibility with pre-SMTPUTF8
|
|
environments</a> </h2>
|
|
|
|
<h3> Mailing lists with UTF-8 and non-UTF-8 subscribers </h3>
|
|
|
|
<p> With Postfix, there is no need to split mailing lists into UTF-8 and
|
|
non-UTF-8 members. Postfix will try to deliver the non-UTF8 subscribers
|
|
over "traditional" non-SMTPUTF8 sessions, as long as the message
|
|
has an ASCII envelope sender address and all-ASCII header values.
|
|
The mailing list manager may have to apply <a href="https://tools.ietf.org/html/rfc2047">RFC 2047</a> encoding to
|
|
satisfy that last condition. </p>
|
|
|
|
<h3> Pre-existing non-ASCII email flows </h3>
|
|
|
|
<p> With "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = no", Postfix handles email with non-ASCII
|
|
in address localparts (and in headers) as before. The vast majority
|
|
of email software is perfectly capable of handling such email, even
|
|
if pre-SMTPUTF8 standards do not support such practice. </p>
|
|
|
|
<h3> Rejecting non-UTF8 addresses </h3>
|
|
|
|
<p> With "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a> = yes", Postfix
|
|
requires that non-ASCII address information is encoded in UTF-8 and
|
|
will reject other encodings such as ISO-8859. It is not practical
|
|
for Postfix to support multiple encodings at the same time. There
|
|
is no problem with <a href="https://tools.ietf.org/html/rfc2047">RFC 2047</a> encodings such as "=?ISO-8859-1?Q?text?=",
|
|
because those use only characters from the ASCII characterset. </p>
|
|
|
|
<h3> Rejecting non-ASCII addresses in non-SMTPUTF8 transactions </h3>
|
|
|
|
<p> Setting "<a href="postconf.5.html#strict_smtputf8">strict_smtputf8</a> = yes" in addition to "<a href="postconf.5.html#smtputf8_enable">smtputf8_enable</a>
|
|
= yes" will enable stricter enforcement of the SMTPUTF8 protocol.
|
|
Specifically, the Postfix SMTP server will not only reject non-UTF8
|
|
sender or recipient addresses, it will in addition accept UTF-8
|
|
sender or recipient addresses only when the client requests an
|
|
SMTPUTF8 mail transaction. </p>
|
|
|
|
<h2> <a name="idna2003">Compatibility with IDNA2003</a> </h2>
|
|
|
|
<p> Postfix ≥ 3.2 by default disables the 'transitional'
|
|
compatibility between IDNA2003 and IDNA2008, when converting UTF-8
|
|
domain names to/from the ASCII form that is used in DNS lookups.
|
|
This makes Postfix behavior consistent with current versions of the
|
|
Firefox and Chrome web browsers. Specify "<a href="postconf.5.html#enable_idna2003_compatibility">enable_idna2003_compatibility</a>
|
|
= yes" to get the historical behavior. </p>
|
|
|
|
<p> This affects the conversion of domain names that contain for
|
|
example the German sz (ß) and the Greek zeta (ς). See
|
|
<a href="https://unicode.org/cldr/utility/idna.jsp">https://unicode.org/cldr/utility/idna.jsp</a> for more examples. </p>
|
|
|
|
<h2> <a name="credits">Credits</a> </h2>
|
|
|
|
<ul>
|
|
|
|
<li> <p> May 15, 2014: Arnt Gulbrandsen posted his patch for Unicode
|
|
email support. This work was sponsored by CNNIC. </p>
|
|
|
|
<li> <p> July 15, 2014: Wietse integrated Arnt Gulbrandsen's code
|
|
and released Postfix with SMTPUTF8 support. </p>
|
|
|
|
<li> <p> January 2015: Wietse added UTF-8 support for casefolding
|
|
in Postfix lookup tables and caseless string comparison in Postfix
|
|
list-based features. </p>
|
|
|
|
</ul>
|
|
|
|
</body>
|
|
|
|
</html>
|
|
|