document passive OS fingerprinting

4 files changed, 419 insertions, 10 deletions

diff --git a/share/man/man4/pf.4 b/share/man/man4/pf.4
index 397f84fbfee..28d12852370 100644
--- a/share/man/man4/pf.4
+++ b/share/man/man4/pf.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pf.4,v 1.34 2003/08/11 20:39:38 dhartmei Exp $
+.\"	$OpenBSD: pf.4,v 1.35 2003/08/21 19:12:59 frantzen Exp $
 .\"
 .\" Copyright (C) 2001, Kjell Wooding.  All rights reserved.
 .\"
@@ -546,6 +546,83 @@ A valid ticket must also be supplied to pfrio_ticket.
 On exit, pfrio_nadd contains 0 if the table was already defined in the
 inactive list, or 1 if a new table has been created.
 pfrio_naddr contains the number of addresses effectively put in the table.
+.It Dv DIOCFPFLUSH
+Flush the passive OS fingerprint table.
+.It Dv DIOCFPADD Fa "struct pf_osfp_ioctl"
+.Bd -literal
+struct pf_osfp_ioctl {
+	struct pf_osfp_entry {
+		SLIST_ENTRY(pf_osfp_entry) fp_entry;
+		pf_osfp_t		fp_os;
+		char			fp_class_nm[PF_OSFP_LEN];
+		char			fp_version_nm[PF_OSFP_LEN];
+		char			fp_subtype_nm[PF_OSFP_LEN];
+	} 			fp_os;
+	u_int16_t		fp_mss;
+	u_int16_t		fp_wsize;
+	u_int16_t		fp_psize;
+	u_int8_t		fp_ttl;
+	u_int8_t		fp_wscale;
+	u_int8_t		fp_flags;
+	int			fp_getnum;
+};
+.Ed
+.Pp
+Add a passive OS fingerprint to the table.
+Set
+.Va fp_os.fp_os
+to the packed fingerprint,
+.Va fp_os.fp_class_nm
+to the name of the class (Linux, Windows, etc),
+.Va fp_os.fp_version_nm
+to the name of the version (NT, 95, 98), and
+.Va fp_os.fp_subtype_nm
+to the name of the subtype or patchlevel.
+The members
+.Va fp_mss
+.Va fp_wsize
+.Va fp_psize
+.Va fp_ttl
+and
+.Va fp_wscale
+are set to the TCP MSS, the TCP window size, the IP length and the IP TTL of
+the TCP SYN packet respectively.
+The
+.Va fp_flags
+member is filled according to the net/pfvar.h include file PF_OSFP_* defines.
+The
+.Va fp_getnum
+is not used with this ioctl.
+.Pp
+The structure's slack space must be zeroed for correct operation; memset
+the whole structure to zero before filling and sending to the kernel.
+.It Dv DIOCFPGET Fa "struct pf_osfp_ioctl"
+.Bd -literal
+struct pf_osfp_ioctl {
+	struct pf_osfp_entry {
+		SLIST_ENTRY(pf_osfp_entry) fp_entry;
+		pf_osfp_t		fp_os;
+		char			fp_class_nm[PF_OSFP_LEN];
+		char			fp_version_nm[PF_OSFP_LEN];
+		char			fp_subtype_nm[PF_OSFP_LEN];
+	} 			fp_os;
+	u_int16_t		fp_mss;
+	u_int16_t		fp_wsize;
+	u_int16_t		fp_psize;
+	u_int8_t		fp_ttl;
+	u_int8_t		fp_wscale;
+	u_int8_t		fp_flags;
+	int			fp_getnum;
+};
+.Ed
+.Pp
+Get the passive OS fingerprint number
+.Va fp_getnum
+from the kernels fingerprint list.
+The rest of the structure members will come back filled.
+Get the whole list by repeatadly incrementing the
+.Va fp_getnum
+number until the ioctl returns EBUSY.
 .El
 .Sh EXAMPLES
 The following example demonstrates how to use the DIOCNATLOOK command
diff --git a/share/man/man5/Makefile b/share/man/man5/Makefile
index 02961a78b1d..88934a7ed6f 100644
--- a/share/man/man5/Makefile
+++ b/share/man/man5/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.33 2003/07/26 07:07:08 jmc Exp $
+#	$OpenBSD: Makefile,v 1.34 2003/08/21 19:12:59 frantzen Exp $
 #	$NetBSD: Makefile,v 1.14 1995/05/11 23:13:15 cgd Exp $
 
 # missing: dump.5 plot.5
