[PATCH] IP networking documentation

jmorrisat_private

Here's some documentation for the IP networking hooks, for comment.


- James
-- 
James Morris
<jmorrisat_private>

--- lsm/include/linux/security.h	Sat Sep 15 21:08:38 2001
+++ lsm-w1/include/linux/security.h	Sat Sep 15 23:19:27 2001
@@ -933,7 +933,31 @@
 typedef unsigned int (*ip_opfn)(unsigned int hooknum, struct sk_buff **skb,
                                 const struct net_device *in, const struct net_device *out,
                                 int (*okfn)(struct sk_buff *));
+/**
+ * IPv4 networking hooks.
+ */
 struct ip_security_ops {
+	/**
+	 * Hooks declared with the &ip_opfn function pointer make use
+	 * of the Netfilter API for intercepting packets as they traverse
+	 * the IP layer.  Each Netfilter hook is grabbed twice: before and
+	 * after packets are passed through the standard iptables-based
+	 * packet filtering and mangling mechanisms.
+	 *
+	 * Parameters for these hooks are as follows:
+	 *
+	 * @hooknum - hook the packet arrived on
+	 * @skb - &sk_buff containing the packet
+	 * @in - incoming netdevice associated with the packet
+	 * @out - outgoing netdevice associated with the packet
+	 * @okfn - used internally by Netfilter
+	 *
+	 * These hooks may return NF_ACCEPT to allow the packet through
+	 * and NF_DROP to drop the packet.
+	 *
+	 * Further information on the Netfilter API may be found in the
+	 * Netfilter Hacking HOWTO at http://netfilter.samba.org/
+	 */
 	ip_opfn preroute_first;
 	ip_opfn preroute_last;
 	ip_opfn input_first;
@@ -944,11 +968,98 @@
 	ip_opfn output_last;
 	ip_opfn postroute_first;
 	ip_opfn postroute_last;
-	void (* fragment)               (struct sk_buff *newskb, const struct sk_buff *oldskb);
-	int (* defragment)		(struct sk_buff *skb);
-	void (* encapsulate)            (struct sk_buff *skb);
-	void (* decapsulate)            (struct sk_buff *skb);
-	int (* decode_options)		(struct sk_buff *skb, const char *optptr, unsigned char **pp_ptr);
+
+	/**
+	 * fragment - IP packet fragmentation hook
+	 * @newskb: the newly created fragment
+	 * @oldskb: the original packet being fragmented
+	 *
+	 * called: ip_fragment <net/ipv4/ip_output.c>
+	 *
+	 * This is called for each fragment generated when an outgoing packet
+	 * is being fragmented, and may be used to copy security attributes
+	 * from the original packet to each fragment.
+	 */
+	void (* fragment) (struct sk_buff *newskb,
+	                   const struct sk_buff *oldskb);
+
+	/**
+	 * defragment - IP packet defragmentation hook
+	 * @skb: the incoming fragment
+	 *
+	 * called: ip_frag_queue <net/ipv4/ip_fragment.c>
+	 *
+	 * This hook is called when an incoming fragment is about to be
+	 * inserted into a reassembly queue.  It's purpose is to enable the
+	 * validation of security attributes for each fragment.  An LSM
+	 * module using this hook will likely need to maintain it's own
+	 * fragment queue information, handle fragment expiration and
+	 * implement DoS countermeasures.
+	 *
+	 * Returns 0 on success.
+	 *
+	 */
+	int (* defragment) (struct sk_buff *skb);
+
+	/**
+	 * encapsulate - IP encapsulation hook
+	 * @skb: the encapsulated packet
+	 *
+	 * called: ipgre_tunnel_xmit <net/ipv4/ip_gre.c>
+	 * called: ipip_tunnel_xmit <net/ipv4/ipip.c>
+	 * called: ip_encap <net/ipv4/ipmr.c>
+	 *
+	 * This hook is called when an IP packet is encapsulated, and
+	 * may be used to update security attributes prior to reprocessing
+	 * via the local_out or forward hooks.
+	 */
+	void (* encapsulate) (struct sk_buff *skb);
+
+	/**
+	 * decapsulate - IP decapsulation hook
+	 * @skb: the decapsulated packet
+	 *
+	 * called: ipgre_rcv <net/ipv4/ip_gre.c>
+	 * called: ipip_rcv <net/ipv4/ipip.c>
+	 * called: pim_rcv_v1 <net/ipv4/ipmr.c>
+	 * called: pim_rcv <net/ipv4/ipmr.c>
+	 *
+	 * This hook is called when a packet is decapsulated, and may
+	 * be used to process security attributes at each level of
+	 * encapsulation.  An example of this would be keeping track of
+	 * nested security associations for an incoming packet.
+	 */
+	void (* decapsulate) (struct sk_buff *skb);
+
+	/**
+	 * decode_options - IP options decoding hook
+	 * @skb: &sk_buff containing IP packet (usually NULL for outgoing)
+	 * @optptr: &ip_options structure
+	 * @pp_ptr: parameter problem pointer
+	 *
+	 * called: ip_options_compile <net/ipv4/ip_options.c>
+	 *
+	 * This hook is used for processing IP security options
+	 * at the network layer when labeled networking (e.g. CIPSO)
+	 * is implemented.
+	 *
+	 * For outgoing packets, IP options passed down from the
+	 * application or transport layers may be verified here
+	 * prior the packet being built.
+	 *
+	 * For incoming packets, IP options may be verified and
+	 * their values recorded via the &sk_buff security blob
+	 * for later processing.
+	 *
+	 * Returns 0 on success.
+	 *
+	 * A non-zero return value will cause an ICMP parameter problem
+	 * message to be generated and transmitted to the sender.  The
+	 * @pp_ptr parameter may be used to point to the offending option
+	 * parameter.
+	 */
+	int (* decode_options) (struct sk_buff *skb,
+	                        const char *optptr, unsigned char **pp_ptr);
 };

 struct netdev_security_ops {


_______________________________________________
linux-security-module mailing list
linux-security-moduleat_private
http://mail.wirex.com/mailman/listinfo/linux-security-module
