The Update Matter command is sent to the datasource to manage the Matter source node ID and session key relationships which are needed to decrypt Matter messages. The command format is:
“Update Matter;matterkeys=<source node id value>, <session key 1 value>, ... <session key N value>".
Whitespace is not allowed between any characters in the first part of the command “Update Matter;matterkeys=”: No whitespace around the first semicolon nor whitespace before the equal sign. Whitespace is allowed after the equal sign.
The values are in the form of first a “<source node id>” followed by zero or more “<session key>" where the parameters are:
-
“source node id” – The 64-bit source node id – must be in the hexadecimal form “0x0123456789abcdef” starting with “0x” followed by 16 hexadecimal characters.
-
“session key” – The 128-bit session key – must be in the hexadecimal form “0x0123456789abcdef0123456789abcdef” starting with “0x” followed by 32 hexadecimal characters.
For both parameters “source node id” and “session key”:
-
The hexadecimal value must have a “0x” prefix, with a lower-case ‘x’, to be consistent with other hexadecimal values in the automation calls. (Note that this requirement does differ from how the keys are entered in the UI, which does not have the “0x” prefix.)
-
The hexadecimal characters ‘a’,’ b’, ’c’, ’d’, ’e’, and ‘f’ may be either upper-case or lower-case.
If the “source node id” is specified without the session keys, then any existing entry for that Source Node ID will be removed from WPS.
If the “source node id” is specified with session keys and that Source Node ID with Session Keys already exists in WPS, then those session keys will be replaced with the current set specified.
Three examples of updating the Matter session keys are:
# Ex 1: Add the first source node id and its session keys (only spaces are allowed for
# whitespace, not newline characters)
UPDATE MATTER;matterkeys= 0x000000005007fdde,0x0aca059c53f000de92866597807ad848,0xf9327337300d35e986adfad20416d083,0x286e2366f08f5c6d6c9d1dd5e71cef9f
# Ex 2: Add the second source node id and its session keys
UPDATE MATTER ;matterkeys=0x000000000A79CEb2, 0x8e1f9380d47d561984250d08f69261d2 , 0x326a3104c61b0ca3e2f50ec4d4f90ff3, 0x20dd04a52326943dc74071b828f4aae8
# Ex 3: Remove the second source node id and its session keys
UPDATE MATTER;matterkeys=0x000000000A79ceb2
Response: “UPDATE MATTER;<status>;Reason=<reason>” where reason will be supplied for SUCCEEDED and FAILED status.
For SUCCEEDED status, “<reason >” will be:
“Matter session keys updated successfully.” – Either the session keys were updated for a source node id, or a source node id and its associated session keys were removed.
For FAILED status, “<reason>” will be one of the following:
-
“Source Node ID is not valid. It should be a 64-bit hex string with a leading 0x.” – The source node id is not 16 hexadecimal digits in the form of the example “0x000000000A79ceb2”. This failure can also be caused if a separator character other than a comma is used to separate the source node id from the session keys.
-
“One or more of the session keys are not valid. They should be 128-bit hex strings with a leading 0x.” – One or more session keys is not 32 hexadecimal digits in the form of the example “0x326a3104c61b0ca3e2f50ec4d4f90ff3”. This failure can also be caused if a separator character other than a comma is used to separate the session keys.
-
“Command is not valid. The equal sign after matterkeys is missing.” – The parameter “matterkeys=” must be lowercase and not have whitespace between “matterkeys” and “=”.
-
“Command is not valid. The command should start with 'matterkeys='” – Most likely there is a typo in the phrase “matterkeys”.