document passive OS fingerprinting

1 files changed, 228 insertions, 0 deletions

diff --git a/share/man/man5/pf.os.5 b/share/man/man5/pf.os.5
new file mode 100644
index 00000000000..0de7d9b487f
--- /dev/null
+++ b/share/man/man5/pf.os.5
@@ -0,0 +1,228 @@
+.\"	$OpenBSD: pf.os.5,v 1.1 2003/08/21 19:12:59 frantzen Exp $
+.\"
+.\" Copyright (c) 2003 Mike Frantzen <frantzen@w4g.org>
+.\" 
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\" 
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.Dd August 18, 2003
+.Dt PF.OS 5
+.Os
+.Sh NAME
+.Nm pf.os
+.Nd format of the operating system fingerprints file
+.Sh DESCRIPTION
+The
+.Xr pf 4
+firewall and the
+.Xr tcpdump 8
+program can both fingerprint the operating system of hosts that
+originate a IPv4 TCP connection.
+The file consists of newline-separated records, one per fingerprint,
+containing twelve colon
+.Pq Ql \&:
+separated fields.
+These fields are as follows:
+.Pp
+.Bl -tag -width Description -offset indent -compact
+.It window
+The TCP window size.
+.It TTL
+The IP time to live.
+.It df
+The presence of the IPv4 don't fragment bit.
+.It packet size
+The size of the initial TCP packet.
+.It TCP options
+An ordered list of the TCP options.
+.It class
+The class of operating system.
+.It version
+The version of the operating system.
+.It subtype
+The subtype of patchlevel of the operating system.
+.It description
+The overall textual description of the operating system, version and subtype.
+.El
+.Pp
+The
+.Ar window
+field corresponds to the th->th_win field in the TCP header and is the
+source host's advertised TCP window size.
+It may be between zero and 65,535 inclusive.
+The window size may be given as a multiple of a constant by prepending
+the size with a percent sign '%' and the value will be used as a modulus.
+Three special values may be used for the window size:
+.Bl -tag -width xxx -offset indent -compact
+.It *
+An asterisk will wildcard the value so any window size will match.
+.It S
+Allow any window size which is a multiple of the maximum segment size (MSS).
+.It T
+Allow any window size which is a multiple of the maximum transmission unit
+(MTU).
+.El
+.Pp
+The 
+.Ar ttl
+value is the initial time to live in the IP header.
+The fingerprint code will account for the volatility of the packets's TTL
+as it traverses a network.
+.Pp
+The
+.Ar df
+bit corresponds to the Don't Fragment bit in an IPv4 header.
+It tells intermediate routers not to fragment the packet and is used for
+path MTU discovery.
+It may be either a zero or a one.
+.Pp
+The
+.Ar packet size
+is the literal size of the full IP packet and is a function of all of
+the IP and TCP options.
+.Pp
+The
+.Ar TCP options
+field is an ordered list of the individual TCP options that appear in the
+SYN packet.
+Each option is described by a single character seperated by a comma and
+certain ones may include a value.
+The options are:
+.Bl -tag -width Description -offset indent -compact
+.It Mnnn
+maximum segment size (MSS) option.
+The value is the maximum packet size of the network link which may
+include the '%' modulus or match all MSSes with the '*' value.
+.It N
+the NOP option (NO Operation).
+.It T[0]
+the timestamp option.
+Certain operating systems always start with a zero timestamp in which
+case a zero value is added to the option; otherwise no value is appended.
+.It S
+the Selective ACKnowledgement OK (SACKOK) option.
+.It Wnnn
+window scaling option.
+The value is the size of the window scaling which may include the
+'%' modulus or match all window scalings with the '*' value.
+.El
+.Pp
+No TCP options in the fingerprint may be given with a single dot '.'.
+.Pp
+An example of OpenBSD's TCP options are:
+.Bd -literal
+	M*,N,N,S,N,W0,N,N,T
+.Ed
+.Pp
+The first option
+.Ar M*
+is the MSS option and will match all values.
+The second and third options
+.Ar N
+will match two NOPs.
+The fourth option
+.Ar S
+will match the SACKOK option.
+The fifth
+.Ar N
+will match another NOP.
+The sixth
+.Ar W0
+will match a window scaling option with a zero scaling size.
+The seventh and eigth
+.Ar N
+options will match two NOPs.
+And the nineth and final option
+.Ar T
+will match the timestamp option with any time value.
+.Pp
+The TCP options in a fingerprint will only match packets with the
+exact same TCP options in the same order.
+.Pp
+The
+.Ar class
+field is the class, genre or vender of the operating system.
+.Pp
+The
+.Ar version
+is the version of the operating system.
+It is used to distinguish between different fingerprints of operating
+systems of the same class but different versions.
+.Pp
+The
+.Ar subtype
+is the subtype or patch level of the operating system version.
+It is used to distinguish between different fingerprints of operating
+systems of the same class and same version but slightly different
+patches or tweaking.
+.Pp
+The
+.Ar description
+is is a general description of the operating system, it's version,
+patchlevel and any further useful details.
+.Sh EXAMPLES
+The fingerprint of a plain OpenBSD 3.3 host is:
+.Bd -literal
+  16384:64:1:64:M*,N,N,S,N,W0,N,N,T:OpenBSD:3.3::OpenBSD 3.3
+.Ed
+.Pp
+The fingerprint of an OpenBSD 3.3 host behind a PF scrubbing firewall
+with a no-df rule would be:
+.Bd -literal
+  16384:64:0:64:M*,N,N,S,N,W0,N,N,T:OpenBSD:3.3:!df:OpenBSD 3.3 scrub no-df
+.Ed
+.Pp
+An absolutely braindead embedded operating system fingerprint could be:
+.Bd -literal
+  65535:255:0:40:.:DUMMY:1.1:p3:Dummy embedded OS v1.1p3
+.Ed
+.Pp
+The
+.Xr tcpdump 8
+output of
+.Bd -literal
+  # tcpdump -s128 -c1 -nv 'tcp[13] == 2'
+  03:13:48.118526 10.0.0.1.3377 > 10.0.0.0.2: S [tcp sum ok] \e
+      534596083:534596083(0) win 57344 <mss 1460> (DF) [tos 0x10] \e
+      (ttl 64, id 11315)
+.Ed
+.Pp
+almost translates into the following fingerprint
+.Bd -literal
+  57344:64:1:44:M1460:	exampleOS:1.0::exampleOS 1.0
+.Ed
+.Pp
+.Xr tcpdump 8
+does not explicitly give the packet length.
+But it can usually be derived by adding the size of the IPv4 header to
+the size of the TCP header to the size of the TCP options.
+The size of both headers is typically twenty each and the usual
+sizes of the TCP options are:
+.Pp
+.Bl -tag -width timestamp -offset indent -compact
+.It mss
+four bytes.
+.It nop
+1 byte.
+.It sackOK
+two bytes.
+.It timestamp
+ten bytes.
+.It wscale
+three bytes.
+.El
+.Pp
+In the above example, the packet size comes out to 44 bytes.
+.Sh SEE ALSO
+.Xr pf.conf 5 ,
+.Xr pf 4 ,
+.Xr pfctl 8 ,
+.Xr tcpdump 8