usr.sbin/pfctl/pf.os.5

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