Trust Center#

sl_zigbee_broadcast_next_network_key#

sl_status_t sl_zigbee_broadcast_next_network_key (sl_zigbee_key_data_t * key)

Broadcast a new encryption key but does not tell the nodes in the network to start using it.

To broadcast a new key, use sl_zigbee_broadcast_network_key_switch(), which is only valid for the Trust Center/Coordinator. It is not valid when operating in Distributed Trust Center mode.

It is up to the application to determine how quickly to send the Switch Key after sending the alternate encryption key. The factors to consider are the polling rate of sleepy end devices and the buffer size of their parent nodes. Sending too quickly may cause a sleepy end device to miss the Alternate Encryption Key and only get the Switch Key message, which means it will be unable to change to the new network key.

Returns

• An ::sl_status_t value that indicates the success or failure of the command.

sl_zigbee_send_unicast_network_key_update#

sl_status_t sl_zigbee_send_unicast_network_key_update (sl_802154_short_addr_t targetShort, sl_802154_long_addr_t targetLong, const sl_zigbee_key_data_t * newKey)

Send a unicast update of the network key to the target device. The APS command will be encrypted using the device's current APS link key. On success, the bit ::EMBER_KEY_UNICAST_NWK_KEY_UPDATE_SENT will be set in the link key table entry for the device. When a successful call is made to sl_zigbee_broadcast_network_key_switch(), the bit will be cleared for all entries.

On the first call to this function, the trust center's local copy of the alternate NWK key will be updated with the new value.

Both the short and long address of the device must be known ahead of time and passed in as parameters. It is assumed that the application has already generated the new network key and will pass the same key value on subsequent calls to send the key to different nodes in the network.

Returns

• An ::sl_status_t value that indicates the success or failure of the command.

sl_zigbee_set_transient_device_table_timeout_ms#

sl_status_t sl_zigbee_set_transient_device_table_timeout_ms (uint16_t timeout)

Set the timeout value for transient device table in milliseconds.

Returns

sl_zigbee_get_transient_device_table_timeout_ms#

uint16_t sl_zigbee_get_transient_device_table_timeout_ms (void )

Get the timeout value of transient device table in milliseconds.

Returns

• an uint16_t value that indicates the timeout value

sl_zigbee_unicast_current_network_key#

sl_status_t sl_zigbee_unicast_current_network_key (sl_802154_short_addr_t targetShort, sl_802154_long_addr_t targetLong, sl_802154_short_addr_t parentShortId)

Send the network key to the target device. The APS command will be encrypted using the device's current APS link key. The call fails if no link key is available.

Both the short and long address of the device must be known ahead of time and passed in as parameters. It is assumed that the application has already generated the new network key and will pass the same key value on subsequent calls to send the key to different nodes in the network.

Returns

• An ::sl_status_t value that indicates the success or failure of the command.

sl_zigbee_broadcast_network_key_switch#

sl_status_t sl_zigbee_broadcast_network_key_switch (void )

Broadcast a switch key message to tell all nodes to change to the sequence number of the previously sent Alternate Encryption Key.

This function is only valid for the Trust Center/Coordinator and will also cause the Trust Center/Coordinator to change its Network Key. It is not valid when operating in Distributed Trust Center mode.

Returns

• An ::sl_status_t value that indicates the success or failure of the command.

sl_zigbee_internal_trust_center_join_handler#

sl_zigbee_join_decision_t sl_zigbee_internal_trust_center_join_handler (sl_802154_short_addr_t newNodeId, sl_802154_long_addr_t newNodeEui64, sl_zigbee_device_update_t status, sl_802154_short_addr_t parentOfNewNode)

Allow the application running on the Trust Center (which is the coordinator for ZigBee networks) to control which nodes are allowed to join the network. If the node is allowed to join, the trust center must decide whether to send the Network Key encrypted or unencrypted to the joining node.

A default handler is provided and its behavior is as follows. A status of ::EMBER_DEVICE_SECURED_REJOIN means that the device has the Network Key, no action is required from the Trust Center. A status of SL_ZIGBEE_DEVICE_LEFT also requires no action. In both cases, SL_ZIGBEE_NO_ACTION is returned.

When operating in a network with a Trust Center and there is a Global Link Key configured, SL_ZIGBEE_USE_PRECONFIGURED_KEY will be returned, which means the Trust Center is using a preconfigured Link Key. The Network Key will be sent to the joining node encrypted with the Link Key. If a Link Key has not been set on the Trust Center, SL_ZIGBEE_DENY_JOIN is returned.

The ::SL_ZIGBEE_ASK_TRUST_CENTER decision has been deprecated. This function will not be called for a router or end device when operating in a Network With a Trust Center.

If the device is a router in a network that is operating in a Distributed Trust Center Security mode, the handler will be called by the stack.

The default handler in a Distributed Trust Center Security mode network is as follows: If the router received an encrypted Network Key when it joined, a preconfigured Link key will be used to send the Network Key Encrypted to the joining device (SL_ZIGBEE_USE_PRECONFIGURED_KEY). If the router received the Network Key in the clear, it will also send the key in the clear to the joining node (SL_ZIGBEE_SEND_KEY_IN_THE_CLEAR).

