Configuration and status of network interfaces (kos_net.h)

The API is defined in the header file sysroot-*-kos/include/kos_net.h from the KasperskyOS SDK.

The API lets you do the following:

• Get a list of network interfaces available in the system.
• Send data on available network interfaces to standard output.
• Convert a textual representation of an IPv6 address into binary format.
• Wait for the appearance of network interfaces with the defined parameters in the list of available network interfaces.
• Configure the available network interfaces with IPv4 and IPv6 addressing.

Information about API functions is provided in the table below.

To get a list of network interfaces that are available in the system, call the get_ifaces_addrs() function. This function uses the pif parameter to return a linked list of ifaddrs structures, each of which contains the following data on the network interface: name, flags, IP address, and subnet mask. The ifaddrs structure is defined in the header file sysroot-*-kos/include/ifaddrs.h.

To send information about available network interfaces to standard output, use the list_network_ifaces() function. This function does not have any parameters. The standard output displays the following data about each network interface: name, type, activity status and address of the network interface with its subnet mask.

Example output of the list_network_ifaces() function:

Name Type Running Address/mask

lo0 inet Yes ::1/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff

lo0 inet Yes fe80:1::1/ffff:ffff:ffff:ffff::

lo0 inet Yes 127.0.0.1/255.0.0.0

en0 mac Yes 52:58:00:12:34:bb

en0 inet Yes 10.0.2.15/255.255.255.

en0 inet Yes fe80:2::5058:ff:fe12:34bb/ffff:ffff:ffff:ffff::

To convert the textual representation of an IPv6 address into binary format, use the ip6_parse_addr() function. This function uses the ip_str input parameter to receive the textual representation of an IPv6 address in accordance with paragraphs 2.2 and 2.3 of the RFC 4291 specification in the following format:

<ipv6_address>[/<prefix_size>]

The function uses the dst_mask output parameter to return the pointer to the sockaddr_in6 structure, which contains the prefix mask in the sin6_addr field. The function uses the dst_ip output parameter to return the pointer to the other sockaddr_in6 structure, which contains the IPv6 address in the sin6_addr field. The sockaddr_in6 structure is defined in the header file sysroot-*-kos/include/strict/posix/netinet/in.6.

Use the wait_for_iface() function to wait for the appearance of a network interface with the necessary parameters in the list of available network interfaces. This function uses the name input parameter to receive the name of the network interface for which the function is waiting. If this parameter is not specified (NULL), the function will wait for the appearance of any network interface except those whose names begin with lo*. This function uses the wait_flags input parameter to receive the flags that determine the wait parameters – availability of IP addresses and default gateways. These flags can be combined. The timeout for waiting for the necessary network interface (in seconds) is defined in the timeout parameter.

To configure the available network interfaces using IPv4 and IPv6 addressing, the API provides the following two functions: configure_net_iface() and configure_net_iface6(). To simplify configuration of network interfaces, there are macros that you can use as input parameters for these functions (see the table below).

Macros of the configure_net_iface() and configure_net_iface6() functions

Macro	Description	Default value	Use in configure_net_iface()	Use in configure_net_iface6()
DEFAULT_INTERFACE	Name of the network interface used for the connection	en0	Yes	Yes
DEFAULT_ADDR	IP address assigned to the network interface	10.0.2.15	Yes	No
DEFAULT_MASK	Subnet mask	255.255.255.0	Yes	No
DEFAULT_GATEWAY	Default gateway	10.0.2.2	Yes	No
DEFAULT_MTU	Maximum size of a transmitted packet, in bytes (Maximum Transmission Unit, MTU)	1500	Yes	No
DEFAULT_TIMEOUT	Timeout (in seconds)	60	Yes	Yes

Information about API functions

kos_net.h functions

Function	Information about the function
get_ifaces_addrs()	Purpose Gets a list of network interfaces available in the system. Parameters [out] pif – linked list of ifaddrs structures containing data on network interfaces. Returned values Returns true if successful, otherwise returns false.
configure_net_iface()	Purpose Configures a network interface using IPv4 addressing. The ip, mask, and gw input parameters must be specified in the format X.X.X.X, where X is a decimal number from 0 to 255. Parameters [in] name – name of the network interface that needs to be configured. [in] ip – IPv4 address that will be assigned to the network interface. [in] mask – subnet mask. [in] gw – IPv4 address of the default gateway. [in] mtu – maximum size (in bytes) of a packet. Returned values Returns true if successful, otherwise returns false.
ip6_parse_addr()	Purpose Converts a textual representation of an IPv6 address into binary format, and (optionally) generates a prefix mask based on the specified prefix size. Parameters [in] ip_str – textual representation of the IPv6 address. [out] dst_mask – pointer to the sockaddr_in6 structure containing the prefix mask in the sin6_addr field. [out] dst_ip – pointer to the sockaddr_in6 structure containing the IPv6 address in the sin6_addr field. Returned values Returns true if successful, otherwise returns false.
configure_net_iface6()	Purpose Configures a network interface using IPv6 addressing. Parameters [in] name – name of the network interface that needs to be configured. [in] ip – IPv6 address according to paragraphs 2.2 and 2.3 of the RFC 4291 specification. [in] gw – IPv6 address of the default gateway according to paragraph 2.2 of the RFC 4291 specification, or NULL if you do not need to specify this parameter. Returned values Returns true if successful, otherwise returns false.
list_network_ifaces()	Purpose Gets a list of network interfaces that are available in the system and sends data on each network interface to standard output. Parameters N/A Returned values Returns true if successful, otherwise returns false.
wait_for_iface()	Purpose Waits for the appearance of an available network interface that meets the requirements defined by the wait flags. Parameters [in] name – name of the network interface for which the function is waiting. If this parameter is not specified (NULL), the function waits for the appearance of any network interface except those whose names begin with lo*. [in] wait_flags – wait flags: IWF_EXISTS – wait for the appearance of a network interface in the list of available network interfaces (always used by default). In this case, the network interface does not have to be active. IWF_IP4 – wait for the assignment of an IPv4 address to the network interface. IWF_IP6 – wait for the assignment of an IPv6 address to the network interface. IWF_GW4 – wait for the appearance of an entry for an IPv4 gateway in the routing table. The entry may be added automatically (via DHCP) or manually by a user. IWF_GW6 – wait for the appearance of an entry for an IPv6 gateway in the routing table. The entry may be added automatically (via DHCP) or manually by a user. [in] timeout – timeout (in seconds) to wait for the network interface with the specified parameters. Returned values Returns true if successful, otherwise returns false.

Example use of API functions:

#include <kos_net.h>

int main(int argc, char *argv[])

{

// Wait 60 seconds for the network interface named en0 to appear in the list of available network interfaces

if (!wait_for_iface(DEFAULT_INTERFACE, IWF_EXISTS, DEFAULT_TIMEOUT))

{

perror("Network interface does not exist");

return EXIT_FAILURE;

}en0

// Configure network interface en0 with the default values

if (!configure_net_iface(DEFAULT_INTERFACE, DEFAULT_ADDR, DEFAULT_MASK, DEFAULT_GATEWAY, DEFAULT_MTU))

{

perror("Can't configure network");

return EXIT_FAILURE;

}

}

Page top