release/src-rt/wl/nas/README

   1 NAS is a minimal VxWorks and Linux compatible Network Authentication
   2 Server that implements 802.1X port authentication (RADIUS only) and
   3 Wi-Fi Protected Access (WPA) for 802.11 networks (Broadcom drivers only).
   4
   5 The code base is split between common code (nas.c and wpa.c), driver
   6 specific code (nas_wl.c), application specific code (nas_wksp.c), and
   7 OS specific code (nas_vx.c and nas_linux.c).
   8
   9 Major features yet to be implemented include:
  10
  11 * RADIUS Accounting. See 802.1X Internet Draft 20.
  12 * Mutual authentication (802.11 IBSS mode).
  13 * Limited network access (e.g., via 802.1Q VLAN)
  14
  15 =====
  16 NAS/Driver interface:
  17
  18 NAS and the Broadcom driver communicate using two mechanisms: ioctls and
  19 802.3/SNAP frames.  Ioctls are used by NAS to query or setup driver states.
  20 802.3/SNAP frames are generated by the driver when it needs to asynchronously
  21 indicate information to NAS. 802.3/SNAP frames are also used to encapsulate
  22 802.1x frames starting from release 3.41.xx. NAS listens on a socket for
  23 these indications and encapsulated 802.1x frames.
  24
  25 -----
  26 The following ioctls are used by NAS:
  27
  28   interface discovery:
  29         WLC_GET_MAGIC
  30         WLC_GET_VERSION
  31         WLC_GET_INSTANCE
  32
  33   per interface initialization:
  34         (clear stuff)
  35         WLC_SET_EAP_RESTRICT (true)
  36         WLC_SET_WEP_RESTRICT* (true)
  37         WLC_SET_KEY (clear all default keys)
  38         WLC_SCB_DEAUTHORIZE (broadcast addr)
  39         (set up)
  40         WLC_SET_WSEC*
  41         WLC_GET_WSEC (verify that SET took)
  42         WLC_SET_WPA_AUTH*
  43
  44   during authentication:
  45         WLC_SCB_AUTHORIZE
  46         WLC_SCB_DEAUTHORIZE
  47         WLC_SET_KEY
  48         WLC_GET_KEY_TXIV
  49         WLC_SCB_DEAUTHENTICATE_FOR_REASON
  50         WLC_TKIP_COUNTERMEASURES (toggle on or off)
  51
  52   on exit:
  53         WLC_SET_EAP_RESTRICT (false)
  54         WLC_SET_WEP_RESTRICT* (false)
  55         WLC_SET_KEY (clear all default keys)
  56         WLC_SCB_DEAUTHORIZE (broadcast addr)
  57
  58   wireless bridging:
  59         WLC_WDS_GET_REMOTE_HWADDR
  60         WLC_WDS_GET_WPA_ROLE
  61         get "wds_wpa_role"
  62         set "wds_wpa_role"
  63
  64   *These are followed by gratuitous WLC_GET_SSID/WLC_SET_SSID pair.
  65
  66
  67 -----
  68 Details of the ioctls:
  69
  70 Most ioctl calls use wl_ioctl(), defined e.g. in src/router/shared/wl_vx.c as:
  71
  72         int wl_ioctl(char *pDevName, int cmd, void *buf, int len)
  73
  74 "buf" is a structure which is specific to each call.  Any portion of buf not
  75 explicitly set on input should be zero.  Structures and values not explicitly
  76 defined below are defined in src/include/wlioctl.h.
  77
  78 WLC_GET_MAGIC
  79         buf:
  80         input:
  81         output:
  82         return:
  83
  84 WLC_GET_VERSION
  85         buf:
  86         input:
  87         output:
  88         return:
  89
  90 WLC_GET_INSTANCE
  91         buf:
  92                 int
  93
  94         input:
  95                 none
  96
  97         output:
  98                 unit number/network interface instance
  99
 100         return:
 101                 0
 102
 103 WLC_SET_EAP_RESTRICT
 104         buf:
 105                 int
 106
 107         input:
 108                 buf = TRUE
 109                         require 802.1X authentication before STA can pass data frames
 110                 buf = FALSE
 111                         allow STA to pass data frames without 802.1X authentication
 112
 113         output:
 114                 none
 115
 116         return:
 117                 0
 118
 119 WLC_SET_WEP_RESTRICT
 120         buf:
 121                 int
 122
 123         input:
 124                 buf = TRUE
 125                         require all data frames to be encrypted
 126                 buf = FALSE
 127                         allow unencrypted data frames
 128
 129         output:
 130                 none
 131
 132         return:
 133                 0
 134
 135 WLC_SET_KEY:
 136         buffer:
 137                 wsec_key_t buf
 138
 139         input:
 140                 buf.index = key index (0-3)
 141                 buf.ea = address of STA (if pairwise key)
 142                 buf.flags = WSEC_PRIMARY_KEY
 143                         key is for transmit and receive
 144                 buf.flags = 0
 145                         key is for receive only
 146                 buf.len = key length in bytes
 147                         when adding a key
 148                 buf.len = 0
 149                         to delete a key
 150                 buf.data = key data
 151
 152         output:
 153                 none
 154
 155         return:
 156                 0 success
 157                 -1 invalid key index or interface currently disabled
 158
 159 WLC_SCB_DEAUTHORIZE:
 160         buf:
 161                 struct ether_addr
 162
 163         input:
 164                 buf = address of STA to be deauthorized
 165
 166         output:
 167                 none
 168
 169         return:
 170                 0
 171
 172 WLC_SET_WSEC
 173         buf:
 174                 int
 175
 176         input:
 177                 buf = any combination of TKIP_ENABLED, AES_ENABLED, WEP_ENABLED
 178
 179         output:
 180                 none
 181
 182         return:
 183                 0 success
 184                 -1 unsupported algorithm
 185
 186 WLC_GET_WSEC
 187         buf:
 188                 int
 189
 190         input:
 191                 none
 192
 193         output:
 194                 buf = any combination of TKIP_ENABLED, AES_ENABLED, WEP_ENABLED
 195
 196         return:
 197                 0 success
 198
 199 WLC_SET_WPA_AUTH
 200         buf:
 201                 int
 202
 203         input:
 204                 buf = one of WPA_AUTH_DISABLED, WPA_AUTH_PSK, or WPA_AUTH_UNSPECIFIED
 205
 206         output:
 207                 none
 208
 209         return:
 210                 0
 211
 212 WLC_SCB_AUTHORIZE
 213         buf:
 214                 struct ether_addr
 215
 216         input:
 217                 buf = address of STA to authorize
 218
 219         output:
 220                 none
 221
 222         return:
 223                 0
 224
 225 WLC_GET_KEY_TXIV:
 226         buf:
 227                 union {
 228                         int index;
 229                         wsec_iv_t iv;
 230                 } buf;
 231
 232         input:
 233             buf.index = index of key to query (0-MAXKEYS)
 234
 235         output:
 236                 buf.iv = current value of the transmit sequence counter for key
 237                         specified by buf.index
 238
 239         return:
 240                 0 success
 241                 -1 invalid key index
 242
 243 WLC_SCB_DEAUTHENTICATE_FOR_REASON
 244         buf:
 245                 scb_val_t
 246
 247         input:
 248                 buf.val = reason code
 249                 buf.ea = address of STA to be deauthenticated
 250
 251         output:
 252                 none
 253
 254         return:
 255                 0
 256
 257 WLC_TKIP_COUNTERMEASURES
 258         buf:
 259                 int
 260
 261         input:
 262                 buf = TRUE
 263                         start countermeasures
 264                 buf = TRUE
 265                         stop countermeasures
 266
 267         output:
 268                 none
 269
 270         return:
 271                 0 success
 272                 -1 TKIP not currently enabled
 273
 274 WLC_WDS_GET_REMOTE_HWADDR
 275         buf:
 276                 struct ether_addr
 277
 278         input:
 279                 none
 280
 281         output:
 282                 buf = wireless bridge's remote endpoint's mac address
 283
 284         return:
 285                 0 success
 286                 -1 the interface is not WDS
 287
 288 WLC_WDS_GET_WPA_ROLE
 289         buf:
 290                 int[2]
 291
 292         input:
 293                 buf = wireless bridge's remote endpoint's mac address
 294
 295         output:
 296                 buf[0] =  <role>
 297
 298                         role:   0 - local endpoint is WPA supplicant
 299                                 1 - local endpoint is WPA authenticator
 300
 301         return:
 302                 0 success
 303                 -1 the interface is not a wireless bridge
 304
 305 get "wds_wpa_role" (using WLC_GET_VAR ioctl)
 306         buf:
 307                 char[N]
 308
 309         input:
 310                 buf = "wds_wpa_role<null><6 bytes remote endpoint's mac address>"
 311
 312         output:
 313                 buf[0] = <role>
 314
 315                         role:   0 - local endpoint is WPA supplicant
 316                                 1 - local endpoint is WPA authenticator
 317
 318         return:
 319                 0 success
 320
 321 set "wds_wpa_role" (using WLC_SET_VAR ioctl)
 322         buf:
 323                 char[N]
 324
 325         input:
 326                 buf = "wds_wpa_role<null><6 bytes remote endpoint's mac address><1 byte role>"
 327                         role:   0 - local endpoint is WPA supplicant
 328                                 1 - local endpoint is WPA authenticator
 329                                 255 - endpoint with lower mac address is WPA supplicant
 330
 331         output:
 332                 none
 333
 334         return:
 335                 0 success
 336
 337 -----
 338 Driver communicates the indication messages to the NAS, message format is
 339
 340 Actual message data follows the header:
 341
 342 Data = (char *(wlc_secpvt_data + 1));
 343
 344 Ethernet protocol type used is ETHER_TYPE_BRCM (0x886c). Frames exchanged are ETHERNET II frames.
 345
 346 (this data structure is defined in include/wlioctl.h)
 347
 348 typedef struct wl_secpvt_data {
 349         struct ether_header eth; /*Regular ethernet header with proto type 0x886c */
 350         bcmeth_bcm_hdr_t bcm_hdr;
 351         /* user specific Data*/
 352         uint8  version;
 353         uint8  msg_type;
 354         char ifname[WL_WPA_MSG_IFNAME_MAX]; /* name of the packet incoming interface*/
 355 }wl_secpvt_data_t;
 356
 357 (this common data structure is defined in proto/bcmeth.h)
 358
 359 typedef  struct bcmeth_bcm_hdr
 360 {
 361         uint16  subtype; /* Vendor specific..32769*/
 362         uint16  length;
 363         uint8   version; /* Version is 0*/
 364         uint8   oui[3]; /* Broadcom OUI*/
 365         /* user specific Data */
 366         uint16  usr_subtype;
 367 } PACKED bcmeth_bcm_hdr_t;
 368
 369 vendor_long is defined as 32769 . to specify this as a vendor specific subtype.
 370 length field indicates the length of the actual frame from this field.
 371 version field is set to 0 BCMILCP_BCM_SUBTYPEHDR_VERSION
 372 oui is broadcom OUI. 0x00/0x10/0x18
 373 sub_type defined in bcmeth_bcm_hdr data structure identifies different messages.
 374
 375 #define BCMILCP_BCM_SUBTYPE_RESERVED    0
 376 #define BCMILCP_BCM_SUBTYPE_WPA         1
 377 #define BCMILCP_BCM_SUBTYPE_EAPOL       2
 378 #define BCMILCP_BCM_SUBTYPE_SES         3
 379
 380 once the sub_type is identified,
 381
 382 version: indicates the version of this user specific data.
 383
 384 msg_type: this has meaning only when sub_type is BCMILCP_BCM_SUBTYPE_WPA
 385
 386 /* Type field values for the WL WPA subtype  driver messages */
 387 #define WLC_ASSOC_MSG           1
 388 #define WLC_DISASSOC_MSG        2
 389 #define WLC_PTK_MIC_MSG         3
 390 #define WLC_GTK_MIC_MSG         4
 391