libnet10 - Man Page

The Network Library provides a simple API for commonly used low-level network functions (mainly packet injection).  Using libnet, it is easy to build and write arbitrary network packets.  It provides a portable framework for low-level network packet writing and handling (use libnet in conjunction with libpcap and you can write some really cool stuff).  Libnet includes packet creation at the IP layer and at the link layer as well as a host of supplementary and complementary functionality.

For a much more verbose treatment of libnet, including verbosely commented examples, please see the online web-based documentation at http://www.packetfactory.net/libnet/manual/.

#include <libnet.h>



PACKET MEMORY MANAGEMENT ROUTINES

int libnet_init_packet(size_t p_size, u_char **buf);

int libnet_destroy_packet(u_char **buf);

int libnet_init_packet_arena(struct libnet_arena **arena, int p_size,
        u_short p_num);
      
    u_char *libnet_next_packet_from_arena(struct libnet_arena **arena,
        int p_size);

int libnet_destroy_packet_arena(struct libnet_arena **arena);
 

ADDRESS RESOLUTION ROUTINES

u_char *libnet_host_lookup(u_long in, u_short use_name);

void libnet_host_lookup_r(u_long in, u_short use_name, u_char *buf);

u_long libnet_name_resolve(u_char *hostname, u_short use_name);

u_long libnet_get_ipaddr(struct libnet_link_int *l, const u_char *device,
        const u_char *buf);

struct ether_addr *libnet_get_hwaddr(struct libnet_link_int *l,
        const u_char *device, const u_char *buf);


PACKET INJECTION FRAMEWORK ROUTINES

int libnet_open_raw_sock(int protocol);

int libnet_close_raw_sock(int fd);

int libnet_select_device(struct sockaddr_in *sin, u_char **device,
        u_char *ebuf);

struct libnet_link_int *libnet_open_link_interface(char *device, char *ebuf);

int libnet_close_link_interface(struct libnet_link_int *l);

int libnet_write_ip(int sock, u_char *packet, int len);

int libnet_write_link_layer(struct libnet_link_int *l, const u_char *device,
         u_char *buf, int len);

int libnet_do_checksum(u_char *buf, int protocol, int len);

u_short libnet_ip_check(u_short *buf, int len);


PACKET BUILDER ROUTINES

int 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 *tha,
        u_char *tpa, const u_char *payload, int payload_s,
        u_char *buf);

int libnet_build_dns(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, const u_char *payload, int payload_s,
        u_char *buf);

int libnet_build_ethernet(u_char *daddr, u_char *saddr, u_short id,
        const u_char *payload, int payload_s, u_char *buf);

int libnet_build_icmp_echo(u_char type, u_char code, u_short id,
        u_short seq, const u_char *payload, int payload_s,
        u_char *buf);

int libnet_build_icmp_mask(u_char type, u_char code, u_short id,
        u_short seq, u_long mask, const u_char *payload,
        int payload_s, u_char *buf);

int libnet_build_icmp_unreach(u_char type, u_char code,
        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_long orig_src, u_long orig_dst, const u_char *orig_payload,
        int payload_s, u_char *buf);

int libnet_build_icmp_timeexceed(u_char type, u_char code,
        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_long orig_src, u_long orig_dst, const u_char *orig_payload,
        int payload_s, u_char *buf);

int libnet_build_icmp_redirect(u_char type, u_char code, 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_long orig_src, u_long orig_dst, const u_char *orig_payload,
        int payload_s, u_char *buf);

int libnet_build_icmp_timestamp(u_char type, u_char code, u_short id,
        u_short seq, n_time otime, n_time rtime, n_time ttime,
        const u_char *payload, int payload_s, u_char *buf);

int libnet_build_igmp(u_char type, u_char code, u_long ip, 
        const u_char *payload, int payload_s, u_char *buf);

int libnet_build_ip(u_short len, u_char tos, u_short id, u_short frag,
        u_char ttl, u_char prot, u_long saddr, u_long daddr,
        const u_char *payload, int payload_s, u_char *buf);

int libnet_build_ospf(u_short len, u_char type, u_long router_id,
        u_long area_id, u_short auth_type, const char *payload,
        int payload_s, u_char *buf);

int libnet_build_ospf_hello(u_long netmask, u_short interval,
        u_char options, u_char priority, u_int dead_interval,
        u_long des_router, u_long backup, u_long neighbor,
        const char *payload, int payload_s, u_char *buf);

