3 This release adds support for Microsoft Statement-of-Health (SoH), which is
4 a form of network access protection.
6 Client supprot is present in Windows XP SP3, Vista and 7.
8 SoH data can come in from several places:
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
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.
21 SoH support in peap is enabled in eap.conf using config like so:
26 soh_virtual_server = "soh-server"
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.
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:
40 ...or (from a Vista machine):
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"
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
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.
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:
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.
87 The SoH module also does dynamic expansions - see below for more info.
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:
98 # note - no SoH attributes are added here, the client hasn't sent them yet
114 The "soh" module decodes the radius & DHCP payloads. It also makes some dynamic
115 variables available, for example:
120 Tmp-String-0 = "%{soh:OS}"
124 ...will give you a string like "Windows Vista 6.1.100 sp 1.0" or "Windows XP 5.x.x sp 3.0"
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)
129 == Non-microsoft SoH data ==
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.
135 At the present time, few plugins are known and I have seen none, so can't
136 add support for them.
138 == Client configuration ==
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):
145 sc config napagent start= auto
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
152 sc config dot3svc start= auto depend= napagent
155 # enable the EAP agent
156 netsh nap client show config
158 # get the "ID" value for the "EAP Quarantine Enforcement Client"
159 netsh nap client set enforce id=$ID admin=enable
161 # repeat for DHCP, VPN or Terminal Services agents
163 This can be automated via Group Policy.
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:
169 http://technet.microsoft.com/en-us/library/bb726965.aspx
171 ...and related links.
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
182 Phil Mayers <p.mayers@imperial.ac.uk>