Modules#

Trust Center

Security#

This file describes the functions necessary to manage security for a regular device. These are the three major modes for security and applications, which 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.

This file describes the functions for performing an AES-MMO hash on a block of data. The block of data may be small and contiguous, in which case the emberAesHashSimple() routine can be used. Or large and discontiguous (such as a file stored in EEPROM), in which case the application must pass chunks to emberAesMmoHashUpdate() routine and use emberAesMmoHashFinal() on the last chunk.

This file describes the functions for performing an AES-CCM* encryption on a block of data.

This file describes routines for getting pseudo- and strong-random numbers.

Variables#

uint16_t

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.

Functions#

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.

emberSetExtendedSecurityBitmask(EmberExtendedSecurityBitmask mask)

Set the extended initial security bitmask.

emberGetExtendedSecurityBitmask(EmberExtendedSecurityBitmask *mask)

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

emberGetCurrentSecurityState(EmberCurrentSecurityState *state)

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

emberGetKey(EmberKeyType type, EmberKeyStruct *keyStruct)

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

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

emberGenerateRandomKey(EmberKeyData *keyAddress)

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

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

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.

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.

emberGetKeyTableEntry(uint8_t index, EmberKeyStruct *result)

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

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

Set an entry in the key table.

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

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

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

Clear a single entry in the key table.

Clear the key table of the current network.

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.

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

bool

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.

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.

emberGetMfgSecurityConfig(EmberMfgSecurityStruct *settings)

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

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.

emberSetOutgoingNwkFrameCounter(uint32_t desiredValue)

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

emberSetOutgoingApsFrameCounter(uint32_t desiredValue)

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

emberAddTransientLinkKey(EmberEUI64 partnerEUI64, EmberKeyData *key)

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

emberGetTransientKeyTableEntry(uint8_t index, EmberTransientKeyData *transientKeyData)

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

emberGetTransientLinkKey(const EmberEUI64 eui, EmberTransientKeyData *transientKeyData)

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

void

Clear all transient link keys from RAM.

void
emberHmacAesHash(const uint8_t *key, const uint8_t *data, uint8_t dataLength, uint8_t *result)
void
emberSetRejoinMode(EmberApsRejoinMode mode)
void
void
emberAesMmoHashInit(EmberAesMmoHashContext *context)

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

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.

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.

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.

emberCcmEncryptAndTag(uint8_t *nonce, uint8_t *authData, uint16_t authlen, uint8_t *encryptData, uint16_t encryptlen, uint8_t *micResult)

performs aes-ccm encryption and tagging, producing an encrypted message and a MIC

emberCcmAuthDecrypt(uint8_t *nonce, uint8_t *authData, uint16_t authlen, uint8_t *encryptData, uint16_t encryptlen, uint8_t *mic)

performs an authenticated decryption on an encrypted message, doing the decryption in place

emberCcmEncryptAndTagPacket(uint8_t *nonce, uint8_t *packet, uint16_t authlen, uint16_t encryptlen)

calculates a message integrity code and performs ccm encryption on a flat packet. Assumes the packet is formatted AUTH_DATA | ENCRYPT_DATA. Performs encryption in place

emberCcmAuthDecryptPacket(uint8_t *nonce, uint8_t *packet, uint16_t authlen, uint16_t encryptlen)

performs an authenticated decryption on a flat packet, assuming the format AUTH_DATA | ENCRYPT_DATA' | MIC, where ENCRYPT_DATA' is the message payload before decryption

void
emberCcmCalculateAndEncryptMic(uint8_t *nonce, uint8_t *authData, uint16_t authlen, uint8_t *payload, uint16_t payloadlen, uint8_t *micResult)

calculates the CCM* MIC of a given message without outputting the ciphertext.

void
emberCcmEncryptBytes(uint8_t *bytes, uint16_t length, uint8_t *nonce)

