contrib/pf/man/pf.os.5

   1 .\"     $OpenBSD: pf.os.5,v 1.8 2007/05/31 19:19:58 jmc Exp $
   2 .\"
   3 .\" Copyright (c) 2003 Mike Frantzen <frantzen@w4g.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .\" $FreeBSD$
  18 .\"
  19 .Dd May 31 2007
  20 .Dt PF.OS 5
  21 .Os
  22 .Sh NAME
  23 .Nm pf.os
  24 .Nd format of the operating system fingerprints file
  25 .Sh DESCRIPTION
  26 The
  27 .Xr pf 4
  28 firewall and the
  29 .Xr tcpdump 1
  30 program can both fingerprint the operating system of hosts that
  31 originate an IPv4 TCP connection.
  32 The file consists of newline-separated records, one per fingerprint,
  33 containing nine colon
  34 .Pq Ql \&:
  35 separated fields.
  36 These fields are as follows:
  37 .Pp
  38 .Bl -tag -width Description -offset indent -compact
  39 .It window
  40 The TCP window size.
  41 .It TTL
  42 The IP time to live.
  43 .It df
  44 The presence of the IPv4 don't fragment bit.
  45 .It packet size
  46 The size of the initial TCP packet.
  47 .It TCP options
  48 An ordered list of the TCP options.
  49 .It class
  50 The class of operating system.
  51 .It version
  52 The version of the operating system.
  53 .It subtype
  54 The subtype of patchlevel of the operating system.
  55 .It description
  56 The overall textual description of the operating system, version and subtype.
  57 .El
  58 .Pp
  59 The
  60 .Ar window
  61 field corresponds to the th->th_win field in the TCP header and is the
  62 source host's advertised TCP window size.
  63 It may be between zero and 65,535 inclusive.
  64 The window size may be given as a multiple of a constant by prepending
  65 the size with a percent sign
  66 .Sq %
  67 and the value will be used as a modulus.
  68 Three special values may be used for the window size:
  69 .Pp
  70 .Bl -tag -width xxx -offset indent -compact
  71 .It *
  72 An asterisk will wildcard the value so any window size will match.
  73 .It S
  74 Allow any window size which is a multiple of the maximum segment size (MSS).
  75 .It T
  76 Allow any window size which is a multiple of the maximum transmission unit
  77 (MTU).
  78 .El
  79 .Pp
  80 The
  81 .Ar ttl
  82 value is the initial time to live in the IP header.
  83 The fingerprint code will account for the volatility of the packet's TTL
  84 as it traverses a network.
  85 .Pp
  86 The
  87 .Ar df
  88 bit corresponds to the Don't Fragment bit in an IPv4 header.
  89 It tells intermediate routers not to fragment the packet and is used for
  90 path MTU discovery.
  91 It may be either a zero or a one.
  92 .Pp
  93 The
  94 .Ar packet size
  95 is the literal size of the full IP packet and is a function of all of
  96 the IP and TCP options.
  97 .Pp
  98 The
  99 .Ar TCP options
 100 field is an ordered list of the individual TCP options that appear in the
 101 SYN packet.
 102 Each option is described by a single character separated by a comma and
 103 certain ones may include a value.
 104 The options are:
 105 .Pp
 106 .Bl -tag -width Description -offset indent -compact
 107 .It Mnnn
 108 maximum segment size (MSS) option.
 109 The value is the maximum packet size of the network link which may
 110 include the
 111 .Sq %
 112 modulus or match all MSSes with the
 113 .Sq *
 114 value.
 115 .It N
 116 the NOP option (NO Operation).
 117 .It T[0]
 118 the timestamp option.
 119 Certain operating systems always start with a zero timestamp in which
 120 case a zero value is added to the option; otherwise no value is appended.
 121 .It S
 122 the Selective ACKnowledgement OK (SACKOK) option.
 123 .It Wnnn
 124 window scaling option.
 125 The value is the size of the window scaling which may include the
 126 .Sq %
 127 modulus or match all window scalings with the
 128 .Sq *
 129 value.
 130 .El
 131 .Pp
 132 No TCP options in the fingerprint may be given with a single dot
 133 .Sq \&. .
 134 .Pp
 135 An example of OpenBSD's TCP options are:
 136 .Pp
 137 .Dl M*,N,N,S,N,W0,N,N,T
 138 .Pp
 139 The first option
 140 .Ar M*
 141 is the MSS option and will match all values.
 142 The second and third options
 143 .Ar N
 144 will match two NOPs.
 145 The fourth option
 146 .Ar S
 147 will match the SACKOK option.
 148 The fifth
 149 .Ar N
 150 will match another NOP.
 151 The sixth
 152 .Ar W0
 153 will match a window scaling option with a zero scaling size.
 154 The seventh and eighth
 155 .Ar N
 156 options will match two NOPs.
 157 And the ninth and final option
 158 .Ar T
 159 will match the timestamp option with any time value.
 160 .Pp
 161 The TCP options in a fingerprint will only match packets with the
 162 exact same TCP options in the same order.
 163 .Pp
 164 The
 165 .Ar class
 166 field is the class, genre or vendor of the operating system.
 167 .Pp
 168 The
 169 .Ar version
 170 is the version of the operating system.
 171 It is used to distinguish between different fingerprints of operating
 172 systems of the same class but different versions.
 173 .Pp
 174 The
 175 .Ar subtype
 176 is the subtype or patch level of the operating system version.
 177 It is used to distinguish between different fingerprints of operating
 178 systems of the same class and same version but slightly different
 179 patches or tweaking.
 180 .Pp
 181 The
 182 .Ar description
 183 is a general description of the operating system, its version,
 184 patchlevel and any further useful details.
 185 .Sh EXAMPLES
 186 The fingerprint of a plain
 187 .Ox 3.3
 188 host is:
 189 .Bd -literal
 190   16384:64:1:64:M*,N,N,S,N,W0,N,N,T:OpenBSD:3.3::OpenBSD 3.3
 191 .Ed
 192 .Pp
 193 The fingerprint of an
 194 .Ox 3.3
 195 host behind a PF scrubbing firewall with a no-df rule would be:
 196 .Bd -literal
 197   16384:64:0:64:M*,N,N,S,N,W0,N,N,T:OpenBSD:3.3:!df:OpenBSD 3.3 scrub no-df
 198 .Ed
 199 .Pp
 200 An absolutely braindead embedded operating system fingerprint could be:
 201 .Bd -literal
 202   65535:255:0:40:.:DUMMY:1.1:p3:Dummy embedded OS v1.1p3
 203 .Ed
 204 .Pp
 205 The
 206 .Xr tcpdump 1
 207 output of
 208 .Bd -literal
 209   # tcpdump -s128 -c1 -nv 'tcp[13] == 2'
 210   03:13:48.118526 10.0.0.1.3377 > 10.0.0.2.80: S [tcp sum ok] \e
 211       534596083:534596083(0) win 57344 <mss 1460> (DF) [tos 0x10] \e
 212       (ttl 64, id 11315, len 44)
 213 .Ed
 214 .Pp
 215 almost translates into the following fingerprint
 216 .Bd -literal
 217   57344:64:1:44:M1460:  exampleOS:1.0::exampleOS 1.0
 218 .Ed
 219 .Sh SEE ALSO
 220 .Xr pf 4 ,
 221 .Xr pf.conf 5 ,
 222 .Xr pfctl 8 ,
 223 .Xr tcpdump 1