Modules
Trust Center

Macros
#define	EMBER_JOIN_NO_PRECONFIG_KEY_BITMASK
	A non-trust center device configuration bitmask example. There is no Preconfigured Link Key, so the NWK key is expected to be sent in-the-clear. The device will request a Trust Center Link key after getting the Network Key.

#define	EMBER_JOIN_PRECONFIG_KEY_BITMASK
	A non-trust center device configuration bitmask example. The device has a Preconfigured Link Key and expects to receive a NWK Key encrypted at the APS Layer. A NWK key sent in-the-clear will be rejected.

Functions
EmberStatus	emberSetInitialSecurityState ( EmberInitialSecurityState *state)
	Sets the initial security state that will be used by the device when it forms or joins a network. If security is enabled, this function must be called prior to forming or joining the network. It must also be called if the device left the network and wishes to form or join another network.

EmberStatus	emberSetExtendedSecurityBitmask ( EmberExtendedSecurityBitmask mask)
	Sets the extended initial security bitmask.

EmberStatus	emberGetExtendedSecurityBitmask ( EmberExtendedSecurityBitmask *mask)
	Gets the extended security bitmask that is used by a device.

EmberStatus	emberGetCurrentSecurityState ( EmberCurrentSecurityState *state)
	Gets the security state that is used by a device joined into the Network.

EmberStatus	emberGetKey ( EmberKeyType type, EmberKeyStruct *keyStruct)
	Gets the specified key and its associated data. This can retrieve the Trust Center Link Key, Current Network Key, or Next Network Key. On the 35x series chips, the data returned by this call is governed by the security policy set in the manufacturing token for TOKEN_MFG_SECURITY_CONFIG. See the API calls emberSetMfgSecurityConfig() and emberGetMfgSecurityConfig() for more information. If the security policy is not set to EMBER_KEY_PERMISSIONS_READING_ALLOWED , the actual encryption key value will not be returned. Other metadata about the key will be returned.

bool	emberHaveLinkKey (EmberEUI64 remoteDevice)
	Returns true if a link key is available for securing messages sent to the remote device.

EmberStatus	emberGenerateRandomKey ( EmberKeyData *keyAddress)
	Generates a Random Key (link, network, or master) and returns the result.

void	emberSwitchNetworkKeyHandler (uint8_t sequenceNumber)
	Callback to inform the application that the Network Key has been updated and the node has been switched over to use the new key. The actual key being used is not passed up, but the sequence number is.

EmberStatus	emberRequestLinkKey (EmberEUI64 partner)
	A function to request a Link Key from the Trust Center with another device device on the Network (which could be the Trust Center). A Link Key with the Trust Center is possible but the requesting device cannot be the Trust Center. Link Keys are optional in ZigBee Standard Security. Therefore, the stack can't know whether the other device supports them.

EmberStatus	emberUpdateTcLinkKey (uint8_t maxAttempts)
	Requests a new link link key from the Trust Center. This function starts by sending a Node Descriptor request to the Trust Center to verify its R21+ stack version compliance. A Request Key message will then be sent, followed by a Verify Key Confirm message.

void	emberZigbeeKeyEstablishmentHandler (EmberEUI64 partner, EmberKeyStatus status)
	Callback to notify the application about the status of the request for a Link Key. The application should define EMBER_APPLICATION_HAS_ZIGBEE_KEY_ESTABLISHMENT_HANDLER to implement its own handler.

EmberStatus	emberGetKeyTableEntry (uint8_t index, EmberKeyStruct *result)
	Gets data from the Key Table. On the 35x series chips, the data returned by this call is governed by the security policy set in the manufacturing token for TOKEN_MFG_SECURITY_CONFIG. See the API calls emberSetMfgSecurityConfig() and emberGetMfgSecurityConfig() for more information. If the security policy is not set to EMBER_KEY_PERMISSIONS_READING_ALLOWED , the actual encryption key value will not be returned. Other metadata about the key will be returned.

EmberStatus	emberSetKeyTableEntry (uint8_t index, EmberEUI64 address, bool linkKey, EmberKeyData *keyData)
	Sets an entry in the key table.

EmberStatus	emberAddOrUpdateKeyTableEntry (EmberEUI64 address, bool linkKey, EmberKeyData *keyData)
	Adds a new entry in the key table or updates an existing entry with a new key. It first searches the key table for an entry that has a matching EUI64. If it does not find one, it searches for the first free entry. If it is successful in either case, it sets the entry with the EUI64, key data, and flag that indicates if it is a Link or Master Key. The Incoming Frame Counter for that key is also reset to 0. If no existing entry was found and there are no free entries in the table, the call will fail.