performs a CCM* encryption in place without tag (tag length zero). This operation basically reduces to AES-CTR with an IV constructed from nonce, and is thus symmetric for both encryption and decryption.

emberGetStrongRandomNumberArray(uint16_t *randomNumber, uint8_t count)

Used to 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 the entropy source used for true random number generation.

Macros#

#define
SECURITY_BLOCK_SIZE 16

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

#define
EMBER_JOIN_NO_PRECONFIG_KEY_BITMASK undefined

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 undefined

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.

#define
MESSAGE_LENGTH_FIELD_SIZE 2
#define
NONCE_LENGTH 15 - MESSAGE_LENGTH_FIELD_SIZE
#define
MIC_LENGTH 4
#define
STANDALONE_FLAGS_INDEX 0
#define
STANDALONE_NONCE_INDEX 1
#define
STANDALONE_VARIABLE_FIELD_INDEX_HIGH 14
#define
STANDALONE_VARIABLE_FIELD_INDEX_LOW 15
#define
emberEncryptPayload emberCcmEncryptBytes
#define
emberGetPseudoRandomNumber ()

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

#define
emberGetTrueRandomNumberArray (randomNumber, count)
#define
emberGetStrongRandomNumber (randomNumber)

Used to get one true random number. For more info check emberGetStrongRandomNumberArray.

#define
emberGetTrueRandomNumber (randomNumber)
#define
emberGetTrueRandomEntropySource ()

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.


Definition at line 602 of file stack/include/security.h

Function Documentation#

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.

Parameters
TypeDirectionArgument NameDescription
EmberInitialSecurityState *N/Astate

The security configuration to be set.

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


Definition at line 80 of file stack/include/security.h

emberSetExtendedSecurityBitmask#

EmberStatus emberSetExtendedSecurityBitmask (EmberExtendedSecurityBitmask mask)

Set the extended initial security bitmask.

Parameters
TypeDirectionArgument NameDescription
EmberExtendedSecurityBitmaskN/Amask

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

Returns


Definition at line 90 of file stack/include/security.h

emberGetExtendedSecurityBitmask#

EmberStatus emberGetExtendedSecurityBitmask (EmberExtendedSecurityBitmask * mask)

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

Parameters
TypeDirectionArgument NameDescription
EmberExtendedSecurityBitmask *N/Amask

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

Returns


Definition at line 100 of file stack/include/security.h

emberGetCurrentSecurityState#

EmberStatus emberGetCurrentSecurityState (EmberCurrentSecurityState * state)

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

Parameters
TypeDirectionArgument NameDescription
EmberCurrentSecurityState *N/Astate

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

Returns


Definition at line 132 of file stack/include/security.h

emberGetKey#

EmberStatus emberGetKey (EmberKeyType type, EmberKeyStruct * keyStruct)

Get 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
TypeDirectionArgument NameDescription
EmberKeyTypeN/Atype

The Type of key to get (e.g., Trust Center Link or Network).

EmberKeyStruct *N/AkeyStruct

A pointer to the EmberKeyStruct data structure that will be populated with the pertinent information.

Returns


Definition at line 151 of file stack/include/security.h

emberHaveLinkKey#

bool emberHaveLinkKey (EmberEUI64 remoteDevice)

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

Parameters
TypeDirectionArgument NameDescription
EmberEUI64N/AremoteDevice

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

Returns

  • bool Returns true if a link key is available.


Definition at line 160 of file stack/include/security.h

emberGenerateRandomKey#

EmberStatus emberGenerateRandomKey (EmberKeyData * keyAddress)

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

Parameters
TypeDirectionArgument NameDescription
EmberKeyData *N/AkeyAddress

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

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


Definition at line 180 of file stack/include/security.h

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.

Parameters
TypeDirectionArgument NameDescription
uint8_tN/AsequenceNumber

The sequence number of the new network key.


Definition at line 189 of file stack/include/security.h

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.

