[knx] Allow decoding of KNX Data Secure frames (#12434)

* [knx] Allow decoding of KNX Data Secure frames Signed-off-by: Holger Friedrich <[email protected]>
openhab · Sep 15, 2024 · dbc607a · dbc607a
1 parent 104f328
commit dbc607a
Show file tree

Hide file tree

Showing 23 changed files with 957 additions and 108 deletions.
diff --git a/bundles/org.openhab.binding.knx/README.md b/bundles/org.openhab.binding.knx/README.md
@@ -50,35 +50,40 @@ as multicast traffic is typically not forwarded.
 The IP Gateway is the most commonly used way to connect to the KNX bus.
 At its base, the _ip_ bridge accepts the following configuration parameters:
 
-| Name | Required | Description | Default value |
-|---------------------|--------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
-| 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 |
-| localSourceAddr | No | The (virtual) individual address for identification of this openHAB Thing within the KNX bus <br/><br/>Note: Use a free address, not the one of the interface. Or leave it at `0.0.0` and let openHAB decide which address to use. When using knxd, make sure _not to use_ one of the addresses reserved for tunneling clients. | 0.0.0 |
-| useNAT | No | Whether there is network address translation between the server and the gateway | false |
-| readingPause | No | Time in milliseconds of how long should be paused between two read requests to the bus during initialization | 50 |
-| responseTimeout | No | Timeout in seconds to wait for a response from the KNX bus | 10 |
-| readRetriesLimit | No | Limits the read retries while initialization from the KNX bus | 3 |
-| autoReconnectPeriod | No | Seconds between connect retries when KNX link has been lost (0 means never). | 0 |
-| routerBackboneKey | No | KNX secure: Backbone key for secure router mode | - |
-| tunnelUserId | No | KNX secure: Tunnel user id for secure tunnel mode (if specified, it must be a number >0) | - |
-| tunnelUserPassword | No | KNX secure: Tunnel user key for secure tunnel mode | - |
-| tunnelDeviceAuthentication | No | KNX secure: Tunnel device authentication for secure tunnel mode | - |
+| Name | Required | Description | Default value |
+|---------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
+| 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 |
+| localSourceAddr | No | The (virtual) individual address for identification of this openHAB Thing within the KNX bus <br/><br/>Note: Use a free address, not the one of the interface. Or leave it at `0.0.0` and let openHAB decide which address to use.<br/>When using knxd, make sure _not to use_ one of the addresses reserved for tunneling clients. | 0.0.0 |
+| useNAT | No | Whether there is network address translation between the server and the gateway | false |
+| readingPause | No | Time in milliseconds of how long should be paused between two read requests to the bus during initialization | 50 |
+| responseTimeout | No | Timeout in seconds to wait for a response from the KNX bus | 10 |
+| readRetriesLimit | No | Limits the read retries while initialization from the KNX bus | 3 |
+| autoReconnectPeriod | No | Seconds between connect retries when KNX link has been lost (0 means never). | 0 |
+| routerBackboneKey | No | KNX secure: Backbone key for secure router mode | - |
+| tunnelUserId | No | KNX secure: Tunnel user id for secure tunnel mode (if specified, it must be a number >0) | - |
+| tunnelUserPassword | No | KNX secure: Tunnel user key for secure tunnel mode | - |
+| tunnelDeviceAuthentication | No | KNX secure: Tunnel device authentication for secure tunnel mode | - |
+| keyringFile | No | KNX secure: Keyring file exported from ETS and placed in openHAB config/misc folder. Mandatory to decode secure group addresses. | - |
+| keyringPassword | No | KNX secure: Keyring file password (set during export from ETS) | - |
+| tunnelSourceAddress | No | KNX secure: Physical KNX address of tunnel in secure mode to identify tunnel. If given, openHAB will read tunnelUserId, tunnelUserPassword, tunnelDeviceAuthentication from keyring. | - |
 
 ### Serial Gateway
 
 The _serial_ bridge accepts the following configuration parameters:
 
-| Name | Required | Description | Default value |
-|---------------------|----------|--------------------------------------------------------------------------------------------------------------|---------------|
-| serialPort | Y | The serial port to use for connecting to the KNX bus | - |
-| readingPause | N | Time in milliseconds of how long should be paused between two read requests to the bus during initialization | 50 |
-| responseTimeout | N | Timeout in seconds to wait for a response from the KNX bus | 10 |
-| readRetriesLimit | N | Limits the read retries while initialization from the KNX bus | 3 |
-| autoReconnectPeriod | N | Seconds between connect retries when KNX link has been lost, 0 means never retry | 0 |
-| useCemi | N | Use newer CEMI message format, useful for newer devices like KNX RF sticks, kBerry, etc. | false |
+| Name | Required | Description | Default value |
+|---------------------|----------|----------------------------------------------------------------------------------------------------------------------------------|---------------|
+| serialPort | Y | The serial port to use for connecting to the KNX bus | - |
+| readingPause | N | Time in milliseconds of how long should be paused between two read requests to the bus during initialization | 50 |
+| responseTimeout | N | Timeout in seconds to wait for a response from the KNX bus | 10 |
+| readRetriesLimit | N | Limits the read retries while initialization from the KNX bus | 3 |
+| autoReconnectPeriod | N | Seconds between connect retries when KNX link has been lost, 0 means never retry | 0 |
+| useCemi | N | Use newer CEMI message format, useful for newer devices like KNX RF sticks, kBerry, etc. | false |
+| keyringFile | N | KNX secure: Keyring file exported from ETS and placed in openHAB config/misc folder. Mandatory to decode secure group addresses. | - |
+| keyringPassword | N | KNX secure: Keyring file password (set during export from ETS) | - |
 
 ## Things
 
@@ -452,24 +457,37 @@ It **requires a KNX Secure Router or a Secure IP Interface** and a KNX installat
 
 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 from 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 that 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, ...).
  `tunnelUserPasswort` is set in ETS in the properties of the tunnel (below the IP interface, you will see the different tunnels listed) and denoted as "Password".
  `tunnelDeviceAuthentication` is set in the properties of the IP interface itself; check for the tab "IP" and the description "Authentication Code".
+- 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
 
 KNX Data Secure protects the content of messages on the KNX bus.
 In a KNX installation, both classic and secure group addresses can coexist.
 Data Secure does _not_ necessarily require a KNX Secure Router or a Secure IP Interface, but a KNX installation with newer KNX devices that support Data Secure and with **security features enabled in the ETS tool**.
 
-> NOTE: **openHAB currently ignores messages with secure group addresses.**
+**openHAB 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 secure group addresses is currently disabled in openHAB.
+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
 

diff --git a/...enhab.binding.knx/src/main/java/org/openhab/binding/knx/internal/KNXBindingConstants.java b/...enhab.binding.knx/src/main/java/org/openhab/binding/knx/internal/KNXBindingConstants.java
@@ -63,10 +63,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