This is an automated email from the ASF dual-hosted git repository.
rcordier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
The following commit(s) were added to refs/heads/master by this push:
new 80b519b1c6 JAMES-3819 Give tools to enforce RFC-8461 MTA-STS (#2697)
80b519b1c6 is described below
commit 80b519b1c662805ef706a9b7d7e0de5b369602a1
Author: Benoit TELLIER <[email protected]>
AuthorDate: Fri Apr 4 05:10:49 2025 +0200
JAMES-3819 Give tools to enforce RFC-8461 MTA-STS (#2697)
---
.../pages/distributed/configure/mat-sts.adoc | 4 ++
.../servers/pages/postgres/configure/mat-sts.adoc | 4 ++
.../architecture/implemented-standards.adoc | 1 +
.../partials/configure/forExtensionsPartial.adoc | 3 +-
.../servers/partials/configure/mta-sts.adoc | 67 ++++++++++++++++++++++
.../apache/james/smtpserver/tls/EnforceMtaSts.java | 57 ++++++++++++++++++
.../apache/james/smtpserver/tls/TestMtaSts.java | 52 +++++++++++++++++
7 files changed, 187 insertions(+), 1 deletion(-)
diff --git a/docs/modules/servers/pages/distributed/configure/mat-sts.adoc
b/docs/modules/servers/pages/distributed/configure/mat-sts.adoc
new file mode 100644
index 0000000000..122fd9e35e
--- /dev/null
+++ b/docs/modules/servers/pages/distributed/configure/mat-sts.adoc
@@ -0,0 +1,4 @@
+= Distributed James Server — MTA STS
+:navtitle: MTA-STS
+
+include::partial$configure/mta-sts.adoc[]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/postgres/configure/mat-sts.adoc
b/docs/modules/servers/pages/postgres/configure/mat-sts.adoc
new file mode 100644
index 0000000000..5b36dd5174
--- /dev/null
+++ b/docs/modules/servers/pages/postgres/configure/mat-sts.adoc
@@ -0,0 +1,4 @@
+= Postgresql James Server — MTA STS
+:navtitle: MTA-STS
+
+include::partial$configure/mta-sts.adoc[]
\ No newline at end of file
diff --git
a/docs/modules/servers/partials/architecture/implemented-standards.adoc
b/docs/modules/servers/partials/architecture/implemented-standards.adoc
index 55d407e5e2..86770ae1c9 100644
--- a/docs/modules/servers/partials/architecture/implemented-standards.adoc
+++ b/docs/modules/servers/partials/architecture/implemented-standards.adoc
@@ -37,6 +37,7 @@ This page details standards implemented by the {server-name}.
- link:https://datatracker.ietf.org/doc/rfc6710/[RFC-6710] SMTP Extension for
Message Transfer Priorities
- link:https://datatracker.ietf.org/doc/rfc8689/[RFC-8689] SMTP Require TLS
Option
- link:https://datatracker.ietf.org/doc/html/rfc1893[RFC-1893] Enhanced Mail
System Status Codes
+- link:https://datatracker.ietf.org/doc/html/rfc8461[RFC-8461] SMTP MTA Strict
Transport Security (MTA-STS)
== LMTP
diff --git a/docs/modules/servers/partials/configure/forExtensionsPartial.adoc
b/docs/modules/servers/partials/configure/forExtensionsPartial.adoc
index 49720b5043..d1088436e6 100644
--- a/docs/modules/servers/partials/configure/forExtensionsPartial.adoc
+++ b/docs/modules/servers/partials/configure/forExtensionsPartial.adoc
@@ -11,4 +11,5 @@ By omitting these files, no extra behaviour is added.
** xref:{xref-base}/collecting-contacts.adoc[This page] documents contact
collection
** xref:{xref-base}/collecting-events.adoc[This page] documents event
collection
** xref:{xref-base}/dsn.adoc[This page] specified how to support SMTP Delivery
Submission Notification (link:https://tools.ietf.org/html/rfc3461[RFC-3461])
-** xref:{xref-base}/droplists.adoc[This page] allows configuring drop lists.
\ No newline at end of file
+** xref:{xref-base}/droplists.adoc[This page] allows configuring drop lists.
+** xref:{xref-base}/mta-sts.adoc[This page] for configuring MTA-STS (RFC-8461)
\ No newline at end of file
diff --git a/docs/modules/servers/partials/configure/mta-sts.adoc
b/docs/modules/servers/partials/configure/mta-sts.adoc
new file mode 100644
index 0000000000..e2f035c8d1
--- /dev/null
+++ b/docs/modules/servers/partials/configure/mta-sts.adoc
@@ -0,0 +1,67 @@
+link:https://datatracker.ietf.org/doc/html/rfc8461[MTA-STS] is a standard for
a SMTP server to advertise its TLS
+set up and whether SSL is required for it to accept emails.
+
+== Securing incoming traffic with MTA-STS
+
+Apache James supports tools for MTA-STS on the incoming traffic.
+
+The *EnforceMtaSts* SMTP hook can be used to ensure *MAIL FROM* transactions
only happens on encrypted channels
+and matches the MTA-STS 'enforce' policy.
+
+Sample set up:
+
+....xml
+<handlerchain>
+ <!-- ... -->
+ <handler class="org.apache.james.smtpserver.tls.EnforceMtaSts"/>
+</handlerchain>
+....
+
+The *TestMtaSts* SMTP hook can be used to audit *MAIL FROM* transactions on
unencrypted channels
+and matches the MTA-STS 'testing' policy. It will log but accept emails from
such connections.
+Sample set up:
+
+
+....xml
+<handlerchain>
+ <!-- ... -->
+ <handler class="org.apache.james.smtpserver.tls.TestMtaSts"/>
+</handlerchain>
+....
+
+=== Advertizing MTA-STS support
+
+Configuring the MTA is only part of the story. Remains telling the world about
it.
+
+First is needed a DNS record for the MTA-STS policy:
+
+....
+_mta-sts.mydomain.com. in TXT "v=STSv1; id=20250403T140800"
+....
+
+Then the policy should be published on
`https://mta-sts.mydomain.com/.well-known/mta-sts.txt` which yields:
+
+....
+version: STSv1
+mode: enforce
+mx: mx.mydomain.com
+max_age: 86400
+....
+
+=== Receiving TLS RPT reports
+
+link:https://datatracker.ietf.org/doc/html/rfc8460[SMTP TLS Reporting] allows
remote senders to notice you on failures
+to establish a TLS connection and thus is a valuable debugging asset.
+
+Where to send the TLSRPT report can be configured via a DNS record:
+
+....
+ _smtp._tls.example.com. IN TXT
"v=TLSRPTv1;rua=mailto:[email protected]";
+....
+
+Please note that if MTA-STS mode is 'enforce' then hosting the TLSRPT rua on a
distinct domain is needed so that sending
+of the report can downgrade to clear text if needed.
+
+== Securing outgoing traffic with MTA-STS
+
+This part of the specification is not implemented yet. Contributions are
welcomed.
\ No newline at end of file
diff --git
a/server/protocols/protocols-smtp/src/main/java/org/apache/james/smtpserver/tls/EnforceMtaSts.java
b/server/protocols/protocols-smtp/src/main/java/org/apache/james/smtpserver/tls/EnforceMtaSts.java
new file mode 100644
index 0000000000..6eab9e23e2
--- /dev/null
+++
b/server/protocols/protocols-smtp/src/main/java/org/apache/james/smtpserver/tls/EnforceMtaSts.java
@@ -0,0 +1,57 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one *
+ * or more contributor license agreements. See the NOTICE file *
+ * distributed with this work for additional information *
+ * regarding copyright ownership. The ASF licenses this file *
+ * to you under the Apache License, Version 2.0 (the *
+ * "License"); you may not use this file except in compliance *
+ * with the License. You may obtain a copy of the License at *
+ * *
+ * http://www.apache.org/licenses/LICENSE-2.0 *
+ * *
+ * Unless required by applicable law or agreed to in writing, *
+ * software distributed under the License is distributed on an *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
+ * KIND, either express or implied. See the License for the *
+ * specific language governing permissions and limitations *
+ * under the License. *
+ ****************************************************************/
+
+package org.apache.james.smtpserver.tls;
+
+import org.apache.james.core.MaybeSender;
+import org.apache.james.protocols.smtp.SMTPSession;
+import org.apache.james.protocols.smtp.hook.HookResult;
+import org.apache.james.protocols.smtp.hook.HookReturnCode;
+import org.apache.james.protocols.smtp.hook.MailHook;
+import org.apache.james.util.MDCStructuredLogger;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * CF https://datatracker.ietf.org/doc/html/rfc8461
+ *
+ * SMTP MTA Strict Transport Security (MTA-STS)
+ *
+ * Aimed at enforcing mode enforce
+ */
+public class EnforceMtaSts implements MailHook {
+ private static final Logger LOGGER =
LoggerFactory.getLogger(EnforceMtaSts.class);
+
+ @Override
+ public HookResult doMail(SMTPSession session, MaybeSender sender) {
+ if (!session.isTLSStarted()) {
+ MDCStructuredLogger.forLogger(LOGGER)
+ .field("sessionId", session.getSessionID())
+ .field("sender", sender.asPrettyString())
+ .log(logger -> logger.warn("Attempt to send to us a clear text
message"));
+
+ return HookResult.builder()
+ .hookReturnCode(HookReturnCode.deny())
+ .smtpReturnCode("571")
+ .smtpDescription("StartTLS required")
+ .build();
+ }
+ return HookResult.DECLINED;
+ }
+}
diff --git
a/server/protocols/protocols-smtp/src/main/java/org/apache/james/smtpserver/tls/TestMtaSts.java
b/server/protocols/protocols-smtp/src/main/java/org/apache/james/smtpserver/tls/TestMtaSts.java
new file mode 100644
index 0000000000..9222a296f2
--- /dev/null
+++
b/server/protocols/protocols-smtp/src/main/java/org/apache/james/smtpserver/tls/TestMtaSts.java
@@ -0,0 +1,52 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one *
+ * or more contributor license agreements. See the NOTICE file *
+ * distributed with this work for additional information *
+ * regarding copyright ownership. The ASF licenses this file *
+ * to you under the Apache License, Version 2.0 (the *
+ * "License"); you may not use this file except in compliance *
+ * with the License. You may obtain a copy of the License at *
+ * *
+ * http://www.apache.org/licenses/LICENSE-2.0 *
+ * *
+ * Unless required by applicable law or agreed to in writing, *
+ * software distributed under the License is distributed on an *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
+ * KIND, either express or implied. See the License for the *
+ * specific language governing permissions and limitations *
+ * under the License. *
+ ****************************************************************/
+
+package org.apache.james.smtpserver.tls;
+
+import org.apache.james.core.MaybeSender;
+import org.apache.james.protocols.smtp.SMTPSession;
+import org.apache.james.protocols.smtp.hook.HookResult;
+import org.apache.james.protocols.smtp.hook.MailHook;
+import org.apache.james.util.MDCStructuredLogger;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * CF https://datatracker.ietf.org/doc/html/rfc8461
+ *
+ * SMTP MTA Strict Transport Security (MTA-STS)
+ *
+ * Aimed at enforcing mode testing. The goal of this SMTP hook is to
+ * allow administrator to evaluate the impact of enforcing MTA-STS
+ * by logging the taffic that would be blocked.
+ */
+public class TestMtaSts implements MailHook {
+ private static final Logger LOGGER =
LoggerFactory.getLogger(TestMtaSts.class);
+
+ @Override
+ public HookResult doMail(SMTPSession session, MaybeSender sender) {
+ if (!session.isTLSStarted()) {
+ MDCStructuredLogger.forLogger(LOGGER)
+ .field("sessionId", session.getSessionID())
+ .field("sender", sender.asPrettyString())
+ .log(logger -> logger.warn("Attempt to send to us a clear text
message"));
+ }
+ return HookResult.DECLINED;
+ }
+}
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
