doc/SoH.txt

   1 == Intro ==
   2
   3 This release adds support for Microsoft Statement-of-Health (SoH), which is
   4 a form of network access protection.
   5
   6 Client supprot is present in Windows XP SP3, Vista and 7.
   7
   8 SoH data can come in from several places:
   9
  10  * inside EAP-PEAP packets for 802.1x wireless/wired connections
  11  * inside a radius packet (Microsoft VSA #55, MS-Quarantine-SOH) - VPN and
  12    terminal services gateways can act as the radius client
  13  * inside a DHCP request, in vendor-specific options
  14
  15 FreeRadius supports all three types. The SoH statement is decoded into
  16 radius-style attributes, and you can write a policy in "unlang" to act
  17 on them, and permit, restrict or deny network access.
  18
  19 == PEAP support ==
  20
  21 SoH support in peap is enabled in eap.conf using config like so:
  22
  23  eap {
  24   peap {
  25    soh = yes
  26    soh_virtual_server = "soh-server"
  27   }
  28  }
  29
  30 When SoH is enabled, an EAP-PEAP client will be challenged to provide an
  31 SoH statement after providing it's identity (or resuming a PEAP session via
  32 SSL session resumption). Clients which do not support PEAP will NAK the
  33 request, and clients which do will answer it.
  34
  35 The client reply will be written into a fake radius request and sent to the
  36 virtual server specified above; it will either look like:
  37
  38  SoH-Supported = no
  39
  40 ...or (from a Vista machine):
  41
  42  SoH-Supported = yes
  43  SoH-MS-Machine-OS-vendor = Microsoft
  44  SoH-MS-Machine-OS-version = 6
  45  SoH-MS-Machine-OS-release = 0
  46  SoH-MS-Machine-OS-build = 6001
  47  SoH-MS-Machine-SP-version = 1
  48  SoH-MS-Machine-SP-release = 0
  49  SoH-MS-Machine-Processor = x86_64
  50  SoH-MS-Machine-Name = "netbios.example.com"
  51  SoH-MS-Correlation-Id = 0x54468936cb494374b127a6a3cc3bb11c01ca78d858ee1ef0
  52  SoH-MS-Machine-Role = client
  53  SoH-MS-Windows-Health-Status = "firewall ok snoozed=0 microsoft=1 up2date=1 enabled=1"
  54  SoH-MS-Windows-Health-Status = "antivirus error not-installed"
  55  SoH-MS-Windows-Health-Status = "antispyware ok snoozed=0 microsoft=1 up2date=1 enabled=1"
  56  SoH-MS-Windows-Health-Status = "auto-updates ok action=install"
  57  SoH-MS-Windows-Health-Status = "security-updates warn some-missing"
  58
  59 If you have "copy_request_to_tunnel = yes" set on the peap module, the
  60 request variables like NAS-IP-Address and so on will be copied to the fake
  61 request as well.
  62
  63 Clients without SoH seem to just NAK the SoH request and continue with the inner
  64 EAP auth. This has been tested as working with Windows XP SP2 and lower, Linux
  65 clients using NetworkManager & wpa_supplicant, MacOS 10.5, Nokia/Symbian S60 and
  66 iPhone OS 3.x. It should therefore be safe to deploy.
  67
  68 == Radius support ==
  69
  70 If you are running a Microsoft VPN or Terminal Services Gateway, these can
  71 be configured to send the SoH data to an upstream radius server, in this
  72 case presumably FreeRadius. To take advantage of this you will need to add
  73 the "soh" module to the "authorize" section of your virtual server, like so:
  74
  75 server tsgateway {
  76   preprocess
  77   soh
  78   if () {
  79     ... policy goes here
  80   }
  81 }
  82
  83 The SoH module simply looks for the Microsoft VSA #55 and decodes the SoH
  84 data, adding the SoH attributes to the request - see above for an example
  85 of the available attributes.
  86
  87 The SoH module also does dynamic expansions - see below for more info.
  88
  89 == DHCP support ==
  90
  91 If you compile FreeRadius with DHCP support, the "soh" module can challenge
  92 a DHCP client for SoH data in the DHCPOFFER packet. As with normal radius,
  93 the SoH attributes are added to the request. You would use like so:
  94
  95 server dhcp {
  96   dhcp DHCP-Discover {
  97     soh
  98     # note - no SoH attributes are added here, the client hasn't sent them yet
  99
 100     # other DHCP config
 101   }
 102
 103   dhcp DHCP-Request {
 104     soh
 105     if () {
 106       # SoH policy
 107     }
 108     # other DHCP config
 109   }
 110 }
 111
 112 == soh module ==
 113
 114 The "soh" module decodes the radius & DHCP payloads. It also makes some dynamic
 115 variables available, for example:
 116
 117 authorize {
 118   soh
 119   update request {
 120     Tmp-String-0 = "%{soh:OS}"
 121   }
 122 }
 123
 124 ...will give you a string like "Windows Vista 6.1.100 sp 1.0" or "Windows XP 5.x.x sp 3.0"
 125
 126 At the moment, this is the only dynamic expansion; in future, we will make
 127 various bits of info available, for example non-Microsoft SoH records (see below)
 128
 129 == Non-microsoft SoH data ==
 130
 131 The Windows SoH structure is extensible and, in principle, clients can be
 132 extended with .dll plugins to add vendor-specific info to the SoH, which
 133 can then be checked on the server.
 134
 135 At the present time, few plugins are known and I have seen none, so can't
 136 add support for them.
 137
 138 == Client configuration ==
 139
 140 The code works fine with Win XP SP3 & Vista on both wired & wireless. However
 141 contrary to what some sites claim, the NAP service is disabled by default, as
 142 are the many NAP remediation agents. These can be enabled from the command prompt
 143 with (for XP; instructions may differ for other windows versions):
 144
 145  sc config napagent start= auto
 146  sc start napagent
 147
 148  # optionally for wired 802.1x; the dot3svc should usually be made dependent
 149  # on the napagent service, else the machine might attempt 802.1x before NAP
 150  # has started...
 151
 152  sc config dot3svc start= auto depend= napagent
 153  sc start dot3svc
 154
 155  # enable the EAP agent
 156  netsh nap client show config
 157
 158  # get the "ID" value for the "EAP Quarantine Enforcement Client"
 159  netsh nap client set enforce id=$ID admin=enable
 160
 161  # repeat for DHCP, VPN or Terminal Services agents
 162
 163 This can be automated via Group Policy.
 164
 165 You then need to enable EAP, PEAP, Quarantine Checks & the relevant auth method
 166 on the relevant adapters. This can be done with "netsh xml profiles" or Group
 167 Policy - google for the relevant terms, or see the MS article:
 168
 169  http://technet.microsoft.com/en-us/library/bb726965.aspx
 170
 171 ...and related links.
 172
 173 == TODO ==
 174
 175 Currently the code does not support sending the final SoH reply. This
 176 is because the SoH reply (see section 2.2.9 of MS-SOH version
 177 v20091104) needs various fields formatted in a manner which is not
 178 obvious to me, and I don't currently have access to a windows NAP
 179 server to look at a working example. The clients I have access don't
 180 seem to mind.
 181
 182  Phil Mayers <p.mayers@imperial.ac.uk>
 183  December 2009