2 .\" $Id: libnet.3,v 1.1.1.1 2000/05/25 00:28:49 route Exp $
4 .\" Copyright (c) 1998 - 2001 Mike D. Schiffman <mike@infonexus.com>
7 .TH LIBNET 3 "01 17 2001" "libnet 1.0.2" ""
9 libnet \- "libpwrite" Network Routine Library
12 The Network Library provides a simple API for commonly used low-level network
13 functions (mainly packet injection). Using libnet, it is easy to build and
14 write arbitrary network packets. It provides a portable framework for
15 low-level network packet writing and handling (use libnet in conjunction
16 with libpcap and you can write some really cool stuff). Libnet includes
17 packet creation at the IP layer and at the link layer as well as a host of
18 supplementary and complementary functionality.
20 For a much more verbose treatment of libnet, including verbosely commented
21 examples, please see the online web-based documentation at
22 http://www.packetfactory.net/libnet/manual/.
33 PACKET MEMORY MANAGEMENT ROUTINES
35 int libnet_init_packet(size_t p_size, u_char **buf);
37 int libnet_destroy_packet(u_char **buf);
39 int libnet_init_packet_arena(struct libnet_arena **arena, int p_size,
43 u_char *libnet_next_packet_from_arena(struct libnet_arena **arena,
47 int libnet_destroy_packet_arena(struct libnet_arena **arena);
50 ADDRESS RESOLUTION ROUTINES
52 u_char *libnet_host_lookup(u_long in, u_short use_name);
54 void libnet_host_lookup_r(u_long in, u_short use_name, u_char *buf);
56 u_long libnet_name_resolve(u_char *hostname, u_short use_name);
58 u_long libnet_get_ipaddr(struct libnet_link_int *l, const u_char *device,
62 struct ether_addr *libnet_get_hwaddr(struct libnet_link_int *l,
64 const u_char *device, const u_char *buf);
67 PACKET INJECTION FRAMEWORK ROUTINES
69 int libnet_open_raw_sock(int protocol);
71 int libnet_close_raw_sock(int fd);
73 int libnet_select_device(struct sockaddr_in *sin, u_char **device,
77 struct libnet_link_int *libnet_open_link_interface(char *device, char *ebuf);
79 int libnet_close_link_interface(struct libnet_link_int *l);
81 int libnet_write_ip(int sock, u_char *packet, int len);
83 int libnet_write_link_layer(struct libnet_link_int *l, const u_char *device,
85 u_char *buf, int len);
87 int libnet_do_checksum(u_char *buf, int protocol, int len);
89 u_short libnet_ip_check(u_short *buf, int len);
92 PACKET BUILDER ROUTINES
94 int libnet_build_arp(u_short hrd, u_short pro, u_short hln, u_short pln,
96 u_short op, u_char *sha, u_char *spa, u_char *tha,
98 u_char *tpa, const u_char *payload, int payload_s,
102 int libnet_build_dns(u_short id, u_short flags, u_short num_q,
104 u_short num_anws_rr, u_short num_auth_rr,
106 u_short num_addi_rr, const u_char *payload, int payload_s,
110 int libnet_build_ethernet(u_char *daddr, u_char *saddr, u_short id,
112 const u_char *payload, int payload_s, u_char *buf);
114 int libnet_build_icmp_echo(u_char type, u_char code, u_short id,
116 u_short seq, const u_char *payload, int payload_s,
120 int libnet_build_icmp_mask(u_char type, u_char code, u_short id,
122 u_short seq, u_long mask, const u_char *payload,
124 int payload_s, u_char *buf);
126 int libnet_build_icmp_unreach(u_char type, u_char code,
128 u_short orig_len, u_char orig_tos, u_short orig_id,
130 u_short orig_frag, u_char orig_ttl, u_char orig_prot,
132 u_long orig_src, u_long orig_dst, const u_char *orig_payload,
134 int payload_s, u_char *buf);
136 int libnet_build_icmp_timeexceed(u_char type, u_char code,
138 u_short orig_len, u_char orig_tos, u_short orig_id,
140 u_short orig_frag, u_char orig_ttl, u_char orig_prot,
142 u_long orig_src, u_long orig_dst, const u_char *orig_payload,
144 int payload_s, u_char *buf);
146 int libnet_build_icmp_redirect(u_char type, u_char code, u_long gateway
148 u_short orig_len, u_char orig_tos, u_short orig_id,
150 u_short orig_frag, u_char orig_ttl, u_char orig_prot,
152 u_long orig_src, u_long orig_dst, const u_char *orig_payload,
154 int payload_s, u_char *buf);
156 int libnet_build_icmp_timestamp(u_char type, u_char code, u_short id,
158 u_short seq, n_time otime, n_time rtime, n_time ttime,
160 const u_char *payload, int payload_s, u_char *buf);
162 int libnet_build_igmp(u_char type, u_char code, u_long ip,
164 const u_char *payload, int payload_s, u_char *buf);
166 int libnet_build_ip(u_short len, u_char tos, u_short id, u_short frag,
168 u_char ttl, u_char prot, u_long saddr, u_long daddr,
170 const u_char *payload, int payload_s, u_char *buf);
172 int libnet_build_ospf(u_short len, u_char type, u_long router_id,
174 u_long area_id, u_short auth_type, const char *payload,
176 int payload_s, u_char *buf);
178 int libnet_build_ospf_hello(u_long netmask, u_short interval,
180 u_char options, u_char priority, u_int dead_interval,
182 u_long des_router, u_long backup, u_long neighbor,
184 const char *payload, int payload_s, u_char *buf);
186 int libnet_build_ospf_dbd(u_short len, u_char options, u_char type,
188 u_int sequence_num, const char *payload, int payload_s,
192 int libnet_build_ospf_lsr(u_int type, u_int ls_id, u_long adv_router,
194 const char *payload, int payload_s, u_char *buf);
196 int libnet_build_ospf_lsu(u_int num, const char *payload, int payload_s,
200 int libnet_build_ospf_lsa(u_short age, u_char options, u_char type,
202 u_int ls_id, u_long adv_router, u_int sequence_num,
204 u_short len, const char *payload, int payload_s,
208 int libnet_build_ospf_lsa_rtr(u_short flags, u_short num, u_int id,
210 u_int data, u_char type, u_char tos, u_short metric,
212 const char *payload, int payload_s, u_char *buf);
214 int libnet_build_ospf_lsa_net(u_long netmask, u_int router_id,
216 const char *payload, int payload_s, u_char *buf);
218 int libnet_build_ospf_lsa_sum(u_long netmask, u_int metric, u_int tos,
220 const char *payload, int payload_s, u_char *buf);
222 int libnet_build_ospf_lsa_as(u_long netmask, u_int metric,
224 u_long fwd_addr, u_int tag, const char *payload,
226 int payload_s, u_char *buf);
228 int libnet_build_rip(u_char command, u_char ver, u_short rd, u_short af,
230 u_short rt, u_long addr, u_long mask, u_long next_hop,
232 u_long metric, const u_char *payload, int payload_s,
236 int libnet_build_tcp(u_short sport, u_short dport, u_long seq,
238 u_long ack, u_char control, u_short win, u_short urg,
240 const u_char *payload, int payload_s, u_char *buf);
242 int libnet_build_udp(u_short sport, u_short dport,
244 const u_char *payload, int payload_s, u_char *buf);
246 int libnet_build_vrrp(u_char vrouter_id, u_char priority,
248 u_char ip_count, u_char auth_type, u_char advert_int,
250 const u_char *payload, int payload_s, u_char *buf);
252 int libnet_insert_ipo(struct ipoption *opt, u_char opt_len, u_char *buf);
254 int libnet_insert_tcpo(struct tcpoption *opt, u_char opt_len,
259 MISCELLANEOUS SUPPORT ROUTINES
261 int libnet_seed_prand();
263 u_long libnet_get_prand(int type);
265 void libnet_hex_dump(u_char *buf, int len, int swap, FILE *stream);
267 int libnet_plist_chain_new(struct libnet_plist_chain **head,
271 int libnet_plist_chain_next_pair(struct libnet_plist_chain *p,
273 u_short *bport, u_short *eport);
275 int libnet_plist_chain_dump(struct libnet_plist_chain *p);
277 u_char *libnet_plist_chain_dump_string(struct libnet_plist_chain *p);
279 int libnet_plist_chain_free(struct libnet_plist_chain *p);
281 void libnet_error(int severity, char *msg, ...);
286 u_char *libnet_build_asn1_int(u_char *data, int *datalen, u_char type,
288 long *int_p, int int_s);
290 u_char *libnet_build_asn1_uint(u_char *data, int *datalen, u_char type,
292 u_char *int_p, int int_s);
294 u_char *libnet_build_asn1_string(u_char *data, int *datalen, u_char type,
296 u_long *string, int str_s);
298 u_char *libnet_build_asn1_header(u_char *data, int *datalen, u_char type,
302 u_char *libnet_build_asn1_length(u_char *data, int *datalen, int len);
304 u_char *libnet_build_asn1_sequence(u_char *data, int *datalen,
306 u_char type, int len);
308 u_char *libnet_build_asn1_objid(u_char *data, int *datalen, u_char type,
310 oid *objid, int oid_s);
312 u_char *libnet_build_asn1_null(u_char *data, int *datalen, u_char type);
314 u_char *libnet_build_asn1_bitstring(u_char *data, int *datalen,
316 u_char type, u_long *string, int str_s);
321 .SH ADDRESS RESOLUTION ROUTINES
322 \fBlibnet_host_lookup()\fP converts the supplied network-ordered (big-endian)
323 IPv4 address into its human-readable coutnerpart. If use_name is 1,
324 \fBlibnet_host_lookup()\fP will attempt to resolve this IP address and return a
325 hostname, otherwise (or if the lookup fails), the function returns a
326 dotted-decimal ASCII string. This function is hopelessly non re-entrant
327 as it uses static data. Users concerned with re-entrancy should use
328 \fBlibnet_host_lookup_r()\fP.
330 \fBlibnet_host_lookup_r()\fP is the (planned) reentrant version of the above
331 function. As soon as reentrant network resolver libraries become available
332 this function will likewise be reentrant. An additional argument of a buffer
333 to store the converted (or resolved) IPv4 address is supplied by the user.
335 \fBlibnet_name_resolve()\fP takes a NULL terminated ASCII string representation
336 of an IPv4 address (dots and decimals or canonical hostname if use_name is
337 1) and converts it into a network-ordered (big-endian) 4-byte value.
339 \fBlibnet_get_ipaddr()\fP takes a pointer to a link layer interface struct, a
340 pointer to the network device name, and an empty buffer to be used in case
341 of error. Upon success the function returns the IP address of the
342 specified interface in host-byte order or 0 upon error (and errbuf will
345 \fBlibnet_get_hwaddr()\fP takes a pointer to a link layer interface struct, a
346 pointer to the network device name, and an empty buffer to be used in case
347 of error. The function returns the MAC address of the specified interface
348 upon success or 0 upon error (and errbuf will contain a reason).
350 .SH PACKET MEMORY MANAGEMENT ROUTINES
351 \fBlibnet_init_packet()\fP initializes a packet for use. If the size
352 parameter is omitted (or negative) the library will pick a reasonable
353 value for the user (currently LIBNET_MAX_PACKET). If the memory allocation is
354 successful, the memory is zeroed and the function returns 1. If there is
355 an error, the function returns -1. Since this function calls malloc, you
356 certainly should, at some point, make a corresponding call to destroy_packet().
358 \fBlibnet_destroy_packet()\fP frees the memory associated with the packet.
360 \fBlibnet_init_packet_arena()\fP allocates and initializes a memory pool. If
361 you plan on building and sending several different packets, this is a good
362 choice. It allocates a pool of memory from which you can grab chunks to
363 build packets (see next_packet_from_arena() below). It takes the address
364 to an arena structure pointer (so it can modify the structure elements),
365 and hints on the possible packet size and number of packets. The last two
366 arguments are used to compute the size of the memory pool. The function
367 returns -1 if the malloc fails or 1 if everything goes ok.
369 \fBlibnet_next_packet_from_arena()\fP returns a chunk of memory from the arena
370 of the requested size pool and decrements the available byte counter. If
371 the requested memory is not available from the arena, it returns NULL.
372 Note that there is nothing preventing a poorly coded application from using
373 more memory than requested and causing all kinds of problems. Take heed.
375 \fBlibnet_destroy_packet_arena()\fP frees the memory associated with the arena.
377 During packet or arena initilization and utilization, if 0 is passed for
378 either of size values, the functions make a best guest. If 0 is passed
379 for the packet size, it adjusts it to be LIBNET_MAX_PACKET, and if 0 is
380 passed for the packet number (in the case of libnet_init_packet_arena) it
381 adjusts it to be 3. Be aware that this is 196605 bytes of memory.
383 The number of bytes allocated may actually be slightly more than requested
384 due to alignment constraints (values are aligned on a 4-byte boundry).
386 For the above three functions, it is a checked runtime error for arena to
389 The arena interface also includes LIBNET_GET_ARENA_SIZE which returns the total
390 size of an arena and LIBNET_GET_ARENA_REMAINING_BYTES which returns the
391 remaining bytes of usable memory from an arena.
393 .SH PACKET INJECTION FRAMEWORK ROUTINES
394 \fBlibnet_open_raw_sock()\fP opens a raw IPv4 socket of the supplied protocol
395 type and sets the IP_HDRINCL socket option. Returned is the socket file
396 descriptor or -1 on error.
398 \fBlibnet_close_raw_sock()\fP closes an opened raw socket. Returned is 1
399 upon success or -1 on error.
401 \fBlibnet_select_device()\fP will run through the list of interfaces and select
402 one for use (ignoring the loopback device). If device points to NULL, (don't
403 pass in a NULL pointer, the function expects a pointer to a pointer, and
404 C can't derefence a NULL pointer) it will try to fill it in with the first
405 non-loopback device it finds, otherwise, it will try to open the specified
406 device. If successful, 1 is returned (and if device was NULL, it will now
407 contain the device name which can be used in libnet_*link*() type calls).
408 If an error occurs, -1 is returned and errbuf will contain a reason. The
409 errbuf should contain a pointer to a buffer at least as large as LIBNET_ERR_BUF.
411 \fBlibnet_open_link_interface()\fP opens a low-level packet interface. This is
412 required to write link layer frames. Supplied is a u_char pointer to the
413 interface device name and a u_char pointer to an error buffer. Returned is
414 a filled in libnet_link_int struct or NULL on error.
416 \fBlibnet_close_link_interface()\fP closes an opened low-level packet interface.
417 Returned is 1 upon success or -1 on error.
419 \fBlibnet_write_ip()\fP writes an IP packet to the network. The first
420 argument is the socket created with \fBlibnet_open_raw_sock()\fP, the second
421 is a pointer to a buffer containing a complete IP datagram, and the third
422 argument is the total packet size. It returns the number of bytes written.
424 \fBlibnet_write_link_layer()\fP writes an link-layer frame to the network. The
425 first argument is a pointer to a filled in libnet_link_int structure, the next
426 is a pointer to the network device, the next is the raw packet and the last
427 is the packet size. Returned is the number of bytes written or -1 on error.
429 \fBlibnet_do_checksum()\fP calculates the checksum for the packet header. The
430 first argument is a pointer to the constructed IPv4 packet buffer. The second
431 is the transport protocol used and the third is the packet length (not including
432 the IP header). The function calculates the checksum for the transport
433 protocol and fills it in at the appropriate header location. This function
434 should be called only after a complete packet has been built. Note that when
435 using raw sockets the IP checksum is always computed by the kernel, but when
436 using link layer interfaces, the IP checksum must be explicitly computed.
437 The function returns 1 upon success or -1 if an error occurs.
439 .SH PACKET BUILDER ROUTINES
440 For all of the build_* functions, it is a checked runtime error for buf
441 to be a NULL pointer (the function will return -1), but an unchecked error
442 for the optional payload or the packet header itself to exceed the allocated
445 \fBlibnet_build_arp()\fP constructs an ARP (Address Resolution Protocol) packet. Supplied are the following:
446 hardware addresss type, protocol address type, the hardware addess length,
447 the protocol address length, the ARP packet type, the sender hardware
448 address, the sender protocol address, the target hardware address, the target
449 protocol address, the packet payload, the payload size, and finally, a pointer
450 to the packet header memory. Note that this function only builds ethernet/IP
451 ARP packets, and consequently the first value should be ARPHRD_ETHER. The
452 ARP packet type should be one of the following: ARPOP_REQUEST, ARPOP_REPLY,
453 ARPOP_REVREQUEST, ARPOP_REVREPLY, ARPOP_INVREQUEST, or ARPOP_INVREPLY.
455 \fBlibnet_build_dns()\fP constructs a DNS (Domain Name Service) packet. Supplied are the following:
456 DNS packet ID, flags, number of questions, number of answer resource records,
457 number of authority resource records, number of additional resource records.
458 All of the above are unsigned shorts. All of the `interesting` fields of the
459 header are variable in content and length, and therefore have to be included
460 at the programmer's discretion. We use the standard libnet payload and
461 payload size interface for this. Finally, please be sure to include a pointer
462 to some preallocated memory.
464 \fBlibnet_build_ethernet()\fP constructs an ethernet packet. Supplied is the
465 destination address, source address (as arrays of unsigned character bytes)
466 and the ethernet frame type, a pointer to an optional data payload, the
467 payload length, and a pointer to a pre-allocated block of memory for the
468 packet. The ethernet packet type should be one of the following:
472 ETHERTYPE_PUP PUP protocol
474 ETHERTYPE_IP IP protocol
476 ETHERTYPE_ARP ARP protocol
478 ETHERTYPE_REVARP Reverse ARP protocol
480 ETHERTYPE_VLAN IEEE VLAN tagging
482 ETHERTYPE_LOOPBACK Used to test intefaces
484 Please note that some low-level interfaces (bpf in particular) do
485 not allow for the spoofing of ethernet addresses without kernel modification.
487 The following functions construct ICMP (Internet Control Message Protocol) packets.
489 \fBlibnet_build_icmp_echo()\fP builds an ICMP_ECHO / ICMP_ECHOREPLY packet.
490 Supplied is a byte for the packet type, a byte for the code, an unsigned
491 short for the packet id, an unsigned short for the packet sequence number,
492 and a pointer to an optional data payload, the payload length, and a pointer
493 to a pre-allocated block of memory for the packet. The type should be
494 ICMP_ECHOREPLY or ICMP_ECHO and the code should be 0.
496 \fBlibnet_build_icmp_mask()\fP builds an ICMP_MASKREQ / ICMP_MASKREPLY packet.
497 Supplied is a byte for the packet type, a byte for the code, an unsigned
498 short for the packet id, an unsigned short for the packet sequence number,
499 a 32-bit subnet mask, a pointer to an optional data payload, the payload
500 length, and a pointer to a pre-allocated block of memory for the packet.
501 The type should be ICMP_MASKREQ or ICMP_MASKREPLY and the code should be 0.
503 \fBlibnet_build_icmp_unreach()\fP builds an ICMP_UNREACH packet. Supplied is
504 the normal ICMP stuff, a byte for the packet type and a byte for the code. Next
505 come the values for the IP header that caused the error that necessitated the
506 unreachable. The standard payload arguments to this function actually apply
507 to the original IP packet and will be tacked on there. The type should be
508 ICMP_UNREACH and the code should be one of the following 16 different
517 2 ICMP_UNREACH_PROTOCOL
521 4 ICMP_UNREACH_NEEDFRAG
523 5 ICMP_UNREACH_SRCFAIL
525 6 ICMP_UNREACH_NET_UNKNOWN
527 7 ICMP_UNREACH_HOST_UNKNOWN
529 8 ICMP_UNREACH_ISOLATED
531 9 ICMP_UNREACH_NET_PROHIB
533 10 ICMP_UNREACH_HOST_PROHIB
535 11 ICMP_UNREACH_TOSNET
537 12 ICMP_UNREACH_TOSHOST
539 13 ICMP_UNREACH_FILTER_PROHIB
541 14 ICMP_UNREACH_HOST_PRECEDENCE
543 15 ICMP_UNREACH_PRECEDENCE_CUTOFF
546 \fBlibnet_build_icmp_timeexceed()\fP builds an ICMP_TIMEXCEED packet. Supplied
547 is the normal ICMP stuff, a byte for the packet type and a byte for the code.
548 Next come the values for the IP header that caused the error that necessitated
549 the unreachable. The standard payload arguments to this function actually
550 apply to the original IP packet and will be tacked on there. The type should
551 be ICMP_REDIRECT and the code should be ICMP_TIMXCEED_INTRANS or
554 \fBlibnet_build_icmp_redirect()\fP builds an ICMP_REDIRECT packet. Supplied
555 is a byte for the packet type, a byte for the code, and the unsigned long
556 IP address of the gateway that should be used. Next come the values for
557 the IP header that caused the error that necessitated the redirect.
558 The standard payload arguments to this function actually apply to the
559 original IP packet and will be tacked on there. The type should be
560 ICMP_REDIRECT and the code should be one of the following:
568 2 ICMP_UNREACH_PROTOCOL (redirect for type of service and network)
570 3 ICMP_UNREACH_PORT (redirect for type of service and host)
572 \fBlibnet_build_icmp_timestamp()\fP builds an ICMP_TSTAMP / ICMP_TSTAMPREPLY
573 packet. Supplied is a byte for the packet type, a byte for the code, an
574 unsigned short for the packet id, an unsigned short for the packet sequence
575 number, the three timestamp values, a pointer to an optional data payload,
576 the payload length, and a pointer to a pre-allocated block of memory for the
577 packet. The type should be ICMP_TSTAMP or ICMP_TSTAMPREPLY and the code
580 \fBlibnet_build_igmp()\fP builds an IGMP (Internet Group Membership Protocol)
581 packet. Supplied is a byte for the
582 packet type, a byte for the code, an unsigned long for the Class D address,
583 and the other usual things.
585 \fBlibnet_build_ip()\fP builds an IP (Internet Protocol) packet. Supplied
587 (not including the IP header), the IP tos bits, the IP ID, the fragmentation
588 flags and offset, the packet TTL, the transport protocol, the source and
589 destination IP addresses (in network-byte order), a pointer to an
590 optional data payload, the payload length, and a pointer to a
591 pre-allocated block of memory for the packet. To just build an IP header
592 with no data payload, only IP_H bytes need to be allocated. The payload
593 and payload size arguments should not be used to build any of the supported
594 transport protocol-type packets; for these transports, the relevant functions
595 should be used. The payload arguments should only be used to build an
596 arbitrary IP packet with a payload.
599 .SH OSPF PACKET CREATION ROUTINES
600 \fBlibnet_build_ospf()\fP builds a OSPF (Open Shortest Path First) packet. You pass the packet length
601 (not including the OSPF header), the packet type, 32-bit router ID, 32-bit
602 area ID, the authentication type, a pointer to an optional data payload, the
603 payload length, and a pointer to a pre-allocated block of memory for the
604 packet. The payload should not be used to build the Hello, LSA, LSU, LSR, or
605 DBD packets. The following variables are to be used for the OSPF packet type:
607 OSPF_UMD UMd monitoring packet
609 OSPF_HELLO Hello packet
611 OSPF_DBD Database Desc. packet
613 OSPF_LSR Link State Request packet
615 OSPF_LSU Link State Update packet
617 OSPF_LSA Link State Ack. packet
619 The following are the possible authentication types:
621 OSPF_AUTH_NULL NULL password
623 OSPF_AUTH_SIMPLE plaintext, 8 char pass.
627 The following is the structure used for the 64 bit field when using
632 u_short ospf_auth_null; /* NULL 16 bits */
634 u_char ospf_auth_keyid; /* Key ID */
636 u_char ospf_auth_len; /* Auth data len */
638 u_int ospf_auth_seq; /* Sequence num */
642 \fBlibnet_build_ospf_hello()\fP builds an OSPF Hello packet. You pass the
643 netmask for the interface, the number of seconds since the last packet was
645 possible options, the router's priority (if 0, it can't be a backup router),
646 the time (in seconds) until a router is deemed down, the networks designated
647 router, the networks backup router, a neighbor, a pointer to an optional data
648 payload, the payload length, and a pointer to a pre-allocated block of
649 memory used for the packet. If there are more than one neighbors that are to
650 be included in the packet, just allocate enough space for the packet buf, and
651 pass the neighbors as the "optional data payload."
653 \fBlibnet_build_ospf_dbd()\fP builds an OSPF DataBase Description (DBD)
655 You pass the maximum length of an IP packet the interface can use, packet
656 options, the type of exchange occuring, a sequence number, a pointer to an
657 optional data payload, the payload length, and a pointer to a pre-allocated
658 block of memory for the packet. The following can be used for the type
663 DBD_MBIT More DBD packets to come
665 DBD_MSBIT sender is the master
667 \fBlibnet_build_ospf_lsr()\fP builds an OSPF Link State Request (LSR) packet.
668 You pass the type of link state packet being requested, the link state ID, the
669 advertising router, a pointer to an optional data payload, the payload length,
670 and a pointer to a pre-allocated block of memory for the packet. See the
671 \fBlibnet_build_ospf_lsa()\fP section for more information regarding
674 \fBlibnet_build_ospf_lsu()\fP builds an OSPF Link State Update (LSU) packet.
675 You pass the number of Link State Acknowledgment (LSA) packets that will be in
676 the packet, a pointer to an optional data payload, the payload length, and a
677 pointer to a pre-allocated block of memory for the packet.
679 \fBlibnet_build_ospf_lsa()\fP builds an OSPF Link State Acknowledgement (LSA)
680 packet. You pass the link state age, packet options, type of LSA, the link
681 state ID, the advertising router, the packet's sequence number, the length of
682 the packet (_not_ including the LSA header length), a pointer to an optional
683 data payload, the payload length, and a pointer to a pre-allocated block of
684 memory for the packet. The following variables can be used for the type of
687 LS_TYPE_RTR Router LSA
689 LS_TYPE_NET Network LSA
691 LS_TYPE_IP Summary LSA (IP Network)
693 LS_TYPE_ASBR Summary LSA (ASBR)
695 LS_TYPE_ASEXT AS-External LSA
697 \fBlibnet_build_ospf_lsa_rtr()\fP builds an OSPF Link State Router packet.
699 pass the optional packet flags, the number of links within that packet, the
700 link ID (helps describe the next variable), the info for the specified link
702 the type of router link, the number of TOS metrics for this link, the metric
703 (the cost of using the link), a pointer to an optional data payload, the
704 payload length, and a pointer to a pre-allocated block of memory for the
705 packet. The possible flags (not including 0x00) are as follows:
713 The possible link ID's are as follows:
715 LINK_ID_NBR_ID Neighbors router ID
717 LINK_ID_IP_DES IP addr of router
719 LINK_ID_SUB IP subnet number
721 The possible values for the router type are as follows:
723 RTR_TYPE_PTP Point-to-point
725 RTR_TYPE_TRANS Connection to a "transit network"
727 RTR_TYPE_STUB Connection to a "stub network"
729 RTR_TYPE_VRTL Connection to a "virtual link"
731 \fBlibnet_build_ospf_lsa_net()\fP builds an OSPF Link Sate Network packet.
733 pass the interface's netmask, the router ID, a pointer to an optional data
734 payload, the payload length, and a pointer to a pre-allocated block of memory
737 \fBlibnet_build_ospf_lsa_sum()\fP builds an OSPF Link State Summary packet.
739 pass the interface's netmask, the cost of using the link (metric), the TOS
740 and metric, which is passed as a unsigned integer but the first 8 bits are the
741 TOS and the last 24 bits are the TOS metric, a pointer to an optional data
742 payload, the payload length, and a pointer to a pre-allocated block of memory
745 \fBlibnet_buils_ospf_lsa_as()\fP builds an OSPF Link State AS External packet.
746 You pass the interface's netmask, the cost of using the link (metric), the
747 forwarding address, the external route tag, a pointer to an optional data
748 payload, the payload length, and a pointer to a pre-allocated block of memory
749 for the packet. In reality, the metric only uses the last 24 bits of the
750 unsigned int. The first 8bits are reserved for a possible bit to be set (the
751 E bit, see above for more info). The variable AS_E_BIT_ON can be used
752 logically to set the E bit on.
755 \fBLIBNET_OSPF_AUTHCPY()\fP simply copies, byte for byte, your authentication
756 buf to the pre-allocated block of memory for your packet.
758 .SH OSPF FUNCTION VARIABLES
779 LS_RTR_LEN LS-Router header
781 LS_NET_LEN LS-Network header
783 LS_SUM_LEN LS-Summary header
785 LS_AS_EXT_LEN LS-AS External header
789 OPT_EBIT AS-external-LSAs are flooded
791 OPT_MCBIT IP multicast dgrams are forwarded
793 OPT_NPBIT Handles type-7 LSAs
795 OPT_EABIT Sends/recv's AS-external LSAs
797 OPT_DCBIT Handles demand circuits
801 \fBlibnet_build_rip()\fP constructs a RIP (Routing Information Protocol)
802 packet. The values supplied depend on the version of the RIP packet you
803 desire to build. The following table applies:
805 Passing Order Datatype RIP v1 RIPv2
807 first byte command command
809 second byte version version
811 third ushort zero routing domain
813 fourth ushort address family address family
815 fifth ushort zero route tag
817 sixth ulong IP address IP address
819 seventh ulong zero subnet mask
821 eighth ulong zero next hop IP
823 ninth ulong metric metric
825 tenth const u_char * Packet payload
827 eleventh int Packet payload size
829 twelfth u_char * Packet header memory
831 The command should be one of the following: RIPCMD_REQUEST, RIPCMD_RESPONSE,
832 RIPCMD_TRACEON, RIPCMD_TRACEOFF, RIPCMD_POLL, RIPCMD_POLLENTRY, or
833 RIPCMD_MAX. The version should be RIPVER_1 or RIPVER_2.
835 \fBlibnet_build_tcp()\fP builds a TCP (Transmission Control Protocol) packet. Supplied is the source port,
836 destination port, the sequence and acknowledgement numbers, the control bits
837 (which can be logically OR'd together to set multiple flags -- see the example
838 below), the advertised window size, the urgent pointer, a pointer to an
839 optional data payload, the payload size, and lastly, the pointer to a
840 pre-allocated block of memory for the packet. To just build a TCP header
841 with no data payload, only TCP_H bytes need be allocated.
843 \fBlibnet_build_udp()\fP builds a UDP (User Datagram Protocol) packet. Supplied is the source port, the
844 destination port, a pointer to an optional data payload, the payload size,
845 and lastly, a pointer to a pre-allocated block of memory for the packet.
846 To just build a UDP header with no data payload, only UDP_H bytes need to
849 \fBlibnet_vuild_vrrp()\fP builds a VRRP (Virtual Router Redundancy Protocol)
850 packet. Supplied is the virtual router ID, the priority, the number of IP
851 addresses in the packet, the authorization type (LIBNET_VRRP_AUTH_NONE,
852 LIBNET_VRRP_AUTH_PASSWD, or LIBNET_VRRP_AUTH_IPAH), the adverstisment interval,
853 a pointer to an optional data payload, the payload size,
854 and lastly, a pointer to a pre-allocated block of memory for the packet.
856 \fBlibnet_insert_ipo()\fP inserts IP options into an already created IP packet.
857 Supplied is a pointer to an ip option struct (which must be filled in by the
858 user), the size of the options list, and a pointer the completed packet. The
859 function returns -1 if the options would make the packet too large (greater
860 then 65535 bytes) or 1 otherwise. It is an unchecked runtime error for
861 the user to have not allocated enough heap memory for the packet + options.
863 \fBlibnet_insert_tcpo()\fP inserts TCP options into an already created IP
864 packet. Replace the pointer to an IP option struct with one to a TCP option
865 struct and this function is exactly the same as above.
867 .SH MISCELLANEOUS SUPPORT ROUTINES
868 \fBlibnet_seed_prand()\fP seeds the psuedorandom number generator. Returns 1
869 on success, -1 on failure.
871 \fBlibnet_get_prand()\fP returns a positive psuedorandom integer of the
872 specified type. Expects type to be one of five symbolics PR2, PR8, PR16,
873 PRu16, PR32 or PRu32. PR2 returns a one or a zero, PR8 returns a byte, PR16
874 returns up to a signed short (from 0 to 32767), PRu16 returns an unsigned
875 short (from 0 to 65535), PR32 returns a signed long (from 0 to 2147483647)
876 and PRu32 returns an unsigned long number (from 0 to 4294967295).
878 \fBlibnet_hex_dump()\fP prints a packet out in hex. Supplied is the packet
879 and its length, a swap flag, and a pointer to a previously opened
880 stream. The swap flag (1 or 0) specifies whether or not to print the packet
881 as it appears in memory (0) or to swap the bytes into host order (1).
883 \fBlibnet_plist_chain_new()\fP builds a new libnet port list chain. A libnet
884 port list chain is a fast and simple way of implementing port list ranges
885 (useful for applications that employ a list of ports like a port scanner).
886 You'll see naive implementations that allocate an entire array of 65535 bytes
887 and fill in the desired ports one by one. However, we only really need to
888 store the beginning port and the ending port, and we can efficiently store
889 multiple port ranges (delimated by commas) by using a linked list chain with
890 each node holding the beginning and ending port for a particular range. For
891 example, The port range `1-1024` would occupy one node with the bport being 1
892 and the eport being 1024. The port range `25,110-161,6000` would result
893 in 3 nodes being allocated. Single ports are taken as single ranges (port
894 25 ends up being 25-25). A port list range without a terminating port
895 (port_num - ) is considered shorthand for (port_num - 65535).
896 The arguments are a pointer to libnet_plist_chain pointer (which will end
897 up being the head of the linked list) and pointer to the port list itself.
898 The function checks this character port list for valid tokens (1234567890,- )
899 and returns an error if an unrecognized token is found. Upon success the
900 function returns 1, and head points to the newly formed port list (and also
901 contains the number of nodes in the list. If an error occurs (an unrecognized
902 token is found or malloc fails) -1 is returned and head is set to NULL.
903 libnet_plist_chain_next_pair() should be used to extract port list pairs.
905 \fBlibnet_plist_chain_next_pair()\fP fetchs the next pair of ports from the
906 list. The function takes a pointer to the head of the prebuilt list and
907 a pointer to a u_short that will contain the beginning port and a pointer
908 to a u_short that will contain the ending port. The function returns 1 and
909 fills in these values if there are nodes remaining, or if the port list
910 chain is exhausted, it returns 0.
912 \fBlibnet_plist_chain_dump()\fP prints the list (as lists of integers).
914 \fBlibnet_plist_chain_dump_string()\fP returns a string containing the
917 \fBlibnet_plist_chain_free()\fP frees the entire list.
919 \fBlibnet_error()\fP dumps an error message to stderr. Included is the
920 severity of the message (LIBNET_ERR_WARNING, LIBNET_ERR_CRITICAL, or
921 LIBNET_ERR_FATAL) and the message string itself. If the severity is
922 LIBNET_ERR_FATAL, the function will exit the program. This is the only
923 defined exit point in the whole library.
926 .SH ASN.1 BER ROUTINES
928 \fBlibnet_build_asn1_int()\fP
930 \fBlibnet_build_asn1_uint()\fP
932 \fBlibnet_build_asn1_string()\fP
934 \fBlibnet_build_asn1_header()\fP
936 \fBlibnet_build_asn1_length()\fP
938 \fBlibnet_build_asn1_sequence()\fP
940 \fBlibnet_build_asn1_objid()\fP
942 \fBlibnet_build_asn1_null()\fP
944 \fBlibnet_build_asn1_bitstring()\fP
946 .SH SYMBOLIC CONSTANTS
947 To make your life and code cleaner, libnet defines symbolic constants to make
950 Default packet header sizes:
957 LIBNET_ETH_H ethernet
959 LIBNET_ICMP_H ICMP header (base)
961 LIBNET_ICMP_ECHO_H ICMP_ECHO / ICMP_ECHOREPLY
963 LIBNET_ICMP_MASK_H ICMP_MASKREQ / ICMP_MASKREPLY
965 LIBNET_ICMP_UNREACH_H ICMP_UNREACHABLE (base)
967 LIBNET_ICMP_REDIRECT_H ICMP_REDIRECT (base)
969 LIBNET_ICMP_TS_H ICMP_TSTAMP (base)
971 LIBNET_ICMP_TIMXCEED_H ICMP_TIMXCEED (base)
983 LIBNET_VRRP_H VRRP (base)
985 Standard memory sizes for packets:
988 LIBNET_PACKET Standard packet size (IP_H + TCP_H)
990 LIBNET_OPTS Maximum IP options list
992 LIBNET_MAX_PACKET Maximum IPv4 packet size
995 Other constants you should know about:
997 IP Type Of Service constants:
1000 IPTOS_LOWDELAY Minimize delay
1002 IPTOS_THROUGHPUT Maximize throughput
1004 IPTOS_RELIABILITY Maximize reliability
1006 IPTOS_MINCOST Minimize monetary cost
1009 IP Fragmentation flags:
1012 IP_DF Don't fragment this datagram
1014 IP_MF More fragments en route
1022 TH_ACK Acknowledgement field valid
1024 TH_PUSH Push this data to application layer
1026 TH_RST Reset the referenced connection
1028 TH_SYN Synchronize connection state
1030 TH_FIN Finished sending data
1033 .SH COMPLIATION USING THE CONFIGURE SCRIPT
1034 To properly compile your applications under libnet, you should use the
1035 `libnet-config` script. This script is created during the GNU configure
1036 process will ensure that future compilations linked against libnet contain the
1037 correct CPP and CFLAG options as well as additional libraries for the targeted
1038 architecture. To invoke it simply:
1040 gcc `libnet-config --defines --cflags` foo.c -o foo `libnet-config --libs`
1042 The script handles all libnet dependencies and concessions for the architecture
1046 pcap(3), bpf(4), dlpi(7P)
1048 Mike D. Schiffman <mike@infonexus.com>
1049 See the online web reference manual for additional contributers.
1051 The current version is always available:
1054 .I http://www.packetfactory.net/libnet
1057 Solaris raw sockets are cooked. They do not allow one to set the ip_len,
1058 ip_frag or the ip_id (including IP options at the raw socket layer doesn't work
1059 either). To work around this, use the link-layer API instead of raw socket
1062 The Berkeley Packet Filter alone does not allow for the arbitrary specification
1063 of source ethernet addresses. This is not so much a bug as an oversight
1064 in the protocol. Included with the distribution is lkm code to work around
1065 this (FreeBSD has support for an ioctl that works around this).
1067 The OSPF functionality has not been extensively tested as yet and is
1068 considered to be in beta release.
1070 Please send bug reports to mike@infonexus.com.
OSDN Git Service
