Building.Open.Source.Network.Security.Tools.Components.And.Techniques [Electronic resources] نسخه متنی

Packet Builder Functions

The core of libnet is the platform-independent packet-building functionality. These functions enable an application programmer to build protocol headers (and data) in a simple and consistent manner without having to worry (too much) about low-level network odds and ends. Each libnet_build() function builds a piece of a packet (generally a protocol header). While it is perfectly possible to build an entire, ready-to-transmit packet with a single call to a libnet_build() function, generally more than one builder-class function call is required to construct a full packet. A "complete" wire-ready packet generally consists of more than one piece.

Every function that builds a protocol header takes a series of arguments roughly corresponding to the header values as they appear on the wire. This process is intuitive but often makes for functions with huge prototypes and large stack frames.

One important thing to note is that you must call these functions in order, corresponding to how they should appear on the wire (from the highest protocol layer on down). This building process is intuitive; it approximates what happens in an operating system kernel. In other words, to build a Network Time Protocol (NTP) packet by using the link-layer interface, the application programmer would call the libnet_build() functions in the following order:

libnet_build_ntp()

libnet_build_udp()

libnet_build_ipv4()

libnet_build_ethernet()

This ordering is essential for libnet 1.1.0 to properly link together the packet internally (previous libnet versions did not have the requirement).

Figure 3.2 shows the protocols that libnet's packet construction functionality support and their general relationships within the context of the ISO Open Systems Interconnectivity (OSI) 7 layer model. Note that libnet supports arbitrary application programmer specified protocols via the libnet_build_data() interface (the "other" protocols).

Figure 3.2: Libnet-supported protocols and their relationships.

All standard libnet_build() functions take the same final four arguments, as Table 3.3 summarizes.

The optional arguments are just that, and the value in parentheses can replace them if they are not to be used.

The four libnet_build() functions that do not take the same final four arguments are as follows:

libnet_autobuild_ethernet(). No payload or ptag

libnet_autobuild_ipv4(). No payload, payload_s, or ptag

libnet_build_ipv4_options(). No payload or payload_s

libnet_build_tcp_options(). No payload or payload_s

The Payload Interface

The payload interface specifies an optional way to include data directly after the protocol header in question. You can use this function for a variety of purposes, including the following:

Including additional or arbitrary protocol header information that is not available from a libnet interface

Including a packet payload (data segment)

Building another protocol header that is not available from a libnet interface

To employ the interface, the application programmer should construct the payload data and pass a u_char * to this data and its size to the desired libnet_build() function. Libnet handles the rest. The example code at the end of this chapter employs this interface to include a packet payload after a UDP header.

Libnet Header Sizes

Certain libnet_build() functions require packet length arguments. For example, libnet_build_ipv4() requires the application programmer to specify the entire IP packet length as the first argument. To make this process easier, libnet includes a list of symbolic constants corresponding to header length values in bytes for every supported protocol (for protocols with variable sized headers, the only base header size is defined). This list appears in Table 3.4.

Protocol Tags and Libnet Packet Builder Return Values

Libnet uses the protocol tag (ptag) to identify individual pieces of a packet after being created. A new ptag results every time a libnet_ build() function with an empty (0) ptag argument completes successfully. This new ptag now refers to the packet piece just created. The application programmer's responsibility is to save this value if he or she plans to modify this particular portion later on in the program. If the application programmer needs to modify some values of that particular packet piece again, he or she calls the same libnet_build() function specifying the saved ptag argument. Libnet then searches for that packet piece and modifies it rather than creating a new one. Upon failure for any reason, libnet_build() functions return -1; libnet_geterror() tells you why.

libnet_ptag_t libnet_build_802_lq(u_char *dst, u_char *src,
u_short tpi, u_char priority, u_char cfi, u_short vid,
u_short len, u_char *payload, u_long payload_s, libnet_t *1,
libnet_ptag_t ptag);

libnet_build_802_lq() builds an IEEE 802.lq VLAN tagging header. Depending on the value of len, the function wraps the 802.lq header inside either an IEEE 802.3 header or an RFC 894 Ethernet II (DIX) header (both resulting in an 18-byte frame). If len is 1500 or less, most receiving protocol stacks parse the frame as an IEEE 802.3 encapsulated frame. If len is one of the Ethernet types in Table 3.6, most protocol stacks parse the frame as an RFC 894 Ethernet II encapsulated frame. The function takes arguments (see Table 3.5).

