feature: [34] Implement TLS connection by crazyrokr · Pull Request #171 · JavaSaBr/mqtt-broker

crazyrokr · 2026-05-17T23:17:58Z

Issue

Description

This pull request adds comprehensive support for Transport Layer Security (TLS) to the MQTT broker, enabling secure client-server communication. The implementation covers the entire stack, from network-level SSL/TLS handling to broker-side configuration and integration testing.

Changes

Network Layer:
- Implemented MqttSslConnection and associated readers/writers for SSL handling.
- Added TlsProperties for flexible SSL configuration.
- Refactored message handling by extracting MqttPacketCreator to decouple logic from PlainMqttMessageReader and SslMqttMessageReader.
Core Service Integration:
- Introduced MqttSslConnectionFactory to manage secure connections.
- Updated existing connection and message processing services to support SSL-enabled transports.
Application Configuration:
- Added MqttTlsSpringConfig to enable and configure TLS support within the Spring context.
Testing:
- Added extensive integration tests (TlsCommunicationTest, TlsIntegrationSpecification) to verify secure end-to-end communication.

Notes:

TLS support is integrated as a configurable option alongside plain connections.
The separation of MqttPacketCreator improves code maintainability and allows cleaner reuse of message creation logic across different transport types.

github-actions · 2026-05-17T23:21:42Z

Test Coverage Report

Overall Project	85.49% `-0.48%`	🍏
Files changed	84.81%	🍏

File	Coverage
MqttExternalPlainNetworkConfig.java	100%	🍏
TlsProperties.java	100%	🍏
TlsMqttMessageReader.java	100%	🍏
TlsMqttMessageWriter.java	100%	🍏
TlsMqttConnectionFactory.java	100%	🍏
PlainMqttConnectionFactory.java	100%	🍏
PlainMqttMessageWriter.java	100%	🍏
PlainMqttMessageReader.java	100%	🍏
MqttBrokerSpringConfig.java	98.78%	🍏
MqttPacketCodec.java	93.02%	🍏
TlsMqttConnection.java	83.77% `-16.23%`	🍏
MqttConnection.java	74.86% `-13.14%`	🍏
MqttExternalTlsNetworkConfig.java	70.62% `-29.38%`	🍏
PropertyAssert.java	21.54% `-18.46%`	❌
TlsProtocolException.java	0%	❌

Copilot

Pull request overview

This PR introduces end-to-end TLS support for the MQTT broker, spanning the network transport (TLS connection + SSL packet reader/writer), Spring Boot application configuration, and integration tests to validate secure client communication.

Changes:

Added TLS transport implementation (TlsMqttConnection, TLS reader/writer) and configuration model (TlsProperties).
Refactored packet parsing by extracting MqttPacketCreator and splitting plain vs TLS message readers/writers.
Added Spring configuration and integration tests to bootstrap a TLS listener and verify MQTT 3.1.1 / MQTT 5 communication over TLS.

Reviewed changes