Parameters
TypeDirectionArgument NameDescription
EmberEUI64N/Apartner

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

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.


Definition at line 220 of file stack/include/security.h

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.

Parameters
TypeDirectionArgument NameDescription
uint8_tN/AmaxAttempts

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.


Definition at line 240 of file stack/include/security.h

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.

Parameters
TypeDirectionArgument NameDescription
EmberEUI64N/Apartner

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

EmberKeyStatusN/Astatus

The status of the key establishment.


Definition at line 251 of file stack/include/security.h

emberGetKeyTableEntry#

EmberStatus emberGetKeyTableEntry (uint8_t index, EmberKeyStruct * result)

Get 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
TypeDirectionArgument NameDescription
uint8_tN/Aindex

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

EmberKeyStruct *N/Aresult

A pointer to the location of an EmberKeyStruct that will contain the results retrieved by the stack.

Returns


Definition at line 268 of file stack/include/security.h

emberSetKeyTableEntry#

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

Set an entry in the key table.

Parameters
TypeDirectionArgument NameDescription
uint8_tN/Aindex

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

EmberEUI64N/Aaddress

The address of the partner device associated with the key.

boolN/AlinkKey

A pointer to the key data associated with the key entry.

EmberKeyData *N/AkeyData

A bool indicating whether this is a Link or Master Key.

Returns


Definition at line 283 of file stack/include/security.h

emberAddOrUpdateKeyTableEntry#

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

Add 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
TypeDirectionArgument NameDescription
EmberEUI64N/Aaddress

The IEEE Address of the partner device that shares the key.

boolN/AlinkKey

A bool indicating whether this is a Link or Master key.

EmberKeyData *N/AkeyData

A pointer to the actual key data.

Returns


Definition at line 318 of file stack/include/security.h

emberFindKeyTableEntry#

uint8_t emberFindKeyTableEntry (EmberEUI64 address, bool linkKey)

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

Parameters
TypeDirectionArgument NameDescription
EmberEUI64N/Aaddress

The IEEE Address of the partner device that shares the key. To find the first empty entry, pass in an address of all zeros.

boolN/AlinkKey

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.


Definition at line 333 of file stack/include/security.h

emberEraseKeyTableEntry#

EmberStatus emberEraseKeyTableEntry (uint8_t index)

Clear a single entry in the key table.

Parameters
TypeDirectionArgument NameDescription
uint8_tN/Aindex

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

Returns


Definition at line 345 of file stack/include/security.h

emberClearKeyTable#

EmberStatus emberClearKeyTable (void )

Clear the key table of the current network.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Returns


Definition at line 357 of file stack/include/security.h

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.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Returns


Definition at line 373 of file stack/include/security.h

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

Parameters
TypeDirectionArgument NameDescription
voidN/A

Returns


Definition at line 385 of file stack/include/security.h

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.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Returns

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


Definition at line 395 of file stack/include/security.h

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.

Parameters
TypeDirectionArgument NameDescription
boolN/Aencrypt

A bool indicating whether perform encryption (true) or decryption (false).

EmberMessageBuffer *N/Abuffer

An ::EmberMessageBuffer containing the APS frame to decrypt or encrypt.

uint8_tN/AapsHeaderEndIndex

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.

EmberEUI64N/AremoteEui64

the ::EmberEUI64 of the remote device the message was received from (decryption) or being sent to (encryption).

Returns


Definition at line 424 of file stack/include/security.h

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.

Parameters
TypeDirectionArgument NameDescription
EmberMfgSecurityStruct *N/Asettings

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

Returns


Definition at line 439 of file stack/include/security.h

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.

Parameters
TypeDirectionArgument NameDescription
uint32_tN/AmagicNumber

A 32-bit value that must correspond to EMBER_MFG_SECURITY_CONFIG_MAGIC_NUMBER, otherwise EMBER_INVALID_CALL will be returned.