uint8_t	emberFindKeyTableEntry (EmberEUI64 address, bool linkKey)
	Searches the key table to find an entry matching the specified IEEE address and key type.

EmberStatus	emberEraseKeyTableEntry (uint8_t index)
	Clears a single entry in the key table.

EmberStatus	emberClearKeyTable (void)
	Clears the key table of the current network.

EmberStatus	emberStopWritingStackTokens (void)
	Suppresses normal write operations of the stack tokens. This is only done in rare circumstances when the device already has network parameters but needs to conditionally rejoin a network in order to perform a security message exchange (i.e., key establishment). If the network is not authenticated properly, it will need to forget any stack data it used and return to the old network. By suppressing writing of the stack tokens the device will not have stored any persistent data about the network and a reboot will clear the RAM copies. The Smart Energy profile feature Trust Center Swap-out uses this to securely replace the Trust Center and re-authenticate to it.

EmberStatus	emberStartWritingStackTokens (void)
	Immediately writes the value of stack tokens and then resumes normal network operation by writing the stack tokens at appropriate intervals or changes in state. It has no effect unless a previous call was made to emberStopWritingStackTokens() .

bool	emberWritingStackTokensEnabled (void)
	Determines whether stack tokens will be written to persistent storage when they change. By default it is set to true meaning the stack will update its internal tokens via HAL calls when the associated RAM values change.

EmberStatus	emberApsCryptMessage (bool encrypt, EmberMessageBuffer *buffer, uint8_t apsHeaderEndIndex, EmberEUI64 remoteEui64)
	Performs APS encryption/decryption of messages directly. Normally, the stack handles all APS encryption/decryption automatically and there is no need to call this function. If APS data is sent or received via some other means (such as over interpan), APS encryption/decryption must be done manually. If the decryption is performed, the Auxiliary security header and MIC will be removed from the message. If encrypting, the auxiliary header and MIC will be added to the message. This is only available on SOC platforms.

EmberStatus	emberGetMfgSecurityConfig ( EmberMfgSecurityStruct *settings)
	Retrieves the security configuration stored in manufacturing tokens. It is only available on the 35x series. See emberSetMfgSecurityConfig() for more details.

EmberStatus	emberSetMfgSecurityConfig (uint32_t magicNumber, const EmberMfgSecurityStruct *settings)
	Sets the security configuration to be stored in manufacturing tokens. It is only available on the 35x series. This API must be called with care. Once set, a manufacturing token CANNOT BE UNSET without using the ISA3 tools and connecting the chip via JTAG. Additionally, a chip with read protection enabled cannot have its configuration changed without a full chip erase. Therefore, this provides a way to disallow access to the keys at runtime that cannot be undone.

EmberStatus	emberSetOutgoingNwkFrameCounter (uint32_t desiredValue)
	Sets the NWK layer outgoing frame counter (intended for device restoration purposes). Caveats:

EmberStatus	emberSetOutgoingApsFrameCounter (uint32_t desiredValue)
	Sets the APS layer outgoing frame counter for Trust Center Link Key (intended for device restoration purposes). Caveats:

EmberStatus	emberAddTransientLinkKey (EmberEUI64 partnerEUI64, EmberKeyData *key)
	Adds a temporary link key for a joining device. The link key will be stored for emberTransientKeyTimeoutS seconds. After that time, the key will be removed. The removed key will need to be added again using this API before it can be used by a joining device again.

EmberStatus	emberGetTransientKeyTableEntry (uint8_t index, EmberTransientKeyData *transientKeyData)
	Gets the transient link key at the index specified in the transient key table.

EmberStatus	emberGetTransientLinkKey (const EmberEUI64 eui, EmberTransientKeyData *transientKeyData)
	Gets the transient link key for a device. This function searches the transient key table for an entry matching the EUI passed in.

void	emberClearTransientLinkKeys (void)
	Clears all transient link keys from RAM.

void	emberHmacAesHash (const uint8_t key, const uint8_t data, uint8_t dataLength, uint8_t *result)

EmberApsRejoinMode	emberGetRejoinMode (void)

void	emberSetRejoinMode ( EmberApsRejoinMode mode)

uint32_t	emberGetSecurityFrameCounter (void)

uint32_t	emberGetApsFrameCounter (void)

uint32_t	emberGetIncomingTcLinkKeyFrameCounter (void)

void	emberSetIncomingTcLinkKeyFrameCounter (uint32_t frameCounter)