Copilot reviewed 37 out of 38 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
test-support/src/main/groovy/javasabr/mqtt/test/support/TestSslContexts.groovy	Generates temporary keystores/truststores for TLS tests.
network/src/test/groovy/javasabr/mqtt/network/TlsMqttConnectionTest.groovy	Adds a basic TLS connection construction test.
network/src/test/groovy/javasabr/mqtt/network/message/PlainMqttMessageReaderTest.groovy	Adds a regression test for incomplete MBI handling.
network/src/main/java/javasabr/mqtt/network/TlsProperties.java	Introduces validated TLS configuration record.
network/src/main/java/javasabr/mqtt/network/TlsMqttConnection.java	Adds TLS-backed MQTT connection implementation.
network/src/main/java/javasabr/mqtt/network/MqttConnectionFactory.java	Generalizes connection factory with generics.
network/src/main/java/javasabr/mqtt/network/MqttConnection.java	Refactors to use `MqttPacketCreator` + plain reader/writer; improves close logging.
network/src/main/java/javasabr/mqtt/network/message/ssl/TlsMqttMessageWriter.java	Implements SSL-aware writer for MQTT packets.
network/src/main/java/javasabr/mqtt/network/message/ssl/TlsMqttMessageReader.java	Implements SSL-aware reader for MQTT packets.
network/src/main/java/javasabr/mqtt/network/message/ssl/package-info.java	Adds `@NullMarked` package annotation for ssl message package.
network/src/main/java/javasabr/mqtt/network/message/plain/PlainMqttMessageWriter.java	Renames/moves plain writer into dedicated package.
network/src/main/java/javasabr/mqtt/network/message/plain/PlainMqttMessageReader.java	Introduces plain reader using shared `MqttPacketCreator`.
network/src/main/java/javasabr/mqtt/network/message/MqttPacketCreator.java	Extracts packet length parsing + packet instantiation logic.
network/src/main/java/javasabr/mqtt/network/message/MqttMessageReader.java	Removes old reader (logic moved into creator + plain reader).
network/src/main/java/javasabr/mqtt/network/exception/TlsProtocolException.java	Adds TLS-specific runtime exception wrapper.
network/build.gradle	Adjusts network module dependencies (logging deps moved to convention).
gradle/libs.versions.toml	Bumps RLib + HiveMQ client versions.
embedded/build.gradle	Removes explicit logging dependency (moved to convention).
credentials-source-db/src/main/java/javasabr/mqtt/auth/credentials/source/DatabaseCredentialsSource.java	Switches debug output/toString to `DebugUtils` JSON representation.
core-service/src/test/groovy/javasabr/mqtt/service/IntegrationServiceSpecification.groovy	Updates test setup to supply `MqttPacketCreator`.
core-service/src/test/groovy/javasabr/mqtt/service/impl/TlsMqttConnectionFactoryTest.groovy	Adds test for TLS factory allocator sharing.
core-service/src/main/java/javasabr/mqtt/service/impl/TlsMqttConnectionFactory.java	Adds TLS connection factory wiring SSLContext + TLS props.
core-service/src/main/java/javasabr/mqtt/service/impl/PlainMqttConnectionFactory.java	Renames/updates plain connection factory to pass `MqttPacketCreator`.
buildSrc/src/test/resources/log4j2-test.xml	Adds buildSrc test Log4j2 config.
buildSrc/src/main/groovy/configure-java.gradle	Adds logging deps to convention and adjusts test runtime classpath.
build.gradle	Centralizes excludes and adds forced SLF4J resolution strategy.
application/src/test/resources/test-acl.gacl	Extends test ACL rules for TLS client IDs/topics.
application/src/test/groovy/javasabr/mqtt/broker/application/TlsIntegrationSpecification.groovy	Adds TLS client builders and TLS Spring test configuration.
application/src/test/groovy/javasabr/mqtt/broker/application/TlsCommunicationTest.groovy	Adds TLS connect/publish tests for MQTT 3.1.1 and MQTT 5.
application/src/test/groovy/javasabr/mqtt/broker/application/TestSslPropertiesInitializer.groovy	Injects generated keystore/truststore paths into Spring test env.
application/src/test/groovy/javasabr/mqtt/broker/application/IntegrationSpecification.groovy	Switches test config to plain-network test config.
application/src/test/groovy/javasabr/mqtt/broker/application/config/TlsNetworkTestConfig.groovy	Adds Spring test config to start TLS network on an ephemeral port.
application/src/test/groovy/javasabr/mqtt/broker/application/config/PlainNetworkTestConfig.groovy	Adds Spring test config to start plain network on an ephemeral port.
application/src/test/groovy/javasabr/mqtt/broker/application/config/MqttTlsSpringConfigTest.groovy	Adds unit test for TLS property mapping.
application/src/test/groovy/javasabr/mqtt/broker/application/config/MqttBrokerTestConfig.groovy	Removes older test config that probed for random ports.
application/src/main/java/javasabr/mqtt/broker/application/config/MqttTlsSpringConfig.java	Adds Spring beans for TLS properties, SSLContext, TLS network + starter.
application/src/main/java/javasabr/mqtt/broker/application/config/MqttBrokerSpringConfig.java	Wires `MqttPacketCreator`, plain connection factory, and imports TLS config.
application/build.gradle	Removes explicit logging deps (moved to convention).

…ters

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…ation

JavaSaBr · 2026-05-27T17:12:02Z

+      @Value("${mqtt.external.tls.truststore-path:}") String truststorePath,
+      @Value("${mqtt.external.tls.truststore-password:}") String truststorePassword,
+      @Value("${mqtt.external.tls.truststore-type:PKCS12}") String truststoreType,
+      @Value("${mqtt.external.tls.require-client-cert:true}") boolean requireClientCert,


I think 'require-client-cert' should not be true by default, because this connection can be used just to have encrypted traffic

Zero Trust is a preferable strategy in terms of private network. Disabling client certificate validation is appropriate only for public network. If the developer still wants to trust all clients indiscriminately, he can always disable this check using the property

Copilot

Pull request overview

Copilot reviewed 38 out of 39 changed files in this pull request and generated 11 comments.

crazyrokr · 2026-05-27T17:54:04Z

