STARTTLS documentation errors & clarifications

[aio-libs]

STARTTLS documentation errors & clarifications

[warsaw]

Please take a look at #126 - I ended up keeping the discussion of the arguments more terse, and adding a new section that goes into more detail. Now with moar crossreferences!

[Mortal]

There was just a StackOverflow question on the topic. It seems currently to be slightly easier to create a TLS-on-connect server than a STARTTLS server. Both could probably be exemplified in the docs.

https://stackoverflow.com/q/45447491/how-do-i-properly-support-starttls-with-aiosmtpd

[tlhackque]

Examples are a good thing.

But in any case, the description of the parameters & their effects needs to be correct and complete.

These are not mutually exclusive. A first step would be for someone with commit privs to cut and paste the edit that I provided into the docs...

[tlhackque]

Sorry I'm late. Thanks for addressing this. It's much better. One divot.

I disagree with including the 'and require_starttls should be True" clause in the parameter summary.

I think what I wrote is the correct functional description. A tls_context is required for STARTTLS to be offered. require_starttls disables all but a small subset of commands until a TLS link is established.

"require_starttls should be True" is a value judgement - well intentioned = that security is important. I happen to agree, but it has nothing to do with whether STARTTLS is offered or can be used. In fact, require_starttls can not be used for a public server that accepts mail for local delivery (section 4 of 3207)

A publicly-referenced SMTP server MUST NOT require use of the
STARTTLS extension in order to deliver mail locally.

require_starttls is valuable for a server that requires authentication for the server to accept mail (typically a relay, but sometimes a server that only serves a restricted set of clients). The primary reason is that the most common authentication mechanisms transmit plaintext passwords; these MUST NOT be transmitted unencrypted. A server that functions only as a relay (has no local delivery or is not publicly referenced) can require authentication for all transactions. In this case, require_starttls can reduce the server's attack surface.

Security commentary (3207 and the AUTH/SASL RFCs have a fuller discussion):

TLS serves two functions: verifying that a connection is established to the intended host, and providing confidentiality of the information transferred. In the SMTP/LMTP context, TLS does not provide end-to-end confidentiality of e-mail. It can provide assurance that the email is delivered to the correct host. And in the case of servers that require authentication, it can ensure confidentiality of the authentication process - especially username & password. A plaintext password MUST never be transmitted without TLS or an equivalent security layer.

A server may change the supported commands (listed by HELP and EHLO/HLO) when STARTTLS succeeds. In particular: STARTTLS MUST NOT be offered if a TLS session is active. And plaintext authentication mechanisms SHOULD NOT be offered (and MUST NOT be accepted) UNLESS a TLS session is active. TLS client authentication can also be used as an authentication mechanism - and for authorizing specific mechanism, such as RELAY or ETRN service.

Per RFC 3207, once a TLS session is established, a client MUST discard all knowledge obtained from the SMTP/LMTP server and start again with the ELHO/LHLO sequence.

require_starttls = True is the recommended configuration for servers that offer the STARTTLS service and that require authentication for all transactions. This configuration minimizes the risk that a plaintext password is exposed or that e-mail can be redirected and/or captured by a host that impersonates a server. In this configuration, only the commands necessary for setting up a secure connection are permitted over an insecure connection.

require_starttls = False allows clients that can not establish a TLS connection to submit mail to your server. Generally, your server should only accept local mail without authentication (open relays promote SPAM). The most common authentication methods use plaintext passwords; these MUST NOT be transmitted without an active TLS session.

Although TLS does encrypt e-mail between your server and it's client, it does NOT provide end-to-end encryption of e-mail; in fact, if the client is a relay, e-mail is unlikely to be encrypted while in the relay's queue.

For end-to-end encryption, see S/MIME or PGP.