Table 3.6 summarizes the different Ethernet-type symbolic constants associated with len (for an RFC 894 encapsulated frame). These constants specify the layer 3 protocol in several link-layer protocols, including 802.lq., 802.2, ARP, RARP, and Ethernet II.

libnet_ptag_t libnet_build_802_2(u_char dsap, u_char dsap,
u_char control, u_char *payload, u_long payload_s, libnet_t
*1, libnet_ptag_t ptag);

libnet_build_802_2() builds an IEEE 802.2 link-layer control (LLC) header. The function takes arguments (see Table 3.7).

Table 3.6 summarizes the different symbolic constants for type. Table 3.8 summarizes the different values for some of the service access point values.

libnet_ptag_t libnet_build_802_2snap(u_char dsap, u_char
dsap, u_char control, u_char *oui, u_short type, u_char
*payload, u_long payload_s, libnet_t *1, libnet_ptag_t ptag);

libnet_build_802_2snap() builds an IEEE 802.2 Link-Layer Control/Subnetwork Attachment Point (LLC/SNAP) header. The function takes arguments (see Table 3.9).

Table 3.6 summarizes the different symbolic constants for type.

libnet_ptag_t libnet_build_802_3(u_char *dst, u_char *src,
u_short tpi, u_char priority, u_char cfi, u_short vid,
u_short len, u_char *payload, u_long payload_s, libnet_t *1,
libnet_ptag_t ptag);

libnet_build_802_3() builds an IEEE 802.3 header. The 802.3 header is almost identical to the RFC 894 Ethernet II header-the exception being that the field immediately following the source address holds the frame's length (as opposed to the layer 3 protocol). You should only use this function when libnet is initialized with the LIBNET_LINK interface. The function takes arguments (see Table 3.10).

The reader should note that an 802.2 LLC/SNAP header generally always proceeds the 802.3 header.

libnet_ptag_t libnet_build_arp(u_short hrd, u_short pro,
u_short hln, u_short pln, u_short op, u_char *sha, u_char
*spa, u_char *tpa, u_char *tpa, u_char *payload, u_long
payload_s, libnet_t *1, libnet_ptag_t ptag);

libnet_build_arp() builds an Address Resolution Protocol (ARP) header. Depending on the op value, the function builds one of several different types of RFC 826 ARP or RFC 903 RARP packets. The function takes arguments (see Table 3.11).

Table 3.12 summarizes the different symbolic constants associated with hrd.

Table 3.6 summarizes the different symbolic constants for pro. Table 3.13 summarizes the different symbolic constants associated with op.

libnet_ptag_t libnet_build_bootpv4(u_char opcode, u_char
htype, u_char hlen, u_char hopcount, u_long xid, u_short
secs, u_short unused, u_long cip, u_long yip, u_long sip,
u_long gip, u_char *payload, u_long payload_s, libnet_t *1,
libnet_ptag_t ptag);

libnet_build_bootpv4() builds an IP version 4 RFC 951 Bootstrap Protocol header. The function takes arguments (see Table 3.14).

The BOOTP protocol also accepts optional additional variable length and size arguments. To include these, the programmer uses the payload interface. Table 3.15 summarizes the opcode symbolic constants.

libnet_ptag_t libnet_build_cdp(u_char version, u_char ttl,
u_short sum, u_short type, u_short len, u_char *value, u_char
*payload, u_long payload_s, libnet_t *l, libnet_ptag_t ptag);

libnet_build_cdp() builds a Cisco Discovery Protocol (CDP) header. Cisco Systems designed CDP to aid in the network management of adjacent Cisco devices. The function takes arguments (see Table 3.16).

The CDP protocol also accepts an arbitrary number of additional "type / length / value" arguments. To include these, the programmer could either use the payload interface or libnet_build_data() to construct them. Table 3.17 summarizes the type symbolic constants.

libnet_ptag_t libnet_build_data(u_char *payload, u_long
payload_s, libnet_t *1, libnet_ptag_t ptag);

libnet_build_data() builds a generic data unit. This function does not build a specific protocol header; rather, it appends an application programmer-specified block of data to the end of the packet list. Other than having no header arguments, it behaves exactly the same as every other protocol builder function.