int libnet_build_ospf_dbd(u_short len, u_char options, u_char type,
        u_int sequence_num, const char *payload, int payload_s,
        u_char *buf);  

int libnet_build_ospf_lsr(u_int type, u_int ls_id, u_long adv_router,
        const char *payload, int payload_s, u_char *buf);

int libnet_build_ospf_lsu(u_int num, const char *payload, int payload_s,
        u_char *buf);

int libnet_build_ospf_lsa(u_short age, u_char options, u_char type,
        u_int ls_id, u_long adv_router, u_int sequence_num,
        u_short len, const char *payload, int payload_s,
        u_char *buf); 

int libnet_build_ospf_lsa_rtr(u_short flags, u_short num, u_int id,
        u_int data, u_char type, u_char tos, u_short metric,
        const char *payload, int payload_s, u_char *buf);

int libnet_build_ospf_lsa_net(u_long netmask, u_int router_id,
        const char *payload, int payload_s, u_char *buf);

int libnet_build_ospf_lsa_sum(u_long netmask, u_int metric, u_int tos,
        const char *payload, int payload_s, u_char *buf); 

int libnet_build_ospf_lsa_as(u_long netmask, u_int metric,
        u_long fwd_addr, u_int tag, const char *payload,
        int payload_s, u_char *buf);

int libnet_build_rip(u_char command, u_char ver, u_short rd, u_short af,
        u_short rt, u_long addr, u_long mask, u_long next_hop,
        u_long metric, const u_char *payload, int payload_s,
        u_char *buf);

int libnet_build_tcp(u_short sport, u_short dport, u_long seq,
        u_long ack, u_char control, u_short win, u_short urg,
        const u_char *payload, int payload_s, u_char *buf);

int libnet_build_udp(u_short sport, u_short dport,
        const u_char *payload, int payload_s, u_char *buf);

int libnet_build_vrrp(u_char vrouter_id, u_char priority,
        u_char ip_count, u_char auth_type, u_char advert_int,
        const u_char *payload, int payload_s, u_char *buf);

int libnet_insert_ipo(struct ipoption *opt, u_char opt_len, u_char *buf);

int libnet_insert_tcpo(struct tcpoption *opt, u_char opt_len,
        u_char *buf);


MISCELLANEOUS SUPPORT ROUTINES

int libnet_seed_prand();

u_long libnet_get_prand(int type);

void libnet_hex_dump(u_char *buf, int len, int swap, FILE *stream);

int libnet_plist_chain_new(struct libnet_plist_chain **head,
        char *tok_list);

int libnet_plist_chain_next_pair(struct libnet_plist_chain *p,
        u_short *bport, u_short *eport);

int libnet_plist_chain_dump(struct libnet_plist_chain *p);

u_char *libnet_plist_chain_dump_string(struct libnet_plist_chain *p);

int libnet_plist_chain_free(struct libnet_plist_chain *p);

void libnet_error(int severity, char *msg, ...);


ASN.1 BER ROUTINES

u_char *libnet_build_asn1_int(u_char *data, int *datalen, u_char type,
        long *int_p, int int_s);

u_char *libnet_build_asn1_uint(u_char *data, int *datalen, u_char type,
        u_char *int_p, int int_s);

u_char *libnet_build_asn1_string(u_char *data, int *datalen, u_char type,
        u_long *string, int str_s);

u_char *libnet_build_asn1_header(u_char *data, int *datalen, u_char type,
        int len);

u_char *libnet_build_asn1_length(u_char *data, int *datalen, int len);

u_char *libnet_build_asn1_sequence(u_char *data, int *datalen,
        u_char type, int len);

u_char *libnet_build_asn1_objid(u_char *data, int *datalen, u_char type,
        oid *objid, int oid_s);

u_char *libnet_build_asn1_null(u_char *data, int *datalen, u_char type);

u_char *libnet_build_asn1_bitstring(u_char *data, int *datalen,
        u_char type, u_long *string, int str_s);

libnet_host_lookup() converts the supplied network-ordered (big-endian) IPv4 address into its human-readable coutnerpart.  If use_name is 1, libnet_host_lookup() will attempt to resolve this IP address and return a hostname, otherwise (or if the lookup fails), the function returns a dotted-decimal ASCII string.  This function is hopelessly non re-entrant as it uses static data.  Users concerned with re-entrancy should use libnet_host_lookup_r().