Variables
uint16_t	emberTransientKeyTimeoutS
	The length of time, in seconds, that a trust center will store a transient link key that a device can use to join its network. A transient key is added with a call to emberAddTransientLinkKey. After the transient key is added, it will be removed once this amount of time has passed. A joining device will not be able to use that key to join until it is added again on the trust center. The default value is 300 seconds, i.e., 5 minutes.

Detailed Description

This file describes the functions necessary to manage security for a regular device. There are three major modes for security and applications should link in the appropriate library:

Residential security uses only network keys. This is the only supported option for ZigBee 2006 devices.
Standard security uses network keys with optional link keys. Ember strongly recommends using Link Keys. It is possible for 2006 devices to run on a network that uses Standard Security.

See security.h for source code.

Macro Definition Documentation

◆ EMBER_JOIN_NO_PRECONFIG_KEY_BITMASK

#define EMBER_JOIN_NO_PRECONFIG_KEY_BITMASK

Value:

( EMBER_STANDARD_SECURITY_MODE \

| EMBER_GET_LINK_KEY_WHEN_JOINING )

EMBER_GET_LINK_KEY_WHEN_JOINING

Definition: ember-types.h:1886

EMBER_STANDARD_SECURITY_MODE

#define EMBER_STANDARD_SECURITY_MODE

This is an EmberInitialSecurityBitmask value but it does not actually set anything. It is the default mode used by the ZigBee Pro stack. It is defined here so that no legacy code is broken by referencing it.

Definition: ember-types.h:1821

A non-trust center device configuration bitmask example. There is no Preconfigured Link Key, so the NWK key is expected to be sent in-the-clear. The device will request a Trust Center Link key after getting the Network Key.

◆ EMBER_JOIN_PRECONFIG_KEY_BITMASK

#define EMBER_JOIN_PRECONFIG_KEY_BITMASK

Value:

         (
         
          EMBER_STANDARD_SECURITY_MODE
         
         \
        
         |
         
          EMBER_HAVE_PRECONFIGURED_KEY
         
         \
        
         |
         
          EMBER_REQUIRE_ENCRYPTED_KEY
         
         )

A non-trust center device configuration bitmask example. The device has a Preconfigured Link Key and expects to receive a NWK Key encrypted at the APS Layer. A NWK key sent in-the-clear will be rejected.

Function Documentation

◆ emberAddOrUpdateKeyTableEntry()

EmberStatus emberAddOrUpdateKeyTableEntry	(	EmberEUI64	`address,`
		bool	`linkKey,`
		EmberKeyData *	`keyData`
	)

Adds a new entry in the key table or updates an existing entry with a new key. It first searches the key table for an entry that has a matching EUI64. If it does not find one, it searches for the first free entry. If it is successful in either case, it sets the entry with the EUI64, key data, and flag that indicates if it is a Link or Master Key. The Incoming Frame Counter for that key is also reset to 0. If no existing entry was found and there are no free entries in the table, the call will fail.

Parameters

`address`	The IEEE Address of the partner device that shares the key.
`linkKey`	A bool indicating whether this is a Link or Master key.
`keyData`	A pointer to the actual key data.

Returns: EMBER_TABLE_FULL if no free entry was found to add. EMBER_KEY_INVALID if the passed key was a reserved value. ::EMBER_KEY_TABLE_ADDRESS_NOT_VALID if the passed address is reserved or invalid. EMBER_SUCCESS on success.

◆ emberAddTransientLinkKey()

EmberStatus emberAddTransientLinkKey	(	EmberEUI64	`partnerEUI64,`
		EmberKeyData *	`key`
	)

Adds a temporary link key for a joining device. The link key will be stored for emberTransientKeyTimeoutS seconds. After that time, the key will be removed. The removed key will need to be added again using this API before it can be used by a joining device again.

Parameters

`partnerEUI64`	The EUI of the joining device. If all FF's are entered for this value, then the key can be used for all joining devices that do not already have transient key table entries.
`key`	The temporary link key to the joining device.

Returns: EMBER_SUCCESS if the transient key has been added. EMBER_BAD_ARGUMENT if the parameters are invalid. EMBER_INVALID_CALL if the key type is invalid. EMBER_NO_BUFFERS if there are no buffers.

◆ emberApsCryptMessage()

EmberStatus emberApsCryptMessage	(	bool	`encrypt,`
		EmberMessageBuffer *	`buffer,`
		uint8_t	`apsHeaderEndIndex,`
		EmberEUI64	`remoteEui64`
	)