@@ -7,9 +7,10 @@ MAN=	a.out.5 acct.5 bsd.port.mk.5 bsd.regress.mk.5 core.5 dir.5 disktab.5 \
 	elf.5 ethers.5 fbtab.5 files.conf.5 forward.5 fs.5 fstab.5 \
 	genassym.cf.5 group.5 hostname.if.5 hosts.equiv.5 hosts.5 intro.5 \
 	link.5 login.conf.5 mk.conf.5 moduli.5 motd.5 myname.5 netgroup.5 \
-	networks.5 passwd.5 passwd.conf.5 pf.conf.5 phones.5 printcap.5 \
-	protocols.5 remote.5 resolv.conf.5 rpc.5 services.5 shells.5 stab.5 \
-	spamd.conf.5 sysctl.conf.5 types.5 utmp.5 wsconsctl.conf.5
+	networks.5 passwd.5 passwd.conf.5 pf.conf.5 pf.os.5 phones.5 \
+	printcap.5 protocols.5 remote.5 resolv.conf.5 rpc.5 services.5 \
+	shells.5 stab.5 spamd.conf.5 sysctl.conf.5 types.5 utmp.5 \
+	wsconsctl.conf.5
 MLINKS= dir.5 dirent.5 fs.5 inode.5 utmp.5 wtmp.5 utmp.5 lastlog.5
 MLINKS+= hosts.equiv.5 .rhosts.5
 MLINKS+= resolv.conf.5 resolver.5
diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 1b4ff530ecf..8f9ac54d041 100644
--- a/share/man/man5/pf.conf.5
+++ b/share/man/man5/pf.conf.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pf.conf.5,v 1.263 2003/07/07 09:15:54 jmc Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.264 2003/08/21 19:12:59 frantzen Exp $
 .\"
 .\" Copyright (c) 2002, Daniel Hartmeier
 .\" All rights reserved.
@@ -431,6 +431,21 @@ disables this enforcement.
 There may be non-trivial and non-obvious implications to an out of
 order ruleset.
 Consider carefully before disabling the order enforcement.
+.It Ar set fingerprints
+Load fingerprints of known operating systems from the given filename.
+By default fingerprints of known operating systems are automatically
+loaded from
+.Xr pf.os 5
+in /etc but can be overridden via this option.
+Setting this option may leave a small period of time where the fingerprints
+referenced by the currently active ruleset are inconsistent until the new
+ruleset finishes loading.
+.Pp
+For example:
+.Bd -literal -offset indent
+set fingerprints "/etc/pf.os.devel"
+.Ed
+.Pp
 .El
 .Sh TRAFFIC NORMALIZATION
 Traffic normalization is used to sanitize packet content in such
@@ -1132,7 +1147,7 @@ For a list of all the protocol name to number mappings used by
 .Xr pfctl 8 ,
 see the file
 .Em /etc/protocols .
-.It Ar from <source> port <source> to <dest> port <dest>
+.It Ar from <source> port <source> os <source> to <dest> port <dest>
 This rule applies only to packets with the specified source and destination
 addresses and ports.
 .Pp
@@ -1204,7 +1219,15 @@ means
 hence ports 1-1999 and 2005-65535.
 .El
 .Pp
-The host and port specifications are optional, as in the following examples:
+The operating system of the source host can be specified in the case of TCP
+rules with the
+.Ar OS
+modifier.
+See the
+.Sx OPERATING SYSTEM FINGERPRINTING
+section for more information.
+.Pp
+The host, port and OS specifications are optional, as in the following examples:
 .Bd -literal -offset indent
 pass in all
 pass in from any to any
@@ -1212,6 +1235,7 @@ pass in proto tcp from any port <= 1024 to any
 pass in proto tcp from any to any port 25
 pass in proto tcp from 10.0.0.0/8 port > 1024 \e
       to ! 10.1.2.3 port != ssh
+pass in proto tcp from any os "OpenBSD" flags S/SA
 .Ed
 .It Ar all
 This is equivalent to "from any to any".
@@ -1713,6 +1737,75 @@ pass in proto tcp from any to any \e
       (max 100, tcp.established 60, tcp.closing 5)
 .Ed
 .El
