libnet-functions.h

tcp数据流重放工具

/*
 *  $Id: libnet-functions.h,v 1.12 2003/09/23 22:36:54 mike Exp $
 *
 *  libnet-functions.h - function prototypes
 *
 *  Copyright (c) 1998 - 2003 Mike D. Schiffman <[e-mail]>
 *  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 */

#ifndef __LIBNET_FUNCTIONS_H
#define __LIBNET_FUNCTIONS_H
/**
 * @file libnet-functions.h
 * @brief libnet exported function prototypes
 */

/**
 * Creates the libnet environment. It initializes the library and returns a 
 * libnet context. If the injection_type is LIBNET_LINK, the function 
 * initializes the injection primitives for the link-layer interface enabling
 * the application programmer to build packets starting at the data-link layer 
 * (which also provides more granular control over the IP layer). If libnet
 * uses the link-layer and the device argument is non-NULL, the function 
 * attempts to use the specified network device for packet injection. This 
 * is either a int16_t canonical string that references the device (such as 
 * "eth0" for a 100MB Ethernet card on Linux or "fxp0" for a 100MB Ethernet 
 * card on OpenBSD) or the dots and decimals representation of the device's
 * IP address (192.168.0.1). If device is NULL, libnet attempts to find a 
 * suitable device to use. If the injection_type is LIBNET_RAW4, the function
 * initializes the injection primitives for the IPv4 raw socket interface. The
 * final argument, err_buf, should be a buffer of size LIBNET_ERRBUF_SIZE and
 * holds an error message if the function fails. This function requires root
 * privileges to execute successfully. Upon success, the function returns a
 * valid libnet context for use in later function calls; upon failure, the 
 * function returns NULL.
 * @param injection_type packet injection type (Add these later)
 * @param device the interface to use (NULL and libnet will choose one)
 * @param err_buf will contain an error message on failure
 * @return libnet context ready for use or NULL on error.
 */
libnet_t *
libnet_init(int injection_type, int8_t *device, int8_t *err_buf);

/**
 * Shuts down the libnet session referenced by l. It closes the network 
 * interface and frees all internal memory structures associated with l.  
 * @param l pointer to a libnet context
 */
void
libnet_destroy(libnet_t *l);

/**
 * Clears the current packet referenced and frees all pblocks. Should be
 * called when the programmer want to send a completely new packet of
 * a different type using the same context.
 * @param l pointer to a libnet context
 */
void
libnet_clear_packet(libnet_t *l);

/**
 * Fills in a libnet_stats structure with packet injection statistics
 * (packets written, bytes written, packet sending errors).
 * @param l pointer to a libnet context
 * @param ls pointer to a libnet statistics structure
 */
void
libnet_stats(libnet_t *l, struct libnet_stats *ls);

/**
 * Returns the FILENO of the file descriptor used for packet injection.
 * @param l pointer to a libnet context
 * @return the file number of the file descriptor used for packet injection
 */
int 
libnet_getfd(libnet_t *l);

/**
 * Returns the canonical name of the device used for packet injection.
 * @param l pointer to a libnet context
 * @return the canonical name of the device used for packet injection or NULL
 * on error
 */
int8_t *
libnet_getdevice(libnet_t *l);

/**
 * Returns the pblock buffer contents for the specified ptag; a
 * subsequent call to libnet_getpbuf_size() should be made to determine the
 * size of the buffer.
 * @param l pointer to a libnet context
 * @param ptag the ptag reference number
 * @return a pointer to the pblock buffer or NULL on error
 */
u_int8_t *
libnet_getpbuf(libnet_t *l, libnet_ptag_t ptag);

/**
 * Returns the pblock buffer size for the specified ptag; a
 * previous call to libnet_getpbuf() should be made to pull the actual buffer
 * contents.
 * @param l pointer to a libnet context
 * @param ptag the ptag reference number
 * @return the size of the pblock buffer
 */ 
u_int32_t
libnet_getpbuf_size(libnet_t *l, libnet_ptag_t ptag);

/**
 * Returns the last error set inside of the referenced libnet context. This
 * function should be called anytime a function fails or an error condition
 * is detected inside of libnet.
 * @param l pointer to a libnet context
 * @return an error string or NULL if no error has occured
 */ 
int8_t *
libnet_geterror(libnet_t *l);

/**
 * Seeds the psuedo-random number generator.
 * @param l pointer to a libnet context
 * @return 1 on success, -1 on failure
 */
int
libnet_seed_prand(libnet_t *l);

/**
 * Generates an unsigned psuedo-random value within the range specified by
 * mod.
 * LIBNET_PR2    0 - 1
 * LIBNET_PR8    0 - 255
 * LIBNET_PR16   0 - 32767
 * LIBNET_PRu16  0 - 65535
 * LIBNET_PR32   0 - 2147483647
 * LIBNET_PRu32  0 - 4294967295
 *
 * @param mod one the of LIBNET_PR* constants
 * @return 1 on success, -1 on failure
 */
u_int32_t
libnet_get_prand(int mod);

