Thread Direct

This module includes functions and definitions for Thread Direct (TD).

Summary

The APIs in this module require Thread Direct functionality to be enabled (e.g., via OPENTHREAD_CONFIG_TD_WAKE_INITIATOR_ENABLE or OPENTHREAD_CONFIG_TD_WAKE_LISTENER_ENABLE).

Typedefs
otThreadDirectKey typedef
An opaque type representing a registered Thread Direct key entry in OpenThread.
otThreadDirectKeyId typedef
otThreadDirectKeyIterator typedef
Represents an iterator for iterating through registered Thread Direct keys.
otThreadDirectKeyMaterial typedef
Represents Thread Direct key material (literal key bytes or cryptographic key reference).

Variables
OT_TOOL_PACKED_END

Functions
otThreadDirectFindKey(otInstance *aInstance, const otThreadDirectKeyMaterial *aKeyMaterial, const otThreadDirectKeyId *aKeyId)
Finds a registered Thread Direct key matching the given key material and Key ID.
otThreadDirectGetNextKey(otThreadDirectKeyIterator *aIterator)
Iterates through the registered Thread Direct keys and returns the next key entry.
otThreadDirectInitKeyIterator(otInstance *aInstance, otThreadDirectKeyIterator *aIterator)
void
Initializes an otThreadDirectKeyIterator.
otThreadDirectKeyGetFrameCounter(const otThreadDirectKey *aKey)
uint32_t
Gets the current MAC security frame counter associated with a registered Thread Direct key.
otThreadDirectKeyGetId(const otThreadDirectKey *aKey)
Gets the Key ID associated with a registered Thread Direct key.
otThreadDirectKeyGetMaterial(const otThreadDirectKey *aKey)
Gets the key material associated with a registered Thread Direct key.
otThreadDirectRegisterKey(otInstance *aInstance, const otThreadDirectKeyMaterial *aKeyMaterial, const otThreadDirectKeyId *aKeyId)
Registers a Thread Direct key and its associated Key ID with OpenThread.
otThreadDirectUnregisterAllKeys(otInstance *aInstance)
void
Unregisters all previously registered Thread Direct keys from OpenThread.
otThreadDirectUnregisterKey(otInstance *aInstance, const otThreadDirectKey *aKey)
void
Unregisters a previously registered Thread Direct key from OpenThread.

Macros
OT_THREAD_DIRECT_KEY_ID_SIZE 5
Size of a Thread Direct Key ID in bytes.
OT_THREAD_DIRECT_KEY_SIZE OT_MAC_KEY_SIZE
Size of a Thread Direct Key in bytes (16 bytes).

Structs
otThreadDirectKeyId

Represents a Thread Direct Key ID.

otThreadDirectKeyIterator

Represents an iterator for iterating through registered Thread Direct keys.

Typedefs

otThreadDirectKey

struct otThreadDirectKey otThreadDirectKey

An opaque type representing a registered Thread Direct key entry in OpenThread.

otThreadDirectKeyId

struct otThreadDirectKeyId otThreadDirectKeyId

otThreadDirectKeyIterator

struct otThreadDirectKeyIterator otThreadDirectKeyIterator

Represents an iterator for iterating through registered Thread Direct keys.

Use otThreadDirectInitKeyIterator() to initialize the iterator before using it with otThreadDirectGetNextKey().

The caller MUST NOT access or update the fields in this struct. It is intended for OpenThread internal use only.

otThreadDirectKeyMaterial

otMacKeyMaterial otThreadDirectKeyMaterial

Represents Thread Direct key material (literal key bytes or cryptographic key reference).

Depending on the build-time configuration OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE, either mKeyMaterial.mKey or mKeyMaterial.mKeyRef is used:

  • When OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE is disabled, mKeyMaterial.mKey.m8 is used to specify or retrieve the literal 16-byte key material.
  • When OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE is enabled, mKeyMaterial.mKeyRef is used to pass or retrieve the otMacKeyRef (otCryptoKeyRef) associated with the key in platform crypto storage.

When key references (mKeyMaterial.mKeyRef) are used, the next higher layer is responsible for importing/creating the key in platform crypto storage prior to registering it with OpenThread. The key reference MUST be stored persistently in platform crypto storage so that the registered mKeyRef remains valid across device reboots/resets. The caller MAY reuse the same mKeyRef associated with an already registered Thread Direct key when registering additional keys with different Key IDs (otThreadDirectKeyId). Upon successful registration via otThreadDirectRegisterKey(), OpenThread manages the lifetime of the mKeyRef and will destroy/remove the key from platform crypto storage (via otPlatCryptoDestroyKey()) once all registered Thread Direct keys using that mKeyRef have been unregistered.

Variables

OT_TOOL_PACKED_END

OT_TOOL_PACKED_BEGIN struct otThreadDirectKeyId OT_TOOL_PACKED_END

Functions

otThreadDirectFindKey

const otThreadDirectKey * otThreadDirectFindKey(
  otInstance *aInstance,
  const otThreadDirectKeyMaterial *aKeyMaterial,
  const otThreadDirectKeyId *aKeyId
)

Finds a registered Thread Direct key matching the given key material and Key ID.