const EmberMfgSecurityStruct *N/Asettings

The security settings that are intended to be set by the application and written to manufacturing token.

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.

Returns


Definition at line 485 of file stack/include/security.h

emberSetOutgoingNwkFrameCounter#

EmberStatus emberSetOutgoingNwkFrameCounter (uint32_t desiredValue)

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

Parameters
TypeDirectionArgument NameDescription
uint32_tN/AdesiredValue

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.

  • 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


Definition at line 507 of file stack/include/security.h

emberSetOutgoingApsFrameCounter#

EmberStatus emberSetOutgoingApsFrameCounter (uint32_t desiredValue)

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

Parameters
TypeDirectionArgument NameDescription
uint32_tN/AdesiredValue

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.

  • 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


Definition at line 532 of file stack/include/security.h

emberAddTransientLinkKey#

EmberStatus emberAddTransientLinkKey (EmberEUI64 partnerEUI64, EmberKeyData * key)

Add 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
TypeDirectionArgument NameDescription
EmberEUI64N/ApartnerEUI64

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.

EmberKeyData *N/Akey

The temporary link key to the joining device.

Returns


Definition at line 557 of file stack/include/security.h

emberGetTransientKeyTableEntry#

EmberStatus emberGetTransientKeyTableEntry (uint8_t index, EmberTransientKeyData * transientKeyData)

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

Parameters
TypeDirectionArgument NameDescription
uint8_tN/Aindex

The index in the transient key table to fetch data from.

EmberTransientKeyData *N/AtransientKeyData

The transient key structure that is filled in upon success.

Returns


Definition at line 572 of file stack/include/security.h

emberGetTransientLinkKey#

EmberStatus emberGetTransientLinkKey (const EmberEUI64 eui, EmberTransientKeyData * transientKeyData)

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

Parameters
TypeDirectionArgument NameDescription
const EmberEUI64N/Aeui

The IEEE address to look up.

EmberTransientKeyData *N/AtransientKeyData

The transient key structure that is filled in upon success.

Returns


Definition at line 588 of file stack/include/security.h

emberClearTransientLinkKeys#

void emberClearTransientLinkKeys (void )

Clear all transient link keys from RAM.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Definition at line 592 of file stack/include/security.h

emberHmacAesHash#

void emberHmacAesHash (const uint8_t * key, const uint8_t * data, uint8_t dataLength, uint8_t * result)
Parameters
TypeDirectionArgument NameDescription
const uint8_t *N/Akey
const uint8_t *N/Adata
uint8_tN/AdataLength
uint8_t *N/Aresult

Definition at line 610 of file stack/include/security.h

emberGetRejoinMode#

EmberApsRejoinMode emberGetRejoinMode (void )
Parameters
TypeDirectionArgument NameDescription
voidN/A

Definition at line 622 of file stack/include/security.h

emberSetRejoinMode#

void emberSetRejoinMode (EmberApsRejoinMode mode)
Parameters
TypeDirectionArgument NameDescription
EmberApsRejoinModeN/Amode

Definition at line 633 of file stack/include/security.h

emberGetSecurityFrameCounter#

uint32_t emberGetSecurityFrameCounter (void )
Parameters
TypeDirectionArgument NameDescription
voidN/A

Definition at line 636 of file stack/include/security.h

emberGetApsFrameCounter#

uint32_t emberGetApsFrameCounter (void )
Parameters
TypeDirectionArgument NameDescription
voidN/A

Definition at line 637 of file stack/include/security.h

emberGetIncomingTcLinkKeyFrameCounter#

uint32_t emberGetIncomingTcLinkKeyFrameCounter (void )
Parameters
TypeDirectionArgument NameDescription
voidN/A

Definition at line 638 of file stack/include/security.h

emberSetIncomingTcLinkKeyFrameCounter#

