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