[knx] Add initial support for KNX secure [WIP]

* add support for KNX IP Secure, new options SECURETUNNEL and SECUREROUTER
* add config options for keyring file and password, and credentials for
  secure connections
* add passive (listening only) access for KNX data secure frames, #8872
* add tests for security functions
* update user documentation

Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>

bundles/org.openhab.binding.knx/README.md

@@ -29,7 +29,7 @@ The IP Gateway is the most commonly used way to connect to the KNX bus. At its b
 
 | Name                | Required     | Description                                                                                                  | Default value                                        |
 |---------------------|--------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
-| type                | Yes          | The IP connection type for connecting to the KNX bus (`TUNNEL` or `ROUTER`)                                  | -                                                    |
+| type                | Yes          | The IP connection type for connecting to the KNX bus (`TUNNEL`, `ROUTER`, `SECURETUNNEL` or `SECUREROUTER`)                                  | -                                                    |
 | ipAddress           | for `TUNNEL` | Network address of the KNX/IP gateway. If type `ROUTER` is set, the IPv4 Multicast Address can be set.       | for `TUNNEL`: \<nothing\>, for `ROUTER`: 224.0.23.12 |
 | portNumber          | for `TUNNEL` | Port number of the KNX/IP gateway                                                                            | 3671                                                 |
 | localIp             | No           | Network address of the local host to be used to set up the connection to the KNX/IP gateway                  | the system-wide configured primary interface address |
@@ -200,6 +200,36 @@ Each configuration parameter has a `mainGA` where commands are written to and op
 The `dpt` element is optional. If omitted, the corresponding default value will be used (see the channel descriptions above).
 
 
+## KNX Secure
+
+> Note: Support for KNX Secure is partly implemented for openHAB and should be considered as experimental.
+
+### KNX IP Secure
+
+KNX IP Secure protects the traffic between openHAB and your KNX installation. It requires either a KNX Secure Router or a Secure IP Interface with security features enabled in ETS tool.
+
+For *Secure routing* mode, the so called `backbone key` needs to be configured in openHAB. It is created by the ETS tool and cannot be changed via the ETS user interface. There are two possible ways to provide the key to openHAB:
+
+- The backbone key can be extracted Security report (ETS, Reports, Security, look for a 32-digit key) and specified in parameter `routerBackboneKey`.
+- The backbone key is included in ETS keyring export (ETS, project settings, export keyring). Keyring file is configured using `keyringFile` (put it in `config\misc` folder of the openHAB installation) and also requires `keyringPassword`.
+
+For *Secure tunneling* with a Secure IP Interface (or a router in tunneling mode), more parameters are required. A unique device authentication key, and a specific tunnel identifier and password need to be available. It can be provided to openHAB in two different ways:
+
+- All information can be looked up in ETS and provided separately: `tunnelDeviceAuthentication`, `tunnelUserPassword`. `tunnelUserId` is a number which is not directly visible in ETS, but can be looked up in keyring export or deduced (typically 2 for the first tunnel of a device, 3 for the second one, ...)
+- All necessary information is included in ETS keyring export (ETS, project settings, export keyring). Keyring file is configured using `keyringFile` (put it in `config\misc` folder of the openHAB installation) and `keyringPassword`. In addition, `tunnelSourceAddress` needs to be set to uniquely identify the tunnel in use.
+
+
+### KNX Data Secure
+
+Data secure protects the content of messages on the KNX bus. In a KNX installation, both classic and secure group addresses can coexist.
+
+openHAB typically ignores messages with secure group addresses, unless data secure is configured.
+
+> NOTE: openHAB currently does fully support passive (listening) access to secure group addresses. Write access to secured GAs is done via the "GO diagnostics" feature described in KNX AN170 and is currently limited. Expect a timeout if a data value is written too often. Initial/periodic read will fail, avoid automatic read (< in thing definition).
+
+All necessary information to decode secure group addresses is included in ETS keyring export (ETS, project settings, export keyring). Keyring file is configured using `keyringFile` (put it in `config\misc` folder of the openHAB installation) and also requires `keyringPassword`.
+
+
 ## Examples
 
 The following two templates are sufficient for almost all purposes.

bundles/org.openhab.binding.knx/src/main/java/org/openhab/binding/knx/internal/KNXBindingConstants.java