Performs APS encryption/decryption of messages directly. Normally, the stack handles all APS encryption/decryption automatically and there is no need to call this function. If APS data is sent or received via some other means (such as over interpan), APS encryption/decryption must be done manually. If the decryption is performed, the Auxiliary security header and MIC will be removed from the message. If encrypting, the auxiliary header and MIC will be added to the message. This is only available on SOC platforms.

Parameters

`encrypt`	A bool indicating whether perform encryption (true) or decryption (false).
`buffer`	An EmberMessageBuffer containing the APS frame to decrypt or encrypt.
`apsHeaderEndIndex`	The index in the buffer where the APS header ends. If encryption is being performed, this should point to the APS payload, where an Auxiliary header will be inserted. If decryption is being performed, this should point to the start of the Auxiliary header frame.
`remoteEui64`	the ::EmberEUI64 of the remote device the message was received from (decryption) or being sent to (encryption).

Returns: EMBER_SUCCESS if encryption/decryption was performed successfully. An appropriate EmberStatus code on failure.

◆ emberClearKeyTable()

EmberStatus emberClearKeyTable ( void )

Clears the key table of the current network.

Returns: EMBER_SUCCESS if the key table was successfully cleared. EMBER_INVALID_CALL otherwise.

◆ emberClearTransientLinkKeys()

void emberClearTransientLinkKeys ( void )

Clears all transient link keys from RAM.

◆ emberEraseKeyTableEntry()

EmberStatus emberEraseKeyTableEntry ( uint8_t index )

Clears a single entry in the key table.

Parameters

index The index in the key table of the entry to erase.

Returns: EMBER_SUCCESS if the index is valid and the key data was erased. EMBER_KEY_INVALID if the index is out of range for the size of the key table.

◆ emberFindKeyTableEntry()

uint8_t emberFindKeyTableEntry	(	EmberEUI64	`address,`
		bool	`linkKey`
	)

Searches the key table to find an entry matching the specified IEEE address and key type.

Parameters

`address`	The IEEE Address of the partner device that shares the key. To find the first empty entry, pass in an address of all zeros.
`linkKey`	A bool indicating whether to search for an entry containing a Link or Master Key.

Returns: The index that matches the search criteria, or 0xFF if no matching entry was found.

◆ emberGenerateRandomKey()

EmberStatus emberGenerateRandomKey ( EmberKeyData * keyAddress )

Generates a Random Key (link, network, or master) and returns the result.

It copies the key into the array that result points to. This is an time-expensive operation as it needs to obtain truly random numbers.

Parameters

keyAddress A pointer to the location in which to copy the generated key.

Returns: EMBER_SUCCESS on success, EMBER_INSUFFICIENT_RANDOM_DATA on failure.

◆ emberGetApsFrameCounter()

uint32_t emberGetApsFrameCounter ( void )

◆ emberGetCurrentSecurityState()

EmberStatus emberGetCurrentSecurityState ( EmberCurrentSecurityState * state )

Gets the security state that is used by a device joined into the Network.

Parameters

state A pointer to an EmberCurrentSecurityState value into which the security configuration will be copied.

Returns: EMBER_SUCCESS if the security settings were successfully retrieved. EMBER_NOT_JOINED if the device is not currently joined in the network.

◆ emberGetExtendedSecurityBitmask()

EmberStatus emberGetExtendedSecurityBitmask ( EmberExtendedSecurityBitmask * mask )

Gets the extended security bitmask that is used by a device.

Parameters

mask A pointer to an EmberExtendedSecurityBitmask value into which the extended security bitmask will be copied.

Returns: EMBER_SUCCESS if the security settings were successfully retrieved. EMBER_INVALID_CALL otherwise.

◆ emberGetIncomingTcLinkKeyFrameCounter()

uint32_t emberGetIncomingTcLinkKeyFrameCounter ( void )

◆ emberGetKey()

EmberStatus emberGetKey	(	EmberKeyType	`type,`
		EmberKeyStruct *	`keyStruct`
	)

Gets the specified key and its associated data. This can retrieve the Trust Center Link Key, Current Network Key, or Next Network Key. On the 35x series chips, the data returned by this call is governed by the security policy set in the manufacturing token for TOKEN_MFG_SECURITY_CONFIG. See the API calls emberSetMfgSecurityConfig() and emberGetMfgSecurityConfig() for more information. If the security policy is not set to EMBER_KEY_PERMISSIONS_READING_ALLOWED , the actual encryption key value will not be returned. Other metadata about the key will be returned.

