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

Enumerations

otThreadDirectWakeType{
  OT_THREAD_DIRECT_WAKE_TYPE_TD_LINK = 0x00,
  OT_THREAD_DIRECT_WAKE_TYPE_REATTACH = 0x01,
  OT_THREAD_DIRECT_WAKE_TYPE_CONNECTIONLESS = 0x02
}
enum
Represents the Thread Direct Wake type.

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).
otThreadDirectLink typedef
An opaque type representing a Thread Direct Link between two peers.
otThreadDirectLinkConfig typedef
Represents the configuration for an otThreadDirectLink.
otThreadDirectWakeType typedef
Represents the Thread Direct Wake type.

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(otThreadDirectKey *aKey)
uint32_t
Gets the current MAC security frame counter associated with a registered Thread Direct key.
otThreadDirectKeyGetId(otThreadDirectKey *aKey)
Gets the Key ID associated with a registered Thread Direct key.
otThreadDirectKeyGetMaterial(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, 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.

otThreadDirectLinkConfig

Represents the configuration for an otThreadDirectLink.

Enumerations

otThreadDirectWakeType

 otThreadDirectWakeType

Represents the Thread Direct Wake type.

Currently, only OT_THREAD_DIRECT_WAKE_TYPE_TD_LINK is supported. OT_THREAD_DIRECT_WAKE_TYPE_REATTACH and OT_THREAD_DIRECT_WAKE_TYPE_CONNECTIONLESS are defined for future use.

Properties
OT_THREAD_DIRECT_WAKE_TYPE_CONNECTIONLESS

Connectionless control (for future use).

OT_THREAD_DIRECT_WAKE_TYPE_REATTACH

Reattach to Thread Network (for future use).

OT_THREAD_DIRECT_WAKE_TYPE_TD_LINK

Establish Thread Direct Link.

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.

struct otThreadDirectLink otThreadDirectLink

An opaque type representing a Thread Direct Link between two peers.

otThreadDirectLinkConfig

struct otThreadDirectLinkConfig otThreadDirectLinkConfig

Represents the configuration for an otThreadDirectLink.

otThreadDirectWakeType

enum otThreadDirectWakeType otThreadDirectWakeType

Represents the Thread Direct Wake type.

Currently, only OT_THREAD_DIRECT_WAKE_TYPE_TD_LINK is supported. OT_THREAD_DIRECT_WAKE_TYPE_REATTACH and OT_THREAD_DIRECT_WAKE_TYPE_CONNECTIONLESS are defined for future use.

Variables

OT_TOOL_PACKED_END

OT_TOOL_PACKED_BEGIN struct otThreadDirectKeyId OT_TOOL_PACKED_END

Functions

otThreadDirectFindKey

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

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

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