NAT64

This module includes functions and structs for the NAT64 function on the border router.

Summary

These functions are only available when OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE is enabled.

Enumerations
otNat64DropReason{
  OT_NAT64_DROP_REASON_UNKNOWN = 0,
  OT_NAT64_DROP_REASON_ILLEGAL_PACKET,
  OT_NAT64_DROP_REASON_UNSUPPORTED_PROTO,
  OT_NAT64_DROP_REASON_NO_MAPPING
} 		enum
Packet drop reasons.
otNat64State{
  OT_NAT64_STATE_DISABLED = 0,
  OT_NAT64_STATE_NOT_RUNNING,
  OT_NAT64_STATE_IDLE,
  OT_NAT64_STATE_ACTIVE
} 		enum
States of NAT64.

Typedefs
otIp4Address typedef
struct otIp4Address
Represents an IPv4 address.
otIp4Cidr typedef
struct otIp4Cidr
otNat64AddressMapping typedef
Represents an address mapping record for NAT64.
otNat64AddressMappingIterator typedef
Used to iterate through NAT64 address mappings.
otNat64Counters typedef
Represents the counters for NAT64.
otNat64DropReason typedef
Packet drop reasons.
otNat64ErrorCounters typedef
Represents the counters of dropped packets due to errors when handling NAT64 packets.
otNat64ProtocolCounters typedef
Represents the counters for the protocols supported by NAT64.
otNat64ReceiveIp4Callback)(otMessage *aMessage, void *aContext) typedef
void(*
Pointer is called when an IPv4 datagram (translated by NAT64 translator) is received.

Variables
OT_TOOL_PACKED_END

Functions
otIp4AddressFromString(const char *aString, otIp4Address *aAddress)
Converts a human-readable IPv4 address string into a binary representation.
otIp4AddressToString(const otIp4Address *aAddress, char *aBuffer, uint16_t aSize)
void
Converts the address to a string.
otIp4CidrFromString(const char *aString, otIp4Cidr *aCidr)
Converts a human-readable IPv4 CIDR string into a binary representation.
otIp4CidrToString(const otIp4Cidr *aCidr, char *aBuffer, uint16_t aSize)
void
Converts the IPv4 CIDR to a string.
otIp4ExtractFromIp6Address(uint8_t aPrefixLength, const otIp6Address *aIp6Address, otIp4Address *aIp4Address)
void
Set aIp4Address by performing NAT64 address translation from aIp6Address as specified in RFC 6052.
otIp4FromIp4MappedIp6Address(const otIp6Address *aIp6Address, otIp4Address *aIp4Address)
Extracts the IPv4 address from a given IPv4-mapped IPv6 address.
otIp4IsAddressEqual(const otIp4Address *aFirst, const otIp4Address *aSecond)
bool
Test if two IPv4 addresses are the same.
otIp4NewMessage(otInstance *aInstance, const otMessageSettings *aSettings)
Allocate a new message buffer for sending an IPv4 message to the NAT64 translator.
otIp4ToIp4MappedIp6Address(const otIp4Address *aIp4Address, otIp6Address *aIp6Address)
void
Converts a given IP4 address to an IPv6 address following the IPv4-mapped IPv6 address format.
otNat64ClearIp4Cidr(otInstance *aInstance)
void
Clears the CIDR used when setting the source address of the outgoing translated IPv4 packets.
otNat64GetCidr(otInstance *aInstance, otIp4Cidr *aCidr)
Gets the IPv4 CIDR configured in the NAT64 translator.
otNat64GetCounters(otInstance *aInstance, otNat64ProtocolCounters *aCounters)
void
Gets NAT64 translator counters.
otNat64GetErrorCounters(otInstance *aInstance, otNat64ErrorCounters *aCounters)
void
Gets the NAT64 translator error counters.
otNat64GetNextAddressMapping(otInstance *aInstance, otNat64AddressMappingIterator *aIterator, otNat64AddressMapping *aMapping)
Gets the next AddressMapping info (using an iterator).
otNat64GetPrefixManagerState(otInstance *aInstance)
Gets the state of NAT64 prefix manager.
otNat64GetTranslatorState(otInstance *aInstance)
Gets the state of NAT64 translator.
otNat64InitAddressMappingIterator(otInstance *aInstance, otNat64AddressMappingIterator *aIterator)
void
otNat64Send(otInstance *aInstance, otMessage *aMessage)
Translates an IPv4 datagram to an IPv6 datagram and sends via the Thread interface.
otNat64SetEnabled(otInstance *aInstance, bool aEnabled)
void
Enable or disable NAT64 functions.
otNat64SetIp4Cidr(otInstance *aInstance, const otIp4Cidr *aCidr)
Sets the CIDR used when setting the source address of the outgoing translated IPv4 packets.
otNat64SetReceiveIp4Callback(otInstance *aInstance, otNat64ReceiveIp4Callback aCallback, void *aContext)
void
Registers a callback to provide received IPv4 datagrams.
otNat64SynthesizeIp6Address(otInstance *aInstance, const otIp4Address *aIp4Address, otIp6Address *aIp6Address)
Sets the IPv6 address by performing NAT64 address translation from the preferred NAT64 prefix and the given IPv4 address as specified in RFC 6052.

Macros
OT_IP4_ADDRESS_SIZE 4
Size of an IPv4 address (bytes)
OT_IP4_ADDRESS_STRING_SIZE 17
Length of 000.000.000.000 plus a suffix NUL.
OT_IP4_CIDR_STRING_SIZE 20
Length of 000.000.000.000/00 plus a suffix NUL.

Structs
otIp4Address

Represents an IPv4 address.

otIp4Cidr

Represents an IPv4 CIDR block.

otNat64AddressMapping

Represents an address mapping record for NAT64.

otNat64AddressMappingIterator

Used to iterate through NAT64 address mappings.

otNat64Counters

Represents the counters for NAT64.

otNat64ErrorCounters

Represents the counters of dropped packets due to errors when handling NAT64 packets.

otNat64ProtocolCounters

Represents the counters for the protocols supported by NAT64.

Unions
otIp4Address::OT_TOOL_PACKED_FIELD

Enumerations

otNat64DropReason

 otNat64DropReason

Packet drop reasons.

Properties
OT_NAT64_DROP_REASON_ILLEGAL_PACKET

Packet drop due to failed to parse the datagram.

OT_NAT64_DROP_REASON_NO_MAPPING

Packet drop due to no mappings found or mapping pool exhausted.

OT_NAT64_DROP_REASON_UNKNOWN

Packet drop for unknown reasons.

OT_NAT64_DROP_REASON_UNSUPPORTED_PROTO

Packet drop due to unsupported IP protocol.

otNat64State

 otNat64State

States of NAT64.

Properties
OT_NAT64_STATE_ACTIVE

The BR is publishing a NAT64 prefix and/or translating packets.

OT_NAT64_STATE_DISABLED

NAT64 is disabled.

OT_NAT64_STATE_IDLE

NAT64 is enabled, but this BR is not an active NAT64 BR.

OT_NAT64_STATE_NOT_RUNNING

NAT64 is enabled, but one or more dependencies of NAT64 are not running.

Typedefs

otIp4Address

struct otIp4Address otIp4Address

Represents an IPv4 address.

otIp4Cidr

struct otIp4Cidr otIp4Cidr

otNat64AddressMapping

struct otNat64AddressMapping otNat64AddressMapping

Represents an address mapping record for NAT64.

otNat64AddressMappingIterator

struct otNat64AddressMappingIterator otNat64AddressMappingIterator

Used to iterate through NAT64 address mappings.

The fields in this type are opaque (intended for use by OpenThread core only) and therefore should not be accessed or used by caller.

Before using an iterator, it MUST be initialized using otNat64AddressMappingIteratorInit().

otNat64Counters

struct otNat64Counters otNat64Counters

Represents the counters for NAT64.

otNat64DropReason

enum otNat64DropReason otNat64DropReason

Packet drop reasons.

otNat64ErrorCounters

struct otNat64ErrorCounters otNat64ErrorCounters

Represents the counters of dropped packets due to errors when handling NAT64 packets.

otNat64ProtocolCounters

struct otNat64ProtocolCounters otNat64ProtocolCounters

Represents the counters for the protocols supported by NAT64.

otNat64ReceiveIp4Callback

void(* otNat64ReceiveIp4Callback)(otMessage *aMessage, void *aContext)

Pointer is called when an IPv4 datagram (translated by NAT64 translator) is received.

Details
Parameters
[in] aMessage
A pointer to the message buffer containing the received IPv6 datagram. This function transfers the ownership of the aMessage to the receiver of the callback. The message should be freed by the receiver of the callback after it is processed.
[in] aContext
A pointer to application-specific context.

Variables

OT_TOOL_PACKED_END

OT_TOOL_PACKED_BEGIN struct otIp4Address OT_TOOL_PACKED_END

Functions

otIp4AddressFromString

otError otIp4AddressFromString(
  const char *aString,
  otIp4Address *aAddress
)

Converts a human-readable IPv4 address string into a binary representation.

Details
Parameters
[in] aString
A pointer to a NULL-terminated string.
[out] aAddress
A pointer to an IPv4 address.
Return Values
OT_ERROR_NONE
Successfully parsed the string.
OT_ERROR_INVALID_ARGS
Failed to parse the string.

otIp4AddressToString

void otIp4AddressToString(
  const otIp4Address *aAddress,
  char *aBuffer,
  uint16_t aSize
)

Converts the address to a string.

The string format uses quad-dotted notation of four bytes in the address (e.g., "127.0.0.1").

If the resulting string does not fit in aBuffer (within its aSize characters), the string will be truncated but the outputted string is always null-terminated.

Details
Parameters
[in] aAddress
A pointer to an IPv4 address (MUST NOT be NULL).
[out] aBuffer
A pointer to a char array to output the string (MUST NOT be nullptr).
[in] aSize
The size of aBuffer (in bytes).

otIp4CidrFromString

otError otIp4CidrFromString(
  const char *aString,
  otIp4Cidr *aCidr
)

Converts a human-readable IPv4 CIDR string into a binary representation.

Details
Parameters
[in] aString
A pointer to a NULL-terminated string.
[out] aCidr
A pointer to an IPv4 CIDR.
Return Values
OT_ERROR_NONE
Successfully parsed the string.
OT_ERROR_INVALID_ARGS
Failed to parse the string.

otIp4CidrToString

void otIp4CidrToString(
  const otIp4Cidr *aCidr,
  char *aBuffer,
  uint16_t aSize
)

Converts the IPv4 CIDR to a string.

The string format uses quad-dotted notation of four bytes in the address with the length of prefix (e.g., "127.0.0.1/32").

If the resulting string does not fit in aBuffer (within its aSize characters), the string will be truncated but the outputted string is always null-terminated.

Details
Parameters
[in] aCidr
A pointer to an IPv4 CIDR (MUST NOT be NULL).
[out] aBuffer
A pointer to a char array to output the string (MUST NOT be nullptr).
[in] aSize
The size of aBuffer (in bytes).

otIp4ExtractFromIp6Address

void otIp4ExtractFromIp6Address(
  uint8_t aPrefixLength,
  const otIp6Address *aIp6Address,
  otIp4Address *aIp4Address
)

Set aIp4Address by performing NAT64 address translation from aIp6Address as specified in RFC 6052.

The NAT64 aPrefixLength MUST be one of the following values: 32, 40, 48, 56, 64, or 96, otherwise the behavior of this method is undefined.

Details
Parameters
[in] aPrefixLength
The prefix length to use for IPv4/IPv6 translation.
[in] aIp6Address
A pointer to an IPv6 address.
[out] aIp4Address
A pointer to output the IPv4 address.

otIp4FromIp4MappedIp6Address

otError otIp4FromIp4MappedIp6Address(
  const otIp6Address *aIp6Address,
  otIp4Address *aIp4Address
)

Extracts the IPv4 address from a given IPv4-mapped IPv6 address.

An IPv4-mapped IPv6 address consists of an 80-bit prefix of zeros, the next 16 bits set to ones, and the remaining, least-significant 32 bits contain the IPv4 address, e.g., ::ffff:192.0.2.128 representing 192.0.2.128.

Details
Parameters
[in] aIp6Address
An IPv6 address to extract IPv4 from.
[out] aIp4Address
An IPv4 address to output the extracted address.
Return Values
OT_ERROR_NONE
Extracted the IPv4 address successfully. aIp4Address is updated.
OT_ERROR_PARSE
The aIp6Address does not follow the IPv4-mapped IPv6 address format.

otIp4IsAddressEqual

bool otIp4IsAddressEqual(
  const otIp4Address *aFirst,
  const otIp4Address *aSecond
)

Test if two IPv4 addresses are the same.

Details
Parameters
[in] aFirst
A pointer to the first IPv4 address to compare.
[in] aSecond
A pointer to the second IPv4 address to compare.
Return Values
TRUE
The two IPv4 addresses are the same.
FALSE
The two IPv4 addresses are not the same.

otIp4NewMessage

otMessage * otIp4NewMessage(
  otInstance *aInstance,
  const otMessageSettings *aSettings
)

Allocate a new message buffer for sending an IPv4 message to the NAT64 translator.

Message buffers allocated by this function will have 20 bytes (difference between the size of IPv6 headers and IPv4 header sizes) reserved.

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aSettings
A pointer to the message settings or NULL to set default settings.
Returns
A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid.
See also:
otNat64Send

otIp4ToIp4MappedIp6Address

void otIp4ToIp4MappedIp6Address(
  const otIp4Address *aIp4Address,
  otIp6Address *aIp6Address
)

Converts a given IP4 address to an IPv6 address following the IPv4-mapped IPv6 address format.

Details
Parameters
[in] aIp4Address
An IPv4 address to convert.
[out] aIp6Address
An IPv6 address to set.

otNat64ClearIp4Cidr

void otNat64ClearIp4Cidr(
  otInstance *aInstance
)

Clears the CIDR used when setting the source address of the outgoing translated IPv4 packets.

Is available only when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
See also:
otNat64SetIp4Cidr

otNat64GetCidr

otError otNat64GetCidr(
  otInstance *aInstance,
  otIp4Cidr *aCidr
)

Gets the IPv4 CIDR configured in the NAT64 translator.

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aCidr
A pointer to an otIp4Cidr. Where the CIDR will be filled.

otNat64GetCounters

void otNat64GetCounters(
  otInstance *aInstance,
  otNat64ProtocolCounters *aCounters
)

Gets NAT64 translator counters.

The counter is counted since the instance initialized.

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aCounters
A pointer to an otNat64Counters where the counters of NAT64 translator will be placed.

otNat64GetErrorCounters

void otNat64GetErrorCounters(
  otInstance *aInstance,
  otNat64ErrorCounters *aCounters
)

Gets the NAT64 translator error counters.

The counters are initialized to zero when the OpenThread instance is initialized.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aCounters
A pointer to an otNat64Counters where the counters of NAT64 translator will be placed.

otNat64GetNextAddressMapping

otError otNat64GetNextAddressMapping(
  otInstance *aInstance,
  otNat64AddressMappingIterator *aIterator,
  otNat64AddressMapping *aMapping
)

Gets the next AddressMapping info (using an iterator).

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in,out] aIterator
A pointer to the iterator. On success the iterator will be updated to point to next NAT64 address mapping record. To get the first entry the iterator should be set to OT_NAT64_ADDRESS_MAPPING_ITERATOR_INIT.
[out] aMapping
A pointer to an otNat64AddressMapping where information of next NAT64 address mapping record is placed (on success).
Return Values
OT_ERROR_NONE
Successfully found the next NAT64 address mapping info (aMapping was successfully updated).
OT_ERROR_NOT_FOUND
No subsequent NAT64 address mapping info was found.