libnet_host_lookup_r() is the (planned) reentrant version of the above function.  As soon as reentrant network resolver libraries become available this function will likewise be reentrant.  An additional argument of a buffer to store the converted (or resolved) IPv4 address is supplied by the user.

libnet_name_resolve() takes a NULL terminated ASCII string representation of an IPv4 address (dots and decimals or canonical hostname if use_name is 1) and converts it into a network-ordered (big-endian) 4-byte value.

libnet_get_ipaddr() takes a pointer to a link layer interface struct, a pointer to the network device name, and an empty buffer to be used in case of error.  Upon success the function returns the IP address of the specified interface in host-byte order or 0 upon error (and errbuf will contain a reason).

libnet_get_hwaddr() takes a pointer to a link layer interface struct, a pointer to the network device name, and an empty buffer to be used in case of error.  The function returns the MAC address of the specified interface upon success or 0 upon error (and errbuf will contain a reason).

libnet_init_packet() initializes a packet for use.  If the size parameter is omitted (or negative) the library will pick a reasonable value for the user (currently LIBNET_MAX_PACKET).  If the memory allocation is successful, the memory is zeroed and the function returns 1.  If there is an error, the function returns -1.  Since this function calls malloc, you certainly should, at some point, make a corresponding call to destroy_packet().

libnet_destroy_packet() frees the memory associated with the packet.

libnet_init_packet_arena() allocates and initializes a memory pool.  If you plan on building and sending several different packets, this is a good choice.  It allocates a pool of memory from which you can grab chunks to build packets (see next_packet_from_arena() below).  It takes the address to an arena structure pointer (so it can modify the structure elements), and hints on the possible packet size and number of packets.  The last two arguments are used to compute the size of the memory pool.  The function returns -1 if the malloc fails or 1 if everything goes ok.

libnet_next_packet_from_arena() returns a chunk of memory from the arena of the requested size pool and decrements the available byte counter.  If the requested memory is not available from the arena, it returns NULL. Note that there is nothing preventing a poorly coded application from using more memory than requested and causing all kinds of problems.  Take heed.

libnet_destroy_packet_arena() frees the memory associated with the arena.

During packet or arena initilization and utilization, if 0 is passed for either of size values, the functions make a best guest.  If 0 is passed for the packet size, it adjusts it to be LIBNET_MAX_PACKET, and if 0 is passed for the packet number (in the case of libnet_init_packet_arena) it adjusts it to be 3.  Be aware that this is 196605 bytes of memory.

The number of bytes allocated may actually be slightly more than requested due to alignment constraints (values are aligned on a 4-byte boundry).

For the above three functions, it is a checked runtime error for arena to be a NULL pointer.

The arena interface also includes LIBNET_GET_ARENA_SIZE which returns the total size of an arena and LIBNET_GET_ARENA_REMAINING_BYTES which returns the remaining bytes of usable memory from an arena.

libnet_open_raw_sock() opens a raw IPv4 socket of the supplied protocol type and sets the IP_HDRINCL socket option.  Returned is the socket file descriptor or -1 on error.

libnet_close_raw_sock() closes an opened raw socket.  Returned is 1 upon success or -1 on error.

libnet_select_device() will run through the list of interfaces and select  one for use (ignoring the loopback device).  If device points to NULL, (don't pass in a NULL pointer, the function expects a pointer to a pointer, and C can't derefence a NULL pointer) it will try to fill it in with the first non-loopback device it finds, otherwise, it will try to open the specified device.  If successful, 1 is returned (and if device was NULL, it will now contain the device name which can be used in libnet_*link*() type calls). If an error occurs, -1 is returned and errbuf will contain a reason.  The errbuf should contain a pointer to a buffer at least as large as LIBNET_ERR_BUF.

libnet_open_link_interface() opens a low-level packet interface.  This is required to write link layer frames.  Supplied is a u_char pointer to the interface device name and a u_char pointer to an error buffer.  Returned is a filled in libnet_link_int struct or NULL on error.

libnet_close_link_interface() closes an opened low-level packet interface. Returned is 1 upon success or -1 on error.

libnet_write_ip() writes an IP packet to the network.  The first argument is the socket created with libnet_open_raw_sock(), the second is a pointer to a buffer containing a complete IP datagram, and the third argument is the total packet size.  It returns the number of bytes written.

