Security#

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 sl_zb_sec_man_import_transient_key. 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.

emberSetInitialSecurityState#

EmberStatus emberSetInitialSecurityState (EmberInitialSecurityState * state)

Set 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 because 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.

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.

emberSetExtendedSecurityBitmask#

EmberStatus emberSetExtendedSecurityBitmask (EmberExtendedSecurityBitmask mask)

Set the extended initial security bitmask.

Returns

• EMBER_SUCCESS if the security settings were successfully retrieved. EMBER_INVALID_CALL otherwise.

emberGetExtendedSecurityBitmask#

EmberStatus emberGetExtendedSecurityBitmask (EmberExtendedSecurityBitmask * mask)

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

Returns

• EMBER_SUCCESS if the security settings were successfully retrieved. EMBER_INVALID_CALL otherwise.

emberGetCurrentSecurityState#

EmberStatus emberGetCurrentSecurityState (EmberCurrentSecurityState * state)

Get the security state that is used by a device joined into the Network. We can still get current security state by calling this function and the return value can be EMBER_NOT_JOINED or EMBER_SUCCESS.

Returns

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

emberGenerateRandomKey#

EmberStatus emberGenerateRandomKey (EmberKeyData * keyAddress)

Generate 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.

Returns

• EMBER_SUCCESS on success, EMBER_INSUFFICIENT_RANDOM_DATA on failure.

emberSwitchNetworkKeyHandler#

void emberSwitchNetworkKeyHandler (uint8_t sequenceNumber)

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.

emberRequestLinkKey#

EmberStatus emberRequestLinkKey (EmberEUI64 partner)

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 can't 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(...)

Returns

• EMBER_SUCCESS if the call succeeds, or EMBER_NO_BUFFERS.

emberUpdateTcLinkKey#

EmberStatus emberUpdateTcLinkKey (uint8_t maxAttempts)

Request 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.

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.

emberZigbeeKeyEstablishmentHandler#

void emberZigbeeKeyEstablishmentHandler (EmberEUI64 partner, EmberKeyStatus status)

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.

emberFindKeyTableEntry#

uint8_t emberFindKeyTableEntry (EmberEUI64 address, bool linkKey)

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

Returns

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

emberEraseKeyTableEntry#

EmberStatus emberEraseKeyTableEntry (uint8_t index)

Clear a single entry in the key table.

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.

emberClearKeyTable#

EmberStatus emberClearKeyTable (void )

Clear the key table of the current network.

Returns

• EMBER_SUCCESS if the key table was successfully cleared. EMBER_INVALID_CALL otherwise.

emberStopWritingStackTokens#

EmberStatus emberStopWritingStackTokens (void )

Suppress 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 needs 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.

emberStartWritingStackTokens#

EmberStatus emberStartWritingStackTokens (void )

Immediately write the value of stack tokens and then resume 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.

emberWritingStackTokensEnabled#

bool emberWritingStackTokensEnabled (void )

Determine 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.

emberApsCryptMessage#

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

Perform 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.

Returns

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

emberGetMfgSecurityConfig#

EmberStatus emberGetMfgSecurityConfig (EmberMfgSecurityStruct * settings)

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

Returns

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

emberSetMfgSecurityConfig#

EmberStatus emberSetMfgSecurityConfig (uint32_t magicNumber, const EmberMfgSecurityStruct * settings)

Set 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 export the key will return the metadata if applicable (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 sl_zb_sec_man_export_key() or similar functions are 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 functions like sl_zb_sec_man_export_key() 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.

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).

emberSetOutgoingNwkFrameCounter#

EmberStatus emberSetOutgoingNwkFrameCounter (uint32_t desiredValue)

Set 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.

Returns

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

emberSetOutgoingApsFrameCounter#

EmberStatus emberSetOutgoingApsFrameCounter (uint32_t desiredValue)

Set 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.

Returns

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

emberClearTransientLinkKeys#

void emberClearTransientLinkKeys (void )

Clear all transient link keys from RAM.

emberHmacAesHash#

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

emberGetRejoinMode#

EmberApsRejoinMode emberGetRejoinMode (void )

emberSetRejoinMode#

void emberSetRejoinMode (EmberApsRejoinMode mode)

emberGetSecurityFrameCounter#

uint32_t emberGetSecurityFrameCounter (void )

emberGetApsFrameCounter#

uint32_t emberGetApsFrameCounter (void )

emberGetIncomingTcLinkKeyFrameCounter#

uint32_t emberGetIncomingTcLinkKeyFrameCounter (void )