/**
 * If a given protocol header is built with the checksum field set to "0", by
 * default libnet will calculate the header checksum prior to injection. If the
 * header is set to any other value, by default libnet will not calculate the
 * header checksum. To over-ride this behavior, use libnet_toggle_checksum().
 * Switches auto-checksumming on or off for the specified ptag. If mode is set
 * to LIBNET_ON, libnet will mark the specificed ptag to calculate a checksum 
 * for the ptag prior to injection. This assumes that the ptag refers to a 
 * protocol that has a checksum field. If mode is set to LIBNET_OFF, libnet
 * will clear the checksum flag and no checksum will be computed prior to 
 * injection. This assumes that the programmer will assign a value (zero or
 * otherwise) to the checksum field.  Often times this is useful if a
 * precomputed checksum or some other predefined value is going to be used.
 * Note that when libnet is initialized with LIBNET_RAW4, the IPv4 header
 * checksum will always be computed by the kernel prior to injection, 
 * regardless of what the programmer sets.
 * @param l pointer to a libnet context
 * @param ptag the ptag reference number
 * @param mode LIBNET_ON or LIBNET_OFF
 * @return 1 on success, -1 on failure
 */
int
libnet_toggle_checksum(libnet_t *l, libnet_ptag_t ptag, int mode);

/**
 * Takes a network byte ordered IPv4 address and returns a pointer to either a 
 * canonical DNS name (if it has one) or a string of dotted decimals. This may
 * incur a DNS lookup if the hostname and mode is set to LIBNET_RESOLVE. If
 * mode is set to LIBNET_DONT_RESOLVE, no DNS lookup will be performed and
 * the function will return a pointer to a dotted decimal string. The function
 * cannot fail -- if no canonical name exists, it will fall back on returning
 * a dotted decimal string. This function is non-reentrant.
 * @param in network byte ordered IPv4 address
 * @param use_name LIBNET_RESOLVE or LIBNET_DONT_RESOLVE
 * @return a pointer to presentation format string
 */
u_int8_t *
libnet_addr2name4(u_int32_t in, u_int8_t use_name);

/**
 * Takes a dotted decimal string or a canonical DNS name and returns a 
 * network byte ordered IPv4 address. This may incur a DNS lookup if mode is
 * set to LIBNET_RESOLVE and host_name refers to a canonical DNS name. If mode
 * is set to LIBNET_DONT_RESOLVE no DNS lookup will occur. The function can
 * fail if DNS lookup fails or if mode is set to LIBNET_DONT_RESOLVE and
 * host_name refers to a canonical DNS name.
 * @param l pointer to a libnet context
 * @param host_name pointer to a string containing a presentation format host
 * name
 * @param use_name LIBNET_RESOLVE or LIBNET_DONT_RESOLVE
 * @return network byte ordered IPv4 address or -1 (2^32 - 1) on error 
 */
u_int32_t
libnet_name2addr4(libnet_t *l, u_int8_t *host_name, u_int8_t use_name);

extern const struct libnet_in6_addr in6addr_error;

/**
 * Takes a dotted decimal string or a canonical DNS name and returns a 
 * network byte ordered IPv6 address. This may incur a DNS lookup if mode is
 * set to LIBNET_RESOLVE and host_name refers to a canonical DNS name. If mode
 * is set to LIBNET_DONT_RESOLVE no DNS lookup will occur. The function can
 * fail if DNS lookup fails or if mode is set to LIBNET_DONT_RESOLVE and
 * host_name refers to a canonical DNS name.
 * @param l pointer to a libnet context
 * @param host_name pointer to a string containing a presentation format host
 * name
 * @param use_name LIBNET_RESOLVE or LIBNET_DONT_RESOLVE
 * @return network byte ordered IPv6 address structure 
 */
struct libnet_in6_addr
libnet_name2addr6(libnet_t *l, u_int8_t *host_name, u_int8_t use_name);

/**
 * Should document this baby right here.
 */
void
libnet_addr2name6_r(struct libnet_in6_addr addr, u_int8_t use_name,
u_int8_t *host_name, int host_name_len);

/**
 * Creates a new port list. Port list chains are useful for TCP and UDP-based
 * applications that need to send packets to a range of ports (contiguous or
 * otherwise). The port list chain, which token_list points to, should contain
 * a series of int8_tacters from the following list: "0123456789,-" of the
 * general format "x - y, z", where "xyz" are port numbers between 0 and 
 * 65,535. plist points to the front of the port list chain list for use in 
 * further libnet_plist_chain() functions. Upon success, the function returns
 * 1. Upon failure, the function returns -1 and libnet_geterror() can tell you
 * why.
 * @param l pointer to a libnet context
 * @param plist if successful, will refer to the portlist, if not, NULL
 * @param token_list string containing the port list primitive
 * @return 1 on success, -1 on failure
 */
int
libnet_plist_chain_new(libnet_t *l, libnet_plist_t **plist, int8_t *token_list);