libnet_ptag_t libnet_build_dhcpv4(u_char opcode, u_char
htype, u_char hlen, u_char hopcount, u_long xid, u_short
secs, u_short flags, u_long cip, u_long yip, u_long sip,
u_long gip, u_char *payload, u_long payload_s, libnet_t *1,
libnet_ptag_t ptag);

libnet_build_dhcpv4() builds an IP version 4 RFC 2131 Dynamic Host Configuration Protocol header. The use of this function is identical to libnet_build_bootpv4().

libnet_ptag_t libnet_build_dnsv4(u_short id, u_short flags,
u_short num_q, u_short num_anws_rr, u_short num_auth_rr,
u_short num_addi_rr, u_char *payload, u_long payload_s,
libnet_t *1, libnet_ptag_t ptag);

libnet_build_dnsv4() builds an RFC 1035 IP version 4 DNS header. The function takes arguments (see Table 3.18).

libnet_ptag_t libnet_build_ethernet(u_char *dst, u_char *src,
u_short type, u_char *payload, u_long payload_s, libnet_t *1,
libnet_ptag_t ptag);

libnet_build_ethernet() builds an RFC 894 Ethernet II header. The RFC 894 Ethernet II header is almost identical to the IEEE 802.3 header, with the exception that the field immediately following the source address holds the layer 3 protocol (as opposed to frame's length). You should only use this function when libnet is initialized with the LIBNET_LINK interface. The function takes arguments (see Table 3.19).

The type symbolic constants are the Ethernet type symbolic constants in Table 3.6.

libnet_ptag_t libnet_autobuild_ethernet(u_char *dst, u_short type,
libnet_t *1);

libnet_autobuild_ethernet() auto builds an Ethernet protocol header. The function is useful to build an Ethernet header quickly when the extra functionality is not needed. The function takes the same dst and type arguments (see Table 3.19). The function does not accept a ptag argument, but it does return a ptag. In other words, you can use it to build a new Ethernet header but not to modify an existing one.

libnet_ptag_t libnet_build_icmpv4_echo(u_char type, u_char
code, u_short sum, u_short id, u_short seq, u_char *payload,
u_long payload_s, libnet_t *1, libnet_ptag_t ptag);

libnet_build_icmpv4_echo() builds an IP version 4 RFC 792 Internet Control Message Protocol echo request/reply header. The function takes arguments (see Table 3.20).

libnet_ptag_t libnet_build_icmpv4_mask(u_char type, u_char
code, u_short sum, u_short id, u_short seq, u_long mask,
u_char *payload, u_long payload_s, libnet_t *1,
libnet_ptag_t ptag);

libnet_build_icmpv4_mask() builds an IP version 4 RFC 792 Internet Control Message Protocol IP netmask request/reply header. The function takes arguments (see Table 3.21).

libnet_ptag_t libnet_build_icmpv4_timestamp(u_char type,
u_char code, u_short sum, u_short id, u_short seq, n_time
otime, n_time rtime, n_time ttime, u_char *payload, u_long
payload_s, libnet_t *1, libnet_ptag_t ptag);

libnet_build_icmpv4_timestamp() builds an IP version 4 RFC 792 Internet Control Message Protocol timestamp request/reply header. The function takes arguments (see Table 3.22).

libnet_ptag_t libnet_build_icmpv4_unreach(u_char type, u_char
code, u_short sum, u_short orig_len, u_char
orig_tos, u_short orig_id, u_short orig_frag, u_char orig_ttl, u_char
orig_prot, u_short orig_check, u_long orig_src, u_long
orig_dst, u_char *payload, u_long payload_s, libnet_t *1,
libnet_ptag_t ptag);

libnet_build_icmpv4_unreach() builds an IP version 4 RFC 792 Internet Control Message Protocol unreachable header. The function takes arguments (see Table 3.23). The additional arguments enable the application programmer to easily specify the original IP header values (the IP header of the packet that supposedly caused the ICMP unreachable message in the first place).

libnet_ptag_t libnet_build_icmpv4_timeexceed(u_char type,
u_char code, u_short sum, u_short orig_len, u_char orig_tos,
u_short orig_id, u_short orig_frag, u_char orig_ttl, u_char
orig_prot, u_short orig_check, u_long orig_src, u_long
orig_dst, u_char *payload, u_long payload_s, libnet_t *l,
libnet_ptag_t ptag);

libnet_build_icmpv4_timeexceed() builds an IP version 4 RFC 792 Internet Control Message Protocol time exceeded header. The function takes arguments (see Table 3.24). The additional arguments enable the application programmer to easily specify the original IP header values (the IP header of the packet that supposedly caused the ICMP time exceeded message in the first place).

libnet_ptag_t libnet_build_icmpv4_redirect(u_char type,
u_char code, u_short sum, u_long gateway, u_short orig_len,
u_char orig_tos, u_short orig_id, u_short orig_frag, u_char
orig_ttl, u_char orig_prot, u_short orig_check, u_long
orig_src, u_long orig_dst, u_char *payload, u_long payload_s,
libnet_t *1, libnet_ptag_t ptag);

libnet_build_icmpv4_redirect() builds an IP version 4 RFC 792 Internet Message Control Protocol redirect header. The function takes arguments (see Table 3.25). The additional arguments enable the application programmer to easily specify the original IP header values (the IP header of the packet that supposedly caused the ICMP redirect message in the first place).

libnet_ptag_t libnet_build_ipv4(u_short len, u_char tos,
u_short id, u_short frag, u_char ttl, u_char prot, u_short
sum, u_long src, u_long dst, u_char *payload, u_long
payload_s, libnet_t *1, libnet_ptag_t ptag);

libnet_build_ipv4() builds a version 4 RFC 791 Internet Protocol header. The function takes arguments (see Table 3.26). Table 3.27 summarizes the tos symbolic constants. Table 3.28 summarizes the frag symbolic constants.

The protocol field can be any upper-layer protocol number found in /etc/protocols on any modern UNIX system. For example, a TCP packet would have this field set to IPPROTO_TCP, and a UDP packet would have this field set to IPPROTO_UDP.

libnet_ptag_t libnet_autobuild_ipv4(u_short len, u_char prot,
u_long dst, libnet_t *1);

libnet_autobuild_ipv4() auto builds a version 4 Internet Protocol header. The function is useful to build an IP header quickly when you do not need a granular level of control. The function takes the same len, prot, and dst arguments (see Table 3.26). The function does not accept a ptag argument, but it does return a ptag. In other words, you can use it to build a new IP header but not to modify an existing one.

libnet_ptag_t libnet_build_ipv4_options(u_char *options,
u_long options_s, libnet_t *1, libnet_ptag_t ptag);

libnet_build_ipv4_options() builds an IP version 4 options header. The function takes arguments (see Table 3.29).

The function expects options to be a valid IP options string of size options_s, no larger than 40 bytes (the maximum size of an options string). The function checks to make sure that the preceding header is an IPv4 header and that the options string would not result in a packet larger than 65,535 bytes (IPMAXPACKET). The function counts up the number of 32-bit words in the options string and adjusts the IP header length value as necessary.

libnet_ptag_t libnet_build_ipv6(u_char tc, u_long fl, u_short
len, u_char nh, u_char hl, struct libnet_in6_addr src, struct
libnet_in6_addr dst, u_char *payload, u_long payload_s, libnet_t *l,
libnet_ptag_t ptag);

libnet_build_ipv6() builds a version 6 RFC 2460 Internet Protocol header. The function takes arguments (see Table 3.30).

libnet_ptag_t libnet_build_ntp(u_char leap_indicator, u_char
version, u_char mode, u_char stratum, u_char poll, u_char
precision, u_short delay_int, u_short delay_frac, u_short
dispersion_int, u_short dispersion_frac, u_long reference_id,
u_long ref_ts_int, u_long ref_ts_frac, u_long orig_ts_int,
u_long orig_ts_frac, u_long rec_ts_int, u_long rec_ts_frac,
u_long xmt_ts_int, u_long xmt_ts_frac, u_char *payload,
u_long payload_s, libnet_t *1, libnet_ptag_t ptag);

libnet_build_ntp() builds a Network Time Protocol header (RFCs 1119 and 1305). The function's massive argument list appears in Table 3.31.

Table 3.32 summarizes the leap_indicator symbolic constants.

Table 3.33 summarizes the version symbolic constants.

Table 3.34 summarizes the mode symbolic constants.

Table 3.35 summarizes the stratum symbolic constants. In addition to those listed, the NTP protocol specifies that stratum values from 0x2-0xf are considered secondary, and values from 0x10-0xff are reserved.

Table 3.36 summarizes the reference_id symbolic constants.