emberSetIncomingTcLinkKeyFrameCounter#

void emberSetIncomingTcLinkKeyFrameCounter (uint32_t frameCounter)

emberAesMmoHashInit#

void emberAesMmoHashInit (EmberAesMmoHashContext * context)

This routine clears the passed context so that a new hash calculation can be performed.

emberAesMmoHashUpdate#

EmberStatus emberAesMmoHashUpdate (EmberAesMmoHashContext * context, uint32_t length, const uint8_t * data)

This routine processes the passed chunk of data and updates the hash calculation based on it. The data passed in MUST have a length that is a multiple of 16.

Returns

• An EmberStatus value indicating EMBER_SUCCESS if the hash was calculated successfully. EMBER_INVALID_CALL if the block size is not a multiple of 16 bytes, and EMBER_INDEX_OUT_OF_RANGE is returned when the data exceeds the maximum limits of the hash function.

emberAesMmoHashFinal#

EmberStatus emberAesMmoHashFinal (EmberAesMmoHashContext * context, uint32_t length, const uint8_t * finalData)

This routine processes the passed chunk of data (if non-NULL) and update the hash context that is passed in. In then performs the final calculations on the hash and returns the final answer in the result parameter of the EmberAesMmoHashContext structure. The length of the data passed in may be any value, it does not have to be a multiple of 16.

Returns

• An EmberStatus value indicating EMBER_SUCCESS if the hash was calculated successfully. EMBER_INVALID_CALL if the block size is not a multiple of 16 bytes, and EMBER_INDEX_OUT_OF_RANGE is returned when the data exceeds the maximum limits of the hash function.

emberAesHashSimple#

EmberStatus emberAesHashSimple (uint8_t totalLength, const uint8_t * data, uint8_t * result)

This is a convenience method when the hash data is less than 255 bytes. It inits, updates, and finalizes the hash in one function call.

Returns

• An EmberStatus value indicating EMBER_SUCCESS if the hash was calculated successfully. EMBER_INVALID_CALL if the block size is not a multiple of 16 bytes, and EMBER_INDEX_OUT_OF_RANGE is returned when the data exceeds the maximum limits of the hash function.

emberGetStrongRandomNumberArray#

EmberStatus emberGetStrongRandomNumberArray (uint16_t * randomNumber, uint8_t count)

Get ::count number of true random numbers. The method of obtaining and quality of the random varies by chip family and the configuration used. For high security applications, please verify that that the generator's properties match your needs.

Returns

• An EmberStatus value.

  • EMBER_SUCCESS If success.

  • EMBER_INSUFFICIENT_RANDOM_DATA In case of any error.

emberGetStrongRandomEntropySource#

EmberEntropySource emberGetStrongRandomEntropySource (void )

Return the entropy source used for true random number generation.

Returns

• An EmberEntropySource value.

  • EMBER_ENTROPY_SOURCE_ERROR If there is any error identifying the entroypy source.

  • EMBER_ENTROPY_SOURCE_RADIO Entropy source is the chips that support this. The method of obtaining and quality of the random varies by chip family. For high security applications, please verify that that the generator's properties match the requirements.

  • EMBER_ENTROPY_SOURCE_MBEDTLS_TRNG Entropy source is the TRNG hardware module (if applicable) and the interface driver is powered by mbed TLS.

  • EMBER_ENTROPY_SOURCE_MBEDTLS Entropy source is not the TRNG hardware module but the interface driver is powered by mbed TLS.

SECURITY_BLOCK_SIZE#

#define SECURITY_BLOCK_SIZE

16

The block size in bytes of the encryption cypher (AES-MMO-128).

EMBER_JOIN_NO_PRECONFIG_KEY_BITMASK#

#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.

EMBER_JOIN_PRECONFIG_KEY_BITMASK#

#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.

emberGetPseudoRandomNumber#

#define emberGetPseudoRandomNumber

()

Wrapper for the HAL API to generate pseudo-random numbers.

Returns

• uint16_t pseudo random number

emberGetTrueRandomNumberArray#

#define emberGetTrueRandomNumberArray

(randomNumber, count)

emberGetStrongRandomNumber#

#define emberGetStrongRandomNumber

(randomNumber)

Generate one true random number. For more info check emberGetStrongRandomNumberArray.

emberGetTrueRandomNumber#

#define emberGetTrueRandomNumber

(randomNumber)

emberGetTrueRandomEntropySource#

#define emberGetTrueRandomEntropySource

()