1 /*- 2 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3 * 4 * Copyright (c) 2005-2009 Sam Leffler, Errno Consulting 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 * 27 * $FreeBSD$ 28 */ 29 #ifndef _NET80211_IEEE80211_SCAN_H_ 30 #define _NET80211_IEEE80211_SCAN_H_ 31 32 /* 33 * 802.11 scanning support. 34 * 35 * Scanning is the procedure by which a station locates a bss to join 36 * (infrastructure/ibss mode), or a channel to use (when operating as 37 * an ap or ibss master). Scans are either "active" or "passive". An 38 * active scan causes one or more probe request frames to be sent on 39 * visiting each channel. A passive request causes each channel in the 40 * scan set to be visited but no frames to be transmitted; the station 41 * only listens for traffic. Note that active scanning may still need 42 * to listen for traffic before sending probe request frames depending 43 * on regulatory constraints; the 802.11 layer handles this by generating 44 * a callback when scanning on a ``passive channel'' when the 45 * IEEE80211_FEXT_PROBECHAN flag is set. 46 * 47 * A scan operation involves constructing a set of channels to inspect 48 * (the scan set), visiting each channel and collecting information 49 * (e.g. what bss are present), and then analyzing the results to make 50 * decisions like which bss to join. This process needs to be as fast 51 * as possible so we do things like intelligently construct scan sets 52 * and dwell on a channel only as long as necessary. The scan code also 53 * maintains a cache of recent scan results and uses it to bypass scanning 54 * whenever possible. The scan cache is also used to enable roaming 55 * between access points when operating in infrastructure mode. 56 * 57 * Scanning is handled with pluggable modules that implement "policy" 58 * per-operating mode. The core scanning support provides an 59 * instrastructure to support these modules and exports a common api 60 * to the rest of the 802.11 layer. Policy modules decide what 61 * channels to visit, what state to record to make decisions (e.g. ap 62 * mode scanning for auto channel selection keeps significantly less 63 * state than sta mode scanning for an ap to associate to), and selects 64 * the final station/channel to return as the result of a scan. 65 * 66 * Scanning is done synchronously when initially bringing a vap to an 67 * operational state and optionally in the background to maintain the 68 * scan cache for doing roaming and rogue ap monitoring. Scanning is 69 * not tied to the 802.11 state machine that governs vaps though there 70 * is linkage to the IEEE80211_SCAN state. Only one vap at a time may 71 * be scanning; this scheduling policy is handled in ieee80211_new_state 72 * and is invisible to the scanning code. 73 */ 74 #define IEEE80211_SCAN_MAX IEEE80211_CHAN_MAX 75 76 struct ieee80211_scanner; /* scan policy state */ 77 78 struct ieee80211_scan_ssid { 79 int len; /* length in bytes */ 80 uint8_t ssid[IEEE80211_NWID_LEN]; /* ssid contents */ 81 }; 82 #define IEEE80211_SCAN_MAX_SSID 1 /* max # ssid's to probe */ 83 84 /* 85 * High-level implementation visible to ieee80211_scan.[ch]. 86 * 87 * The default scanner (ieee80211_scan_sw.[ch]) implements a software 88 * driven scanner. Firmware driven scanning needs a different set of 89 * behaviours. 90 */ 91 struct ieee80211_scan_methods { 92 void (*sc_attach)(struct ieee80211com *); 93 void (*sc_detach)(struct ieee80211com *); 94 void (*sc_vattach)(struct ieee80211vap *); 95 void (*sc_vdetach)(struct ieee80211vap *); 96 void (*sc_set_scan_duration)(struct ieee80211vap *, u_int); 97 int (*sc_start_scan)(const struct ieee80211_scanner *, 98 struct ieee80211vap *, int, u_int, u_int, u_int, u_int, 99 const struct ieee80211_scan_ssid ssids[]); 100 int (*sc_check_scan)(const struct ieee80211_scanner *, 101 struct ieee80211vap *, int, u_int, u_int, u_int, u_int, 102 const struct ieee80211_scan_ssid ssids[]); 103 int (*sc_bg_scan)(const struct ieee80211_scanner *, 104 struct ieee80211vap *, int); 105 void (*sc_cancel_scan)(struct ieee80211vap *); 106 void (*sc_cancel_anyscan)(struct ieee80211vap *); 107 void (*sc_scan_next)(struct ieee80211vap *); 108 void (*sc_scan_done)(struct ieee80211vap *); 109 void (*sc_scan_probe_curchan)(struct ieee80211vap *, int); 110 void (*sc_add_scan)(struct ieee80211vap *, 111 struct ieee80211_channel *, 112 const struct ieee80211_scanparams *, 113 const struct ieee80211_frame *, 114 int, int, int); 115 }; 116 117 /* 118 * Scan state visible to the 802.11 layer. Scan parameters and 119 * results are stored in this data structure. The ieee80211_scan_state 120 * structure is extended with space that is maintained private to 121 * the core scanning support. We allocate one instance and link it 122 * to the ieee80211com structure; then share it between all associated 123 * vaps. We could allocate multiple of these, e.g. to hold multiple 124 * scan results, but this is sufficient for current needs. 125 */ 126 struct ieee80211_scan_state { 127 struct ieee80211vap *ss_vap; 128 struct ieee80211com *ss_ic; 129 const struct ieee80211_scanner *ss_ops; /* policy hookup, see below */ 130 void *ss_priv; /* scanner private state */ 131 uint16_t ss_flags; 132 #define IEEE80211_SCAN_NOPICK 0x0001 /* scan only, no selection */ 133 #define IEEE80211_SCAN_ACTIVE 0x0002 /* active scan (probe req) */ 134 #define IEEE80211_SCAN_PICK1ST 0x0004 /* ``hey sailor'' mode */ 135 #define IEEE80211_SCAN_BGSCAN 0x0008 /* bg scan, exit ps at end */ 136 #define IEEE80211_SCAN_ONCE 0x0010 /* do one complete pass */ 137 #define IEEE80211_SCAN_NOBCAST 0x0020 /* no broadcast probe req */ 138 #define IEEE80211_SCAN_NOJOIN 0x0040 /* no auto-sequencing */ 139 #define IEEE80211_SCAN_GOTPICK 0x1000 /* got candidate, can stop */ 140 uint8_t ss_nssid; /* # ssid's to probe/match */ 141 struct ieee80211_scan_ssid ss_ssid[IEEE80211_SCAN_MAX_SSID]; 142 /* ssid's to probe/match */ 143 /* ordered channel set */ 144 struct ieee80211_channel *ss_chans[IEEE80211_SCAN_MAX]; 145 uint16_t ss_next; /* ix of next chan to scan */ 146 uint16_t ss_last; /* ix+1 of last chan to scan */ 147 unsigned long ss_mindwell; /* min dwell on channel */ 148 unsigned long ss_maxdwell; /* max dwell on channel */ 149 }; 150 151 /* 152 * The upper 16 bits of the flags word is used to communicate 153 * information to the scanning code that is NOT recorded in 154 * ss_flags. It might be better to split this stuff out into 155 * a separate variable to avoid confusion. 156 */ 157 #define IEEE80211_SCAN_FLUSH 0x00010000 /* flush candidate table */ 158 #define IEEE80211_SCAN_NOSSID 0x80000000 /* don't update ssid list */ 159 160 struct ieee80211com; 161 void ieee80211_scan_attach(struct ieee80211com *); 162 void ieee80211_scan_detach(struct ieee80211com *); 163 void ieee80211_scan_vattach(struct ieee80211vap *); 164 void ieee80211_scan_vdetach(struct ieee80211vap *); 165 166 void ieee80211_scan_dump_channels(const struct ieee80211_scan_state *); 167 168 #define IEEE80211_SCAN_FOREVER 0x7fffffff 169 int ieee80211_start_scan(struct ieee80211vap *, int flags, 170 u_int duration, u_int mindwell, u_int maxdwell, 171 u_int nssid, const struct ieee80211_scan_ssid ssids[]); 172 int ieee80211_check_scan(struct ieee80211vap *, int flags, 173 u_int duration, u_int mindwell, u_int maxdwell, 174 u_int nssid, const struct ieee80211_scan_ssid ssids[]); 175 int ieee80211_check_scan_current(struct ieee80211vap *); 176 int ieee80211_bg_scan(struct ieee80211vap *, int); 177 void ieee80211_cancel_scan(struct ieee80211vap *); 178 void ieee80211_cancel_anyscan(struct ieee80211vap *); 179 void ieee80211_scan_next(struct ieee80211vap *); 180 void ieee80211_scan_done(struct ieee80211vap *); 181 void ieee80211_probe_curchan(struct ieee80211vap *, int); 182 struct ieee80211_channel *ieee80211_scan_pickchannel(struct ieee80211com *, int); 183 184 struct ieee80211_scanparams; 185 void ieee80211_add_scan(struct ieee80211vap *, 186 struct ieee80211_channel *, 187 const struct ieee80211_scanparams *, 188 const struct ieee80211_frame *, 189 int subtype, int rssi, int noise); 190 void ieee80211_scan_timeout(struct ieee80211com *); 191 192 void ieee80211_scan_assoc_success(struct ieee80211vap *, 193 const uint8_t mac[IEEE80211_ADDR_LEN]); 194 enum { 195 IEEE80211_SCAN_FAIL_TIMEOUT = 1, /* no response to mgmt frame */ 196 IEEE80211_SCAN_FAIL_STATUS = 2 /* negative response to " " */ 197 }; 198 void ieee80211_scan_assoc_fail(struct ieee80211vap *, 199 const uint8_t mac[IEEE80211_ADDR_LEN], int reason); 200 void ieee80211_scan_flush(struct ieee80211vap *); 201 202 struct ieee80211_scan_entry; 203 typedef void ieee80211_scan_iter_func(void *, 204 const struct ieee80211_scan_entry *); 205 void ieee80211_scan_iterate(struct ieee80211vap *, 206 ieee80211_scan_iter_func, void *); 207 enum { 208 IEEE80211_BPARSE_BADIELEN = 0x01, /* ie len past end of frame */ 209 IEEE80211_BPARSE_RATES_INVALID = 0x02, /* invalid RATES ie */ 210 IEEE80211_BPARSE_XRATES_INVALID = 0x04, /* invalid XRATES ie */ 211 IEEE80211_BPARSE_SSID_INVALID = 0x08, /* invalid SSID ie */ 212 IEEE80211_BPARSE_CHAN_INVALID = 0x10, /* invalid FH/DSPARMS chan */ 213 IEEE80211_BPARSE_OFFCHAN = 0x20, /* DSPARMS chan != curchan */ 214 IEEE80211_BPARSE_BINTVAL_INVALID= 0x40, /* invalid beacon interval */ 215 IEEE80211_BPARSE_CSA_INVALID = 0x80, /* invalid CSA ie */ 216 IEEE80211_BPARSE_MESHID_INVALID = 0x100, /* invalid Mesh ID ie */ 217 }; 218 219 /* 220 * Parameters supplied when adding/updating an entry in a 221 * scan cache. Pointer variables should be set to NULL 222 * if no data is available. Pointer references can be to 223 * local data; any information that is saved will be copied. 224 * All multi-byte values must be in host byte order. 225 */ 226 struct ieee80211_scanparams { 227 uint32_t status; /* bitmask of IEEE80211_BPARSE_* */ 228 uint8_t chan; /* channel # from FH/DSPARMS */ 229 uint8_t bchan; /* curchan's channel # */ 230 uint8_t fhindex; 231 uint16_t fhdwell; /* FHSS dwell interval */ 232 uint16_t capinfo; /* 802.11 capabilities */ 233 uint16_t erp; /* NB: 0x100 indicates ie present */ 234 uint16_t bintval; 235 uint8_t timoff; 236 uint8_t *ies; /* all captured ies */ 237 size_t ies_len; /* length of all captured ies */ 238 uint8_t *tim; 239 uint8_t *tstamp; 240 uint8_t *country; 241 uint8_t *ssid; 242 uint8_t *rates; 243 uint8_t *xrates; 244 uint8_t *doth; 245 uint8_t *wpa; 246 uint8_t *rsn; 247 uint8_t *wme; 248 uint8_t *htcap; 249 uint8_t *htinfo; 250 uint8_t *ath; 251 uint8_t *tdma; 252 uint8_t *csa; 253 uint8_t *quiet; 254 uint8_t *meshid; 255 uint8_t *meshconf; 256 uint8_t *vhtcap; 257 uint8_t *vhtopmode; 258 uint8_t *spare[1]; 259 }; 260 261 /* 262 * Scan cache entry format used when exporting data from a policy 263 * module; this data may be represented some other way internally. 264 */ 265 struct ieee80211_scan_entry { 266 uint8_t se_macaddr[IEEE80211_ADDR_LEN]; 267 uint8_t se_bssid[IEEE80211_ADDR_LEN]; 268 /* XXX can point inside se_ies */ 269 uint8_t se_ssid[2+IEEE80211_NWID_LEN]; 270 uint8_t se_rates[2+IEEE80211_RATE_MAXSIZE]; 271 uint8_t se_xrates[2+IEEE80211_RATE_MAXSIZE]; 272 union { 273 uint8_t data[8]; 274 u_int64_t tsf; 275 } se_tstamp; /* from last rcv'd beacon */ 276 uint16_t se_intval; /* beacon interval (host byte order) */ 277 uint16_t se_capinfo; /* capabilities (host byte order) */ 278 struct ieee80211_channel *se_chan;/* channel where sta found */ 279 uint16_t se_timoff; /* byte offset to TIM ie */ 280 uint16_t se_fhdwell; /* FH only (host byte order) */ 281 uint8_t se_fhindex; /* FH only */ 282 uint8_t se_dtimperiod; /* DTIM period */ 283 uint16_t se_erp; /* ERP from beacon/probe resp */ 284 int8_t se_rssi; /* avg'd recv ssi */ 285 int8_t se_noise; /* noise floor */ 286 uint8_t se_cc[2]; /* captured country code */ 287 uint8_t se_meshid[2+IEEE80211_MESHID_LEN]; 288 struct ieee80211_ies se_ies; /* captured ie's */ 289 u_int se_age; /* age of entry (0 on create) */ 290 }; 291 MALLOC_DECLARE(M_80211_SCAN); 292 293 /* 294 * Template for an in-kernel scan policy module. 295 * Modules register with the scanning code and are 296 * typically loaded as needed. 297 */ 298 struct ieee80211_scanner { 299 const char *scan_name; /* printable name */ 300 int (*scan_attach)(struct ieee80211_scan_state *); 301 int (*scan_detach)(struct ieee80211_scan_state *); 302 int (*scan_start)(struct ieee80211_scan_state *, 303 struct ieee80211vap *); 304 int (*scan_restart)(struct ieee80211_scan_state *, 305 struct ieee80211vap *); 306 int (*scan_cancel)(struct ieee80211_scan_state *, 307 struct ieee80211vap *); 308 int (*scan_end)(struct ieee80211_scan_state *, 309 struct ieee80211vap *); 310 int (*scan_flush)(struct ieee80211_scan_state *); 311 struct ieee80211_channel *(*scan_pickchan)( 312 struct ieee80211_scan_state *, int); 313 /* add an entry to the cache */ 314 int (*scan_add)(struct ieee80211_scan_state *, 315 struct ieee80211_channel *, 316 const struct ieee80211_scanparams *, 317 const struct ieee80211_frame *, 318 int subtype, int rssi, int noise); 319 /* age and/or purge entries in the cache */ 320 void (*scan_age)(struct ieee80211_scan_state *); 321 /* note that association failed for an entry */ 322 void (*scan_assoc_fail)(struct ieee80211_scan_state *, 323 const uint8_t macaddr[IEEE80211_ADDR_LEN], 324 int reason); 325 /* note that association succeed for an entry */ 326 void (*scan_assoc_success)(struct ieee80211_scan_state *, 327 const uint8_t macaddr[IEEE80211_ADDR_LEN]); 328 /* iterate over entries in the scan cache */ 329 void (*scan_iterate)(struct ieee80211_scan_state *, 330 ieee80211_scan_iter_func *, void *); 331 void (*scan_spare0)(void); 332 void (*scan_spare1)(void); 333 void (*scan_spare2)(void); 334 void (*scan_spare4)(void); 335 }; 336 void ieee80211_scanner_register(enum ieee80211_opmode, 337 const struct ieee80211_scanner *); 338 void ieee80211_scanner_unregister(enum ieee80211_opmode, 339 const struct ieee80211_scanner *); 340 void ieee80211_scanner_unregister_all(const struct ieee80211_scanner *); 341 const struct ieee80211_scanner *ieee80211_scanner_get(enum ieee80211_opmode); 342 void ieee80211_scan_update_locked(struct ieee80211vap *vap, 343 const struct ieee80211_scanner *scan); 344 void ieee80211_scan_copy_ssid(struct ieee80211vap *vap, 345 struct ieee80211_scan_state *ss, 346 int nssid, const struct ieee80211_scan_ssid ssids[]); 347 void ieee80211_scan_dump_probe_beacon(uint8_t subtype, int isnew, 348 const uint8_t mac[IEEE80211_ADDR_LEN], 349 const struct ieee80211_scanparams *sp, int rssi); 350 void ieee80211_scan_dump(struct ieee80211_scan_state *ss); 351 352 #endif /* _NET80211_IEEE80211_SCAN_H_ */ 353