@@ -54,6 +54,13 @@ public class KNXBindingConstants {
     public static final String PORT_NUMBER = "portNumber";
     public static final String SERIAL_PORT = "serialPort";
     public static final String USE_CEMI = "useCemi";
+    public static final String KEYRING_FILE = "keyringFile";
+    public static final String KEYRING_PASSWORD = "keyringPassword";
+    public static final String ROUTER_BACKBONE_GROUP_KEY = "routerBackboneGroupKey";
+    public static final String TUNNEL_USER_ID = "tunnelUserId";
+    public static final String TUNNEL_USER_PASSWORD = "tunnelUserPassword";
+    public static final String TUNNEL_DEVICE_AUTHENTICATION = "tunnelDeviceAuthentication";
+    public static final String TUNNEL_SOURCE_ADDRESS = "tunnelSourceAddress";
 
     // The default multicast ip address (see <a
     // href="http://www.iana.org/assignments/multicast-addresses/multicast-addresses.xml">iana</a> EIBnet/IP

bundles/org.openhab.binding.knx/src/main/java/org/openhab/binding/knx/internal/channel/TypeColor.java

@@ -40,7 +40,8 @@ class TypeColor extends KNXChannelType {
 
     @Override
     protected Set<String> getAllGAKeys() {
-        return Stream.of(SWITCH_GA, POSITION_GA, INCREASE_DECREASE_GA, HSB_GA).collect(toSet());
+        final var tmp = Stream.of(SWITCH_GA, POSITION_GA, INCREASE_DECREASE_GA, HSB_GA).collect(toSet());
+        return tmp;
     }
 
     @Override

bundles/org.openhab.binding.knx/src/main/java/org/openhab/binding/knx/internal/channel/TypeDimmer.java

@@ -40,7 +40,8 @@ class TypeDimmer extends KNXChannelType {
 
     @Override
     protected Set<String> getAllGAKeys() {
-        return Stream.of(SWITCH_GA, POSITION_GA, INCREASE_DECREASE_GA).collect(toSet());
+        final var tmp = Stream.of(SWITCH_GA, POSITION_GA, INCREASE_DECREASE_GA).collect(toSet());
+        return tmp;
     }
 
     @Override

bundles/org.openhab.binding.knx/src/main/java/org/openhab/binding/knx/internal/channel/TypeRollershutter.java

@@ -53,6 +53,7 @@ protected String getDefaultDPT(String gaConfigKey) {
 
     @Override
     protected Set<String> getAllGAKeys() {
-        return Stream.of(UP_DOWN_GA, STOP_MOVE_GA, POSITION_GA).collect(toSet());
+        final var tmp = Stream.of(UP_DOWN_GA, STOP_MOVE_GA, POSITION_GA).collect(toSet());
+        return tmp;
     }
 }

bundles/org.openhab.binding.knx/src/main/java/org/openhab/binding/knx/internal/client/AbstractKNXClient.java

@@ -55,6 +55,7 @@
 import tuwien.auto.calimero.process.ProcessCommunicatorImpl;
 import tuwien.auto.calimero.process.ProcessEvent;
 import tuwien.auto.calimero.process.ProcessListener;
+import tuwien.auto.calimero.secure.KnxSecureException;
 import tuwien.auto.calimero.secure.SecureApplicationLayer;
 import tuwien.auto.calimero.secure.Security;
 
@@ -79,6 +80,7 @@ public abstract class AbstractKNXClient implements NetworkLinkListener, KNXClien
     private final int readRetriesLimit;
     private final StatusUpdateCallback statusUpdateCallback;
     private final ScheduledExecutorService knxScheduler;
+    protected final Security openhabSecurity;
 
     private @Nullable ProcessCommunicator processCommunicator;
     private @Nullable ProcessCommunicationResponder responseCommunicator;
@@ -92,6 +94,9 @@ public abstract class AbstractKNXClient implements NetworkLinkListener, KNXClien
     private final Set<GroupAddressListener> groupAddressListeners = new CopyOnWriteArraySet<>();
     private final LinkedBlockingQueue<ReadDatapoint> readDatapoints = new LinkedBlockingQueue<>();
 
+    private boolean firstConnect;
+    private long lastDisconnectSysMillis;
+
     @FunctionalInterface
     private interface ListenerNotification {
         void apply(BusMessageListener listener, IndividualAddress source, GroupAddress destination, byte[] asdu);
@@ -102,6 +107,7 @@ private interface ListenerNotification {
 
         @Override
         public void detached(DetachEvent e) {
+            lastDisconnectSysMillis = System.currentTimeMillis();
             logger.debug("The KNX network link was detached from the process communicator");
         }
 
@@ -128,14 +134,18 @@ public void groupReadResponse(ProcessEvent e) {
     };
 
     public AbstractKNXClient(int autoReconnectPeriod, ThingUID thingUID, int responseTimeout, int readingPause,
-            int readRetriesLimit, ScheduledExecutorService knxScheduler, StatusUpdateCallback statusUpdateCallback) {
+            int readRetriesLimit, ScheduledExecutorService knxScheduler, StatusUpdateCallback statusUpdateCallback,
+            Security openhabSecurity) {
         this.autoReconnectPeriod = autoReconnectPeriod;
         this.thingUID = thingUID;
         this.responseTimeout = responseTimeout;
         this.readingPause = readingPause;
         this.readRetriesLimit = readRetriesLimit;
         this.knxScheduler = knxScheduler;
         this.statusUpdateCallback = statusUpdateCallback;
+        this.openhabSecurity = openhabSecurity;
+        firstConnect = true;
+        lastDisconnectSysMillis = System.currentTimeMillis();
     }
 
     public void initialize() {
@@ -146,7 +156,9 @@ public void initialize() {
 
     private boolean scheduleReconnectJob() {
         if (autoReconnectPeriod > 0) {
-            connectJob = knxScheduler.schedule(this::connect, autoReconnectPeriod, TimeUnit.SECONDS);
+            // schedule connect job, for the first connection ignore autoReconnectPeriod and use 1 sec
+            connectJob = knxScheduler.schedule(this::connect, firstConnect ? 1 : autoReconnectPeriod, TimeUnit.SECONDS);
+            firstConnect = false;
             return true;
         } else {
             return false;
@@ -174,6 +186,12 @@ private synchronized boolean connect() {
         if (isConnected()) {
             return true;
         }
+        long now = System.currentTimeMillis();
+        if ((now - lastDisconnectSysMillis) < 1000) {
+            logger.debug("fast reconnect");
+            // SECURETUNNEL: TCP Connections need additional efforts to avoid grabbing all tunnel connections
+            // the interface, this is implemented in IPClient
+        }
         try {
             releaseConnection();
 
@@ -196,7 +214,7 @@ private synchronized boolean connect() {
             this.processCommunicator = processCommunicator;
 
             ProcessCommunicationResponder responseCommunicator = new ProcessCommunicationResponder(link,
-                    new SecureApplicationLayer(link, Security.defaultInstallation()));
+                    new SecureApplicationLayer(link, openhabSecurity));
             this.responseCommunicator = responseCommunicator;
 
             link.addLinkListener(this);
@@ -207,7 +225,7 @@ private synchronized boolean connect() {
             statusUpdateCallback.updateStatus(ThingStatus.ONLINE);
             connectJob = null;
             return true;
-        } catch (KNXException | InterruptedException e) {
+        } catch (KNXException | InterruptedException | KnxSecureException e) {
             logger.debug("Error connecting to the bus: {}", e.getMessage(), e);
             disconnect(e);
             scheduleReconnectJob();
@@ -216,18 +234,19 @@ private synchronized boolean connect() {
     }
 
     private void disconnect(@Nullable Exception e) {
+        lastDisconnectSysMillis = System.currentTimeMillis();
+
         releaseConnection();
         if (e != null) {
-            String message = e.getLocalizedMessage();
             statusUpdateCallback.updateStatus(ThingStatus.OFFLINE, ThingStatusDetail.COMMUNICATION_ERROR,
-                    message != null ? message : "");
+                    "" + e.getLocalizedMessage());
         } else {
             statusUpdateCallback.updateStatus(ThingStatus.OFFLINE);
         }
     }
 
     @SuppressWarnings("null")
-    private void releaseConnection() {
+    protected void releaseConnection() {
         logger.debug("Bridge {} is disconnecting from the KNX bus", thingUID);
         readDatapoints.clear();
         busJob = nullify(busJob, j -> j.cancel(true));
@@ -276,6 +295,7 @@ private String toDPTValue(Type type, String dpt) {
         return typeHelper.toDPTValue(type, dpt);
     }
 
+    // datapoint is null at end of the list, warning is misleading
     @SuppressWarnings("null")
     private void readNextQueuedDatapoint() {
         if (!connectIfNotAutomatic()) {
@@ -286,7 +306,15 @@ private void readNextQueuedDatapoint() {
             return;
         }
         ReadDatapoint datapoint = readDatapoints.poll();
+
         if (datapoint != null) {
+            // TODO #8872: allow write access, currently only listening mode
+            if (openhabSecurity.groupKeys().containsKey(datapoint.getDatapoint().getMainAddress())) {
+                logger.debug("outgoing secure communication not implemented, explicit read from GA '{}' skipped",
+                        datapoint.getDatapoint().getMainAddress());
+                return;
+            }
+
             datapoint.incrementRetries();
             try {
                 logger.trace("Sending a Group Read Request telegram for {}", datapoint.getDatapoint().getMainAddress());
@@ -459,6 +487,12 @@ private void sendToKNX(ProcessCommunication communicator, KNXNetworkLink link, G
             return;
         }
 
+        // TODO #8872: allow write access, currently only listening mode
+        if (openhabSecurity.groupKeys().containsKey(groupAddress)) {
+            logger.debug("outgoing secure communication not implemented, write to GA '{}' skipped", groupAddress);
+            return;
+        }
+
         Datapoint datapoint = new CommandDP(groupAddress, thingUID.toString(), 0, dpt);
         String mappedValue = toDPTValue(type, dpt);
 

bundles/org.openhab.binding.knx/src/main/java/org/openhab/binding/knx/internal/client/CustomKNXNetworkLinkIP.java

@@ -30,6 +30,7 @@
 public class CustomKNXNetworkLinkIP extends KNXNetworkLinkIP {
 
     public static final int TUNNELING = KNXNetworkLinkIP.TUNNELING;
+    public static final int TUNNELINGV2 = KNXNetworkLinkIP.TunnelingV2;
     public static final int ROUTING = KNXNetworkLinkIP.ROUTING;
 
     CustomKNXNetworkLinkIP(final int serviceMode, KNXnetIPConnection conn, KNXMediumSettings settings)