otNat64GetPrefixManagerState

otNat64State otNat64GetPrefixManagerState(
  otInstance *aInstance
)

Gets the state of NAT64 prefix manager.

Available when OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
OT_NAT64_STATE_DISABLED
NAT64 prefix manager is disabled.
OT_NAT64_STATE_NOT_RUNNING
NAT64 prefix manager is enabled, but is not running (because the routing manager is not running).
OT_NAT64_STATE_IDLE
NAT64 prefix manager is enabled, but is not publishing a NAT64 prefix. Usually when there is another border router publishing a NAT64 prefix with higher priority.
OT_NAT64_STATE_ACTIVE
NAT64 prefix manager is enabled, and is publishing NAT64 prefix to the Thread network.

otNat64GetTranslatorState

otNat64State otNat64GetTranslatorState(
  otInstance *aInstance
)

Gets the state of NAT64 translator.

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
OT_NAT64_STATE_DISABLED
NAT64 translator is disabled.
OT_NAT64_STATE_NOT_RUNNING
NAT64 translator is enabled, but the translator is not configured with a valid NAT64 prefix and a CIDR.
OT_NAT64_STATE_ACTIVE
NAT64 translator is enabled, and is translating packets.

otNat64InitAddressMappingIterator

void otNat64InitAddressMappingIterator(
  otInstance *aInstance,
  otNat64AddressMappingIterator *aIterator
)