+      MqttPacketCodec mqttPacketCodec) {
+    this.sslEngine = sslContext.createSSLEngine();
+    super(network, channel, bufferAllocator, maxPacketsByRead, serverConnectionConfig, mqttUserFactory, mqttPacketCodec);
+    this.sslEngine.setUseClientMode(clientMode);
+    this.sslEngine.setNeedClientAuth(tlsProperties.requireClientCert());


It's a new Java 25 feature, so the comment is not relevant

crazyrokr · 2026-05-27T18:20:30Z

+    Files.list(tempDir).forEach { Files.deleteIfExists(it) }
+    Files.deleteIfExists(tempDir)


Stream inherit nor Closable neither AutoClosable, so the comment is not relevant

    super(network, channel, bufferAllocator, maxPacketsByRead);
    this.serverConnectionConfig = serverConnectionConfig;
-    this.packetReader = createPacketReader();
-    this.packetWriter = createPacketWriter();
+    this.packetReader = createPacketReader(mqttPacketCodec);
+    this.packetWriter = createPacketWriter(mqttPacketCodec);
    this.user = mqttUserFactory.createNetworkUser(this);


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

crazyrokr added 7 commits May 18, 2026 00:43

Add TLS support infrastructure and exception classes

c7df961

Implement SSL connection and message handlers

ab06f61

Implement SSL connection factory in core service

c4386fc

Configure Spring support for TLS

e66bad1

Add tests for SSL network and core services

c49f314

Add integration tests for application TLS

c8a80a9

Update project dependencies and build configuration

6534480

crazyrokr linked an issue May 17, 2026 that may be closed by this pull request

Implement TLS connection #34

Open

crazyrokr self-assigned this May 17, 2026

crazyrokr added security networking labels May 17, 2026

crazyrokr added 4 commits May 18, 2026 11:35

Merge branch 'develop' into feature/34-implement-tls-connection

8114a18

Improve TLS properties handling

51b38be

Remove redundant @Qualifier annotations

d6e68a2

Extract MqttPacketCreator from PlainMessageReader and SslMessageReader

4b2626c

crazyrokr requested a review from JavaSaBr May 18, 2026 20:27

Merge branch 'develop' into feature/34-implement-tls-connection

2345a89

crazyrokr marked this pull request as ready for review May 18, 2026 20:28

crazyrokr added 2 commits May 25, 2026 21:40

Rename SSL components to TLS

5c4d75f

Add error log on user releasing failure

7729f67

JavaSaBr reviewed May 26, 2026

View reviewed changes

JavaSaBr requested a review from Copilot May 26, 2026 17:09

Copilot started reviewing on behalf of JavaSaBr May 26, 2026 17:10 View session

Copilot AI reviewed May 26, 2026

View reviewed changes

crazyrokr added 4 commits May 26, 2026 22:01

Improve TlsProperties bean creation

e9c467a

Improve network configs

ac7f82d

Remove generic type from MqttConnectionFactory

cc98101

Apply formatting

41444b9

crazyrokr and others added 8 commits May 26, 2026 22:36

Make keytool working on Windows

e9b527c

Extract common writers logic into MqttPacketCodec

924f7d3

Rename MqttPacketCodec methods distinguishing between readers and wri…

4dde54e

…ters

Fix datetime in log message pattern

f142170

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Rename TLS-related members according internal/external network segreg…

2ae2036

…ation

Make TlsCommunicationTest more robust

551b613

Merge branch 'develop' into feature/34-implement-tls-connection

d88c276

Revert redundant change

7a96f79

crazyrokr requested a review from JavaSaBr May 27, 2026 09:12

JavaSaBr reviewed May 27, 2026

View reviewed changes

JavaSaBr requested a review from Copilot May 27, 2026 17:17

Copilot started reviewing on behalf of JavaSaBr May 27, 2026 17:17 View session

Copilot AI reviewed May 27, 2026

View reviewed changes

crazyrokr and others added 7 commits May 27, 2026 19:51

Fix property validation error message

1471d23

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Small refactoring

72407b8

Remove redundant code

9d38c0e

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Remove redundant configuration

0ce600e

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Small refactoring

a090e82

Revert redundant change

37b510e

Update default property values

b20f712

		Files.list(tempDir).forEach { Files.deleteIfExists(it) }
		Files.deleteIfExists(tempDir)

Conversation

crazyrokr commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue

Description

Changes

Notes:

Uh oh!

github-actions Bot commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Coverage Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JavaSaBr May 27, 2026

Choose a reason for hiding this comment

Uh oh!

crazyrokr May 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

crazyrokr May 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

crazyrokr May 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

crazyrokr commented May 17, 2026 •

edited

Loading

github-actions Bot commented May 17, 2026 •

edited

Loading