Parameters

`type`	The Type of key to get (e.g., Trust Center Link or Network).
`keyStruct`	A pointer to the EmberKeyStruct data structure that will be populated with the pertinent information.

Returns: EMBER_SUCCESS if the key was retrieved successfully. EMBER_INVALID_CALL if an attempt was made to retrieve an EMBER_APPLICATION_LINK_KEY .

◆ emberGetKeyTableEntry()

EmberStatus emberGetKeyTableEntry	(	uint8_t	`index,`
		EmberKeyStruct *	`result`
	)

Gets data from the Key Table. On the 35x series chips, the data returned by this call is governed by the security policy set in the manufacturing token for TOKEN_MFG_SECURITY_CONFIG. See the API calls emberSetMfgSecurityConfig() and emberGetMfgSecurityConfig() for more information. If the security policy is not set to EMBER_KEY_PERMISSIONS_READING_ALLOWED , the actual encryption key value will not be returned. Other metadata about the key will be returned.

Parameters

`index`	The index in the key table of the entry to get.
`result`	A pointer to the location of an EmberKeyStruct that will contain the results retrieved by the stack.

Returns: EMBER_TABLE_ENTRY_ERASED if the index is an erased key entry. EMBER_INDEX_OUT_OF_RANGE if the passed index is not valid. EMBER_SUCCESS on success.

◆ emberGetMfgSecurityConfig()

EmberStatus emberGetMfgSecurityConfig ( EmberMfgSecurityStruct * settings )

Retrieves the security configuration stored in manufacturing tokens. It is only available on the 35x series. See emberSetMfgSecurityConfig() for more details.

Parameters

settings A pointer to the EmberMfgSecurityStruct variable that will contain the returned data.

Returns: EMBER_SUCCESS if the tokens were successfully read. EmberStatus error code otherwise.

◆ emberGetRejoinMode()

EmberApsRejoinMode emberGetRejoinMode ( void )

◆ emberGetSecurityFrameCounter()

uint32_t emberGetSecurityFrameCounter ( void )

◆ emberGetTransientKeyTableEntry()

EmberStatus emberGetTransientKeyTableEntry	(	uint8_t	`index,`
		EmberTransientKeyData *	`transientKeyData`
	)

Gets the transient link key at the index specified in the transient key table.

Parameters

`index`	The index in the transient key table to fetch data from.
`transientKeyData`	The transient key structure that is filled in upon success.

Returns: EMBER_SUCCESS if a valid transient key is returned. EMBER_BAD_ARGUMENT if no valid key is found at the specified index. EMBER_INVALID_CALL if transient key support is missing.

◆ emberGetTransientLinkKey()

EmberStatus emberGetTransientLinkKey	(	const EmberEUI64	`eui,`
		EmberTransientKeyData *	`transientKeyData`
	)

Gets the transient link key for a device. This function searches the transient key table for an entry matching the EUI passed in.

Parameters

`eui`	The IEEE address to look up.
`transientKeyData`	The transient key structure that is filled in upon success.

Returns: EMBER_SUCCESS if the transient key for the EUI is found. EMBER_BAD_ARGUMENT if the parameters are invalid. EMBER_INVALID_CALL if the this function is stubbed. EMBER_NOT_FOUND if the transient key for the EUI is not found.

◆ emberHaveLinkKey()

bool emberHaveLinkKey ( EmberEUI64 remoteDevice )

Returns true if a link key is available for securing messages sent to the remote device.

Parameters

remoteDevice The long address of a some other device in the network.

Returns: bool Returns true if a link key is available.

◆ emberHmacAesHash()

void emberHmacAesHash	(	const uint8_t *	`key,`
		const uint8_t *	`data,`
		uint8_t	`dataLength,`
		uint8_t *	`result`
	)

◆ emberRequestLinkKey()

EmberStatus emberRequestLinkKey ( EmberEUI64 partner )

A function to request a Link Key from the Trust Center with another device device on the Network (which could be the Trust Center). A Link Key with the Trust Center is possible but the requesting device cannot be the Trust Center. Link Keys are optional in ZigBee Standard Security. Therefore, the stack can't know whether the other device supports them.

If the partner device is the Trust Center, only that device needs to request the key. The Trust Center will immediately respond to those requests and send the key back to the device.

If the partner device is not the Trust Center, both devices must request an Application Link Key with each other. The requests will be sent to the Trust Center for it to answer. The Trust Center will store the first request and wait EMBER_REQUEST_KEY_TIMEOUT for the second request to be received. The Trust Center only supports one outstanding Application key request at a time and therefore will ignore other requests that are not associated with the first request.