libnet_write_link_layer() writes an link-layer frame to the network.  The first argument is a pointer to a filled in libnet_link_int structure, the next is a pointer to the network device, the next is the raw packet and the last is the packet size.  Returned is the number of bytes written or -1 on error.

libnet_do_checksum() calculates the checksum for the packet header.  The first argument is a pointer to the constructed IPv4 packet buffer.  The second is the transport protocol used and the third is the packet length (not including the IP header).  The function calculates the checksum for the transport protocol and fills it in at the appropriate header location.  This function should be called only after a complete packet has been built.  Note that when using raw sockets the IP checksum is always computed by the kernel, but when using link layer interfaces, the IP checksum must be explicitly computed. The function returns 1 upon success or -1 if an error occurs.

For all of the build_* functions, it is a checked runtime error for buf to be a NULL pointer (the function will return -1), but an unchecked error for the optional payload or the packet header itself to exceed the allocated memory.  Take heed.

libnet_build_arp() constructs an ARP (Address Resolution Protocol) packet.  Supplied are the following: hardware addresss type, protocol address type, the hardware addess length, the protocol address length, the ARP packet type, the sender hardware address, the sender protocol address, the target hardware address, the target protocol address, the packet payload, the payload size, and finally, a pointer to the packet header memory.  Note that this function only builds ethernet/IP ARP packets, and consequently the first value should be ARPHRD_ETHER.  The ARP packet type should be one of the following: ARPOP_REQUEST, ARPOP_REPLY, ARPOP_REVREQUEST, ARPOP_REVREPLY, ARPOP_INVREQUEST, or ARPOP_INVREPLY.

libnet_build_dns() constructs a DNS (Domain Name Service) packet.  Supplied are the following: DNS packet ID, flags, number of questions, number of answer resource records, number of authority resource records, number of additional resource records. All of the above are unsigned shorts.  All of the `interesting` fields of the header are variable in content and length, and therefore have to be included at the programmer's discretion.  We use the standard libnet payload and payload size interface for this.  Finally, please be sure to include a pointer to some preallocated memory.

libnet_build_ethernet() constructs an ethernet packet.  Supplied is the destination address, source address (as arrays of unsigned character bytes) and the ethernet frame type, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.  The ethernet packet type should be one of the following:

Value               Type
ETHERTYPE_PUP       PUP protocol
ETHERTYPE_IP        IP protocol
ETHERTYPE_ARP       ARP protocol
ETHERTYPE_REVARP    Reverse ARP protocol
ETHERTYPE_VLAN      IEEE VLAN tagging
ETHERTYPE_LOOPBACK  Used to test intefaces

Please note that some low-level interfaces (bpf in particular) do not allow for the spoofing of ethernet addresses without kernel modification.

The following functions construct ICMP (Internet Control Message Protocol) packets.

libnet_build_icmp_echo() builds an ICMP_ECHO / ICMP_ECHOREPLY packet. Supplied is a byte for the packet type, a byte for the code, an unsigned short for the packet id, an unsigned short for the packet sequence number, and a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.  The type should be ICMP_ECHOREPLY or ICMP_ECHO and the code should be 0.

libnet_build_icmp_mask() builds an ICMP_MASKREQ / ICMP_MASKREPLY packet. Supplied is a byte for the packet type, a byte for the code, an unsigned short for the packet id, an unsigned short for the packet sequence number, a 32-bit subnet mask, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet. The type should be ICMP_MASKREQ or ICMP_MASKREPLY and the code should be 0.

libnet_build_icmp_unreach() builds an ICMP_UNREACH packet.  Supplied is the normal ICMP stuff, a byte for the packet type and a byte for the code.  Next come the values for the IP header that caused the error that necessitated the unreachable.  The standard payload arguments to this function actually apply to the original IP packet and will be tacked on there.  The type should be ICMP_UNREACH and the code should be one of the following 16 different unreachable codes:

Code    Symbolic Name
0       ICMP_UNREACH_NET
1       ICMP_UNREACH_HOST
2       ICMP_UNREACH_PROTOCOL
3       ICMP_UNREACH_PORT
4       ICMP_UNREACH_NEEDFRAG
5       ICMP_UNREACH_SRCFAIL
6       ICMP_UNREACH_NET_UNKNOWN
7       ICMP_UNREACH_HOST_UNKNOWN
8       ICMP_UNREACH_ISOLATED
9       ICMP_UNREACH_NET_PROHIB
10      ICMP_UNREACH_HOST_PROHIB
11      ICMP_UNREACH_TOSNET
12      ICMP_UNREACH_TOSHOST
13      ICMP_UNREACH_FILTER_PROHIB
14      ICMP_UNREACH_HOST_PRECEDENCE
15      ICMP_UNREACH_PRECEDENCE_CUTOFF