Details
Parameters
[in] aInstance
The OpenThread instance.
[in] aKeyMaterial
The key material to match.
[in] aKeyId
The Key ID to match.
Returns
A pointer to the matching registered otThreadDirectKey, or NULL if no match was found.

otThreadDirectGetNextKey

const otThreadDirectKey * otThreadDirectGetNextKey(
  otThreadDirectKeyIterator *aIterator
)

Iterates through the registered Thread Direct keys and returns the next key entry.

Details
Parameters
[in,out] aIterator
The iterator. MUST be initialized via otThreadDirectInitKeyIterator().
Returns
A pointer to the next registered otThreadDirectKey, or NULL if the end of the list is reached.

otThreadDirectInitKeyIterator

void otThreadDirectInitKeyIterator(
  otInstance *aInstance,
  otThreadDirectKeyIterator *aIterator
)

Initializes an otThreadDirectKeyIterator.

An iterator MUST be initialized before it is used with otThreadDirectGetNextKey(). An iterator can be initialized again to restart iteration from the beginning of the registered keys list.

Details
Parameters
[in] aInstance
The OpenThread instance.
[out] aIterator
The iterator to initialize.

otThreadDirectKeyGetFrameCounter

uint32_t otThreadDirectKeyGetFrameCounter(
  const otThreadDirectKey *aKey
)

Gets the current MAC security frame counter associated with a registered Thread Direct key.

Details
Parameters
[in] aKey
A registered otThreadDirectKey.
Returns
The MAC security frame counter associated with aKey.

otThreadDirectKeyGetId

const otThreadDirectKeyId * otThreadDirectKeyGetId(
  const otThreadDirectKey *aKey
)

Gets the Key ID associated with a registered Thread Direct key.

Details
Parameters
[in] aKey
A registered otThreadDirectKey.
Returns
The otThreadDirectKeyId associated with aKey.

otThreadDirectKeyGetMaterial

const otThreadDirectKeyMaterial * otThreadDirectKeyGetMaterial(
  const otThreadDirectKey *aKey
)

Gets the key material associated with a registered Thread Direct key.

Details
Parameters
[in] aKey
A registered otThreadDirectKey.
Returns
The otThreadDirectKeyMaterial associated with aKey.

otThreadDirectRegisterKey

const otThreadDirectKey * otThreadDirectRegisterKey(
  otInstance *aInstance,
  const otThreadDirectKeyMaterial *aKeyMaterial,
  const otThreadDirectKeyId *aKeyId
)

Registers a Thread Direct key and its associated Key ID with OpenThread.

If a matching key with the same aKeyMaterial and aKeyId is already registered, this function returns a pointer to the existing otThreadDirectKey entry. Otherwise, it allocates and registers a new entry. If a new entry cannot be allocated (e.g., the maximum number of allowed/supported registered keys is reached), NULL is returned.

As described in otThreadDirectKeyMaterial, either aKeyMaterial->mKeyMaterial.mKey or aKeyMaterial->mKeyMaterial.mKeyRef is used depending on whether OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE is enabled. When using mKeyMaterial.mKeyRef, the caller MUST ensure that the key reference is stored persistently in platform crypto storage across reboots, and MAY reuse the same mKeyRef across multiple registered keys with different Key IDs. Upon successful registration, OpenThread manages aKeyMaterial->mKeyMaterial.mKeyRef and will destroy/remove the key from platform crypto storage once all Thread Direct keys using that mKeyRef are unregistered.

Details
Parameters
[in] aInstance
The OpenThread instance.
[in] aKeyMaterial
The Thread Direct key material to register.
[in] aKeyId
The Thread Direct Key ID to register.
Returns
A pointer to the registered otThreadDirectKey entry, or NULL if it could not be registered.

otThreadDirectUnregisterAllKeys

void otThreadDirectUnregisterAllKeys(
  otInstance *aInstance
)

Unregisters all previously registered Thread Direct keys from OpenThread.

When OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE is enabled, this call also destroys/removes the associated key references (mKeyRef) for all registered keys from platform crypto storage (via otPlatCryptoDestroyKey()).

Details
Parameters
[in] aInstance
The OpenThread instance.

otThreadDirectUnregisterKey

void otThreadDirectUnregisterKey(
  otInstance *aInstance,
  const otThreadDirectKey *aKey
)

Unregisters a previously registered Thread Direct key from OpenThread.

Once unregistered, the aKey pointer is no longer valid and MUST NOT be used.

When OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE is enabled, this call also destroys/removes the associated key reference (mKeyRef) from platform crypto storage (via otPlatCryptoDestroyKey()) if no other registered Thread Direct key is still using the same mKeyRef.

Details
Parameters
[in] aInstance
The OpenThread instance.
[in] aKey
The registered otThreadDirectKey to unregister.

Macros

OT_THREAD_DIRECT_KEY_ID_SIZE

 OT_THREAD_DIRECT_KEY_ID_SIZE 5

Size of a Thread Direct Key ID in bytes.

OT_THREAD_DIRECT_KEY_SIZE

 OT_THREAD_DIRECT_KEY_SIZE OT_MAC_KEY_SIZE

Size of a Thread Direct Key in bytes (16 bytes).

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.