Introducing the tls protocol to automaticaly encapsulate a ZMQ socket in

TLS.

Author: fbacchella

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v2.0.0 (2026-??-??)
+
+## Added
+
+* Errno now embed the thrown exception if needed. So adding event to notify that an exception was thrown, that can be 
+  logged or handled. This needs to increase the value of zmq.ZMQ.ZMQ_EVENT_ALL to 0xffffffff.
+* Many inner Enum are now autonomous.
+* Event serialization now directly resolve serialized values.
+* Adding the protocol TLS protocol. As Java doesn’t provide a way to handle TLS in channel, it’s not supporterd in the
+  default package, an implementation using [tls-channel](https://github.com/marianobarrios/tls-channel) is available.
+
 ## v0.7.0 (2025-11-14)
 
 ### Added

jeromq-core/src/main/java/org/zeromq/ZMQ.java

@@ -7,6 +7,7 @@
 import java.nio.channels.SelectableChannel;
 import java.nio.channels.Selector;
 import java.nio.charset.Charset;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.ThreadLocalRandom;
@@ -15,6 +16,9 @@
 import java.util.function.BiFunction;
 import java.util.function.Consumer;
 
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.SSLParameters;
+
 import org.zeromq.proto.ZPicture;
 
 import zmq.Ctx;
@@ -28,6 +32,7 @@
 import zmq.io.mechanism.Mechanisms;
 import zmq.io.net.SocketFactory.ChannelFactoryWrapper;
 import zmq.io.net.SelectorProviderChooser;
+import zmq.io.net.tls.PrincipalConverter;
 import zmq.msg.MsgAllocator;
 import zmq.util.Draft;
 import zmq.util.Z85;
@@ -3103,6 +3108,69 @@ public ChannelFactoryWrapper<? extends SocketAddress> getChannelWrapper()
             return base.getSocketOptx(zmq.ZMQ.ZMQ_CHANNEL_WRAPPER_FACTORY);
         }
 