libnet_build_icmp_timeexceed() builds an ICMP_TIMEXCEED packet.  Supplied is the normal ICMP stuff, a byte for the packet type and a byte for the code. Next come the values for the IP header that caused the error that necessitated the unreachable.  The standard payload arguments to this function actually apply to the original IP packet and will be tacked on there.  The type should be ICMP_REDIRECT and the code should be ICMP_TIMXCEED_INTRANS or ICMP_TIMXCEED_REASS.

libnet_build_icmp_redirect() builds an ICMP_REDIRECT packet.  Supplied is a byte for the packet type, a byte for the code, and the unsigned long IP address of the gateway that should be used.  Next come the values for the IP header that caused the error that necessitated the redirect. The standard payload arguments to this function actually apply to the original IP packet and will be tacked on there.  The type should be ICMP_REDIRECT and the code should be one of the following:

Code    Symbolic Name
0       ICMP_UNREACH_NET
1       ICMP_UNREACH_HOST
2       ICMP_UNREACH_PROTOCOL   (redirect for type of service and network)
3       ICMP_UNREACH_PORT       (redirect for type of service and host)

libnet_build_icmp_timestamp() builds an ICMP_TSTAMP / ICMP_TSTAMPREPLY packet.  Supplied is a byte for the packet type, a byte for the code, an unsigned short for the packet id, an unsigned short for the packet sequence number, the three timestamp values, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.  The type should be ICMP_TSTAMP or ICMP_TSTAMPREPLY and the code should be 0.

libnet_build_igmp() builds an IGMP (Internet Group Membership Protocol) packet.  Supplied is a byte for the packet type, a byte for the code, an unsigned long for the Class D address, and the other usual things.

libnet_build_ip() builds an IP (Internet Protocol) packet.  Supplied is the packet length (not including the IP header), the IP tos bits, the IP ID, the fragmentation flags and offset, the packet TTL, the transport protocol, the source and destination IP addresses (in network-byte order), a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.  To just build an IP header with no data payload, only IP_H bytes need to be allocated.  The payload and payload size arguments should not be used to build any of the supported transport protocol-type packets; for these transports, the relevant functions should be used.  The payload arguments should only be used to build an arbitrary IP packet with a payload.

libnet_build_ospf() builds a OSPF (Open Shortest Path First) packet.  You pass the packet length (not including the OSPF header), the packet type, 32-bit router ID, 32-bit area ID, the authentication type, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.  The payload should not be used to build the Hello, LSA, LSU, LSR, or DBD packets.  The following variables are to be used for the OSPF packet type:

       OSPF_UMD                UMd monitoring packet
       OSPF_HELLO              Hello packet
       OSPF_DBD                Database Desc. packet
       OSPF_LSR                Link State Request packet
       OSPF_LSU                Link State Update packet
       OSPF_LSA                Link State Ack. packet

The following are the possible authentication types:

       OSPF_AUTH_NULL          NULL password
       OSPF_AUTH_SIMPLE        plaintext, 8 char pass.
       OSPF_AUTH_MD5           MD5

The following is the structure used for the 64 bit field when using MD5:

       struct auth {
           u_short ospf_auth_null;  /* NULL 16 bits */
           u_char ospf_auth_keyid;  /* Key ID */
           u_char ospf_auth_len;    /* Auth data len */
           u_int ospf_auth_seq;     /* Sequence num */
       };

libnet_build_ospf_hello() builds an OSPF Hello packet.  You pass the netmask for the interface, the number of seconds since the last packet was sent, possible options, the router's priority (if 0, it can't be a backup router), the time (in seconds) until a router is deemed down, the networks designated router, the networks backup router, a neighbor, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory used for the packet.  If there are more than one neighbors that are to be included in the packet, just allocate enough space for the packet buf, and pass the neighbors as the "optional data payload."