Initializes an otNat64AddressMappingIterator.

An iterator MUST be initialized before it is used.

An iterator can be initialized again to restart from the beginning of the mapping info.

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

otNat64Send

otError otNat64Send(
  otInstance *aInstance,
  otMessage *aMessage
)

Translates an IPv4 datagram to an IPv6 datagram and sends via the Thread interface.

The caller transfers ownership of aMessage when making this call. OpenThread will free aMessage when processing is complete, including when a value other than OT_ERROR_NONE is returned.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aMessage
A pointer to the message buffer containing the IPv4 datagram.
Return Values
OT_ERROR_NONE
Successfully processed the message.
OT_ERROR_DROP
Message was well-formed but not fully processed due to packet processing rules.
OT_ERROR_NO_BUFS
Could not allocate necessary message buffers when processing the datagram.
OT_ERROR_NO_ROUTE
No route to host.
OT_ERROR_INVALID_SOURCE_ADDRESS
Source address is invalid, e.g. an anycast address or a multicast address.
OT_ERROR_PARSE
Encountered a malformed header when processing the message.

otNat64SetEnabled

void otNat64SetEnabled(
  otInstance *aInstance,
  bool aEnabled
)

Enable or disable NAT64 functions.

Note: This includes the NAT64 Translator (when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled) and the NAT64 Prefix Manager (when OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE is enabled).

When OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled, setting disabled to true resets the mapping table in the translator.

Available when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE or OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aEnabled
A boolean to enable/disable the NAT64 functions
See also:
otNat64GetTranslatorState
otNat64GetPrefixManagerState

otNat64SetIp4Cidr

otError otNat64SetIp4Cidr(
  otInstance *aInstance,
  const otIp4Cidr *aCidr
)

Sets the CIDR used when setting the source address of the outgoing translated IPv4 packets.

Is available only when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aCidr
A pointer to an otIp4Cidr for the IPv4 CIDR block for NAT64.
Return Values
OT_ERROR_INVALID_ARGS
The given CIDR is not a valid IPv4 CIDR for NAT64.
OT_ERROR_NONE
Successfully set the CIDR for NAT64.
See also:
otNat64Send
otNat64SetReceiveIp4Callback

otNat64SetReceiveIp4Callback

void otNat64SetReceiveIp4Callback(
  otInstance *aInstance,
  otNat64ReceiveIp4Callback aCallback,
  void *aContext
)

Registers a callback to provide received IPv4 datagrams.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aCallback
A pointer to a function that is called when an IPv4 datagram is received or NULL to disable the callback.
[in] aContext
A pointer to application-specific context.

otNat64SynthesizeIp6Address

otError otNat64SynthesizeIp6Address(
  otInstance *aInstance,
  const otIp4Address *aIp4Address,
  otIp6Address *aIp6Address
)

Sets the IPv6 address by performing NAT64 address translation from the preferred NAT64 prefix and the given IPv4 address as specified in RFC 6052.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aIp4Address
A pointer to the IPv4 address to translate to IPv6.
[out] aIp6Address
A pointer to the synthesized IPv6 address.
Returns
OT_ERROR_NONE Successfully synthesized the IPv6 address from NAT64 prefix and IPv4 address.
Returns
OT_ERROR_INVALID_STATE No valid NAT64 prefix in the network data.

Macros

OT_IP4_ADDRESS_SIZE

 OT_IP4_ADDRESS_SIZE 4

Size of an IPv4 address (bytes)

OT_IP4_ADDRESS_STRING_SIZE

 OT_IP4_ADDRESS_STRING_SIZE 17

Length of 000.000.000.000 plus a suffix NUL.

OT_IP4_CIDR_STRING_SIZE

 OT_IP4_CIDR_STRING_SIZE 20

Length of 000.000.000.000/00 plus a suffix NUL.

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.