Sleepy devices should poll at a higher rate until a response is received or the request times out.

The success or failure of the request is returned via emberZigbeeKeyEstablishmentHandler (...)

Parameters

partner The IEEE address of the partner device. If NULL is passed in, the Trust Center IEEE Address is assumed.

Returns: EMBER_SUCCESS if the call succeeds, or EMBER_NO_BUFFERS.

◆ emberSetExtendedSecurityBitmask()

EmberStatus emberSetExtendedSecurityBitmask ( EmberExtendedSecurityBitmask mask )

Sets the extended initial security bitmask.

Parameters

mask An object of type EmberExtendedSecurityBitmask that indicates what the extended security bitmask should be set to.

Returns: EMBER_SUCCESS if the security settings were successfully retrieved. EMBER_INVALID_CALL otherwise.

◆ emberSetIncomingTcLinkKeyFrameCounter()

void emberSetIncomingTcLinkKeyFrameCounter ( uint32_t frameCounter )

◆ emberSetInitialSecurityState()

EmberStatus emberSetInitialSecurityState ( EmberInitialSecurityState * state )

Sets the initial security state that will be used by the device when it forms or joins a network. If security is enabled, this function must be called prior to forming or joining the network. It must also be called if the device left the network and wishes to form or join another network.

This call should not be used when restoring prior network operation from saved state via emberNetworkInit as this will cause saved security settings and keys table from the prior network to be erased, resulting in improper keys and/or frame counter values being used, which will prevent proper communication with other devices in the network. Calling emberNetworkInit is sufficient to restore all saved security settings after a reboot and re-enter the network.

The call may be used by either the Trust Center or non Trust Center devices, the options that are set are different depending on which role the device will assume. See the EmberInitialSecurityState structure for more explanation about the various security settings.

The function will return EMBER_SECURITY_CONFIGURATION_INVALID in the following cases:

Distributed Trust Center Mode was enabled with Hashed Link Keys.

Parameters

state The security configuration to be set.

Returns: An EmberStatus value. EMBER_SUCCESS if the security state has been set successfully. EMBER_INVALID_CALL if the device is not in the EMBER_NO_NETWORK state. The value EMBER_SECURITY_CONFIGURATION_INVALID is returned if the combination of security parameters is not valid. EMBER_KEY_INVALID is returned if a reserved or invalid key value was passed in the key structure for one of the keys.

◆ emberSetKeyTableEntry()

EmberStatus emberSetKeyTableEntry	(	uint8_t	`index,`
		EmberEUI64	`address,`
		bool	`linkKey,`
		EmberKeyData *	`keyData`
	)

Sets an entry in the key table.

Parameters

`index`	The index in the key table of the entry to set.
`address`	The address of the partner device associated with the key.
`keyData`	A pointer to the key data associated with the key entry.
`linkKey`	A bool indicating whether this is a Link or Master Key.

Returns: EMBER_KEY_INVALID if the passed key data is using one of the reserved key values. EMBER_INDEX_OUT_OF_RANGE if passed index is not valid. EMBER_SUCCESS on success.

◆ emberSetMfgSecurityConfig()

EmberStatus emberSetMfgSecurityConfig	(	uint32_t	`magicNumber,`
		const EmberMfgSecurityStruct *	`settings`
	)

Sets the security configuration to be stored in manufacturing tokens. It is only available on the 35x series. This API must be called with care. Once set, a manufacturing token CANNOT BE UNSET without using the ISA3 tools and connecting the chip via JTAG. Additionally, a chip with read protection enabled cannot have its configuration changed without a full chip erase. Therefore, this provides a way to disallow access to the keys at runtime that cannot be undone.

To call this API, the magic number must be passed in corresponding to EMBER_MFG_SECURITY_CONFIG_MAGIC_NUMBER . This prevents accidental calls to this function when emberGetMfgSecurityConfig() was actually intended.

This function will disable external access to the actual key data used for decryption/encryption outside the stack. Attempts to call emberGetKey() or emberGetKeyTableEntry() will return the metadata (e.g., sequence number, associated EUI64, frame counters) but the key value may be modified, see below.

The stack always has access to the actual key data.