libnet_build_ospf_dbd() builds an OSPF DataBase Description (DBD) packet. You pass the maximum length of an IP packet the interface can use, packet options, the type of exchange occuring, a sequence number, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.  The following can be used for the type variable:

       DBD_IBIT                Init bit
       DBD_MBIT                More DBD packets to come
       DBD_MSBIT               sender is the master

libnet_build_ospf_lsr() builds an OSPF Link State Request (LSR) packet. You pass the type of link state packet being requested, the link state ID, the advertising router, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.  See the libnet_build_ospf_lsa() section for more information regarding variables.

libnet_build_ospf_lsu() builds an OSPF Link State Update (LSU) packet. You pass the number of Link State Acknowledgment (LSA) packets that will be in the packet, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.

libnet_build_ospf_lsa() builds an OSPF Link State Acknowledgement (LSA) packet.  You pass the link state age, packet options, type of LSA, the link state ID, the advertising router, the packet's sequence number, the length of the packet (_not_ including the LSA header length), a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.  The following variables can be used for the type of LSA:

       LS_TYPE_RTR             Router LSA
       LS_TYPE_NET             Network LSA
       LS_TYPE_IP              Summary LSA (IP Network)
       LS_TYPE_ASBR            Summary LSA (ASBR)
       LS_TYPE_ASEXT           AS-External LSA

libnet_build_ospf_lsa_rtr() builds an OSPF Link State Router packet. You pass the optional packet flags, the number of links within that packet, the link ID (helps describe the next variable), the info for the specified link ID, the type of router link, the number of TOS metrics for this link, the metric (the cost of using the link), a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.  The possible flags (not including 0x00) are as follows:

       RTR_FLAGS_W             W bit
       RTR_FLAGS_E             E bit
       RTR_FLAGS_B             B bit
The possible link ID's are as follows:

       LINK_ID_NBR_ID          Neighbors router ID
       LINK_ID_IP_DES          IP addr of router
       LINK_ID_SUB             IP subnet number

The possible values for the router type are as follows:

       RTR_TYPE_PTP            Point-to-point
       RTR_TYPE_TRANS          Connection to a "transit network"
       RTR_TYPE_STUB           Connection to a "stub network"
       RTR_TYPE_VRTL           Connection to a "virtual link"

libnet_build_ospf_lsa_net() builds an OSPF Link Sate Network packet. You pass the interface's netmask, the router ID, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.

libnet_build_ospf_lsa_sum() builds an OSPF Link State Summary packet. You pass the interface's netmask, the cost of using the link (metric), the TOS and metric, which is passed as a unsigned integer but the first 8 bits are the TOS and the last 24 bits are the TOS metric, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.

libnet_buils_ospf_lsa_as() builds an OSPF Link State AS External packet. You pass the interface's netmask, the cost of using the link (metric), the forwarding address, the external route tag, a pointer to an optional data payload, the payload length, and a pointer to a pre-allocated block of memory for the packet.  In reality, the metric only uses the last 24 bits of the unsigned int.  The first 8bits are reserved for a possible bit to be set (the E bit, see above for more info).  The variable AS_E_BIT_ON can be used logically to set the E bit on.

LIBNET_OSPF_AUTHCPY() simply copies, byte for byte, your authentication buf to the pre-allocated block of memory for your packet.

Random variables:

       IPPROTO_OSPF            89
       OSPFVERSION             2

Header Lengths:

       OSPF_H                  OSPF header
       HELLO_H                 Hello header
       DBD_H                   DBD header
       LSR_H                   LSR header
       LSU_H                   LSU header
       LSA_H                   LSA header
       LS_RTR_LEN              LS-Router header
       LS_NET_LEN              LS-Network header
       LS_SUM_LEN              LS-Summary header
       LS_AS_EXT_LEN           LS-AS External header

Packet options:

       OPT_EBIT        AS-external-LSAs are flooded
       OPT_MCBIT       IP multicast dgrams are forwarded
       OPT_NPBIT       Handles type-7 LSAs
       OPT_EABIT       Sends/recv's AS-external LSAs
       OPT_DCBIT       Handles demand circuits

libnet_build_rip() constructs a RIP (Routing Information Protocol) packet.  The values supplied depend on the version of the RIP packet you desire to build.  The following table applies:

Passing Order   Datatype    RIP v1          RIPv2
first           byte        command         command
second          byte        version         version
third           ushort      zero            routing domain  
fourth          ushort      address family  address family
fifth           ushort      zero            route tag
sixth           ulong       IP address      IP address
seventh         ulong       zero            subnet mask
eighth          ulong       zero            next hop IP
ninth           ulong       metric          metric
tenth           const u_char *      Packet payload
eleventh        int                 Packet payload size
twelfth         u_char *            Packet header memory

The command should be one of the following: RIPCMD_REQUEST, RIPCMD_RESPONSE, RIPCMD_TRACEON, RIPCMD_TRACEOFF, RIPCMD_POLL, RIPCMD_POLLENTRY, or RIPCMD_MAX.  The version should be RIPVER_1 or RIPVER_2.

libnet_build_tcp() builds a TCP (Transmission Control Protocol) packet.  Supplied is the source port, destination port, the sequence and acknowledgement numbers, the control bits (which can be logically OR'd together to set multiple flags -- see the example below), the advertised window size, the urgent pointer, a pointer to an optional data payload, the payload size, and lastly, the pointer to a pre-allocated block of memory for the packet.  To just build a TCP header with no data payload, only TCP_H bytes need be allocated.

libnet_build_udp() builds a UDP (User Datagram Protocol) packet.  Supplied is the source port, the destination port, a pointer to an optional data payload, the payload size, and lastly, a pointer to a pre-allocated block of memory for the packet. To just build a UDP header with no data payload, only UDP_H bytes need to be allocated.

libnet_vuild_vrrp() builds a VRRP (Virtual Router Redundancy Protocol) packet.  Supplied is the virtual router ID, the priority, the number of IP addresses in the packet, the authorization type (LIBNET_VRRP_AUTH_NONE, LIBNET_VRRP_AUTH_PASSWD, or LIBNET_VRRP_AUTH_IPAH), the adverstisment interval, a pointer to an optional data payload, the payload size, and lastly, a pointer to a pre-allocated block of memory for the packet.

libnet_insert_ipo() inserts IP options into an already created IP packet. Supplied is a pointer to an ip option struct (which must be filled in by the user), the size of the options list, and a pointer the completed packet.  The function returns -1 if the options would make the packet too large (greater then 65535 bytes) or 1 otherwise.  It is an unchecked runtime error for the user to have not allocated enough heap memory for the packet + options.

libnet_insert_tcpo() inserts TCP options into an already created IP packet.  Replace the pointer to an IP option struct with one to a TCP option struct and this function is exactly the same as above.

libnet_seed_prand() seeds the psuedorandom number generator.  Returns 1 on success, -1 on failure.

libnet_get_prand() returns a positive psuedorandom integer of the specified type.  Expects type to be one of five symbolics PR2, PR8, PR16, PRu16, PR32 or PRu32.  PR2 returns a one or a zero, PR8 returns a byte, PR16 returns up to a signed short (from 0 to 32767), PRu16 returns an unsigned short (from 0 to 65535), PR32 returns a signed long (from 0 to 2147483647) and PRu32 returns an unsigned long number (from 0 to 4294967295).

libnet_hex_dump() prints a packet out in hex.  Supplied is the packet and its length, a swap flag, and a pointer to a previously opened stream.  The swap flag (1 or 0) specifies whether or not to print the packet as it appears in memory (0) or to swap the bytes into host order (1).

libnet_plist_chain_new() builds a new libnet port list chain.  A libnet port list chain is a fast and simple way of implementing port list ranges (useful for applications that employ a list of ports like a port scanner). You'll see naive implementations that allocate an entire array of 65535 bytes and fill in the desired ports one by one.  However, we only really need to store the beginning port and the ending port, and we can efficiently store multiple port ranges (delimated by commas) by using a linked list chain with each node holding the beginning and ending port for a particular range.  For example, The port range `1-1024` would occupy one node with the bport being 1 and the eport being 1024.  The port range `25,110-161,6000` would result in 3 nodes being allocated.  Single ports are taken as single ranges (port 25 ends up being 25-25).  A port list range without a terminating port  (port_num - ) is considered shorthand for (port_num - 65535). The arguments are a pointer to libnet_plist_chain pointer (which will end up being the head of the linked list) and pointer to the port list itself. The function checks this character port list for valid tokens (1234567890,- ) and returns an error if an unrecognized token is found.  Upon success the function returns 1, and head points to the newly formed port list (and also contains the number of nodes in the list.  If an error occurs (an unrecognized token is found or malloc fails) -1 is returned and head is set to NULL. libnet_plist_chain_next_pair() should be used to extract port list pairs.

libnet_plist_chain_next_pair() fetchs the next pair of ports from the list.  The function takes a pointer to the head of the prebuilt list and a pointer to a u_short that will contain the beginning port and a pointer to a u_short that will contain the ending port.  The function returns 1 and fills in these values if there are nodes remaining, or if the port list chain is exhausted, it returns 0.

libnet_plist_chain_dump() prints the list (as lists of integers).

libnet_plist_chain_dump_string() returns a string containing the port list chain.

libnet_plist_chain_free() frees the entire list.

libnet_error() dumps an error message to stderr.  Included is the severity of the message (LIBNET_ERR_WARNING, LIBNET_ERR_CRITICAL, or LIBNET_ERR_FATAL) and the message string itself.  If the severity is LIBNET_ERR_FATAL, the function will exit the program.  This is the only defined exit point in the whole library.

libnet_build_asn1_int()

libnet_build_asn1_uint()

libnet_build_asn1_string()

libnet_build_asn1_header()

libnet_build_asn1_length()

libnet_build_asn1_sequence()

libnet_build_asn1_objid()

libnet_build_asn1_null()

libnet_build_asn1_bitstring()

To make your life and code cleaner, libnet defines symbolic constants to make your life easier.

Default packet header sizes:

LIBNET_ARP_H               ARP
LIBNET_DNS_H               DNS
LIBNET_ETH_H               ethernet
LIBNET_ICMP_H              ICMP header (base)
LIBNET_ICMP_ECHO_H         ICMP_ECHO / ICMP_ECHOREPLY
LIBNET_ICMP_MASK_H         ICMP_MASKREQ / ICMP_MASKREPLY
LIBNET_ICMP_UNREACH_H      ICMP_UNREACHABLE (base)
LIBNET_ICMP_REDIRECT_H     ICMP_REDIRECT (base)
LIBNET_ICMP_TS_H           ICMP_TSTAMP (base)
LIBNET_ICMP_TIMXCEED_H     ICMP_TIMXCEED (base)
LIBNET_IGMP_H              IGMP
LIBNET_IP_H                IP
LIBNET_RIP_H               RIP
LIBNET_TCP_H               TCP
LIBNET_UDP_H               UDP
LIBNET_VRRP_H              VRRP (base)

Standard memory sizes for packets:

LIBNET_PACKET              Standard packet size (IP_H + TCP_H)
LIBNET_OPTS                Maximum IP options list
LIBNET_MAX_PACKET          Maximum IPv4 packet size

Other constants you should know about:

IP Type Of Service constants:

IPTOS_LOWDELAY      Minimize delay
IPTOS_THROUGHPUT    Maximize throughput
IPTOS_RELIABILITY   Maximize reliability
IPTOS_MINCOST       Minimize monetary cost

IP Fragmentation flags:

IP_DF               Don't fragment this datagram
IP_MF               More fragments en route

TCP control bits:

TH_URG              Urgent flag
TH_ACK              Acknowledgement field valid
TH_PUSH             Push this data to application layer
TH_RST              Reset the referenced connection
TH_SYN              Synchronize connection state
TH_FIN              Finished sending data

To properly compile your applications under libnet, you should use the  `libnet-config` script.  This script is created during the GNU configure process will ensure that future compilations linked against libnet contain the correct CPP and CFLAG options as well as additional libraries for the targeted architecture.  To invoke it simply:

   gcc `libnet-config --defines --cflags` foo.c -o foo `libnet-config --libs`

The script handles all libnet dependencies and concessions for the architecture it was compiled on.

pcap(3), bpf(4), dlpi(7P)

Mike D. Schiffman <mike@infonexus.com> See the online web reference manual for additional contributers.

The current version is always available:

Solaris raw sockets are cooked.  They do not allow one to set the ip_len, ip_frag or the ip_id (including IP options at the raw socket layer doesn't work either). To work around this, use the link-layer API instead of raw socket functions.

The Berkeley Packet Filter alone does not allow for the arbitrary specification of source ethernet addresses.  This is not so much a bug as an oversight in the protocol.  Included with the distribution is lkm code to work around this (FreeBSD has support for an ioctl that works around this).

The OSPF functionality has not been extensively tested as yet and is considered to be in beta release.

Please send bug reports to mike@infonexus.com.

libnet10-config(1).