> Documentation index: https://openthread.io/reference/llms.txt

# 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 }` | enumRepresents the Thread Direct Wake type. |

| ### Typedefs ||
|---|---|
| `otThreadDirectKey` | typedef `struct otThreadDirectKey` An opaque type representing a registered Thread Direct key entry in OpenThread. |
| `otThreadDirectKeyId` | typedef `struct otThreadDirectKeyId` |
| `otThreadDirectKeyIterator` | typedef `struct otThreadDirectKeyIterator` Represents an iterator for iterating through registered Thread Direct keys. |
| `otThreadDirectKeyMaterial` | typedef `otMacKeyMaterial` Represents Thread Direct key material (literal key bytes or cryptographic key reference). |
| `otThreadDirectLink` | typedef `struct otThreadDirectLink` An opaque type representing a Thread Direct Link between two peers. |
| `otThreadDirectLinkConfig` | typedef `struct otThreadDirectLinkConfig` Represents the configuration for an `otThreadDirectLink`. |
| `otThreadDirectWakeType` | typedef `enum otThreadDirectWakeType` Represents the Thread Direct Wake type. |

| ### Variables ||
|---|---|
| `OT_TOOL_PACKED_END` | `OT_TOOL_PACKED_BEGIN struct otThreadDirectKeyId` |

| ### Functions ||
|---|---|
| `otThreadDirectFindKey(otInstance *aInstance, const otThreadDirectKeyMaterial *aKeyMaterial, const otThreadDirectKeyId *aKeyId)` | `otThreadDirectKey *` Finds a registered Thread Direct key matching the given key material and Key ID. |
| `otThreadDirectGetNextKey(otThreadDirectKeyIterator *aIterator)` | `otThreadDirectKey *` 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)` | `const otThreadDirectKeyId *` Gets the Key ID associated with a registered Thread Direct key. |
| `otThreadDirectKeyGetMaterial(otThreadDirectKey *aKey)` | `const otThreadDirectKeyMaterial *` Gets the key material associated with a registered Thread Direct key. |
| `otThreadDirectRegisterKey(otInstance *aInstance, const otThreadDirectKeyMaterial *aKeyMaterial, const otThreadDirectKeyId *aKeyId)` | `otThreadDirectKey *` 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](https://openthread.io/reference/struct/ot-thread-direct-key-id.md.txt) | Represents a Thread Direct Key ID. |
| [otThreadDirectKeyIterator](https://openthread.io/reference/struct/ot-thread-direct-key-iterator.md.txt) | Represents an iterator for iterating through registered Thread Direct keys. |
| [otThreadDirectLinkConfig](https://openthread.io/reference/struct/ot-thread-direct-link-config.md.txt) | 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.

<br />

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.

### otThreadDirectLink

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


> [!NOTE]
> **Note:** The Thread Direct Link APIs and definition are provisional and work in progress. Not all functions are fully implemented yet, and the API definitions may change in future revisions.

<br />

### otThreadDirectLinkConfig

```
struct otThreadDirectLinkConfig otThreadDirectLinkConfig
```
Represents the configuration for an `otThreadDirectLink`.


> [!NOTE]
> **Note:** This structure is a placeholder and will be updated in future revisions as link establishment support is added.

<br />

### 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](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources.md.txt).