Skip to content

Commit 4a42a47

Browse files
holgerfriedrichdigitaldan
holgerfriedrich
authored and
digitaldan
committed
[knx] Allow decoding of KNX Data Secure frames (openhab#12434)
* [knx] Allow decoding of KNX Data Secure frames Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>
1 parent 3a58310 commit 4a42a47

23 files changed

Lines changed: 957 additions & 108 deletions

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

Lines changed: 43 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -50,35 +50,40 @@ as multicast traffic is typically not forwarded.
5050
The IP Gateway is the most commonly used way to connect to the KNX bus.
5151
At its base, the _ip_ bridge accepts the following configuration parameters:
5252

53-
| Name | Required | Description | Default value |
54-
|---------------------|--------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
55-
| type | Yes | The IP connection type for connecting to the KNX bus (`TUNNEL`, `ROUTER`, `SECURETUNNEL` or `SECUREROUTER`) | - |
56-
| 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 |
57-
| portNumber | for `TUNNEL` | Port number of the KNX/IP gateway | 3671 |
58-
| 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 |
59-
| 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 |
60-
| useNAT | No | Whether there is network address translation between the server and the gateway | false |
61-
| readingPause | No | Time in milliseconds of how long should be paused between two read requests to the bus during initialization | 50 |
62-
| responseTimeout | No | Timeout in seconds to wait for a response from the KNX bus | 10 |
63-
| readRetriesLimit | No | Limits the read retries while initialization from the KNX bus | 3 |
64-
| autoReconnectPeriod | No | Seconds between connect retries when KNX link has been lost (0 means never). | 0 |
65-
| routerBackboneKey | No | KNX secure: Backbone key for secure router mode | - |
66-
| tunnelUserId | No | KNX secure: Tunnel user id for secure tunnel mode (if specified, it must be a number >0) | - |
67-
| tunnelUserPassword | No | KNX secure: Tunnel user key for secure tunnel mode | - |
68-
| tunnelDeviceAuthentication | No | KNX secure: Tunnel device authentication for secure tunnel mode | - |
53+
| Name | Required | Description | Default value |
54+
|---------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
55+
| type | Yes | The IP connection type for connecting to the KNX bus (`TUNNEL`, `ROUTER`, `SECURETUNNEL` or `SECUREROUTER`) | - |
56+
| 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 |
57+
| portNumber | for `TUNNEL` | Port number of the KNX/IP gateway | 3671 |
58+
| 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 |
59+
| 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 |
60+
| useNAT | No | Whether there is network address translation between the server and the gateway | false |
61+
| readingPause | No | Time in milliseconds of how long should be paused between two read requests to the bus during initialization | 50 |
62+
| responseTimeout | No | Timeout in seconds to wait for a response from the KNX bus | 10 |
63+
| readRetriesLimit | No | Limits the read retries while initialization from the KNX bus | 3 |
64+
| autoReconnectPeriod | No | Seconds between connect retries when KNX link has been lost (0 means never). | 0 |
65+
| routerBackboneKey | No | KNX secure: Backbone key for secure router mode | - |
66+
| tunnelUserId | No | KNX secure: Tunnel user id for secure tunnel mode (if specified, it must be a number >0) | - |
67+
| tunnelUserPassword | No | KNX secure: Tunnel user key for secure tunnel mode | - |
68+
| tunnelDeviceAuthentication | No | KNX secure: Tunnel device authentication for secure tunnel mode | - |
69+
| keyringFile | No | KNX secure: Keyring file exported from ETS and placed in openHAB config/misc folder. Mandatory to decode secure group addresses. | - |
70+
| keyringPassword | No | KNX secure: Keyring file password (set during export from ETS) | - |
71+
| 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. | - |
6972

7073
### Serial Gateway
7174

7275
The _serial_ bridge accepts the following configuration parameters:
7376

74-
| Name | Required | Description | Default value |
75-
|---------------------|----------|--------------------------------------------------------------------------------------------------------------|---------------|
76-
| serialPort | Y | The serial port to use for connecting to the KNX bus | - |
77-
| readingPause | N | Time in milliseconds of how long should be paused between two read requests to the bus during initialization | 50 |
78-
| responseTimeout | N | Timeout in seconds to wait for a response from the KNX bus | 10 |
79-
| readRetriesLimit | N | Limits the read retries while initialization from the KNX bus | 3 |
80-
| autoReconnectPeriod | N | Seconds between connect retries when KNX link has been lost, 0 means never retry | 0 |
81-
| useCemi | N | Use newer CEMI message format, useful for newer devices like KNX RF sticks, kBerry, etc. | false |
77+
| Name | Required | Description | Default value |
78+
|---------------------|----------|----------------------------------------------------------------------------------------------------------------------------------|---------------|
79+
| serialPort | Y | The serial port to use for connecting to the KNX bus | - |
80+
| readingPause | N | Time in milliseconds of how long should be paused between two read requests to the bus during initialization | 50 |
81+
| responseTimeout | N | Timeout in seconds to wait for a response from the KNX bus | 10 |
82+
| readRetriesLimit | N | Limits the read retries while initialization from the KNX bus | 3 |
83+
| autoReconnectPeriod | N | Seconds between connect retries when KNX link has been lost, 0 means never retry | 0 |
84+
| useCemi | N | Use newer CEMI message format, useful for newer devices like KNX RF sticks, kBerry, etc. | false |
85+
| keyringFile | N | KNX secure: Keyring file exported from ETS and placed in openHAB config/misc folder. Mandatory to decode secure group addresses. | - |
86+
| keyringPassword | N | KNX secure: Keyring file password (set during export from ETS) | - |
8287

8388
## Things
8489

@@ -452,24 +457,37 @@ It **requires a KNX Secure Router or a Secure IP Interface** and a KNX installat
452457

453458
For _Secure routing_ mode, the so-called `backbone key` needs to be configured in openHAB.
454459
It is created by the ETS tool and cannot be changed via the ETS user interface.
460+
There are two possible ways to provide the key to openHAB:
455461

456462
- The backbone key can be extracted from Security report (ETS, Reports, Security, look for a 32-digit key) and specified in parameter `routerBackboneKey`.
463+
- 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`.
457464

458465
For _Secure tunneling_ with a Secure IP Interface (or a router in tunneling mode), more parameters are required.
459466
A unique device authentication key, and a specific tunnel identifier and password need to be available.
467+
It can be provided to openHAB in two different ways:
460468

461469
- All information can be looked up in ETS and provided separately: `tunnelDeviceAuthentication`, `tunnelUserPassword`.
462470
`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, ...).
463471
`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".
464472
`tunnelDeviceAuthentication` is set in the properties of the IP interface itself; check for the tab "IP" and the description "Authentication Code".
473+
- All necessary information is included in ETS keyring export (ETS, project settings, export keyring).
474+
Keyring file is configured using `keyringFile` (put it in `config\misc` folder of the openHAB installation) and `keyringPassword`.
475+
In addition, `tunnelSourceAddress` needs to be set to uniquely identify the tunnel in use.
465476

466477
### KNX Data Secure
467478

468479
KNX Data Secure protects the content of messages on the KNX bus.
469480
In a KNX installation, both classic and secure group addresses can coexist.
470481
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**.
471482

472-
> NOTE: **openHAB currently ignores messages with secure group addresses.**
483+
**openHAB ignores messages with secure group addresses, unless data secure is configured.**
484+
485+
> NOTE: openHAB currently does fully support passive (listening) access to secure group addresses.
486+
Write access to secure group addresses is currently disabled in openHAB.
487+
Initial/periodic read will fail, avoid automatic read (< in thing definition).
488+
489+
All necessary information to decode secure group addresses is included in ETS keyring export (ETS, project settings, export keyring).
490+
Keyring file is configured using `keyringFile` (put it in `config\misc` folder of the openHAB installation) and also requires `keyringPassword`.
473491

474492
## Examples
475493

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,10 +63,13 @@ public class KNXBindingConstants {
6363
public static final String PORT_NUMBER = "portNumber";
6464
public static final String SERIAL_PORT = "serialPort";
6565
public static final String USE_CEMI = "useCemi";
66+
public static final String KEYRING_FILE = "keyringFile";
67+
public static final String KEYRING_PASSWORD = "keyringPassword";
6668
public static final String ROUTER_BACKBONE_GROUP_KEY = "routerBackboneGroupKey";
6769
public static final String TUNNEL_USER_ID = "tunnelUserId";
6870
public static final String TUNNEL_USER_PASSWORD = "tunnelUserPassword";
6971
public static final String TUNNEL_DEVICE_AUTHENTICATION = "tunnelDeviceAuthentication";
72+
public static final String TUNNEL_SOURCE_ADDRESS = "tunnelSourceAddress";
7073

7174
// The default multicast ip address (see <a
7275
// href="http://www.iana.org/assignments/multicast-addresses/multicast-addresses.xml">iana</a> EIBnet/IP

0 commit comments

Comments
 (0)