void emberSetIncomingTcLinkKeyFrameCounter (uint32_t frameCounter)
Parameters
TypeDirectionArgument NameDescription
uint32_tN/AframeCounter

Definition at line 639 of file stack/include/security.h

emberAesMmoHashInit#

void emberAesMmoHashInit (EmberAesMmoHashContext * context)

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

Parameters
TypeDirectionArgument NameDescription
EmberAesMmoHashContext *N/Acontext

A pointer to the location of hash context to clear.


Definition at line 41 of file stack/include/aes-mmo.h

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.

Parameters
TypeDirectionArgument NameDescription
EmberAesMmoHashContext *N/Acontext

A pointer to the location of the hash context to update.

uint32_tN/Alength

The length of the passed data.

const uint8_t *N/Adata

A pointer to the location of the data to hash.

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.


Definition at line 57 of file stack/include/aes-mmo.h

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.

Parameters
TypeDirectionArgument NameDescription
EmberAesMmoHashContext *N/Acontext

A pointer to the location of the hash context to finalize.

uint32_tN/Alength

The length of the finalData parameter.

const uint8_t *N/AfinalData

A pointer to the location of data to hash. May be NULL.

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.


Definition at line 78 of file stack/include/aes-mmo.h

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.

Parameters
TypeDirectionArgument NameDescription
uint8_tN/AtotalLength

The length of the data.

const uint8_t *N/Adata

The data to hash.

uint8_t *N/Aresult

The location where the result of the hash will be written.

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.


Definition at line 95 of file stack/include/aes-mmo.h

emberCcmEncryptAndTag#

EmberStatus emberCcmEncryptAndTag (uint8_t * nonce, uint8_t * authData, uint16_t authlen, uint8_t * encryptData, uint16_t encryptlen, uint8_t * micResult)

performs aes-ccm encryption and tagging, producing an encrypted message and a MIC

Parameters
TypeDirectionArgument NameDescription
uint8_t *N/Anonce

the initial vector to the ccm encryption

uint8_t *N/AauthData

additional authentication data used in the calculation of the MIC, but does not get encrypted in the result

uint16_tN/Aauthlen

length in bytes of the authentication data

uint8_t *N/AencryptData

the data to be encrypted

uint16_tN/Aencryptlen

length in bytes of the data to be encrypted

uint8_t *N/AmicResult

an array that will containing the resulting MIC

Returns

  • EMBER_SUCCESS or other EmberStatus indicating a failure


Definition at line 56 of file stack/include/ccm-star.h

emberCcmAuthDecrypt#

EmberStatus emberCcmAuthDecrypt (uint8_t * nonce, uint8_t * authData, uint16_t authlen, uint8_t * encryptData, uint16_t encryptlen, uint8_t * mic)

performs an authenticated decryption on an encrypted message, doing the decryption in place

Parameters
TypeDirectionArgument NameDescription
uint8_t *N/Anonce

the initial vector for the ccm decryption

uint8_t *N/AauthData

additional authentication data

uint16_tN/Aauthlen

length in bytes of the authenticated data

uint8_t *N/AencryptData

the encrypted data

uint16_tN/Aencryptlen

length in bytes of the encrypted data

uint8_t *N/Amic

the message integrity code to be checked against for authentication

Returns

  • EMBER_SUCCESS on successful authentication and decryption, EMBER_AUTH_FAILURE if the calculated MIC does not match what was passed


Definition at line 75 of file stack/include/ccm-star.h

emberCcmEncryptAndTagPacket#

EmberStatus emberCcmEncryptAndTagPacket (uint8_t * nonce, uint8_t * packet, uint16_t authlen, uint16_t encryptlen, micResult)

calculates a message integrity code and performs ccm encryption on a flat packet. Assumes the packet is formatted AUTH_DATA | ENCRYPT_DATA. Performs encryption in place

Parameters
TypeDirectionArgument NameDescription
uint8_t *N/Anonce

initial vector to the ccm encryption

