Demo
Demo

Knowledge base

PMTA knowledge base›Block <source>›Directive§ 3.3.7.14

require-starttls

<source>

Whether to require encryption before any commands during submission
in the configuration this is a linerequire-starttls falseinside the block <source>
The same name 1:<domain><source>— some of them are other settings, some are the same one
No commands until the connection is encrypted

The line requires the submitting client to perform STARTTLS before any commands, except those listed in the manual: EHLO, QUIT, NOOP, XACK, RSET and STARTTLS itself. The default is false.

This is the stricter of the two forms of the requirement. The neighboring require-starttls-before-auth requires encryption only before the password; this one before everything.

It works only together with the permission. allow-starttls must be in the same source, otherwise there is nothing to require.

The price is compatibility. A client that cannot do STARTTLS or is configured for plain submission will not be able to submit at all.

The main trap is the same source selection as for the permission. The requirement is checked on the connection, and the source for it is selected by the submitter’s address. A line in a login-based source will not work — the commands come before authentication.
What the Hub does. It does not write it: the base configuration has only the permission. The reason is compatibility: different platforms may submit, and a strict requirement would stop one configured for a plain connection. A sensible step forward is not this line but require-starttls-before-auth: it closes the main thing, the password, and breaks nothing for those who encrypt.
Recommended values

Two forms of the requirement, and they differ in strictness:

Line What it requires Whom you lose
do not set (default) nothing no one; passwords may go out in plain text
require-starttls-before-auth encryption before the password those who send the password in the clear
this line encryption before everything also those who submit without authentication

A sensible order is the second line first, and only if submission is fully under control, the third.

The false default and the list of commands allowed before encryption come from the manual (§ 3.3.7.14). The comparison of the two forms of the requirement is ours.
Example configuration
# the strictest form — both lines in the source matched by address
<source 10.0.0.0/24>
    allow-starttls true
    require-starttls true</source>
The manual’s example, narrowed down to the submission subnet. In the <source> 0/0 block such a line is set only when all submitters definitely support encryption.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends2 mistakes▶

Setting the requirement without the permission

§ 3.3.7.14

What it costsThere is nothing to require: the node does not announce STARTTLS at all. Clients can neither encrypt nor submit in plain text — submission stops completely.
How to spot itAll submitters get a refusal at the very first command.
How to do it rightSet allow-starttls in the same source. This is one setting made of two lines.

Enabling the strictest form right away

our experience

What it costsThe requirement applies both to submission without authentication and to clients that cannot do STARTTLS. Everything that was not checked in advance stops.
How to spot itSome platforms stop connecting after the apply.
How to do it rightStart with require-starttls-before-auth: it closes the password and leaves everything else alone.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
require-starttls <boolean>
Values
yes | no | true | false
Default
false § 3.3.7.14
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<source>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive lives in <source> and merges by the source rule: a narrower block overrides a broader one. The source is selected by the submitter’s address — before authentication — so the line plays no part in login-based sources.
⇄

Related directives

1 relation

Does not work without

allow-starttls<source>There is nothing to require until encryption is allowed: both lines are needed together. § 3.3.7.14

Referenced from

require-starttls<domain>A namesake on the other side: that one is about the node receiving mail, this one is about sending. § 3.3.7.14

How to check on the node
It is checked by trying to send a command without encryption:
printf 'EHLO test\r\nMAIL FROM:<a@b.c>\r\nQUIT\r\n' | openssl s_client -connect localhost:25 -quiet 2>/dev/null | head -5
A refusal at the MAIL FROM command means the requirement is in effect. Successful acceptance means the line is missing or is in a source that did not match by address.
◇

What else to read

3 articles

◇Submission over HTTPS on its own listener, modeled on SparkPostA separate entry point: its own listener with a certificate, its own keys and a reserved source name through which the usual submission settings apply to such mail.◇The receiver declares an encryption requirement on its websiteThe node fetches the recipient domain’s policy over HTTPS and, if it is in enforce mode, delivers only when the MX matches, the connection is encrypted and the certificate is verified.◇The receiver declares an encryption requirement in its DNS zoneThe node looks at the recipient domain’s DANE records and, if STARTTLS is required, sends only over an encrypted channel with a certificate verified by fingerprint.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connection encryption
Neighboring settings of the block <source>:require-starttls-before-authallow-starttlssmtp-serviceretain-x-dkim-keyprocess-x-dkim-keyAll 74 directives of the block →