+        /**
+         * When using the tls {@link zmq.io.net.NetProtocol}, it will set the {@link SSLContext} to be used.
+         * @param sslContext The {@link SSLContext} to used
+         *
+         * @return true if the option was set, otherwise false
+         */
+        public boolean setSslContext(SSLContext sslContext)
+        {
+            return base.setSocketOpt(zmq.ZMQ.ZMQ_TLS_CONTEXT, sslContext);
+        }
+
+        /**
+         * The {@link SSLContext} to use can be defined both in the factory or specific for the current socket using
+         * {@link #setSslContext}. This method return the effective one.
+         * @return The effective {@link SSLContext}
+         */
+        public SSLContext getSslContext()
+        {
+            return base.getSocketOptx(zmq.ZMQ.ZMQ_TLS_CONTEXT);
+        }
+
+        /**
+         * When using the tls {@link zmq.io.net.NetProtocol}, it will set the {@link SSLParameters} to be used.
+         * @param sslParams The {@link SSLParameters} to used
+         *
+         * @return true if the option was set, otherwise false
+         */
+        public boolean setSslParameters(SSLParameters sslParams)
+        {
+            return base.setSocketOpt(zmq.ZMQ.ZMQ_TLS_PARAMETERS, sslParams);
+        }
+
+        /**
+         * The {@link SSLContext} to use can be defined both in the factory or specific for the current socket using
+         * {@link #setSslParameters}. This method return the effective one.
+         * @return The effective {@link SSLParameters}
+         */
+        public SSLParameters getSslParameter()
+        {
+            return base.getSocketOptx(zmq.ZMQ.ZMQ_TLS_PARAMETERS);
+        }
+
+        /**
+         * When using the tls {@link zmq.io.net.NetProtocol}, it will set the {@link PrincipalConverter} to be used.
+         * @param principalConverter The {@link PrincipalConverter} to be used
+         *
+         * @return true if the option was set, otherwise false
+         */
+        public boolean setPrincipalConvert(PrincipalConverter principalConverter)
+        {
+            return base.setSocketOpt(zmq.ZMQ.ZMQ_TLS_PRINCIPAL_CONVERT, principalConverter);
+        }
+
+        /**
+         * The {@link PrincipalConverter} to use can be defined both in the factory or specific for the current socket using
+         * {@link #setPrincipalConvert}. This method return the effective one.
+         * @return The effective {@link PrincipalConverter}
+         */
+        public PrincipalConverter getPrincipalConverter()
+        {
+            return base.getSocketOptx(zmq.ZMQ.ZMQ_TLS_PRINCIPAL_CONVERT);
+        }
+
         /**
          * Bind to network interface. Start listening for new connections.
          *

jeromq-core/src/main/java/zmq/Options.java

@@ -8,6 +8,9 @@
 import java.util.Arrays;
 import java.util.List;
 
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.SSLParameters;
+
 import zmq.io.coder.IDecoder;
 import zmq.io.coder.IEncoder;
 import zmq.io.mechanism.Mechanisms;
@@ -18,6 +21,7 @@
 import zmq.io.net.ipc.IpcAddress;
 import zmq.io.net.tcp.TcpAddress;
 import zmq.io.net.tcp.TcpAddress.TcpAddressMask;
+import zmq.io.net.tls.PrincipalConverter;
 import zmq.msg.MsgAllocator;
 import zmq.msg.MsgAllocatorThreshold;
 import zmq.util.Errno;
@@ -196,6 +200,11 @@ public class Options
     private ChannelFactoryWrapper<? extends SocketAddress> channelWrapperFactory = SocketFactory.TRANSPARENT;
     private SocketFactory<? extends SocketAddress> effectiveFactory = null;
 
+    // Must be kept as null, default values will be handled by the TLS socket factory
+    public SSLContext sslContext = null;
+    public SSLParameters sslParameters = null;
+    public PrincipalConverter principalConverter = null;
+
     /**
      * <p>Set an option with the given object.</p>
      * <p>When an option expect a duration, it can be given as an integer number of milliseconds, a floating
@@ -580,6 +589,33 @@ else if (optval instanceof MsgAllocator) {
                 return false;
             }
 
+        case ZMQ.ZMQ_TLS_CONTEXT:
+            if (optval instanceof SSLContext) {
+                sslContext = (SSLContext) optval;
+                return true;
+            }
+            else {
+                return false;
+            }
+
+        case ZMQ.ZMQ_TLS_PARAMETERS:
+            if (optval instanceof SSLParameters) {
+                sslParameters = (SSLParameters) optval;
+                return true;
+            }
+            else {
+                return false;
+            }
+
+        case ZMQ.ZMQ_TLS_PRINCIPAL_CONVERT:
+            if (optval instanceof PrincipalConverter) {
+                this.principalConverter = (PrincipalConverter) optval;
+                return true;
+            }
+            else {
+                return false;
+            }
+
         default:
             throw new IllegalArgumentException("Unknown Option " + option);
         }
@@ -836,6 +872,15 @@ public <T> T getSocketOpt(int option)
         case ZMQ.ZMQ_CHANNEL_WRAPPER_FACTORY:
             return (T) channelWrapperFactory;
 
+        case ZMQ.ZMQ_TLS_CONTEXT:
+            return (T) sslContext;
+
+        case ZMQ.ZMQ_TLS_PARAMETERS:
+            return (T) sslParameters;
+
+        case ZMQ.ZMQ_TLS_PRINCIPAL_CONVERT:
+            return (T) principalConverter;
+
         default:
             throw new IllegalArgumentException("option=" + option);
         }

jeromq-core/src/main/java/zmq/ZMQ.java

@@ -156,7 +156,10 @@ public class ZMQ
     public static final int ZMQ_MSG_ALLOCATOR                 = ZMQ_CUSTOM_OPTION + 3;
     public static final int ZMQ_MSG_ALLOCATION_HEAP_THRESHOLD = ZMQ_CUSTOM_OPTION + 4;
     public static final int ZMQ_HEARTBEAT_CONTEXT             = ZMQ_CUSTOM_OPTION + 5;
-    public static final int ZMQ_CHANNEL_WRAPPER_FACTORY       = ZMQ_CUSTOM_OPTION + 6;
+    public static final int ZMQ_CHANNEL_WRAPPER_FACTORY       = ZMQ_CUSTOM_OPTION + 7;
+    public static final int ZMQ_TLS_CONTEXT                   = ZMQ_CUSTOM_OPTION + 8;
+    public static final int ZMQ_TLS_PARAMETERS                = ZMQ_CUSTOM_OPTION + 9;
+    public static final int ZMQ_TLS_PRINCIPAL_CONVERT         = ZMQ_CUSTOM_OPTION + 10;
 
     /*  Message options                                                           */
     public static final int ZMQ_MORE = 1;

jeromq-core/src/main/java/zmq/io/net/NetProtocol.java

@@ -32,6 +32,14 @@ public <S extends SocketAddress> void resolve(Address<S> paddr, boolean ipv6)
             paddr.resolve(ipv6);
         }
     },
+    tls(false, false)
+    {
+        @Override
+        public <S extends SocketAddress> void resolve(Address<S> paddr, boolean ipv6)
+        {
+            paddr.resolve(ipv6);
+        }
+    },
     udp(true, true)
     {
         @Override

jeromq-core/src/main/java/zmq/io/net/tls/PrincipalConverter.java

@@ -0,0 +1,14 @@
+package zmq.io.net.tls;
+
+import java.util.Optional;
+
+import javax.net.ssl.SSLSession;
+
+/**
+ * This class will be used to extract an identity from the current {@link SSLSession} and it will be stored in the "User-Id"
+ * metadata attribute.
+ */
+@FunctionalInterface
+public interface PrincipalConverter {
+    Optional<String> getPrincipal(SSLSession session);
+}

jeromq-tls/README.md

@@ -0,0 +1,4 @@
+An implementation of a TLS protocol using [TLS Channel](https://github.com/marianobarrios/tls-channel)
+
+It can be used as simple drop-in, and it will be used automatically. For better control, it can be used as channel wrapper
+for better control using and configuring the factory zmq.io.net.tls.TlsSocketFactory directly.

jeromq-tls/pom.xml

@@ -31,7 +31,7 @@
         <dependency>
             <groupId>com.github.marianobarrios</groupId>
             <artifactId>tls-channel</artifactId>
-            <version>0.9.0</version>
+            <version>0.9.1</version>
         </dependency>
         <dependency>
             <groupId>org.bouncycastle</groupId>