uint8_t *N/Apacket

flat packet containing the authData followed by the data to be encrypted

uint16_tN/Aauthlen

length in bytes of the authenticated data

uint16_tN/Aencryptlen

length in bytes of the encrypted data

N/AmicResult

the resulting MIC

Returns

  • EMBER_SUCCESS or other EmberStatus indicating a failure

Note

  • packet must be large enough to append the resulting MIC to the end of the buffer (len(packet) >= authlen + encryptlen + miclen)


Definition at line 95 of file stack/include/ccm-star.h

emberCcmAuthDecryptPacket#

EmberStatus emberCcmAuthDecryptPacket (uint8_t * nonce, uint8_t * packet, uint16_t authlen, uint16_t encryptlen, encryptlen)

performs an authenticated decryption on a flat packet, assuming the format AUTH_DATA | ENCRYPT_DATA' | MIC, where ENCRYPT_DATA' is the message payload before decryption

Parameters
TypeDirectionArgument NameDescription
uint8_t *N/Anonce

the initial vector to the ccm decryption

uint8_t *N/Apacket

flat packet containing the authentication data, followed by the data to be decrypted, followed by the MIC

uint16_tN/Aauthlen

length in bytes of the authentication data

uint16_tN/Aencryptlen

pointer to the beginning of the encrypted data, will store the resulting decrypted message

N/Aencryptlen

length in bytes of the encrypted data

Returns

  • EMBER_SUCCESS on successful authentication and decryption, EMBER_AUTH_FAILURE if the calculated MIC does not match what was passed


Definition at line 114 of file stack/include/ccm-star.h

emberCcmCalculateAndEncryptMic#

void emberCcmCalculateAndEncryptMic (uint8_t * nonce, uint8_t * authData, uint16_t authlen, uint8_t * payload, uint16_t payloadlen, uint8_t * micResult)

calculates the CCM* MIC of a given message without outputting the ciphertext.

Parameters
TypeDirectionArgument NameDescription
uint8_t *N/Anonce

initial vector as input to the CCM* algorithm

uint8_t *N/AauthData

additional authentication data

uint16_tN/Aauthlen

length in bytes of authentication data

uint8_t *N/Apayload

the message payload

uint16_tN/Apayloadlen

length of the payload in bytes

uint8_t *N/AmicResult

the resulting MIC

Returns

  • EMBER_SUCCESS or other EmberStatus indicating a failure


Definition at line 129 of file stack/include/ccm-star.h

emberCcmEncryptBytes#

void emberCcmEncryptBytes (uint8_t * bytes, uint16_t length, uint8_t * nonce)

performs a CCM* encryption in place without tag (tag length zero). This operation basically reduces to AES-CTR with an IV constructed from nonce, and is thus symmetric for both encryption and decryption.

Parameters
TypeDirectionArgument NameDescription
uint8_t *N/Abytes

bytes to be encrypted/decrypted

uint16_tN/Alength

length of the input/output

uint8_t *N/Anonce

nonce (of length NONCE_LENGTH) to use for the operation

Note

  • this function previously had an input parameter 'blockCount', which got removed since the function didn't adhere to its intent when setting blockCount to any other value then 1.

Returns

  • EMBER_SUCCESS or other EmberStatus indicating a failure


Definition at line 147 of file stack/include/ccm-star.h

emberGetStrongRandomNumberArray#

EmberStatus emberGetStrongRandomNumberArray (uint16_t * randomNumber, uint8_t count)

Used to 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.

Parameters
TypeDirectionArgument NameDescription
uint16_t *N/ArandomNumber
uint8_tN/Acount

Returns


Definition at line 48 of file stack/include/ember-random-api.h

emberGetStrongRandomEntropySource#

EmberEntropySource emberGetStrongRandomEntropySource (void )

Returns the entropy source used for true random number generation.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Returns


Definition at line 75 of file stack/include/ember-random-api.h