If the EmberKeySettings within the EmberMfgSecurityStruct are set to EMBER_KEY_PERMISSIONS_NONE , the key value will be set to zero when emberGetKey() or emberGetKeyTableEntry() is called. If the EmberKeySettings within the EmberMfgSecurityStruct are set to EMBER_KEY_PERMISSIONS_HASHING_ALLOWED , the AES-MMO hash of the key will replace the actual key data when calls to emberGetKey() or emberGetKeyTableEntry() are made. If the EmberKeySettings within the EmberMfgSecurityStruct are set to EMBER_KEY_PERMISSIONS_READING_ALLOWED , the actual key data is returned. This is the default value of the token.

Parameters

`magicNumber`	A 32-bit value that must correspond to EMBER_MFG_SECURITY_CONFIG_MAGIC_NUMBER , otherwise EMBER_INVALID_CALL will be returned.
`settings`	The security settings that are intended to be set by the application and written to manufacturing token.

Returns: EMBER_BAD_ARGUMENT if the passed magic number is invalid. EMBER_INVALID_CALL if the chip does not support writing MFG tokens EMBER_SECURITY_CONFIGURATION_INVALID if there was an attempt to write an unerased manufacturing token (i.e., the token has already been set).

◆ emberSetOutgoingApsFrameCounter()

EmberStatus emberSetOutgoingApsFrameCounter ( uint32_t desiredValue )

Sets the APS layer outgoing frame counter for Trust Center Link Key (intended for device restoration purposes). Caveats:

Can only be called before NetworkInit / FormNetwork / JoinNetwork, when emberNetworkState() ==EMBER_NO_NETWORK.
This function should be called before emberSetInitialSecurityState , and the EMBER_NO_FRAME_COUNTER_RESET bitmask should be added to the initial security bitmask when ::emberSetInitialSecuritState is called.
If used in multi-network context, call emberSetCurrentNetwork() prior to calling this function.

Parameters

desiredValue The desired outgoing APS frame counter value. This needs to be less than MAX_INT32U_VALUE to ensure that rollover does not occur on the next encrypted transmission.

Returns: EMBER_SUCCESS if calling context is valid ( emberNetworkState() == EMBER_NO_NETWORK) and desiredValue < MAX_INT32U_VALUE. Otherwise, EMBER_INVALID_CALL .

◆ emberSetOutgoingNwkFrameCounter()

EmberStatus emberSetOutgoingNwkFrameCounter ( uint32_t desiredValue )

Sets the NWK layer outgoing frame counter (intended for device restoration purposes). Caveats:

Can only be called before NetworkInit / FormNetwork / JoinNetwork, when emberNetworkState() ==EMBER_NO_NETWORK.
This function should be called before emberSetInitialSecurityState , and the EMBER_NO_FRAME_COUNTER_RESET bitmask should be added to the initial security bitmask when ::emberSetInitialSecuritState is called.
If used in multi-network context, emberSetCurrentNetwork() must be called prior to calling this function.

Parameters

desiredValue The desired outgoing NWK frame counter value. This needs to be less than MAX_INT32U_VALUE to ensure that rollover does not occur on the next encrypted transmission.

Returns: EMBER_SUCCESS if calling context is valid ( emberNetworkState() == EMBER_NO_NETWORK) and desiredValue < MAX_INT32U_VALUE. Otherwise, EMBER_INVALID_CALL .

◆ emberSetRejoinMode()

void emberSetRejoinMode ( EmberApsRejoinMode mode )

◆ emberStartWritingStackTokens()

EmberStatus emberStartWritingStackTokens ( void )

Immediately writes the value of stack tokens and then resumes normal network operation by writing the stack tokens at appropriate intervals or changes in state. It has no effect unless a previous call was made to emberStopWritingStackTokens() .

Returns: EMBER_SUCCESS if it had previously unwritten tokens from a call to emberStopWritingStackTokens() that it now wrote to the token system. EMBER_INVALID_CALL otherwise.

◆ emberStopWritingStackTokens()

EmberStatus emberStopWritingStackTokens ( void )

Suppresses normal write operations of the stack tokens. This is only done in rare circumstances when the device already has network parameters but needs to conditionally rejoin a network in order to perform a security message exchange (i.e., key establishment). If the network is not authenticated properly, it will need to forget any stack data it used and return to the old network. By suppressing writing of the stack tokens the device will not have stored any persistent data about the network and a reboot will clear the RAM copies. The Smart Energy profile feature Trust Center Swap-out uses this to securely replace the Trust Center and re-authenticate to it.

Returns: EMBER_SUCCESS if it could allocate temporary buffers to store network information. EMBER_NO_BUFFERS otherwise.

◆ emberSwitchNetworkKeyHandler()

void emberSwitchNetworkKeyHandler ( uint8_t sequenceNumber )

