diff options
| -rw-r--r-- | src/extra/ipv4.c | 52 | ||||
| -rw-r--r-- | src/extra/tcp.c | 46 | ||||
| -rw-r--r-- | src/extra/udp.c | 20 | ||||
| -rw-r--r-- | src/nlmsg.c | 4 |
4 files changed, 86 insertions, 36 deletions
diff --git a/src/extra/ipv4.c b/src/extra/ipv4.c index c03f23f..caafd37 100644 --- a/src/extra/ipv4.c +++ b/src/extra/ipv4.c @@ -26,11 +26,15 @@ */ /** - * nfq_ip_get_hdr - get IPv4 header + * nfq_ip_get_hdr - get the IPv4 header * \param pktb: Pointer to user-space network packet buffer + * \returns validated pointer to the IPv4 header or NULL if IP is malformed or + * not version 4 * - * This funcion returns NULL if the IPv4 is malformed or the protocol version - * is not 4. On success, it returns a valid pointer to the IPv4 header. + * Many programs will not need to call this function. A possible use is to + * determine the layer 4 protocol. The validation is that the buffer is big + * enough for the declared lengths in the header, i.e. an extra check for packet + * truncation. */ EXPORT_SYMBOL struct iphdr *nfq_ip_get_hdr(struct pkt_buff *pktb) @@ -56,13 +60,14 @@ struct iphdr *nfq_ip_get_hdr(struct pkt_buff *pktb) } /** - * nfq_ip_set_transport_header - set transport header + * nfq_ip_set_transport_header - set the \b transport_header field in \b pktb * \param pktb: Pointer to user-space network packet buffer * \param iph: Pointer to the IPv4 header - * - * Sets the \b transport_header field in \b pktb - * - * Level 4 helper functions need this to be set. + * \returns 0 on success or -1 if a minimal validation check fails + * \note + * Most programs should call __nfq_ip_set_transport_header__ as soon as + * possible, since most layer 4 helper functions assume the + * \b transport_header field is valid. */ EXPORT_SYMBOL int nfq_ip_set_transport_header(struct pkt_buff *pktb, struct iphdr *iph) @@ -78,11 +83,20 @@ int nfq_ip_set_transport_header(struct pkt_buff *pktb, struct iphdr *iph) } /** + * \defgroup ip_internals Internal IP functions + * + * Most user-space programs will never need these. + * + * @{ + */ + +/** * nfq_ip_set_checksum - set IPv4 checksum * \param iph: Pointer to the IPv4 header - * - * \note Call to this function if you modified the IPv4 header to update the - * checksum. + * \note + * nfq_ip_mangle() invokes this function. + * As long as developers always use the appropriate mangler for the layer being + * mangled, there is no need to call __nfq_ip_set_checksum__. */ EXPORT_SYMBOL void nfq_ip_set_checksum(struct iphdr *iph) @@ -94,16 +108,20 @@ void nfq_ip_set_checksum(struct iphdr *iph) } /** + * @} + */ + +/** * nfq_ip_mangle - mangle IPv4 packet buffer * \param pktb: Pointer to user-space network packet buffer - * \param dataoff: Offset to layer 4 header + * \param dataoff: Offset to layer 4 header, or zero to mangle IP header * \param match_offset: Offset to content that you want to mangle * \param match_len: Length of the existing content you want to mangle * \param rep_buffer: Pointer to data you want to use to replace current content * \param rep_len: Length of data you want to use to replace current content * \returns 1 for success and 0 for failure. See pktb_mangle() for failure case - * \note This function updates the IPv4 length and recalculates the IPv4 - * checksum (if necessary) + * \note This function updates the IPv4 length if necessary and recalculates the + * IPv4 checksum. */ EXPORT_SYMBOL int nfq_ip_mangle(struct pkt_buff *pktb, unsigned int dataoff, @@ -128,10 +146,8 @@ int nfq_ip_mangle(struct pkt_buff *pktb, unsigned int dataoff, * \param buf: Pointer to buffer that will be used to print the header * \param size: Size of the buffer (or remaining room in it) * \param iph: Pointer to a valid IPv4 header - * - * This function returns the number of bytes written (excluding the - * string-terminating NUL) *assuming sufficient room in the buffer*. - * Read the snprintf manpage for more information about this strange behaviour. + * \returns same as snprintf + * \sa **snprintf**(3) */ EXPORT_SYMBOL int nfq_ip_snprintf(char *buf, size_t size, const struct iphdr *iph) diff --git a/src/extra/tcp.c b/src/extra/tcp.c index 0f83500..be400c5 100644 --- a/src/extra/tcp.c +++ b/src/extra/tcp.c @@ -32,14 +32,12 @@ */ /** - * nfq_tcp_get - get the TCP header + * nfq_tcp_get_hdr - get the TCP header * \param pktb: pointer to user-space network packet buffer - * - * This function returns NULL if an invalid TCP header is found. On success, - * it returns the TCP header. - * - * \note You have to call nfq_ip_set_transport_header or - * nfq_ip6_set_transport_header first to access the TCP header. + * \returns validated pointer to the TCP header or NULL if the TCP header was + * not set or if a minimal length check fails. + * \note You have to call nfq_ip_set_transport_header() or + * nfq_ip6_set_transport_header() first to set the TCP header. */ EXPORT_SYMBOL struct tcphdr *nfq_tcp_get_hdr(struct pkt_buff *pktb) @@ -58,6 +56,7 @@ struct tcphdr *nfq_tcp_get_hdr(struct pkt_buff *pktb) * nfq_tcp_get_payload - get the TCP packet payload * \param tcph: pointer to the TCP header * \param pktb: pointer to user-space network packet buffer + * \returns Pointer to the TCP payload, or NULL if malformed TCP packet. */ EXPORT_SYMBOL void *nfq_tcp_get_payload(struct tcphdr *tcph, struct pkt_buff *pktb) @@ -79,6 +78,7 @@ void *nfq_tcp_get_payload(struct tcphdr *tcph, struct pkt_buff *pktb) * nfq_tcp_get_payload_len - get the tcp packet payload * \param tcph: pointer to the TCP header * \param pktb: pointer to user-space network packet buffer + * \returns Length of TCP payload (user data) */ EXPORT_SYMBOL unsigned int nfq_tcp_get_payload_len(struct tcphdr *tcph, struct pkt_buff *pktb) @@ -87,9 +87,22 @@ unsigned int nfq_tcp_get_payload_len(struct tcphdr *tcph, struct pkt_buff *pktb) } /** + * \defgroup tcp_internals Internal TCP functions + * + * Most user-space programs will never need these. + * + * @{ + */ + +/** * nfq_tcp_compute_checksum_ipv4 - computes IPv4/TCP packet checksum * \param tcph: pointer to the TCP header * \param iph: pointer to the IPv4 header + * \note + * nfq_tcp_mangle_ipv4() invokes this function. + * As long as developers always use __nfq_tcp_mangle_ipv4__ when changing the + * content of a TCP message, there is no need to call + * __nfq_tcp_compute_checksum_ipv4__. */ EXPORT_SYMBOL void nfq_tcp_compute_checksum_ipv4(struct tcphdr *tcph, struct iphdr *iph) @@ -103,6 +116,11 @@ void nfq_tcp_compute_checksum_ipv4(struct tcphdr *tcph, struct iphdr *iph) * nfq_tcp_compute_checksum_ipv6 - computes IPv6/TCP packet checksum * \param tcph: pointer to the TCP header * \param ip6h: pointer to the IPv6 header + * \note + * nfq_tcp_mangle_ipv6() invokes this function. + * As long as developers always use __nfq_tcp_mangle_ipv6__ when changing the + * content of a TCP message, there is no need to call + * __nfq_tcp_compute_checksum_ipv6__. */ EXPORT_SYMBOL void nfq_tcp_compute_checksum_ipv6(struct tcphdr *tcph, struct ip6_hdr *ip6h) @@ -112,6 +130,10 @@ void nfq_tcp_compute_checksum_ipv6(struct tcphdr *tcph, struct ip6_hdr *ip6h) tcph->check = nfq_checksum_tcpudp_ipv6(ip6h, tcph, IPPROTO_TCP); } +/** + * @} + */ + /* * The union cast uses a gcc extension to avoid aliasing problems * (union is compatible to any of its members) @@ -130,6 +152,8 @@ union tcp_word_hdr { * \param buf: pointer to buffer that is used to print the object * \param size: size of the buffer (or remaining room in it). * \param tcph: pointer to a valid tcp header. + * \returns Same as \b snprintf + * \sa __snprintf__(3) * */ EXPORT_SYMBOL @@ -184,8 +208,12 @@ int nfq_tcp_snprintf(char *buf, size_t size, const struct tcphdr *tcph) * \param match_len: length of the existing content you want to mangle * \param rep_buffer: pointer to data you want to use to replace current content * \param rep_len: length of data you want to use to replace current content - * - * \note This function recalculates the IPv4 and TCP checksums for you. + * \returns 1 for success and 0 for failure. See pktb_mangle() for failure case + * \note This function updates the IPv4 length and recalculates the IPv4 & TCP + * checksums for you. + * \warning After changing the length of a TCP message, the application will + * need to mangle sequence numbers in both directions until another change + * puts them in sync again */ EXPORT_SYMBOL int nfq_tcp_mangle_ipv4(struct pkt_buff *pktb, diff --git a/src/extra/udp.c b/src/extra/udp.c index 9eee1c7..dc476d4 100644 --- a/src/extra/udp.c +++ b/src/extra/udp.c @@ -34,7 +34,10 @@ * nfq_udp_get_hdr - get the UDP header. * \param pktb: Pointer to userspace network packet buffer * - * \returns Pointer to the UDP header, or NULL if no valid UDP header is found. + * \returns validated pointer to the UDP header or NULL if the UDP header was + * not set or if a minimal length check fails. + * \note You have to call nfq_ip_set_transport_header() or + * nfq_ip6_set_transport_header() first to set the UDP header. */ EXPORT_SYMBOL struct udphdr *nfq_udp_get_hdr(struct pkt_buff *pktb) @@ -84,7 +87,7 @@ unsigned int nfq_udp_get_payload_len(struct udphdr *udph, struct pkt_buff *pktb) } /** - * \defgroup internals Internal functions + * \defgroup udp_internals Internal UDP functions * * Most user-space programs will never need these. * @@ -110,13 +113,14 @@ void nfq_udp_compute_checksum_ipv4(struct udphdr *udph, struct iphdr *iph) } /** - * @} - */ - -/** * nfq_udp_compute_checksum_ipv6 - sets up the UDP checksum in a UDP/IPv6 packet * \param udph: pointer to the UDP header * \param ip6h: pointer to the IPv6 header + * \note + * nfq_udp_mangle_ipv6() invokes this function. + * As long as developers always use __nfq_udp_mangle_ipv6__ when changing the + * content of a UDP message, there is no need to call + * __nfq_udp_compute_checksum_ipv6__. */ EXPORT_SYMBOL void nfq_udp_compute_checksum_ipv6(struct udphdr *udph, struct ip6_hdr *ip6h) @@ -127,6 +131,10 @@ void nfq_udp_compute_checksum_ipv6(struct udphdr *udph, struct ip6_hdr *ip6h) } /** + * @} + */ + +/** * nfq_udp_mangle_ipv4 - Mangle UDP/IPv4 packet buffer * \param pktb: Pointer to network packet buffer * \param match_offset: Offset from start of UDP data of content that you want diff --git a/src/nlmsg.c b/src/nlmsg.c index cbf49a6..4f09bf6 100644 --- a/src/nlmsg.c +++ b/src/nlmsg.c @@ -263,9 +263,7 @@ static int nfq_pkt_parse_attr_cb(const struct nlattr *attr, void *data) * nfq_nlmsg_parse - set packet attributes from netlink message * \param nlh netlink message that you want to read. * \param attr pointer to array of attributes to set. - * - * This function returns MNL_CB_ERROR if any error occurs, or MNL_CB_OK on - * success. + * \returns MNL_CB_OK on success or MNL_CB_ERROR if any error occurs. */ EXPORT_SYMBOL int nfq_nlmsg_parse(const struct nlmsghdr *nlh, struct nlattr **attr) |