+.Sh OPERATING SYSTEM FINGERPRINTING
+Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP
+connection's initial SYN packet and guess at the host's operating system.
+Unfortunately these nuaces are easily spoofed by an attacker so the
+fingerprint is not useful in making security decisions.
+But the fingerprint is typically accurate enough to make policy decisions
+upon.
+.Pp
+The fingerprints may be specified by operating system class, by
+version, or by subtype/patchlevel.
+The class of an operating system is typically the vender or genre
+and would be OpenBSD for the
+.Xr pf 4
+firewall itself.
+The version of the oldest available OpenBSD release on the main ftp site
+would be 2.6 and the fingerprint would be written
+.Bd -literal indent
+	"OpenBSD 2.6"
+.Ed
+.Pp
+The subtype of an operating system is typically used to describe the
+patchlevel if that patch led to changes in the TCP stack behavior.
+In the case of OpenBSD, the only subtype is for a fingerprint on the
+loopback interface lo0 since it utilizes a different TCP maximum segment
+size and would be specified like
+.Bd -literal indent
+	"OpenBSD 3.3 lo0"
+.Ed
+.Pp
+Fingerprints for most popular operating systems are provided by
+.Xr pf.os 5 .
+Once 
+.Xr pf 4
+is running, a complete list of known operating system fingerprints may
+be listed by running:
+.Bd -literal -offset indent
+# pfctl -so
+.Ed
+.Pp
+Filter rules can enforce policy at any level of operating system specification
+assuming a fingerprint is present.
+Policy could limit traffic to approved operating systems or even ban traffic
+from hosts that aren't at the latest service pack.
+.Pp
+The
+.Ar unknown
+class can also be used as the fingerprint which will match packets for
+which no operating system fingerprint is known.
+.Pp
+Examples:
+.Bd -literal -offset indent
+pass  out proto tcp from any os OpenBSD keep state
+block out proto tcp from any os Doors
+block out proto tcp from any os "Doors PT"
+block out proto tcp from any os "Doors PT SP3"
+block out from any os "unknown"
+pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" keep state
+.Ed
+.Pp
+Operating system fingerprinting is limited only to the TCP SYN packet.
+This means that it will not work on other protocols and will not match
+a curretly established connection.
+.Pp
+Caveat: operating system fingerprints are occasionally wrong.
+There are three problems: an attacker can trivially craft his packets to
+appear as any operating system he chooses;
+an operating system patch could change the stack behavior and no fingerprints
+will match it until the database is updated;
+and multiple operating systems may have the same fingerprint.
 .Sh BLOCKING SPOOFED TRAFFIC
 "Spoofing" is the faking of IP addresses, typically for malicious
 purposes.
@@ -2141,6 +2234,11 @@ pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e
 pass in on $ext_if proto tcp from any to 157.161.48.183 port >= 49152 \e
       flags S/SA keep state
 
+# Do not allow Windows 9x SMTP connections since they are typically
+# a viral worm.  Alternately we could limit these OSes to 1 connection each.
+block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e
+      to any port smtp
+
 # Packet Tagging
 
 # three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is
@@ -2181,7 +2279,8 @@ option         = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] |
                  [ "limit" ( limit-item | "{" limit-list "}" ) ] |
                  [ "loginterface" ( interface-name | "none" ) ] |
                  [ "block-policy" ( "drop" | "return" ) ] |
-                 [ "require-order" ( "yes" | "no" ) ] )
+                 [ "require-order" ( "yes" | "no" ) ]
+                 [ "fingerprints" filename ] )
 
 pf-rule        = action [ ( "in" | "out" ) ]
                  [ "log" | "log-all" ] [ "quick" ]
@@ -2267,7 +2366,7 @@ proto-list     = ( proto-name | proto-number ) [ [ "," ] proto-list ]
 
 hosts          = "all" |
                  "from" ( "any" | "no-route" | "self" | host |
-                 "{" host-list "}" ) [ port ]
+                 "{" host-list "}" ) [ port ] [ os ]
                  "to"   ( "any" | "no-route" | "self" | host |
                  "{" host-list "}" ) [ port ]
 
@@ -2283,6 +2382,7 @@ routehost-list = routehost [ [ "," ] routehost-list ]
 
 port           = "port" ( unary-op | binary-op | "{" op-list "}" )
 portspec       = "port" ( number | name ) [ ":" ( "*" | number | name ) ]
+os             = "os"  ( os-name | "{" os-list "}" )
 user           = "user" ( unary-op | binary-op | "{" op-list "}" )
 group          = "group" ( unary-op | binary-op | "{" op-list "}" )
 
@@ -2291,6 +2391,9 @@ unary-op       = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ]
 binary-op      = number ( "<>" | "><" | ":" ) number
 op-list        = ( unary-op | binary-op ) [ [ "," ] op-list ]
 
+os-name        = operating-system-name
+os-list        = os-name [ [ "," ] os-list ]
+
 flags          = "flags" [ flag-set ] "/" flag-set
 flag-set       = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ]
                  [ "W" ]
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