This function is run only on the SoC and NCP; it will invoke sl_zigbee_trust center_post_join_handler upon making a decision, which allows application code running on either SoC or host to react to the join decision that was made.

Returns

• SL_ZIGBEE_USE_PRECONFIGURED_KEY to allow the node to join without sending it the key. SL_ZIGBEE_SEND_KEY_IN_THE_CLEAR to allow the node to join and send it the key. SL_ZIGBEE_DENY_JOIN to reject the join attempt. The value should not be returned if the local node is itself the trust center.

sl_zigbee_trust_center_post_join_handler#

void sl_zigbee_trust_center_post_join_handler (sl_802154_short_addr_t newNodeId, sl_802154_long_addr_t newNodeEui64, sl_zigbee_device_update_t status, sl_zigbee_join_decision_t policyDecision, sl_802154_short_addr_t parentOfNewNode)

Allow the application running on the Trust Center (which is the coordinator for ZigBee networks) to respond to a decision that has been made by stack or xNCP code about whether a device should be allowed to join. This is invoked when sl_zigbee_internal_trust_center_join_handler has made a decision.

sl_zigbee_get_trust_center_link_key_request_policy#

sl_zigbee_tc_link_key_request_policy_t sl_zigbee_get_trust_center_link_key_request_policy (void )

Control the policy that the Trust Center uses for determining whether to allow or deny requests for Trust Center link keys.

The following is a good set of guidelines for TC Link key requests:

• If preconfigured TC link keys are set up on devices, requests for the TC key should never be allowed (SL_ZIGBEE_DENY_TC_LINK_KEY_REQUESTS).

• If devices request link keys during joining (i.e., join in the clear and set SL_ZIGBEE_GET_LINK_KEY_WHEN_JOINING) then it is advisable to allow requesting keys from the TC for a short period of time (e.g., the same amount of time "permit joining" is turned on). Afterwards, requests for the TC link key should be denied.

sl_zigbee_set_trust_center_link_key_request_policy#

void sl_zigbee_set_trust_center_link_key_request_policy (sl_zigbee_tc_link_key_request_policy_t policy)

sl_zigbee_get_app_link_key_request_policy#

sl_zigbee_app_link_key_request_policy_t sl_zigbee_get_app_link_key_request_policy (void )

Control the policy that the Trust Center uses for determining whether to allow or deny requests for application link keys between device pairs. When a request is received and the policy is SL_ZIGBEE_ALLOW_TC_LINK_KEY_REQUEST_AND_SEND_CURRENT_KEY, the TC will generate a random key and send a copy to both devices encrypted with their individual link keys.

Generally, application link key requests may always be allowed.

sl_zigbee_set_app_link_key_request_policy#

void sl_zigbee_set_app_link_key_request_policy (sl_zigbee_app_link_key_request_policy_t policy)

sl_zigbee_send_remove_device#

sl_status_t sl_zigbee_send_remove_device (sl_802154_short_addr_t destShort, sl_802154_long_addr_t destLong, sl_802154_long_addr_t deviceToRemoveLong)

Send an APS remove device command to the destination. If the destination is an end device, this must be sent to the parent of the end device. In that case, the deviceToRemoveLong and the destLong will be different values. Otherwise, if a router is being asked to leave, those parameters will be the same. This command will be APS encrypted with the destination device's link key, which means a link key must be present.

Returns

• An ::sl_status_t value indicating success or failure of the operation.

sl_zigbee_send_trust_center_link_key#

sl_status_t sl_zigbee_send_trust_center_link_key (sl_802154_short_addr_t destinationNodeId, sl_802154_long_addr_t destinationEui64)

Send the trust center link key to a node.

This function sends an APS TransportKey command containing the current trust center link key. The node to which the command is sent is specified via the short and long address arguments.

Returns

• An ::sl_status_t value indicating success or failure of the operation.

SL_ZIGBEE_FORM_TRUST_CENTER_NETWORK_BITMASK#

#define SL_ZIGBEE_FORM_TRUST_CENTER_NETWORK_BITMASK

A Trust Center device configuration bitmask example. The Trust Center is expected to be set up with a Network Key Preconfigured Link Key that is global throughout all devices on the Network. The decision whether or not to send the key in-the-clear is NOT controlled through this bitmask. It is controlled via the sl_zigbee_internal_trust_center_join_handler(...) function.

SL_ZIGBEE_FORM_DISTRIBUTED_TRUST_CENTER_NETWORK_BITMASK#

#define SL_ZIGBEE_FORM_DISTRIBUTED_TRUST_CENTER_NETWORK_BITMASK

A coordinator device configuration bitmask example. The coordinator is expected to be set up with a Network Key and a Preconfigured Link Key that is global throughout all devices on the Network. The decision whether or not to send the key in-the-clear is decentralized. Each individual router can make this decision via the sl_zigbee_internal_trust_center_join_handler(...) function.