Callback to inform the application that the Network Key has been updated and the node has been switched over to use the new key. The actual key being used is not passed up, but the sequence number is.

Parameters

sequenceNumber The sequence number of the new network key.

◆ emberUpdateTcLinkKey()

EmberStatus emberUpdateTcLinkKey ( uint8_t maxAttempts )

Requests a new link link key from the Trust Center. This function starts by sending a Node Descriptor request to the Trust Center to verify its R21+ stack version compliance. A Request Key message will then be sent, followed by a Verify Key Confirm message.

Parameters

maxAttempts The maximum number of attempts a node should make when sending the Node Decriptor, Request Key, and Verify Key Confirm messages. The number of attempts resets for each message type sent (e.g., if maxAttempts is 3, up to 3 Node Descriptors are sent, up to 3 Request Keys, and up to 3 Verify Key Confirm messages are sent).

Returns: EMBER_ERR_FATAL is the Security Core Library is not included. EMBER_INVALID_CALL if already requesting a key from TC, not on network, or if local node is Trust Center. EMBER_SECURITY_CONFIGURATION_INVALID if the Trust Center's EUI is unknown. Otherwise, the return status from sending the initial Node Descriptor is returned.

◆ emberWritingStackTokensEnabled()

bool emberWritingStackTokensEnabled ( void )

Determines whether stack tokens will be written to persistent storage when they change. By default it is set to true meaning the stack will update its internal tokens via HAL calls when the associated RAM values change.

Returns: True if the device will update the persistent storage for tokens when values in RAM change. False otherwise.

◆ emberZigbeeKeyEstablishmentHandler()

void emberZigbeeKeyEstablishmentHandler	(	EmberEUI64	`partner,`
		EmberKeyStatus	`status`
	)

Callback to notify the application about the status of the request for a Link Key. The application should define EMBER_APPLICATION_HAS_ZIGBEE_KEY_ESTABLISHMENT_HANDLER to implement its own handler.

Parameters

`partner`	The IEEE address of the partner device or all zeros if the Key establishment failed.
`status`	The status of the key establishment.

Variable Documentation

◆ emberTransientKeyTimeoutS

uint16_t emberTransientKeyTimeoutS

The length of time, in seconds, that a trust center will store a transient link key that a device can use to join its network. A transient key is added with a call to emberAddTransientLinkKey. After the transient key is added, it will be removed once this amount of time has passed. A joining device will not be able to use that key to join until it is added again on the trust center. The default value is 300 seconds, i.e., 5 minutes.

Security EmberZNet Stack API Reference

Modules

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ EMBER_JOIN_NO_PRECONFIG_KEY_BITMASK

◆ EMBER_JOIN_PRECONFIG_KEY_BITMASK

Function Documentation

◆ emberAddOrUpdateKeyTableEntry()

◆ emberAddTransientLinkKey()

◆ emberApsCryptMessage()

◆ emberClearKeyTable()

◆ emberClearTransientLinkKeys()

◆ emberEraseKeyTableEntry()

◆ emberFindKeyTableEntry()

◆ emberGenerateRandomKey()

◆ emberGetApsFrameCounter()

◆ emberGetCurrentSecurityState()

◆ emberGetExtendedSecurityBitmask()

◆ emberGetIncomingTcLinkKeyFrameCounter()

◆ emberGetKey()

◆ emberGetKeyTableEntry()

◆ emberGetMfgSecurityConfig()

◆ emberGetRejoinMode()

◆ emberGetSecurityFrameCounter()

◆ emberGetTransientKeyTableEntry()

◆ emberGetTransientLinkKey()

◆ emberHaveLinkKey()

◆ emberHmacAesHash()

◆ emberRequestLinkKey()

◆ emberSetExtendedSecurityBitmask()

◆ emberSetIncomingTcLinkKeyFrameCounter()

◆ emberSetInitialSecurityState()

◆ emberSetKeyTableEntry()

◆ emberSetMfgSecurityConfig()

◆ emberSetOutgoingApsFrameCounter()

◆ emberSetOutgoingNwkFrameCounter()

◆ emberSetRejoinMode()

◆ emberStartWritingStackTokens()

◆ emberStopWritingStackTokens()

◆ emberSwitchNetworkKeyHandler()

◆ emberUpdateTcLinkKey()

◆ emberWritingStackTokensEnabled()

◆ emberZigbeeKeyEstablishmentHandler()

Variable Documentation

◆ emberTransientKeyTimeoutS

Security
EmberZNet Stack API Reference