/**
 * Returns the next port list chain pair from the port list chain plist. bport
 * and eport contain the starting port number and ending port number, 
 * respectively. Upon success, the function returns 1 and fills in the port
 * variables; however, if the list is empty, the function returns 0 and sets 
 * both port variables to 0. Upon failure, the function returns -1.
 * @param plist previously created portlist
 * @param bport will contain the beginning port number or 0
 * @param eport will contain the ending port number or 0
 * @return 1 on success, 0 if empty, -1 on failure
 */
int
libnet_plist_chain_next_pair(libnet_plist_t *plist, u_int16_t *bport, 
u_int16_t *eport); 

/**
 * Runs through the port list and prints the contents of the port list chain
 * list to stdout.
 * @param plist previously created portlist
 * @return 1 on success, -1 on failure
 */
int
libnet_plist_chain_dump(libnet_plist_t *plist);

/**
 * Runs through the port list and prints the contents of the port list chain
 * list to string. This function uses strdup and is not re-entrant.  It also
 * has a memory leak and should not really be used.
 * @param plist previously created portlist
 * @return a printable string containing the port list contents on success
 * NULL on error
 */
int8_t *
libnet_plist_chain_dump_string(libnet_plist_t *plist);

/**
 * Frees all memory associated with port list chain.
 * @param plist previously created portlist
 * @erturn 1 on success, -1 on failure
 */
int
libnet_plist_chain_free(libnet_plist_t *plist);

/**
 * Builds an IEEE 802.1q VLAN tagging header. Depending on the value of
 * len_proto, the function wraps the 802.1q 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 type
 * values, most protocol stacks parse the frame as an RFC 894 Ethernet II
 * encapsulated frame. Note the length value is calculated without the 802.1q
 * header of 18 bytes.
 * @param dst pointer to a six byte source ethernet address
 * @param src pointer to a six byte destination ethernet address
 * @param tpi tag protocol identifier
 * @param priority priority
 * @param cfi canonical format indicator
 * @param vlan_id vlan identifier
 * @param len_proto length (802.3) protocol (Ethernet II) 
 * @param payload optional payload or NULL
 * @param payload_s payload length or 0
 * @param l pointer to a libnet context
 * @param ptag protocol tag to modify an existing header, 0 to build a new one
 */
libnet_ptag_t
libnet_build_802_1q(u_int8_t *dst, u_int8_t *src, u_int16_t tpi,
u_int8_t priority, u_int8_t cfi, u_int16_t vlan_id, u_int16_t len_proto,
u_int8_t *payload, u_int32_t payload_s, libnet_t *l, libnet_ptag_t ptag);

/*
 *  libnet_build_802_1x
 *
 *  Function builds an 802.1x header.
 */
libnet_ptag_t           /* packet id on success, -1 on failure */
libnet_build_802_1x(
    u_int8_t,             /* EAP version */
    u_int8_t,             /* EAP type */
    u_int16_t,            /* frame length */
    u_int8_t *,           /* payload (or NULL) */
    u_int32_t,             /* payload length */
    libnet_t *,         /* libnet context pointer */
    libnet_ptag_t       /* packet id */
    );


/*
 *  libnet_build_802_2
 *
 *  Function builds an 802.2 LLC header.
 */
libnet_ptag_t           /* packet id on success, -1 on failure */
libnet_build_802_2(
    u_int8_t,             /* DSAP */
    u_int8_t,             /* SSAP */
    u_int8_t,             /* control */
    u_int8_t *,           /* payload (or NULL) */
    u_int32_t,             /* payload length */
    libnet_t *,         /* libnet context pointer */
    libnet_ptag_t       /* packet id */
    );


/*
 *  libnet_build_802_2snap
 *
 *  Function builds an 802.2 LLC/SNAP header.
 */
libnet_ptag_t           /* packet id on success, -1 on failure */
libnet_build_802_2snap(
    u_int8_t,             /* DSAP */
    u_int8_t,             /* SSAP */
    u_int8_t,             /* control */
    u_int8_t *,           /* OUI */
    u_int16_t,            /* type */
    u_int8_t *,           /* payload (or NULL) */
    u_int32_t,             /* payload length */
    libnet_t *,         /* libnet context pointer */
    libnet_ptag_t       /* packet id */
    );


/*
 *  libnet_build_802.3
 *
 *  Function builds an 802.3 header.
 */
libnet_ptag_t           /* packet id on success, -1 on failure */
libnet_build_802_3(
    u_int8_t *,           /* pointer to a 6 byte ethernet address */
    u_int8_t *,           /* pointer to a 6 byte ethernet address */
    u_int16_t,            /* length */
    u_int8_t *,           /* payload (or NULL) */
    u_int32_t,             /* payload length */
    libnet_t *,         /* libnet context pointer */
    libnet_ptag_t       /* packet id */
    );


/*
 *  libnet_build_ethernet
 *
 *  Function builds an Ethernet header.
 */
libnet_ptag_t           /* packet id on success, -1 on failure */
libnet_build_ethernet(
    u_int8_t *,           /* pointer to a 6 byte ethernet address */