pknock: add manpage for pknock

diff --git a/doc/changelog.txt b/doc/changelog.txt
index e5413228b6ddb86588541846d8ce2d6cce2deb6c..e408e1a77a552aac19d1e2c9f98e7e4e3d234355 100644 (file)
--- a/doc/changelog.txt
+++ b/doc/changelog.txt
@@ -14,6 +14,7 @@
   - pknock: check interknock time only for !ST_ALLOWED peers
   - pknock: preserve time/autoclose values for rules added in
     reverse/arbitrary order
+  - pknock: add a manpage
 
 
 Xtables-addons 1.18 (September 09 2009)

diff --git a/extensions/libxt_pknock.man b/extensions/libxt_pknock.man
new file mode 100644 (file)
index 0000000..1552a35
--- /dev/null
+++ b/extensions/libxt_pknock.man
@@ -0,0 +1,112 @@
+Pknock match implements so-called Port-Knocking, a stealthy system
+for network authentication: client sends packets to selected
+ports in a specific sequence (= simple mode, see Example 1 below), or HMAC
+payload to a single port (= complex mode, see Example 2 below),
+to target machine that has pknock rule(s) installed. The target machine
+then decides whether to unblock or block (again) pknock-protected port with
+listening service. This can be, for instance, used to avoid brute force
+attacks on ssh or ftp services.
+.PP
+Example prerequisites:
+.IP
+modprobe cn
+.IP
+modprobe xt_pknock
+.PP
+Example 1 (TCP mode, manual closing of opened port not possible):
+.IP
+iptables -P INPUT DROP
+.IP
+iptables -A INPUT -p tcp -m pknock --knockports 4002,4001,4004 --strict
+--name SSH --time 10 --autoclose 60 --dport 22 -j ACCEPT
+.PP
+The rule will open tcp port 22 after successfull reception of TCP SYN packets
+to ports 4002, 4001, 4004 in this sequence (a.k.a port-knocking), for the IP
+that sent them. Port numbers in connect sequence must follow each other, no
+other ports may be "knocked" inbetween. The rule is named '\fBSSH\fP' - file of
+the same name for tracking port knocking states will be created in
+\fB/proc/net/xt_pknock\fP .
+Port knocks must follow each other with delay <= 10 seconds. The port 22 will
+be auto-closed in 60 minutes since its opening.
+.PP
+Example 2 (UDP mode - nonreplayable and nonspoofable, manual closing
+of opened port possible, secure, also called "SPA" = Secure Port
+Authorization):
+.IP
+iptables -A INPUT -p udp -m pknock --knockports 4000 --name FTP
+--opensecret foo --closesecret bar --autoclose 240 -j DROP
+.IP
+iptables -A INPUT -p tcp -m pknock --checkip --name FTP --dport 21 -j ACCEPT
+.PP
+First rule will create 'ALLOWED' record in /proc/net/xt_pknock/FTP after
+successfull reception of UDP packet to port 4000. The packet payload must be
+constructed as HMAC256 using 'foo' as a key, and clients IP in network byteorder
+unsigned long format, concatenated with minutes since epoch in the same format,
+as HMAC'd content (a.k.a Simple Packet Authorization, also called "SPA").
+In such case, any subsequent attempt to connect to port 21 from clients IP
+will trigger ACCEPT in the second rule.
+.PP
+Similarly, upon reception of UDP packet, constructed the same way, but with
+key 'bar', the first rule will remove previously installed 'ALLOWED' state
+record from /proc/net/xt_pknock/FTP, which means that the second rule will
+stop matching for subsequent attempts to connect to port 21.
+In case no close-secret packet is received within 4 hours, the first rule
+will remove 'ALLOWED' record from /proc/net/xt_pknock/FTP itself.
+.PP
+Things worth noting:
+.PP
+\fBGeneral\fP:
+.PP
+Specifying \fB--autoclose 0\fP means no autoclose will be performed at all.
+.PP
+xt_pknock is capable of sending information about successful match
+via netlink socket to userspace, should you need to implement your own
+way of received portknock handling.
+Be sure to read documentation in 'doc/xtables-addons/pknock' directory,
+or visit the original site - http://portknocko.berlios.de/ .
+.PP
+\fBTCP mode\fP:
+.PP
+This mode is not immune against eavesdropping, spoofing and
+replaying of the port knock sequence by someone else (but its use may still
+be sufficient for scenarios, where these factors are not necessarilly
+so important, such as bare shielding of SSH port from brute-force attacks).
+If you need these features, you should use UDP mode.
+.PP
+It is always wise to specify 3 or more ports, that dont subsequently
+follow each other in ascending or descending sequence, to avoid triggering
+the rule by a portscan.
+.PP
+Specifying inter-knock timeout with \fB--time\fP is mandatory in TCP mode,
+to avoid permanent DoS by clogging up peer knock-state tracking table
+that xt_pknock internally keeps, forever, should there be a DDoS on the
+first-in-row knock port from more hostile IPs than what is the actual size
+of this table (16, can be changed via 'peer_hasht_ents' module parameter).
+It is also wise to use as short \fB--time\fP as possible (1 second)
+for this very reason, too. You may also consider increasing the size
+of peer knock-state tracking table. Using \fB--strict\fP also helps,
+as it requires the knock sequence to be exact. This means that if the
+hostile IP client sends more knocks to the same port, xt_pknock will
+mark such attempt as failed knock sequence and will forget it immediately.
+To completely thwart this kind of DDoS, knock-ports would need to have
+an additional rate-limit protection. Or you may consider using UDP mode.
+.PP
+\fBUDP mode\fP:
+.PP
+This mode is immune against eavesdropping, replaying and spoofing attacks.
+It is also immune against DDoS attack on the knockport.
+.PP
+For this mode to work, the clock difference on the client and on the server
+must be below 1 minute. Synchronizing time on both ends by means
+of NTP or rdate is strongly suggested.
+.PP
+There is a rate limiter built into xt_pknock, that blocks any subsequent
+opening attempt in UDP mode, should it arrive in period shorter than 1
+minute since the first successfull opening. This is intentional;
+it thwarts eventual spoofing attacks.
+.PP
+Becouse the payload value of UDP knock packet is influenced by client's IP,
+UDP mode cannot be used across NAT.
+.PP
+For sending UDP "SPA" packets, you may use either \fBknock.sh\fP or
+\fBknock-orig.sh\fP. You'll find these in 'doc/xtables-addons/pknock/util'.