* [PATCH libnetfilter_queue 1/2] src: doc: Major re-work of user packet buffer documentation
@ 2019-11-18 3:36 Duncan Roe
2019-11-18 3:36 ` [PATCH libnetfilter_queue 2/2] Minor tweak to pktb_len function description Duncan Roe
` (2 more replies)
0 siblings, 3 replies; 5+ messages in thread
From: Duncan Roe @ 2019-11-18 3:36 UTC (permalink / raw)
To: pablo; +Cc: netfilter-devel
Divide functions into a hierarchy:
top-level: Functions all programs that modify data will use
2nd-level: Rarely-used functions
3rd-level: Functions not to use (should have been declared static)
Only the top-level functions appear on the "User-space network packet buffer"
page, which looks a lot less daunting than it used to.
Parameter descriptions all match prototypes
All non-void functions have a "Returns" paragraph
Code change:
pktb_alloc: set errno to EPROTONOSUPPORT before doing error return because
protocol is not supported
Detailed other updates (top-level)
pktb_alloc: - Add "Errors" para
- Add "See also" para
pktb_data, pktb_len: Add "appropriate use" line
pktb_mangle: Add warning to use a different function unless mangling MAC hddr
pktb_mangled: Add usage hint line
Detailed other updates (2nd-level)
pktb_mac_header: Point out only for AF_BRIDGE
pktb_tailroom: Point out no dynamic expansion
pktb_transport_header: Add note that programmer must code to set this
Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
| 154 +++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 117 insertions(+), 37 deletions(-)
--git a/src/extra/pktbuff.c b/src/extra/pktbuff.c
index f1f8323..26d7ca8 100644
--- a/src/extra/pktbuff.c
+++ b/src/extra/pktbuff.c
@@ -9,6 +9,7 @@
* This code has been sponsored by Vyatta Inc. <http://www.vyatta.com>
*/
+#include <errno.h>
#include <stdlib.h>
#include <string.h> /* for memcpy */
#include <stdbool.h>
@@ -30,7 +31,8 @@
/**
* pktb_alloc - allocate a new packet buffer
- * \param family Indicate what family, eg. AF_BRIDGE, AF_INET, AF_INET6, ...
+ * \param family Indicate what family. Currently supported families are
+ * AF_BRIDGE, AF_INET & AF_INET6.
* \param data Pointer to packet data
* \param len Packet length
* \param extra Extra memory in the tail to be allocated (for mangling)
@@ -38,7 +40,13 @@
* This function returns a packet buffer that contains the packet data and
* some extra memory room in the tail (if requested).
*
- * \return a pointer to a new queue handle or NULL on failure.
+ * \return Pointer to a new userspace packet buffer or NULL on failure.
+ * \par Errors
+ * __ENOMEM__ From __calloc__()
+ * \n
+ * __EPROTONOSUPPORT__ _family_ was __AF_BRIDGE__ and this is not an IP packet
+ * (v4 or v6)
+ * \sa __calloc__(3)
*/
EXPORT_SYMBOL
struct pkt_buff *pktb_alloc(int family, void *data, size_t len, size_t extra)
@@ -78,6 +86,7 @@ struct pkt_buff *pktb_alloc(int family, void *data, size_t len, size_t extra)
break;
default:
/* This protocol is unsupported. */
+ errno = EPROTONOSUPPORT;
free(pktb);
return NULL;
}
@@ -88,8 +97,12 @@ struct pkt_buff *pktb_alloc(int family, void *data, size_t len, size_t extra)
}
/**
- * pktb_data - return pointer to the beginning of the packet buffer
- * \param pktb Pointer to packet buffer
+ * pktb_data - get pointer to network packet
+ * \param pktb Pointer to userspace packet buffer
+ * \return Pointer to start of network packet data within __pktb__
+ * \par
+ * It is appropriate to use _pktb_data_ as the second argument of
+ * nfq_nlmsg_verdict_put_pkt()
*/
EXPORT_SYMBOL
uint8_t *pktb_data(struct pkt_buff *pktb)
@@ -99,7 +112,11 @@ uint8_t *pktb_data(struct pkt_buff *pktb)
/**
* pktb_len - return length of the packet buffer
- * \param pktb Pointer to packet buffer
+ * \param pktb Pointer to userspace packet buffer
+ * \return Length of packet contained within __pktb__
+ * \par
+ * It is appropriate to use _pktb_len_ as the third argument of
+ * nfq_nlmsg_verdict_put_pkt()
*/
EXPORT_SYMBOL
uint32_t pktb_len(struct pkt_buff *pktb)
@@ -109,7 +126,7 @@ uint32_t pktb_len(struct pkt_buff *pktb)
/**
* pktb_free - release packet buffer
- * \param pktb Pointer to packet buffer
+ * \param pktb Pointer to userspace packet buffer
*/
EXPORT_SYMBOL
void pktb_free(struct pkt_buff *pktb)
@@ -118,8 +135,35 @@ void pktb_free(struct pkt_buff *pktb)
}
/**
- * pktb_push - update pointer to the beginning of the packet buffer
- * \param pktb Pointer to packet buffer
+ * \defgroup otherfns Other functions
+ *
+ * The library provides a number of other functions which many user-space
+ * programs will never need. These divide into 2 groups:
+ * \n
+ * 1. Functions to get values of members of opaque __struct pktbuff__, described
+ * below
+ * \n
+ * 2. Internal functions, described in Module __Internal functions__
+ *
+ * @{
+ */
+
+/**
+ * \defgroup uselessfns Internal functions
+ *
+ * \warning Do not use these functions. Instead, always use the mangle
+ * function appropriate to the level at which you are working.
+ * \n
+ * pktb_mangle() uses all the below functions except _pktb_pull_, which is not
+ * used by anything.
+ *
+ * @{
+ */
+
+/**
+ * pktb_push - decrement pointer to packet buffer
+ * \param pktb Pointer to userspace packet buffer
+ * \param len Number of bytes to subtract from packet start address
*/
EXPORT_SYMBOL
void pktb_push(struct pkt_buff *pktb, unsigned int len)
@@ -129,8 +173,9 @@ void pktb_push(struct pkt_buff *pktb, unsigned int len)
}
/**
- * pktb_pull - update pointer to the beginning of the packet buffer
- * \param pktb Pointer to packet buffer
+ * pktb_pull - increment pointer to packet buffer
+ * \param pktb Pointer to userspace packet buffer
+ * \param len Number of bytes to add to packet start address
*/
EXPORT_SYMBOL
void pktb_pull(struct pkt_buff *pktb, unsigned int len)
@@ -141,7 +186,8 @@ void pktb_pull(struct pkt_buff *pktb, unsigned int len)
/**
* pktb_put - add extra bytes to the tail of the packet buffer
- * \param pktb Pointer to packet buffer
+ * \param pktb Pointer to userspace packet buffer
+ * \param len Number of bytes to add to packet tail (and length)
*/
EXPORT_SYMBOL
void pktb_put(struct pkt_buff *pktb, unsigned int len)
@@ -152,7 +198,8 @@ void pktb_put(struct pkt_buff *pktb, unsigned int len)
/**
* pktb_trim - set new length for this packet buffer
- * \param pktb Pointer to packet buffer
+ * \param pktb Pointer to userspace packet buffer
+ * \param len New packet length (tail is adjusted to reflect this)
*/
EXPORT_SYMBOL
void pktb_trim(struct pkt_buff *pktb, unsigned int len)
@@ -162,8 +209,17 @@ void pktb_trim(struct pkt_buff *pktb, unsigned int len)
}
/**
- * pktb_tailroom - get room in bytes in the tail of the packet buffer
- * \param pktb Pointer to packet buffer
+ * @}
+ */
+
+/**
+ * pktb_tailroom - get room available for packet expansion
+ * \param pktb Pointer to userspace packet buffer
+ * \return room in bytes after the tail of the packet buffer
+ * \n
+ * This starts off as the __extra__ argument to pktb_alloc().
+ * Programmers should ensure this __extra__ argument is sufficient for any
+ * packet mangle, as packet buffers cannot be expanded dynamically.
*/
EXPORT_SYMBOL
unsigned int pktb_tailroom(struct pkt_buff *pktb)
@@ -172,8 +228,11 @@ unsigned int pktb_tailroom(struct pkt_buff *pktb)
}
/**
- * pktb_mac_header - return pointer to layer 2 header (if any)
- * \param pktb Pointer to packet buffer
+ * pktb_mac_header - get address of layer 2 header (if any)
+ * \param pktb Pointer to userspace packet buffer
+ * \return Pointer to MAC header or NULL if no such header present.
+ * \n
+ * Only packet buffers in family __AF_BRIDGE__ have a non-NULL MAC header.
*/
EXPORT_SYMBOL
uint8_t *pktb_mac_header(struct pkt_buff *pktb)
@@ -182,8 +241,10 @@ uint8_t *pktb_mac_header(struct pkt_buff *pktb)
}
/**
- * pktb_network_header - return pointer to layer 3 header
- * \param pktb Pointer to packet buffer
+ * pktb_network_header - get address of layer 3 header
+ * \param pktb Pointer to userspace packet buffer
+ * \return Pointer to layer 3 header or NULL if the packet buffer was created
+ * with an unsupported family
*/
EXPORT_SYMBOL
uint8_t *pktb_network_header(struct pkt_buff *pktb)
@@ -192,8 +253,13 @@ uint8_t *pktb_network_header(struct pkt_buff *pktb)
}
/**
- * pktb_transport_header - return pointer to layer 4 header (if any)
- * \param pktb Pointer to packet buffer
+ * pktb_transport_header - get address of layer 4 header (if known)
+ * \param pktb Pointer to userspace packet buffer
+ * \return Pointer to layer 4 header or NULL if not (yet) set
+ * \note
+ * Unlike the lower-level headers, it is the programmer's responsibility to
+ * create the level 4 (transport) header pointer by caling e.g.
+ * nfq_ip_set_transport_header()
*/
EXPORT_SYMBOL
uint8_t *pktb_transport_header(struct pkt_buff *pktb)
@@ -201,6 +267,10 @@ uint8_t *pktb_transport_header(struct pkt_buff *pktb)
return pktb->transport_header;
}
+/**
+ * @}
+ */
+
static int pktb_expand_tail(struct pkt_buff *pkt, int extra)
{
/* No room in packet, cannot mangle it. We don't support dynamic
@@ -228,19 +298,24 @@ static int enlarge_pkt(struct pkt_buff *pkt, unsigned int extra)
/**
* pktb_mangle - adjust contents of a packet
- * \param pkt Pointer to packet buffer
+ * \param pktb Pointer to userspace packet buffer
* \param dataoff Offset to layer 4 header. Specify zero to access layer 3 (IP)
- * header
+ * header (layer 2 for family \b AF_BRIDGE)
* \param match_offset Further 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. Failure will occur if the \b extra
- * argument to the pktb_alloc() call that created \b pkt is less than the excess
- * of \b rep_len over \b match_len
+ * argument to the pktb_alloc() call that created \b pktb is less than the
+ * excess of \b rep_len over \b match_len
+ \warning pktb_mangle does not update any checksums. Developers should use the
+ appropriate mangler for the protocol level: nfq_ip_mangle(),
+ nfq_tcp_mangle_ipv4() or nfq_udp_mangle_ipv4(). IPv6 versions are planned.
+ \n
+ It is appropriate to use pktb_mangle to change the MAC header.
*/
EXPORT_SYMBOL
-int pktb_mangle(struct pkt_buff *pkt,
+int pktb_mangle(struct pkt_buff *pktb,
unsigned int dataoff,
unsigned int match_offset,
unsigned int match_len,
@@ -250,39 +325,44 @@ int pktb_mangle(struct pkt_buff *pkt,
unsigned char *data;
if (rep_len > match_len &&
- rep_len - match_len > pktb_tailroom(pkt) &&
- !enlarge_pkt(pkt, rep_len - match_len))
+ rep_len - match_len > pktb_tailroom(pktb) &&
+ !enlarge_pkt(pktb, rep_len - match_len))
return 0;
- data = pkt->network_header + dataoff;
+ data = pktb->network_header + dataoff;
/* move post-replacement */
memmove(data + match_offset + rep_len,
data + match_offset + match_len,
- pkt->tail - (pkt->network_header + dataoff +
+ pktb->tail - (pktb->network_header + dataoff +
match_offset + match_len));
/* insert data from buffer */
memcpy(data + match_offset, rep_buffer, rep_len);
- /* update pkt info */
+ /* update packet info */
if (rep_len > match_len)
- pktb_put(pkt, rep_len - match_len);
+ pktb_put(pktb, rep_len - match_len);
else
- pktb_trim(pkt, pkt->len + rep_len - match_len);
+ pktb_trim(pktb, pktb->len + rep_len - match_len);
- pkt->mangled = true;
+ pktb->mangled = true;
return 1;
}
/**
- * pktb_mangled - return true if packet has been mangled
- * \param pktb Pointer to packet buffer
+ * pktb_mangled - test whether packet has been mangled
+ * \param pktb Pointer to userspace packet buffer
+ * \return __true__ if packet has been mangled (modified), else __false__
+ * \par
+ * When assembling a verdict, it is not necessary to return the contents of
+ * un-modified packets. Use _pktb_mangled_ to decide whether packet contents
+ * need to be returned.
*/
EXPORT_SYMBOL
-bool pktb_mangled(const struct pkt_buff *pkt)
+bool pktb_mangled(const struct pkt_buff *pktb)
{
- return pkt->mangled;
+ return pktb->mangled;
}
/**
--
2.14.5
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH libnetfilter_queue 2/2] Minor tweak to pktb_len function description
2019-11-18 3:36 [PATCH libnetfilter_queue 1/2] src: doc: Major re-work of user packet buffer documentation Duncan Roe
@ 2019-11-18 3:36 ` Duncan Roe
2019-12-07 17:58 ` Pablo Neira Ayuso
2019-12-07 0:32 ` [PATCH libnetfilter_queue 1/2] src: doc: Major re-work of user packet buffer documentation Duncan Roe
2019-12-07 17:58 ` Pablo Neira Ayuso
2 siblings, 1 reply; 5+ messages in thread
From: Duncan Roe @ 2019-11-18 3:36 UTC (permalink / raw)
To: pablo; +Cc: netfilter-devel
Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
---
| 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
--git a/src/extra/pktbuff.c b/src/extra/pktbuff.c
index 26d7ca8..c4f3da3 100644
--- a/src/extra/pktbuff.c
+++ b/src/extra/pktbuff.c
@@ -111,7 +111,7 @@ uint8_t *pktb_data(struct pkt_buff *pktb)
}
/**
- * pktb_len - return length of the packet buffer
+ * pktb_len - get length of packet buffer
* \param pktb Pointer to userspace packet buffer
* \return Length of packet contained within __pktb__
* \par
--
2.14.5
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH libnetfilter_queue 1/2] src: doc: Major re-work of user packet buffer documentation
2019-11-18 3:36 [PATCH libnetfilter_queue 1/2] src: doc: Major re-work of user packet buffer documentation Duncan Roe
2019-11-18 3:36 ` [PATCH libnetfilter_queue 2/2] Minor tweak to pktb_len function description Duncan Roe
@ 2019-12-07 0:32 ` Duncan Roe
2019-12-07 17:58 ` Pablo Neira Ayuso
2 siblings, 0 replies; 5+ messages in thread
From: Duncan Roe @ 2019-12-07 0:32 UTC (permalink / raw)
To: Pablo Neira Ayuso; +Cc: Netfilter Development
Hi Pablo,
On Mon, Nov 18, 2019 at 02:36:37PM +1100, Duncan Roe wrote:
> Divide functions into a hierarchy:
> top-level: Functions all programs that modify data will use
> 2nd-level: Rarely-used functions
> 3rd-level: Functions not to use (should have been declared static)
> Only the top-level functions appear on the "User-space network packet buffer"
> page, which looks a lot less daunting than it used to.
>
> Parameter descriptions all match prototypes
>
> All non-void functions have a "Returns" paragraph
>
> Code change:
>
> pktb_alloc: set errno to EPROTONOSUPPORT before doing error return because
> protocol is not supported
>
> Detailed other updates (top-level)
>
> pktb_alloc: - Add "Errors" para
> - Add "See also" para
>
> pktb_data, pktb_len: Add "appropriate use" line
>
> pktb_mangle: Add warning to use a different function unless mangling MAC hddr
>
> pktb_mangled: Add usage hint line
>
> Detailed other updates (2nd-level)
>
> pktb_mac_header: Point out only for AF_BRIDGE
>
> pktb_tailroom: Point out no dynamic expansion
>
> pktb_transport_header: Add note that programmer must code to set this
>
> Signed-off-by: Duncan Roe <duncan_roe@optusnet.com.au>
> ---
> src/extra/pktbuff.c | 154 +++++++++++++++++++++++++++++++++++++++-------------
> 1 file changed, 117 insertions(+), 37 deletions(-)
>
> diff --git a/src/extra/pktbuff.c b/src/extra/pktbuff.c
> index f1f8323..26d7ca8 100644
> --- a/src/extra/pktbuff.c
> +++ b/src/extra/pktbuff.c
> @@ -9,6 +9,7 @@
> * This code has been sponsored by Vyatta Inc. <http://www.vyatta.com>
> */
>
> +#include <errno.h>
> #include <stdlib.h>
> #include <string.h> /* for memcpy */
> #include <stdbool.h>
> @@ -30,7 +31,8 @@
>
> /**
> * pktb_alloc - allocate a new packet buffer
> - * \param family Indicate what family, eg. AF_BRIDGE, AF_INET, AF_INET6, ...
> + * \param family Indicate what family. Currently supported families are
> + * AF_BRIDGE, AF_INET & AF_INET6.
> * \param data Pointer to packet data
> * \param len Packet length
> * \param extra Extra memory in the tail to be allocated (for mangling)
> @@ -38,7 +40,13 @@
> * This function returns a packet buffer that contains the packet data and
> * some extra memory room in the tail (if requested).
> *
> - * \return a pointer to a new queue handle or NULL on failure.
> + * \return Pointer to a new userspace packet buffer or NULL on failure.
> + * \par Errors
> + * __ENOMEM__ From __calloc__()
> + * \n
> + * __EPROTONOSUPPORT__ _family_ was __AF_BRIDGE__ and this is not an IP packet
> + * (v4 or v6)
> + * \sa __calloc__(3)
> */
> EXPORT_SYMBOL
> struct pkt_buff *pktb_alloc(int family, void *data, size_t len, size_t extra)
> @@ -78,6 +86,7 @@ struct pkt_buff *pktb_alloc(int family, void *data, size_t len, size_t extra)
> break;
> default:
> /* This protocol is unsupported. */
> + errno = EPROTONOSUPPORT;
> free(pktb);
> return NULL;
> }
> @@ -88,8 +97,12 @@ struct pkt_buff *pktb_alloc(int family, void *data, size_t len, size_t extra)
> }
>
> /**
> - * pktb_data - return pointer to the beginning of the packet buffer
> - * \param pktb Pointer to packet buffer
> + * pktb_data - get pointer to network packet
> + * \param pktb Pointer to userspace packet buffer
> + * \return Pointer to start of network packet data within __pktb__
> + * \par
> + * It is appropriate to use _pktb_data_ as the second argument of
> + * nfq_nlmsg_verdict_put_pkt()
> */
> EXPORT_SYMBOL
> uint8_t *pktb_data(struct pkt_buff *pktb)
> @@ -99,7 +112,11 @@ uint8_t *pktb_data(struct pkt_buff *pktb)
>
> /**
> * pktb_len - return length of the packet buffer
> - * \param pktb Pointer to packet buffer
> + * \param pktb Pointer to userspace packet buffer
> + * \return Length of packet contained within __pktb__
> + * \par
> + * It is appropriate to use _pktb_len_ as the third argument of
> + * nfq_nlmsg_verdict_put_pkt()
> */
> EXPORT_SYMBOL
> uint32_t pktb_len(struct pkt_buff *pktb)
> @@ -109,7 +126,7 @@ uint32_t pktb_len(struct pkt_buff *pktb)
>
> /**
> * pktb_free - release packet buffer
> - * \param pktb Pointer to packet buffer
> + * \param pktb Pointer to userspace packet buffer
> */
> EXPORT_SYMBOL
> void pktb_free(struct pkt_buff *pktb)
> @@ -118,8 +135,35 @@ void pktb_free(struct pkt_buff *pktb)
> }
>
> /**
> - * pktb_push - update pointer to the beginning of the packet buffer
> - * \param pktb Pointer to packet buffer
> + * \defgroup otherfns Other functions
> + *
> + * The library provides a number of other functions which many user-space
> + * programs will never need. These divide into 2 groups:
> + * \n
> + * 1. Functions to get values of members of opaque __struct pktbuff__, described
> + * below
> + * \n
> + * 2. Internal functions, described in Module __Internal functions__
> + *
> + * @{
> + */
> +
> +/**
> + * \defgroup uselessfns Internal functions
> + *
> + * \warning Do not use these functions. Instead, always use the mangle
> + * function appropriate to the level at which you are working.
> + * \n
> + * pktb_mangle() uses all the below functions except _pktb_pull_, which is not
> + * used by anything.
> + *
> + * @{
> + */
> +
> +/**
> + * pktb_push - decrement pointer to packet buffer
> + * \param pktb Pointer to userspace packet buffer
> + * \param len Number of bytes to subtract from packet start address
> */
> EXPORT_SYMBOL
> void pktb_push(struct pkt_buff *pktb, unsigned int len)
> @@ -129,8 +173,9 @@ void pktb_push(struct pkt_buff *pktb, unsigned int len)
> }
>
> /**
> - * pktb_pull - update pointer to the beginning of the packet buffer
> - * \param pktb Pointer to packet buffer
> + * pktb_pull - increment pointer to packet buffer
> + * \param pktb Pointer to userspace packet buffer
> + * \param len Number of bytes to add to packet start address
> */
> EXPORT_SYMBOL
> void pktb_pull(struct pkt_buff *pktb, unsigned int len)
> @@ -141,7 +186,8 @@ void pktb_pull(struct pkt_buff *pktb, unsigned int len)
>
> /**
> * pktb_put - add extra bytes to the tail of the packet buffer
> - * \param pktb Pointer to packet buffer
> + * \param pktb Pointer to userspace packet buffer
> + * \param len Number of bytes to add to packet tail (and length)
> */
> EXPORT_SYMBOL
> void pktb_put(struct pkt_buff *pktb, unsigned int len)
> @@ -152,7 +198,8 @@ void pktb_put(struct pkt_buff *pktb, unsigned int len)
>
> /**
> * pktb_trim - set new length for this packet buffer
> - * \param pktb Pointer to packet buffer
> + * \param pktb Pointer to userspace packet buffer
> + * \param len New packet length (tail is adjusted to reflect this)
> */
> EXPORT_SYMBOL
> void pktb_trim(struct pkt_buff *pktb, unsigned int len)
> @@ -162,8 +209,17 @@ void pktb_trim(struct pkt_buff *pktb, unsigned int len)
> }
>
> /**
> - * pktb_tailroom - get room in bytes in the tail of the packet buffer
> - * \param pktb Pointer to packet buffer
> + * @}
> + */
> +
> +/**
> + * pktb_tailroom - get room available for packet expansion
> + * \param pktb Pointer to userspace packet buffer
> + * \return room in bytes after the tail of the packet buffer
> + * \n
> + * This starts off as the __extra__ argument to pktb_alloc().
> + * Programmers should ensure this __extra__ argument is sufficient for any
> + * packet mangle, as packet buffers cannot be expanded dynamically.
> */
> EXPORT_SYMBOL
> unsigned int pktb_tailroom(struct pkt_buff *pktb)
> @@ -172,8 +228,11 @@ unsigned int pktb_tailroom(struct pkt_buff *pktb)
> }
>
> /**
> - * pktb_mac_header - return pointer to layer 2 header (if any)
> - * \param pktb Pointer to packet buffer
> + * pktb_mac_header - get address of layer 2 header (if any)
> + * \param pktb Pointer to userspace packet buffer
> + * \return Pointer to MAC header or NULL if no such header present.
> + * \n
> + * Only packet buffers in family __AF_BRIDGE__ have a non-NULL MAC header.
> */
> EXPORT_SYMBOL
> uint8_t *pktb_mac_header(struct pkt_buff *pktb)
> @@ -182,8 +241,10 @@ uint8_t *pktb_mac_header(struct pkt_buff *pktb)
> }
>
> /**
> - * pktb_network_header - return pointer to layer 3 header
> - * \param pktb Pointer to packet buffer
> + * pktb_network_header - get address of layer 3 header
> + * \param pktb Pointer to userspace packet buffer
> + * \return Pointer to layer 3 header or NULL if the packet buffer was created
> + * with an unsupported family
> */
> EXPORT_SYMBOL
> uint8_t *pktb_network_header(struct pkt_buff *pktb)
> @@ -192,8 +253,13 @@ uint8_t *pktb_network_header(struct pkt_buff *pktb)
> }
>
> /**
> - * pktb_transport_header - return pointer to layer 4 header (if any)
> - * \param pktb Pointer to packet buffer
> + * pktb_transport_header - get address of layer 4 header (if known)
> + * \param pktb Pointer to userspace packet buffer
> + * \return Pointer to layer 4 header or NULL if not (yet) set
> + * \note
> + * Unlike the lower-level headers, it is the programmer's responsibility to
> + * create the level 4 (transport) header pointer by caling e.g.
> + * nfq_ip_set_transport_header()
> */
> EXPORT_SYMBOL
> uint8_t *pktb_transport_header(struct pkt_buff *pktb)
> @@ -201,6 +267,10 @@ uint8_t *pktb_transport_header(struct pkt_buff *pktb)
> return pktb->transport_header;
> }
>
> +/**
> + * @}
> + */
> +
> static int pktb_expand_tail(struct pkt_buff *pkt, int extra)
> {
> /* No room in packet, cannot mangle it. We don't support dynamic
> @@ -228,19 +298,24 @@ static int enlarge_pkt(struct pkt_buff *pkt, unsigned int extra)
>
> /**
> * pktb_mangle - adjust contents of a packet
> - * \param pkt Pointer to packet buffer
> + * \param pktb Pointer to userspace packet buffer
> * \param dataoff Offset to layer 4 header. Specify zero to access layer 3 (IP)
> - * header
> + * header (layer 2 for family \b AF_BRIDGE)
> * \param match_offset Further 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. Failure will occur if the \b extra
> - * argument to the pktb_alloc() call that created \b pkt is less than the excess
> - * of \b rep_len over \b match_len
> + * argument to the pktb_alloc() call that created \b pktb is less than the
> + * excess of \b rep_len over \b match_len
> + \warning pktb_mangle does not update any checksums. Developers should use the
> + appropriate mangler for the protocol level: nfq_ip_mangle(),
> + nfq_tcp_mangle_ipv4() or nfq_udp_mangle_ipv4(). IPv6 versions are planned.
> + \n
> + It is appropriate to use pktb_mangle to change the MAC header.
> */
> EXPORT_SYMBOL
> -int pktb_mangle(struct pkt_buff *pkt,
> +int pktb_mangle(struct pkt_buff *pktb,
> unsigned int dataoff,
> unsigned int match_offset,
> unsigned int match_len,
> @@ -250,39 +325,44 @@ int pktb_mangle(struct pkt_buff *pkt,
> unsigned char *data;
>
> if (rep_len > match_len &&
> - rep_len - match_len > pktb_tailroom(pkt) &&
> - !enlarge_pkt(pkt, rep_len - match_len))
> + rep_len - match_len > pktb_tailroom(pktb) &&
> + !enlarge_pkt(pktb, rep_len - match_len))
> return 0;
>
> - data = pkt->network_header + dataoff;
> + data = pktb->network_header + dataoff;
>
> /* move post-replacement */
> memmove(data + match_offset + rep_len,
> data + match_offset + match_len,
> - pkt->tail - (pkt->network_header + dataoff +
> + pktb->tail - (pktb->network_header + dataoff +
> match_offset + match_len));
>
> /* insert data from buffer */
> memcpy(data + match_offset, rep_buffer, rep_len);
>
> - /* update pkt info */
> + /* update packet info */
> if (rep_len > match_len)
> - pktb_put(pkt, rep_len - match_len);
> + pktb_put(pktb, rep_len - match_len);
> else
> - pktb_trim(pkt, pkt->len + rep_len - match_len);
> + pktb_trim(pktb, pktb->len + rep_len - match_len);
>
> - pkt->mangled = true;
> + pktb->mangled = true;
> return 1;
> }
>
> /**
> - * pktb_mangled - return true if packet has been mangled
> - * \param pktb Pointer to packet buffer
> + * pktb_mangled - test whether packet has been mangled
> + * \param pktb Pointer to userspace packet buffer
> + * \return __true__ if packet has been mangled (modified), else __false__
> + * \par
> + * When assembling a verdict, it is not necessary to return the contents of
> + * un-modified packets. Use _pktb_mangled_ to decide whether packet contents
> + * need to be returned.
> */
> EXPORT_SYMBOL
> -bool pktb_mangled(const struct pkt_buff *pkt)
> +bool pktb_mangled(const struct pkt_buff *pktb)
> {
> - return pkt->mangled;
> + return pktb->mangled;
> }
>
> /**
> --
> 2.14.5
>
Did you forget about this one?
Cheers ... Duncan.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH libnetfilter_queue 1/2] src: doc: Major re-work of user packet buffer documentation
2019-11-18 3:36 [PATCH libnetfilter_queue 1/2] src: doc: Major re-work of user packet buffer documentation Duncan Roe
2019-11-18 3:36 ` [PATCH libnetfilter_queue 2/2] Minor tweak to pktb_len function description Duncan Roe
2019-12-07 0:32 ` [PATCH libnetfilter_queue 1/2] src: doc: Major re-work of user packet buffer documentation Duncan Roe
@ 2019-12-07 17:58 ` Pablo Neira Ayuso
2 siblings, 0 replies; 5+ messages in thread
From: Pablo Neira Ayuso @ 2019-12-07 17:58 UTC (permalink / raw)
To: Duncan Roe; +Cc: netfilter-devel
Applied, thanks.
Please, next time include the s/pkt->/pktb->/ in a separated patch,
better if only one thing at a time for easier review.
Thanks for polishing this!
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH libnetfilter_queue 2/2] Minor tweak to pktb_len function description
2019-11-18 3:36 ` [PATCH libnetfilter_queue 2/2] Minor tweak to pktb_len function description Duncan Roe
@ 2019-12-07 17:58 ` Pablo Neira Ayuso
0 siblings, 0 replies; 5+ messages in thread
From: Pablo Neira Ayuso @ 2019-12-07 17:58 UTC (permalink / raw)
To: Duncan Roe; +Cc: netfilter-devel
Also applied, thanks.
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2019-12-07 17:58 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-11-18 3:36 [PATCH libnetfilter_queue 1/2] src: doc: Major re-work of user packet buffer documentation Duncan Roe
2019-11-18 3:36 ` [PATCH libnetfilter_queue 2/2] Minor tweak to pktb_len function description Duncan Roe
2019-12-07 17:58 ` Pablo Neira Ayuso
2019-12-07 0:32 ` [PATCH libnetfilter_queue 1/2] src: doc: Major re-work of user packet buffer documentation Duncan Roe
2019-12-07 17:58 ` Pablo Neira Ayuso
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.