pknock: manpage writing style updates

extensions/libxt_pknock.man

@@ -1,10 +1,10 @@
-Pknock match implements so-called Port-Knocking, a stealthy system
+Pknock match implements so-called "port knocking", a stealthy system
-for network authentication: client sends packets to selected
+for network authentication: a client sends packets to selected
-ports in a specific sequence (= simple mode, see Example 1 below), or HMAC
+ports in a specific sequence (= simple mode, see example 1 below), or a HMAC
-payload to a single port (= complex mode, see Example 2 below),
+payload to a single port (= complex mode, see example 2 below),
-to target machine that has pknock rule(s) installed. The target machine
+to a target machine that has pknock rule(s) installed. The target machine
-then decides whether to unblock or block (again) pknock-protected port with
+then decides whether to unblock or block (again) the pknock-protected port(s).
-listening service. This can be, for instance, used to avoid brute force
+This can be used, for instance, to avoid brute force
 attacks on ssh or ftp services.
 .PP
 Example prerequisites:
@@ -20,16 +20,16 @@ iptables -P INPUT DROP
 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
+The rule will allow tcp port 22 for the attempting IP address after the successful reception of TCP SYN packets
-to ports 4002, 4001, 4004 in this sequence (a.k.a port-knocking), for the IP
+to ports 4002, 4001 and 4004, in this order (a.k.a. port-knocking).
-that sent them. Port numbers in connect sequence must follow each other, no
+Port numbers in the connect sequence must follow the exact specification, no
-other ports may be "knocked" inbetween. The rule is named '\fBSSH\fP' - file of
+other ports may be "knocked" inbetween. The rule is named '\fBSSH\fP' \(em a 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
+Successive port knocks must occur with delay of at most 10 seconds. Port 22 (from the example) will
-be auto-closed in 60 minutes since its opening.
+be automatiaclly dropped after 60 minutes after it was previously allowed.
 .PP
-Example 2 (UDP mode - nonreplayable and nonspoofable, manual closing
+Example 2 (UDP mode \(em non-replayable and non-spoofable, manual closing
 of opened port possible, secure, also called "SPA" = Secure Port
 Authorization):
 .IP
@@ -38,55 +38,56 @@ iptables -A INPUT -p udp -m pknock --knockports 4000 --name FTP
 .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
+The first rule will create an "ALLOWED" record in /proc/net/xt_pknock/FTP after
-successfull reception of UDP packet to port 4000. The packet payload must be
+the successful reception of an UDP packet to port 4000. The packet payload must be
-constructed as HMAC256 using 'foo' as a key, and clients IP in network byteorder
+constructed as a HMAC256 using "foo" as a key. The HMAC content is the particular client's IP address as a 32-bit network byteorder quantity,
-unsigned long format, concatenated with minutes since epoch in the same format,
+plus the number of minutes since the Unix epoch, also as a 32-bit value.
-as HMAC'd content (a.k.a Simple Packet Authorization, also called "SPA").
+(This is known as Simple Packet Authorization, also called "SPA".)
-In such case, any subsequent attempt to connect to port 21 from clients IP
+In such case, any subsequent attempt to connect to port 21 from the client's IP
-will trigger ACCEPT in the second rule.
+address will cause such packets to be accepted in the second rule.
 .PP
-Similarly, upon reception of UDP packet, constructed the same way, but with
+Similarly, upon reception of an UDP packet constructed the same way, but with
-key 'bar', the first rule will remove previously installed 'ALLOWED' state
+the key "bar", the first rule will remove a 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.
+stop matching for subsequent connection attempts 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.
+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.
+Specifying \fB--autoclose 0\fP means that no automatic close will be performed at all.
 .PP
-xt_pknock is capable of sending information about successful match
+xt_pknock is capable of sending information about successful matches
-via netlink socket to userspace, should you need to implement your own
+via a netlink socket to userspace, should you need to implement your own
-way of received portknock handling.
+way of receiving and handling portknock notifications.
-Be sure to read documentation in 'doc/xtables-addons/pknock' directory,
+Be sure to read the documentation in the doc/pknock/ directory,
-or visit the original site - http://portknocko.berlios.de/ .
+or visit the original site \(em 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
+be sufficient for scenarios where these factors are not necessarily
-so important, such as bare shielding of SSH port from brute-force attacks).
+this important, such as bare shielding of the SSH port from brute-force attacks).
-If you need these features, you should use UDP mode.
+However, if you need these features, you should use UDP mode.
 .PP
-It is always wise to specify 3 or more ports, that dont subsequently
+It is always wise to specify three or more ports that are not monotonically
-follow each other in ascending or descending sequence, to avoid triggering
+increasing or decreasing with a small stepsize (e.g. 1024,1025,1026)
+to avoid accidentally triggering
 the rule by a portscan.
 .PP
-Specifying inter-knock timeout with \fB--time\fP is mandatory in TCP mode,
+Specifying the inter-knock timeout with \fB--time\fP is mandatory in TCP mode,
-to avoid permanent DoS by clogging up peer knock-state tracking table
+to avoid permanent denial of services by clogging up the peer knock-state tracking table
-that xt_pknock internally keeps, forever, should there be a DDoS on the
+that xt_pknock internally keeps, should there be a DDoS on the
-first-in-row knock port from more hostile IPs than what is the actual size
+first-in-row knock port from more hostile IP addresses than what the actual size
-of this table (16, can be changed via 'peer_hasht_ents' module parameter).
+of this table is (defaults to 16, can be changed via the "peer_hasht_ents" module parameter).
-It is also wise to use as short \fB--time\fP as possible (1 second)
+It is also wise to use as short a time as possible (1 second) for \fB--time\fP
-for this very reason, too. You may also consider increasing the size
+for this very reason. You may also consider increasing the size
-of peer knock-state tracking table. Using \fB--strict\fP also helps,
+of the 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
+hostile 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.
@@ -100,13 +101,13 @@ 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
+There is a rate limiter built into xt_pknock which blocks any subsequent
-opening attempt in UDP mode, should it arrive in period shorter than 1
+open attempt in UDP mode should the request arrive within less than one
-minute since the first successfull opening. This is intentional;
+minute since the first successful open. This is intentional;
 it thwarts eventual spoofing attacks.
 .PP
-Becouse the payload value of UDP knock packet is influenced by client's IP,
+Because the payload value of an UDP knock packet is influenced by client's IP address,
 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'.
+\fBknock-orig.sh\fP. These may be found in doc/pknock/util.