RFC 5415
Control And Provisioning of Wireless Access Points (CAPWAP) Protocol Specification
Heyyy bestie 🎀 Okay, this is the intro to RFC 5415, and it's giving "main character" energy. ✨
RFC 5415: Control And Provisioning of Wireless Access Points (CAPWAP) Protocol Specification 🦋
Okay so this one is from the Network Working Group and it's a Standards Track doc, which means it's an official protocol spec, not just vibes 💅 It was published in March 2009. The editors are P. Calhoun (Cisco Systems, Inc.), M. Montemurro (Research In Motion) and D. Stanley (Aruba Networks), and all three are marked as Ed., aka the editors who wrangled the whole thing together 🫶 The header doesn't list anything it obsoletes or updates, so there's no drama there. 🙈
Status of This Memo 📜
Okay, so this part is about the document's status. The doc specifies an Internet standards track protocol for the Internet community and asks for discussion and suggestions for improvements 💖 If you want to know where it stands officially, check the current edition of "Internet Official Protocol Standards" (STD 1). And distribution of this memo is totally unlimited, so share away 🌸
Copyright Notice ⚖️
Copyright (c) 2009 by the IETF Trust and the people listed as the document authors. All rights reserved 💜
Heads up, this bit is legal stuff, so read it carefully 👀 The document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which were in effect on the publication date. You can find those at http://trustee.ietf.org/license-info, and they explain your rights and restrictions.
⚠️ Heads up: this doc may include stuff from IETF Documents or IETF Contributions that were published or made public before November 10, 2008. The people who own the copyright on some of that material may not have given the IETF Trust permission to allow changes outside the IETF Standards Process. So unless you get a proper license from those copyright owners, you can't modify this document outside the IETF Standards Process, and you can't make derivative works of it outside that process either. The only exceptions are formatting it for publication as an RFC or translating it into languages other than English 🌈
Abstract 🎀
This spec defines the Control And Provisioning of Wireless Access Points (CAPWAP) Protocol and meets the goals set by the CAPWAP Working Group in RFC 4564 🔥 CAPWAP is built to be flexible, so it can work with a whole bunch of different wireless technologies. This document covers the base CAPWAP protocol, and separate binding extensions will let it work with extra wireless technologies later on 🧚
Table of Contents 🍓
Here's the full map of the doc, copied exactly so the section numbers still line up:
1. Introduction ....................................................7
1.1. Goals ......................................................8
1.2. Conventions Used in This Document ..........................9
1.3. Contributing Authors .......................................9
1.4. Terminology ...............................................10
2. Protocol Overview ..............................................11
2.1. Wireless Binding Definition ...............................12
2.2. CAPWAP Session Establishment Overview .....................13
2.3. CAPWAP State Machine Definition ...........................15
2.3.1. CAPWAP Protocol State Transitions ..................17
2.3.2. CAPWAP/DTLS Interface ..............................31
2.4. Use of DTLS in the CAPWAP Protocol ........................33
2.4.1. DTLS Handshake Processing ..........................33
2.4.2. DTLS Session Establishment .........................35
2.4.3. DTLS Error Handling ................................35
2.4.4. DTLS Endpoint Authentication and Authorization .....36
3. CAPWAP Transport ...............................................40
3.1. UDP Transport .............................................40
3.2. UDP-Lite Transport ........................................41
3.3. AC Discovery ..............................................41
3.4. Fragmentation/Reassembly ..................................42
3.5. MTU Discovery .............................................43
4. CAPWAP Packet Formats ..........................................43
4.1. CAPWAP Preamble ...........................................46
4.2. CAPWAP DTLS Header ........................................46
4.3. CAPWAP Header .............................................47
4.4. CAPWAP Data Messages ......................................50
4.4.1. CAPWAP Data Channel Keep-Alive .....................51
4.4.2. Data Payload .......................................52
4.4.3. Establishment of a DTLS Data Channel ...............52
4.5. CAPWAP Control Messages ...................................52
4.5.1. Control Message Format .............................53
4.5.2. Quality of Service .................................56
4.5.3. Retransmissions ....................................57
4.6. CAPWAP Protocol Message Elements ..........................58
4.6.1. AC Descriptor ......................................61
4.6.2. AC IPv4 List .......................................64
4.6.3. AC IPv6 List .......................................64
4.6.4. AC Name ............................................65
4.6.5. AC Name with Priority ..............................65
4.6.6. AC Timestamp .......................................66
4.6.7. Add MAC ACL Entry ..................................66
4.6.8. Add Station ........................................67
4.6.9. CAPWAP Control IPv4 Address ........................68
4.6.10. CAPWAP Control IPv6 Address .......................68
4.6.11. CAPWAP Local IPv4 Address .........................69
4.6.12. CAPWAP Local IPv6 Address .........................69
4.6.13. CAPWAP Timers .....................................70
4.6.14. CAPWAP Transport Protocol .........................71
4.6.15. Data Transfer Data ................................72
4.6.16. Data Transfer Mode ................................73
4.6.17. Decryption Error Report ...........................73
4.6.18. Decryption Error Report Period ....................74
4.6.19. Delete MAC ACL Entry ..............................74
4.6.20. Delete Station ....................................75
4.6.21. Discovery Type ....................................75
4.6.22. Duplicate IPv4 Address ............................76
4.6.23. Duplicate IPv6 Address ............................77
4.6.24. Idle Timeout ......................................78
4.6.25. ECN Support .......................................78
4.6.26. Image Data ........................................79
4.6.27. Image Identifier ..................................79
4.6.28. Image Information .................................80
4.6.29. Initiate Download .................................81
4.6.30. Location Data .....................................81
4.6.31. Maximum Message Length ............................81
4.6.32. MTU Discovery Padding .............................82
4.6.33. Radio Administrative State ........................82
4.6.34. Radio Operational State ...........................83
4.6.35. Result Code .......................................84
4.6.36. Returned Message Element ..........................85
4.6.37. Session ID ........................................86
4.6.38. Statistics Timer ..................................87
4.6.39. Vendor Specific Payload ...........................87
4.6.40. WTP Board Data ....................................88
4.6.41. WTP Descriptor ....................................89
4.6.42. WTP Fallback ......................................92
4.6.43. WTP Frame Tunnel Mode .............................92
4.6.44. WTP MAC Type ......................................93
4.6.45. WTP Name ..........................................94
4.6.46. WTP Radio Statistics ..............................94
4.6.47. WTP Reboot Statistics .............................96
4.6.48. WTP Static IP Address Information .................97
4.7. CAPWAP Protocol Timers ....................................98That's the whole map for this part! 🦋💜
4.7.1. ChangeStatePendingTimer ............................98 4.7.2. DataChannelKeepAlive ...............................98 4.7.3. DataChannelDeadInterval ............................99 4.7.4. DataCheckTimer .....................................99 4.7.5. DiscoveryInterval ..................................99 4.7.6. DTLSSessionDelete ..................................99 4.7.7. EchoInterval .......................................99 4.7.8. IdleTimeout ........................................99 4.7.9. ImageDataStartTimer ...............................100 4.7.10. MaxDiscoveryInterval .............................100 4.7.11. ReportInterval ...................................100 4.7.12. RetransmitInterval ...............................100 4.7.13. SilentInterval ...................................100 4.7.14. StatisticsTimer ..................................100 4.7.15. WaitDTLS .........................................101 4.7.16. WaitJoin .........................................101 4.8. CAPWAP Protocol Variables ................................101 4.8.1. AdminState ........................................101 4.8.2. DiscoveryCount ....................................101 4.8.3. FailedDTLSAuthFailCount ...........................101 4.8.4. FailedDTLSSessionCount ............................101 4.8.5. MaxDiscoveries ....................................102 4.8.6. MaxFailedDTLSSessionRetry .........................102 4.8.7. MaxRetransmit .....................................102 4.8.8. RetransmitCount ...................................102 4.8.9. WTPFallBack .......................................102 4.9. WTP Saved Variables ......................................102 4.9.1. AdminRebootCount ..................................102 4.9.2. FrameEncapType ....................................102 4.9.3. LastRebootReason ..................................103 4.9.4. MacType ...........................................103 4.9.5. PreferredACs ......................................103 4.9.6. RebootCount .......................................103 4.9.7. Static IP Address .................................103 4.9.8. WTPLinkFailureCount ...............................103 4.9.9. WTPLocation .......................................103 4.9.10. WTPName ..........................................103
- CAPWAP Discovery Operations ...................................103 5.1. Discovery Request Message ................................103 5.2. Discovery Response Message ...............................105 5.3. Primary Discovery Request Message ........................106 5.4. Primary Discovery Response ...............................107
- CAPWAP Join Operations ........................................108 6.1. Join Request .............................................108 6.2. Join Response ............................................110
- Control Channel Management ....................................111 7.1. Echo Request .............................................111 7.2. Echo Response ............................................112
- WTP Configuration Management ..................................112 8.1. Configuration Consistency ................................112 8.1.1. Configuration Flexibility .........................113 8.2. Configuration Status Request .............................114 8.3. Configuration Status Response ............................115 8.4. Configuration Update Request .............................116 8.5. Configuration Update Response ............................117 8.6. Change State Event Request ...............................117 8.7. Change State Event Response ..............................118 8.8. Clear Configuration Request ..............................119 8.9. Clear Configuration Response .............................119
- Device Management Operations ..................................120 9.1. Firmware Management ......................................120 9.1.1. Image Data Request ................................124 9.1.2. Image Data Response ...............................125 9.2. Reset Request ............................................126 9.3. Reset Response ...........................................127 9.4. WTP Event Request ........................................127 9.5. WTP Event Response .......................................128 9.6. Data Transfer ............................................128 9.6.1. Data Transfer Request .............................130 9.6.2. Data Transfer Response ............................131
- Station Session Management ...................................131 10.1. Station Configuration Request ...........................131 10.2. Station Configuration Response ..........................132
- NAT Considerations ...........................................132
- Security Considerations ......................................134 12.1. CAPWAP Security .........................................134 12.1.1. Converting Protected Data into Unprotected Data ..135 12.1.2. Converting Unprotected Data into Protected Data (Insertion) .......................135 12.1.3. Deletion of Protected Records ....................135 12.1.4. Insertion of Unprotected Records .................135 12.1.5. Use of MD5 .......................................136 12.1.6. CAPWAP Fragmentation .............................136 12.2. Session ID Security .....................................136 12.3. Discovery or DTLS Setup Attacks .........................137 12.4. Interference with a DTLS Session ........................137 12.5. CAPWAP Pre-Provisioning .................................138 12.6. Use of Pre-Shared Keys in CAPWAP ........................139 12.7. Use of Certificates in CAPWAP ...........................140 12.8. Use of MAC Address in CN Field ..........................140 12.9. AAA Security ............................................141 12.10. WTP Firmware ...........................................141
- Operational Considerations ...................................141
- Transport Considerations .....................................142
- IANA Considerations ..........................................143 15.1. IPv4 Multicast Address ..................................143 15.2. IPv6 Multicast Address ..................................144 15.3. UDP Port ................................................144 15.4. CAPWAP Message Types ....................................144 15.5. CAPWAP Header Flags .....................................144 15.6. CAPWAP Control Message Flags ............................145 15.7. CAPWAP Message Element Type .............................145 15.8. CAPWAP Wireless Binding Identifiers .....................145 15.9. AC Security Types .......................................146 15.10. AC DTLS Policy .........................................146 15.11. AC Information Type ....................................146 15.12. CAPWAP Transport Protocol Types ........................146 15.13. Data Transfer Type .....................................147 15.14. Data Transfer Mode .....................................147 15.15. Discovery Types ........................................147 15.16. ECN Support ............................................148 15.17. Radio Admin State ......................................148 15.18. Radio Operational State ................................148 15.19. Radio Failure Causes ...................................148 15.20. Result Code ............................................149 15.21. Returned Message Element Reason ........................149 15.22. WTP Board Data Type ....................................149 15.23. WTP Descriptor Type ....................................149 15.24. WTP Fallback Mode ......................................150 15.25. WTP Frame Tunnel Mode ..................................150 15.26. WTP MAC Type ...........................................150 15.27. WTP Radio Stats Failure Type ...........................151 15.28. WTP Reboot Stats Failure Type ..........................151
- Acknowledgments ..............................................151
- References ...................................................151 17.1. Normative References ....................................151 17.2. Informative References ..................................153
1. Introduction ✨
Okay so bestie, this doc is all about CAPWAP 💖. It's a standard, interoperable protocol that lets an Access Controller (AC) manage a whole crew of Wireless Termination Points (WTPs) 🎀. CAPWAP doesn't care what Layer 2 (L2) technology is underneath, and it hits the goals in "Objectives for Control and Provisioning of Wireless Access Points (CAPWAP)" [RFC4564] 🫶
So centralized IEEE 802.11 Wireless Local Area Network (WLAN) setups are a whole thing right now, where simple IEEE 802.11 WTPs get managed by one AC 🦋. People realized a standards-based, interoperable protocol could seriously simplify how wireless networks get deployed and managed, and it's giving main character energy 👑. WTPs need a bunch of dynamic management and control stuff for their main job, which is connecting the wireless and wired worlds 🌸. The older ways of doing this were either manual static configuration over HTTP, proprietary L2-specific stuff, or nothing at all if the WTPs were self-contained 💀. The IEEE 802.11 binding is defined in [RFC5416], which lets CAPWAP work with IEEE 802.11 WLAN networks 🧚
CAPWAP assumes you've got multiple WTPs talking over the Internet Protocol (IP) to an AC 🌈. The WTPs are basically remote radio frequency (RF) interfaces that the AC controls 💅. CAPWAP has two modes: Split and Local MAC (medium access control) 🍓. In Split MAC mode, all the L2 wireless data and management frames get wrapped up with CAPWAP and passed between the AC and the WTP 🔥. Check out Figure 1 below: a mobile device (called a Station (STA) in this spec) sends wireless frames, and the WTP just encapsulates them and forwards them to the AC, no cap 😭
+-+ wireless frames +-+
| |--------------------------------| |
| | +-+ | |
| |--------------| |---------------| |
| |wireless PHY/ | | CAPWAP | |
| | MAC sublayer | | | |
+-+ +-+ +-+
STA WTP ACFigure 1: Representative CAPWAP Architecture for Split MAC
Local MAC mode is a little different 🦋. Data frames can either get bridged locally or tunneled out as 802.3 frames, and the tunneled version means the WTP is doing the 802.11 Integration function 🎀. Either way, the L2 wireless management frames get handled locally by the WTP first, and then they're forwarded to the AC ✨. Figure 2 shows this: a station sends a wireless frame, it gets wrapped in an 802.3 frame, and that goes to the AC 💖
+-+wireless frames +-+ 802.3 frames +-+
| |----------------| |--------------| |
| | | | | |
| |----------------| |--------------| |
| |wireless PHY/ | | CAPWAP | |
| | MAC sublayer | | | |
+-+ +-+ +-+
STA WTP ACFigure 2: Representative CAPWAP Architecture for Local MAC
Handing out security credentials to WTPs and deciding which WTPs are allowed to provide service has usually been a proprietary mess 🙈. Letting a centralized AC do all of that in an interoperable way makes things way more manageable and lets network operators control their wireless infrastructure more tightly 💜
1.1. Goals
The CAPWAP goals are listed below, and honestly they're iconic 👑:
- To centralize the authentication and policy enforcement functions for a wireless network. The AC may also provide centralized bridging, forwarding, and encryption of user traffic. Centralizing these things means reduced cost and higher efficiency by using network processing silicon for wireless, just like wired LANs do 💅.
- To shift higher-level protocol processing away from the WTP. That leaves the time-critical wireless control and access stuff in the WTP, which makes good use of the computing power in WTPs. Those are under severe cost pressure, so this matters a lot 😭.
- To provide an extensible protocol that isn't tied to one specific wireless technology. Extensibility comes from a generic encapsulation and transport mechanism, so CAPWAP can be applied to many access point types in the future through a specific wireless binding 🌈.
CAPWAP only cares about the interface between the WTP and the AC 🎀. Inter-AC communication and station-to-AC communication are strictly outside the scope of this document 🙅♀️. Not our problem, bestie 💅
1.2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119] 🧚
1.3. Contributing Authors
This section lists and thanks the authors of the significant text and concepts in this spec 🫶
The CAPWAP Working Group picked the Lightweight Access Point Protocol (LWAPP) [LWAPP] as the basis for the CAPWAP protocol spec 🦋. These people wrote the LWAPP document:
Bob O'Hara
Email: bob.ohara@computer.org
Pat Calhoun, Cisco Systems, Inc.
170 West Tasman Drive, San Jose, CA 95134
Phone: +1 408-902-3240, Email: pcalhoun@cisco.com
Rohit Suri, Cisco Systems, Inc.
170 West Tasman Drive, San Jose, CA 95134
Phone: +1 408-853-5548, Email: rsuri@cisco.com
Nancy Cam Winget, Cisco Systems, Inc.
170 West Tasman Drive, San Jose, CA 95134
Phone: +1 408-853-0532, Email: ncamwing@cisco.com
Scott Kelly, Aruba Networks
1322 Crossman Ave, Sunnyvale, CA 94089
Phone: +1 408-754-8408, Email: skelly@arubanetworks.com
Michael Glenn Williams, Nokia, Inc.
313 Fairchild Drive, Mountain View, CA 94043
Phone: +1 650-714-7758, Email: Michael.G.Williams@Nokia.com
Sue Hares, Green Hills Software
825 Victors Way, Suite 100, Ann Arbor, MI 48108
Phone: +1 734 222 1610, Email: shares@ndzh.comDatagram Transport Layer Security (DTLS) [RFC4347] is the security solution for CAPWAP 🔐. These people wrote the significant DTLS-related text in this document 💜:
Scott Kelly, Aruba Networks
1322 Crossman Ave, Sunnyvale, CA 94089
Phone: +1 408-754-8408
Email: skelly@arubanetworks.com
Eric Rescorla, Network Resonance
2483 El Camino Real, #212,Palo Alto CA, 94303
Email: ekr@networkresonance.comThe idea of using DTLS to secure CAPWAP was part of the Secure Light Access Point Protocol (SLAPP) proposal [SLAPP] 🌸. These people wrote the SLAPP proposal:
Partha Narasimhan, Aruba Networks
1322 Crossman Ave, Sunnyvale, CA 94089
Phone: +1 408-480-4716
Email: partha@arubanetworks.com
Dan Harkins
Trapeze Networks
5753 W. Las Positas Blvd, Pleasanton, CA 94588
Phone: +1-925-474-2212
EMail: dharkins@trpz.com
Subbu Ponnuswamy, Aruba Networks
1322 Crossman Ave, Sunnyvale, CA 94089
Phone: +1 408-754-1213
Email: subbu@arubanetworks.comThese individuals contributed significant security-related text to the document [RFC5418] 🔥:
T. Charles Clancy, Laboratory for Telecommunications Sciences,
8080 Greenmead Drive, College Park, MD 20740
Phone: +1 240-373-5069, Email: clancy@ltsnet.net
Scott Kelly, Aruba Networks
1322 Crossman Ave, Sunnyvale, CA 94089
Phone: +1 408-754-8408, Email: scott@hyperthought.com1.4. Terminology
Here are the key terms, so everybody's on the same page 📖✨
- Access Controller (AC): The network entity that gives WTPs access to the network infrastructure in the data plane, control plane, management plane, or some combination of those 👑.
- CAPWAP Control Channel: A bi-directional flow defined by the AC IP Address, WTP IP Address, AC control port, WTP control port, and the transport-layer protocol (UDP or UDP-Lite) that CAPWAP Control packets get sent and received over 🎀.
- CAPWAP Data Channel: A bi-directional flow defined by the AC IP Address, WTP IP Address, AC data port, WTP data port, and the transport-layer protocol (UDP or UDP-Lite) that CAPWAP Data packets get sent and received over 🦋.
- Station (STA): A device that has an interface to a wireless medium (WM) 📱.
- Wireless Termination Point (WTP): The physical or network entity that has an RF antenna and a wireless Physical Layer (PHY) to transmit and receive station traffic for wireless access networks 🌈.
This document uses additional terminology defined in [RFC3753] 🫶
2. Protocol Overview ✨
okay bestie, so CAPWAP is basically a generic protocol that lets an AC and a WTP talk over their control and data planes through a CAPWAP transport mechanism 💖. CAPWAP Control messages, and optionally CAPWAP Data messages, get locked down with Datagram Transport Layer Security (DTLS) [RFC4347] 🔐. DTLS is a standards-track IETF protocol built on TLS, and the security stuff TLS does has been deployed successfully for many years, so it's not a random new experiment 💅.
The CAPWAP transport layer carries two kinds of payload: CAPWAP Data messages and CAPWAP Control messages 🎀. Data messages wrap up forwarded wireless frames. Control messages are the management messages that a WTP and an AC swap with each other 🦋. The Data and Control packets go out over separate UDP ports, and both can be bigger than the Maximum Transmission Unit (MTU), so the payload of either one can get fragmented 🧩. The fragmentation rules live in Section 3, so go check that out when you get there 🌸.
The CAPWAP Protocol kicks off with a Discovery phase 🔍. The WTP sends a Discovery Request message, and any Access Controller (AC) that hears it responds with a Discovery Response message 📡. From all the Discovery Responses it gets back, the WTP picks an AC to set up a secure DTLS session with. To make that DTLS connection happen, the WTP needs some pre-provisioning, which is spelled out in Section 12.5 🧾. CAPWAP protocol messages get fragmented down to the maximum length the network is found to support 🍓.
Once the WTP and the AC finish the DTLS session setup, they do a configuration exchange where both sides agree on version info 🤝. During that exchange the WTP might receive provisioning settings, and then it's enabled for operation 🚀.
When the version and provision exchange is done and the WTP is enabled, CAPWAP is used to encapsulate the wireless data frames going between the WTP and the AC 🫶. If the encapsulated wireless user data (Data) or protocol control (Management) frames would make the CAPWAP packet bigger than the MTU between the WTP and AC, CAPWAP fragments the L2 frames. The fragments then get reassembled to rebuild the original payload 🧃. MTU Discovery and Fragmentation are both covered in Section 3 💜.
CAPWAP also delivers commands from the AC to the WTP for managing the stations talking to that WTP 📶. That can include creating local data structures in the WTP for those stations, and collecting statistics about the traffic between the WTP and the stations 📊. CAPWAP gives the AC a way to grab those statistics from the WTP too 👑.
There's a keep-alive feature that keeps the communication channel between the WTP and AC alive 💓. If the AC stops appearing alive, the WTP goes looking for a new AC 🔄.
2.1. Wireless Binding Definition
CAPWAP doesn't care about any one WTP radio technology or its wireless link layer protocol, which makes it super flexible 🌈. Its elements are built so each wireless technology can get what it needs in a standard way ✨. Any implementation of CAPWAP for a specific wireless technology MUST follow the binding requirements defined for that technology 🎯.
When somebody defines a binding for a wireless technology, the authors MUST include every necessary definition for the technology-specific messages, plus all the technology-specific message elements for those messages 📝. At a minimum, a binding MUST provide:
- The definition for a binding-specific Statistics message element, carried in the WTP Event Request message.
- A message element carried in the Station Configuration Request message to configure station information on the WTP.
- A WTP Radio Information message element carried in the Discovery, Primary Discovery, and Join Request and Response messages, indicating the binding-specific radio types supported at the WTP and AC.
If any existing CAPWAP message defined in this specification needs technology-specific message elements, those MUST also be defined in the technology binding document 📚.
The names of binding-specific message elements MUST begin with the name of the technology type. For example, the IEEE 802.11 binding, provided in [RFC5416], begins with "IEEE 802.11" 🏷️.
The CAPWAP binding concept MUST also be used in any future specification that adds functionality to either the base CAPWAP protocol specification or any published CAPWAP binding specification 🔮. A separate WTP Radio Information message element MUST be created to properly advertise support for that specification 📣. This setup allows for future protocol extensibility, and the WTP Radio Information message element provides the capabilities advertisement needed to keep WTP/AC interoperability working 🫧.
2.2. CAPWAP Session Establishment Overview
This section walks through the session establishment message exchanges between a CAPWAP WTP and AC 🎬. The ladder diagram shows the AC on the right and the WTP on the left, and it assumes certificates are used for DTLS authentication 🪪. The CAPWAP protocol state machine gets the full treatment in Section 2.3 🧠. Also, DTLS lets certain messages get bundled into a single frame, which is marked with an asterisk in Figure 3 ⭐.
============ ============
WTP AC
============ ============
[----------- begin optional discovery ------------]
Discover Request
------------------------------------>
Discover Response
<------------------------------------
[----------- end optional discovery ------------]
(-- begin DTLS handshake --)
ClientHello
------------------------------------>
HelloVerifyRequest (with cookie)
<------------------------------------
ClientHello (with cookie)
------------------------------------>
ServerHello,
Certificate,
ServerHelloDone*
<------------------------------------
(-- WTP callout for AC authorization --)
Certificate (optional),
ClientKeyExchange,
CertificateVerify (optional),
ChangeCipherSpec,
Finished*
------------------------------------>
(-- AC callout for WTP authorization --)
ChangeCipherSpec,
Finished*
<------------------------------------
(-- DTLS session is established now --)
Join Request
------------------------------------>
Join Response
<------------------------------------
[-- Join State Complete --]
(-- assume image is up to date --)
Configuration Status Request
------------------------------------>
Configuration Status Response
<------------------------------------
[-- Configure State Complete --]
Change State Event Request
------------------------------------>
Change State Event Response
<------------------------------------
[-- Data Check State Complete --]
(-- enter RUN state --)
:
:
Echo Request
------------------------------------>
Echo Response
<------------------------------------
:
:
Event Request
------------------------------------>
Event Response
<------------------------------------
:
:
Figure 3: CAPWAP Control Protocol ExchangeBy the end of this illustrated exchange, the AC and WTP are securely swapping CAPWAP Control messages 🔐💖. This picture is there to make the protocol operation clearer, and it doesn't show any error conditions 🙈. Section 2.3 has the detailed state machine description 🦋.
2.3. CAPWAP State Machine Definition ✨
Okay so this is the lifecycle of a WTP-AC session, and it's giving two state machines living together. 🦋 DTLS is basically the security bestie, and it runs its own state machine right next to CAPWAP's. They're nominally separate but tightly bound, so they talk through an API: commands (see Section 2.3.2.1) go from CAPWAP to DTLS, and notifications (see Section 2.3.2.2) go back the other way. So some DTLS transitions get kicked off by CAPWAP commands, and some CAPWAP transitions get triggered by DTLS notifications. Iconic teamwork 🫶
/-------------------------------------\
| /-------------------------\|
| p| ||
| q+----------+ r +------------+ ||
| | Run |-->| Reset |-\||
| +----------+ +------------+ |||
n| o ^ ^ ^ s|||
+------------+--------/ | | |||
| Data Check | /-------/ | |||
+------------+<-------\ | | |||
| | | |||
/------------------+--------\ | |||
f| m| h| j v k| |||
+--------+ +-----------+ +--------------+|||
| Join |---->| Configure | | Image Data ||||
+--------+ n +-----------+ +--------------+|||
^ |g i| l| |||
| | \-------------------\ | |||
| \--------------------------------------\| | |||
\------------------------\ || | |||
/--------------<----------------+---------------\ || | |||
| /------------<----------------+-------------\ | || | |||
| | 4 |d t| | vv v vvv
| | +----------------+ +--------------+ +-----------+
| | | DTLS Setup | | DTLS Connect |-->| DTLS TD |
/-|-|---+----------------+ +--------------+ e +-----------+
| | | |$ ^ ^ |5 ^6 ^ ^ |w
v v v | | | | \-------\ | | |
| | | | | | \---------\ | | /-----------/ |
| | | | | \--\ | | | | |
| | | | | | | | | | |
| | | v 3| 1 |% # v | |a |b v
| | \->+------+-->+------+ +-----------+ +--------+
| | | Idle | | Disc | | Authorize | | Dead |
| | +------+<--+------+ +-----------+ +--------+
| | ^ 0^ 2 |!
| | | | | +-------+
*| |u | \---------+---| Start |
| | |@ | +-------+
| \->+---------+<------/
\--->| Sulking |
+---------+&
Figure 4: CAPWAP Integrated State MachineHere's the vibe: the CAPWAP protocol state machine (the diagram above) is used by both the AC and the WTP. 💜 If a state isn't shared, meaning it only lives in one of them (the AC or the WTP), the transition descriptions below will call that out. Every state has its own guest list: only certain messages are allowed to be sent and received in each one. The CAPWAP Control message definitions say which state(s) each message is valid in. Very strict, very cute 🎀
Now here's where the WTP and AC are totally different people. 🧚 The WTP only talks to one AC, so it only needs a single instance of the CAPWAP state machine. The AC is the popular one, though, since it's chatting with many WTPs at once, so it runs the show with three threads:
- Listener Thread: The AC's Listener thread handles incoming DTLS session establishment requests through the DTLSListen command. The moment it's created, it starts out in the DTLS Setup state. Once a DTLS session has been validated (which happens when the state machine enters the "Authorize" state), the Listener thread spins up a WTP session-specific Service thread and state context. The state machine transitions in Figure 4 are marked with numerals. The AC also has to protect itself from the various attacks that come with non-authenticated frames, so see Section 12 for the full story. 🛡️
- Discovery Thread: The AC's Discovery thread is in charge of receiving and responding to Discovery Request messages. Its transitions in Figure 4 are also marked with numerals. Fun fact: the Discovery thread doesn't keep any per-WTP context at all, so there's just one single state context for everyone. Still, it has to guard against non-authenticated-frame attacks too, so see Section 12 for more information. 👑
- Service Thread: The AC's Service thread handles the per-WTP states, and there's one of these per WTP connection. The Listener thread creates it when the Authorize state is reached. When it's born, it inherits a copy of the state machine context from the Listener thread. When communication with the WTP is done, the Service thread is terminated and all its resources are released. Its transitions in Figure 4 are marked with alphabetic and punctuation characters instead of numerals. 💅
Just so we're clear, the word "thread" here doesn't mean implementers have to use threads. It's just one possible way to build the AC's state machine, so no pressure 🌸
2.3.1. CAPWAP Protocol State Transitions 🦋
This section is all about the different state transitions and the events that set them off. It doesn't cover interactions between DTLS- and CAPWAP-specific states, though. Those interactions, plus the DTLS-specific states and transitions, live in Section 2.3.2. Let's go! 🚀
Start to Idle (0): This transition happens once device initialization is complete. ✨
- WTP: This transition is how the WTP starts its CAPWAP state machine.
- AC: The AC creates its Discovery and Listener threads and starts the CAPWAP state machine.
Idle to Discovery (1): This transition kicks off the CAPWAP discovery process. 🔍
- WTP: Before sending the first Discovery Request message (see Section 5.1), the WTP enters the Discovery state. As soon as it gets there, it sets the DiscoveryInterval timer (see Section 4.7) and resets the DiscoveryCount counter to zero (0) (see Section 4.8). It also clears out any info it got from ACs during a previous Discovery phase. Clean slate, bestie 🧹
- AC: The AC's Discovery thread runs this transition whenever a Discovery Request message comes in. The AC SHOULD respond with a Discovery Response message (see Section 5.2). 💌
Discovery to Discovery (#): In the Discovery state, the WTP figures out which AC it's going to connect to. 🤔
- WTP: This transition happens when the DiscoveryInterval timer runs out. If the WTP has a list of ACs configured, it sends a Discovery Request message to every AC it hasn't gotten a Discovery Response from yet. Every time this transition happens, the WTP increments the DiscoveryCount counter. For how the WTP figures out which ACs to send Discovery Requests to, see Section 5.1. The WTP also restarts the DiscoveryInterval timer whenever it sends Discovery Request messages.
- AC: This is an invalid transition for the AC. Not me trying it 🙅♀️
Discovery to Idle (2): This transition happens on the AC's Discovery thread once Discovery processing is finished. 🎉
- WTP: This is an invalid transition for the WTP.
- AC: The AC's Discovery thread runs this transition after it has sent the Discovery Response to a Discovery Request.
Discovery to Sulking (!): This transition happens on a WTP when AC discovery fails. 😭
- WTP: The WTP enters this state when the DiscoveryInterval timer expires and the DiscoveryCount variable equals the MaxDiscoveries variable (see Section 4.8). Right when it enters, the WTP MUST start the SilentInterval timer. While it's in the Sulking state, all received CAPWAP protocol messages MUST be ignored. Silent treatment, fully deserved 🤐
- AC: This is an invalid transition for the AC.
The Sulking state is basically the timeout corner. Being quiet here is what keeps the WTP from getting spammed, so don't skip it! 🙈
Sulking to Idle (@): This transition happens on a WTP when it has to restart the Discovery phase. 🔄
- WTP: The WTP enters this state when the SilentInterval timer (see Section 4.7) expires. The FailedDTLSSessionCount, DiscoveryCount, and FailedDTLSAuthFailCount counters all get reset to zero. Fresh start, new era ✨
- AC: This is an invalid transition for the AC.
Sulking to Sulking (&): The Sulking state gives the WTP a silent period, which keeps the chances of Denial-of-Service (DoS) attacks low. 🛑
- WTP: All packets received from the AC while in the Sulking state are ignored.
- AC: This is an invalid transition for the AC.
Idle to DTLS Setup (3): This transition happens to set up a secure DTLS session with the peer. 🔐
- WTP: The WTP starts this transition by invoking the DTLSStart command (see Section 2.3.2.1). That kicks off DTLS session establishment with the chosen AC, and the WaitDTLS timer starts (see Section 4.7). If the Discovery phase gets skipped, it's assumed the WTP has its ACs configured locally. Main character behavior 👑
- AC: When the newly created Listener thread enters the Idle state from the Start state, it automatically transitions to the DTLS Setup state and invokes the DTLSListen command (see Section 2.3.2.1). The WaitDTLS timer starts too (see Section 4.7).
Discovery to DTLS Setup (%): This transition happens to set up a secure DTLS session with the peer. 💜
- WTP: The WTP starts this transition by invoking the DTLSStart command (see Section 2.3.2.1), which kicks off DTLS session establishment with the chosen AC. Which AC that is comes out of the Discovery phase, described in Section 3.3. 🎯
- AC: This is an invalid transition for the AC.
DTLS Setup to Idle ($): This transition happens when the DTLS connection setup fails. 💀
- WTP: The WTP starts this transition when it gets a DTLSEstablishFail notification from DTLS (see Section 2.3.2.2), and the FailedDTLSSessionCount counter or the FailedDTLSAuthFailCount counter hasn't hit the MaxFailedDTLSSessionRetry variable's value yet (see Section 4.8). That error notification aborts the secure DTLS session setup. When it arrives, the FailedDTLSSessionCount counter goes up by one. This transition also happens if the WaitDTLS timer expires. Second chances, bestie 🌈
- AC: This is an invalid transition for the AC.
DTLS Setup to Sulking (*): This transition happens when repeated attempts to set up the DTLS connection have failed. 😤
WTP: Okay so the WTP enters this state when its FailedDTLSSessionCount or FailedDTLSAuthFailCount counter hits the value of MaxFailedDTLSSessionRetry 🥺 (see Section 4.8). The second it gets here, the WTP MUST start the SilentInterval timer. 🤫 While it's sulking, every CAPWAP and DTLS protocol message it receives MUST be ignored. Full ghost mode 👻
AC: This is an invalid transition for the AC, so not for it 💅
DTLS Setup to DTLS Setup (4): This one happens when the DTLS session fails to get established 💔
WTP: Invalid transition for the WTP too, sorry bestie 🙈
AC: The AC's Listener kicks this off when it gets a DTLSEstablishFail notification from DTLS (see Section 2.3.2.2). That notification aborts the secure DTLS session setup, so the FailedDTLSSessionCount counter goes up, and then the Listener thread calls the DTLSListen command (see Section 2.3.2.1) to start listening again 🔁
DTLS Setup to Authorize (5): This happens when an incoming DTLS session is being set up and the DTLS stack needs authorization before it can keep going 🛂
WTP: This transition happens when the WTP gets the DTLSPeerAuthorize notification (see Section 2.3.2.2). Once it's in this state, the WTP checks the AC credentials for authorization. See Section 2.4.4 for more on AC authorization 🔐
AC: The AC's Listener thread handles this one when the DTLS module sends the DTLSPeerAuthorize notification (see Section 2.3.2.2). The Listener forks off an instance of the Service thread, along with a copy of the state context 🍴 Then the Service thread checks the WTP credentials for authorization. See Section 2.4.4 for more on WTP authorization ✨
Authorize to DTLS Setup (6): The Listener thread uses this transition so it can start listening for new incoming sessions again 👂
WTP: Invalid transition for the WTP 🙅♀️
AC: This happens when the AC's Listener thread has made the WTP context and the Service thread. Then the Listener calls the DTLSListen command (see Section 2.3.2.1) 🎀
Authorize to DTLS Connect (a): This transition tells the DTLS stack that the session should be established 🤝
WTP: This happens once the WTP has successfully authorized the AC's credentials (see Section 2.4.4). The WTP does it by invoking the DTLSAccept DTLS command (see Section 2.3.2.1) 🥂
AC: This happens once the AC has successfully authorized the WTP's credentials (see Section 2.4.4). The AC also does it by invoking the DTLSAccept DTLS command (see Section 2.3.2.1) 🥂
Authorize to DTLS Teardown (b): This transition tells the DTLS stack that the session should be aborted 🛑
WTP: This happens when the WTP can't authorize the AC using the AC credentials. The WTP then aborts the DTLS session by invoking the DTLSAbortSession command (see Section 2.3.2.1). It also happens if the WaitDTLS timer runs out, and then the WTP starts the DTLSSessionDelete timer (see Section 4.7.6) ⏰
AC: This happens when the AC can't authorize the WTP using the WTP credentials. The AC aborts the DTLS session by invoking the DTLSAbortSession command (see Section 2.3.2.1). It also happens if the WaitDTLS timer expires, and the AC starts the DTLSSessionDelete timer (see Section 4.7.6) 😭
DTLS Connect to DTLS Teardown (c): This is the "the DTLS session didn't make it" transition 💀
WTP: This happens when the WTP gets either a DTLSAborted or a DTLSAuthenticateFail notification (see Section 2.3.2.2), which means the DTLS session didn't get set up. If it was the DTLSAuthenticateFail one, the FailedDTLSAuthFailCount goes up. Otherwise, the FailedDTLSSessionCount counter goes up. It also happens if the WaitDTLS timer expires, and then the WTP starts the DTLSSessionDelete timer (see Section 4.7.6) 🫠
AC: This happens when the AC gets either a DTLSAborted or a DTLSAuthenticateFail notification (see Section 2.3.2.2), meaning the DTLS session didn't get established, and both the FailedDTLSAuthFailCount and FailedDTLSSessionCount counters are still below the value of MaxFailedDTLSSessionRetry (see Section 4.8). It also happens if the WaitDTLS timer expires, and the AC starts the DTLSSessionDelete timer (see Section 4.7.6) 🥀
DTLS Connect to Join (d): Yay, this is the good one! This happens when the DTLS session is successfully established 🎉
WTP: This happens when the WTP gets the DTLSEstablished notification (see Section 2.3.2.2), which means the DTLS session worked. The FailedDTLSSessionCount counter gets reset to zero. Then the WTP enters the Join state by sending the Join Request to the AC, and it stops the WaitDTLS timer 🚀
AC: This happens when the AC gets the DTLSEstablished notification (see Section 2.3.2.2), which means the DTLS session worked. The FailedDTLSSessionCount counter gets reset to zero. The AC stops the WaitDTLS timer and starts the WaitJoin timer 🌈
Join to DTLS Teardown (e): This happens when the join process fails 📉
WTP: This happens when the WTP gets a Join Response message with a Result Code message element containing an error. It also happens if the Image Identifier the AC sent in the Join Response is different from the WTP's currently running firmware version and the WTP has the requested image in its non-volatile memory. Either way, the WTP starts the DTLSShutdown command (see Section 2.3.2.1). It also happens if the WTP gets any of these DTLS notifications: DTLSAborted, DTLSReassemblyFailure, or DTLSPeerDisconnect. Then the WTP starts the DTLSSessionDelete timer (see Section 4.7.6) 🧹
AC: This happens if the WaitJoin timer expires, or if the AC sends a Join Response message with a Result Code message element containing an error. That makes the AC start the DTLSShutdown command (see Section 2.3.2.1). It also happens if the AC gets any of these DTLS notifications: DTLSAborted, DTLSReassemblyFailure, or DTLSPeerDisconnect. The AC starts the DTLSSessionDelete timer (see Section 4.7.6) 🫶
Join to Image Data (f): This state transition is how the WTP and the AC download executable firmware 📦
WTP: The WTP enters the Image Data state when it gets a successful Join Response message and figures out that the software version in the Image Identifier message element isn't the same as its currently running image. The WTP also notices that the requested image version isn't available in its non-volatile storage (see Section 9.1 for the full firmware download process). Then it starts the EchoInterval timer (see Section 4.7) and sends the Image Data Request message (see Section 9.1.1) to ask for the firmware download to start 💾
AC: This happens when the AC gets the Image Data Request message from the WTP, after it has already sent its Join Response to the WTP. The AC stops the WaitJoin timer. The AC MUST transmit an Image Data Response message (see Section 9.1.2) to the WTP, and that message includes a piece of the firmware 🧩
Join to Configure (g): This state transition is how the WTP and the AC swap configuration info ⚙️
WTP: The WTP enters the Configure state when it gets a successful Join Response message and sees that the Image Identifier message element is the same as its currently running image. Then it sends the Configuration Status Request message (see Section 8.2) to the AC, with message elements describing its current configuration 📝
AC: This happens when the AC gets the Configuration Status Request message from the WTP (see Section 8.2). That message MAY include specific message elements to override the WTP's configuration, so the AC has the final say 👑 The AC stops the WaitJoin timer, sends the Configuration Status Response message (see Section 8.3), and starts the ChangeStatePendingTimer timer (see Section 4.7) ⏳
Configure to Reset (h): This state transition resets the connection, either because of an error during the configuration phase or because the WTP figures out it needs to reset for the new configuration to take effect 🔄 The CAPWAP Reset command is used to tell the peer that it will start a DTLS teardown 🧨
WTP: The WTP enters the Reset state when it gets a Configuration Status Response message that signals an error, or when it decides a reset is needed because of what the new configuration looks like 🔧
AC: The AC moves to the Reset state when it gets a Change State Event message from the WTP that has an error AC policy won't allow the WTP to get service for. This also happens when the AC's ChangeStatePendingTimer timer expires ⏰
Configure to DTLS Teardown (i): This transition happens when the configuration process aborts because of a DTLS error 🚫
WTP: The WTP enters this state when it gets any of these DTLS notifications: DTLSAborted, DTLSReassemblyFailure, or DTLSPeerDisconnect (see Section 2.3.2.2). The WTP MAY tear down the DTLS session if it keeps getting frequent DTLSDecapFailure notifications 🧯 Then it starts the DTLSSessionDelete timer (see Section 4.7.6) 🌸
AC: The AC enters this state when it gets any of these DTLS notifications: DTLSAborted, DTLSReassemblyFailure, or DTLSPeerDisconnect (see Section 2.3.2.2). The AC MAY tear down the DTLS session if it keeps getting frequent DTLSDecapFailure notifications 🧯 The AC then starts the DTLSSessionDelete timer (see Section 4.7.6) 💜
Image Data to Data (j): okay so this is the Image Data state, and it's where the WTP and AC are busy with the firmware download phase 💾✨ Both of them use it during that phase, bestie 🎀
WTP: the WTP enters the Image Data state when it gets an Image Data Response message saying the AC still has more data to send 📦 This transition also happens when the WTP gets the next Image Data Requests. At that point it resets the ImageDataStartTimer so it's ready for the next expected Image Data Request from the AC ⏱️ It can also happen when the WTP's EchoInterval timer (see Section 4.7.7) expires. Then the WTP sends an Echo Request message (see Section 7.1) and resets its EchoInterval timer 🔄 And it happens when the WTP receives an Echo Response from the AC (see Section 7.2) 🫶
AC: this transition happens when the AC gets an Image Data Response message from the WTP while it's already in the Image Data state 💅 It also happens when the AC receives an Echo Request (see Section 7.1) from the WTP. The AC replies with an Echo Response (see Section 7.2) and resets its EchoInterval timer (see Section 4.7.7) 🌸
Image Data to Reset (k): this one is used to reset the DTLS connection before the WTP restarts after an image download 🔁
WTP: when an image download finishes, or the ImageDataStartTimer timer expires, the WTP enters the Reset state 🏁 The WTP MAY also move to this state if it gets an Image Data Response message from the AC (see Section 9.1.2) that indicates a failure 🙈
AC: the AC enters the Reset state either when the image transfer has successfully completed or when an error happens during the image download process 🌈
Image Data to DTLS Teardown (l): this transition happens when the firmware download process aborts because of a DTLS error 💀
WTP: the WTP enters this state when it receives one of these DTLS notifications: DTLSAborted, DTLSReassemblyFailure, or DTLSPeerDisconnect (see Section 2.3.2.2) 😭 The WTP MAY tear down the DTLS session if it keeps getting frequent DTLSDecapFailure notifications. Then the WTP starts the DTLSSessionDelete timer (see Section 4.7.6) ⏳
AC: the AC enters this state when it receives one of these same DTLS notifications: DTLSAborted, DTLSReassemblyFailure, or DTLSPeerDisconnect (see Section 2.3.2.2) 🥀 The AC MAY tear down the DTLS session if it gets frequent DTLSDecapFailure notifications. The AC starts the DTLSSessionDelete timer (see Section 4.7.6) 💜
Configure to Data Check (m): this is where the WTP and AC confirm the configuration together 🤝
WTP: the WTP enters this state when it receives a successful Configuration Status Response message from the AC ✅ The WTP sends the Change State Event Request message (see Section 8.6) 📨
AC: this transition happens when the AC receives the Change State Event Request message (see Section 8.6) from the WTP 👀 The AC responds with a Change State Event Response message (see Section 8.7). The AC MUST start the DataCheckTimer timer and stops the ChangeStatePendingTimer timer (see Section 4.7) 🎯
Data Check to DTLS Teardown (n): this transition happens when the WTP doesn't finish the Data Check exchange 😬
WTP: this transition happens if the WTP doesn't receive the Change State Event Response message before a CAPWAP retransmission timeout occurs. The WTP also moves to this state if the underlying reliable transport's RetransmitCount counter has reached the MaxRetransmit variable (see Section 4.7). The WTP starts the DTLSSessionDelete timer (see Section 4.7.6) 🫠
AC: the AC enters this state when the DataCheckTimer timer expires (see Section 4.7). The AC starts the DTLSSessionDelete timer (see Section 4.7.6) 💔
Data Check to Run (o): this is the glow-up moment 🦋 It happens when the link between the control and data channels is established, and the WTP and AC enter their normal state of operation 👑
WTP: the WTP enters this state when it receives a successful Change State Event Response message from the AC 🎉 The WTP initiates the data channel, which MAY require the establishment of a DTLS session. Then it starts the DataChannelKeepAlive timer (see Section 4.7.2) and sends a Data Channel Keep-Alive packet (see Section 4.4.1) 💖 After that, the WTP starts the EchoInterval timer and the DataChannelDeadInterval timer (see Section 4.7) ⭐
AC: this transition happens when the AC receives the Data Channel Keep-Alive packet (see Section 4.4.1), with a Session ID message element that matches the one the WTP included in the Join Request message 🔗 The AC disables the DataCheckTimer timer. Also, if AC policy is to require the data channel to be encrypted, this process would also need the establishment of a data channel DTLS session 🔐 When the AC gets the Data Channel Keep-Alive packet, it sends its own Data Channel Keep Alive packet 🌷
Run to DTLS Teardown (p): this transition happens when something goes wrong in the DTLS stack and the DTLS session gets torn down 🌪️
WTP: the WTP enters this state when it receives one of these DTLS notifications: DTLSAborted, DTLSReassemblyFailure, or DTLSPeerDisconnect (see Section 2.3.2.2) 🙃 The WTP MAY tear down the DTLS session if it receives frequent DTLSDecapFailure notifications. The WTP also moves to this state if the underlying reliable transport's RetransmitCount counter has reached the MaxRetransmit variable (see Section 4.7). Then it starts the DTLSSessionDelete timer (see Section 4.7.6) 🧚
AC: the AC enters this state when it receives one of these DTLS notifications: DTLSAborted, DTLSReassemblyFailure, or DTLSPeerDisconnect (see Section 2.3.2.2) 😤 The AC MAY tear down the DTLS session if it receives frequent DTLSDecapFailure notifications. The AC moves to this state if the underlying reliable transport's RetransmitCount counter has reached the MaxRetransmit variable (see Section 4.7). This transition also happens when the AC's EchoInterval timer (see Section 4.7.7) expires. The AC starts the DTLSSessionDelete timer (see Section 4.7.6) 🪦
Run to Run (q): this is the normal state of operation, the main character energy of the whole state machine 👑💅
WTP: this is the WTP's normal state of operation. The WTP resets its EchoInterval timer whenever it sends a request to the AC 📬 A bunch of events lead to this transition:
- Configuration Update: the WTP receives a Configuration Update Request message (see Section 8.4). The WTP MUST respond with a Configuration Update Response message (see Section 8.5) 🛠️
- Change State Event: the WTP receives a Change State Event Response message, or it decides it has to start a Change State Event Request message because a radio's state has failed or changed 📡
- Echo Request: the WTP sends an Echo Request message (Section 7.1) or receives the matching Echo Response message (see Section 7.2) from the AC. When the WTP gets the Echo Response, it resets its
EchoIntervaltimer (see Section 4.7.7) 🏓 - Clear Config Request: the WTP receives a Clear Configuration Request message (see Section 8.8) and MUST generate a matching Clear Configuration Response message (see Section 8.9). The WTP MUST reset its configuration back to manufacturer defaults 🧹
- WTP Event: the WTP sends a WTP Event Request message, delivering information to the AC (see Section 9.4). The WTP receives a WTP Event Response message from the AC (see Section 9.5) 📋
- Data Transfer: the WTP sends a Data Transfer Request or Data Transfer Response message to the AC (see Section 9.6). The WTP receives a Data Transfer Request or Data Transfer Response message from the AC (see Section 9.6). When the WTP gets a Data Transfer Request, it sends a Data Transfer Response to the AC 📤📥
- Station Configuration Request: the WTP receives a Station Configuration Request message (see Section 10.1), and it MUST respond with a Station Configuration Response message (see Section 10.2) 📶
AC: this is the AC's normal state of operation. Keep in mind that getting any Request from the WTP makes the AC reset its EchoInterval timer (see Section 4.7.7) ⏰
- Configuration Update: the AC sends a Configuration Update Request message (see Section 8.4) to the WTP to update its configuration. The AC receives a Configuration Update Response message (see Section 8.5) from the WTP 🧩
- Change State Event: the AC receives a Change State Event Request message (see Section 8.6), and it MUST respond with the Change State Event Response message (see Section 8.7) 💌
- Echo Request: the AC receives an Echo Request message (see Section 7.1), and it MUST respond with an Echo Response message (see Section 7.2) 🏐
- Clear Config Response: the AC sends a Clear Configuration Request message (see Section 8.8) to the WTP to clear its configuration. The AC receives a Clear Configuration Response message from the WTP (see Section 8.9) 🫧
- WTP Event: the AC receives a WTP Event Request message from the WTP (see Section 9.4) and MUST generate a matching WTP Event Response message (see Section 9.5) 🎀
- Data Transfer: the AC sends a Data Transfer Request or Data Transfer Response message to the WTP (see Section 9.6). The AC receives a Data Transfer Request or Data Transfer Response message from the WTP (see Section 9.6). When the AC gets a Data Transfer Request, it sends a Data Transfer Response to the WTP 💫
- Station Configuration Request: the AC sends a Station Configuration Request message (see Section 10.1) or receives the matching Station Configuration Response message (see Section 10.2) from the WTP 🌟
Okay so the state machine is about to get dramatic 💅 Anyway, bestie, here's how the connection gets torn down, one transition at a time.
Run to Reset (r): this one fires when either the AC or the WTP decides to tear the connection down 🙈 It can happen during normal operation or because something went wrong.
- WTP: the WTP enters Reset when it receives a Reset Request message from the AC 🫶
- AC: the AC enters Reset when it sends a Reset Request message to the WTP ✨
Reset to DTLS Teardown (s): once the CAPWAP reset is done, it's time to shut down the DTLS session 🦋
- WTP: the WTP sends a Reset Response message, and that's what moves it along. It does not invoke the DTLSShutdown command (see Section 2.3.2.1) 🙅♀️ It starts the DTLSSessionDelete timer (see Section 4.7.6) ⏰
- AC: the AC receives a Reset Response message, which makes it initiate the DTLSShutdown command (see Section 2.3.2.1) 💜 It also starts the DTLSSessionDelete timer (see Section 4.7.6).
DTLS Teardown to Idle (t): this is the "all clean" transition, once the DTLS session has been shut down 🌸
- WTP: this happens when the WTP has finished cleaning up everything tied to the control plane DTLS session, or when the DTLSSessionDelete timer (see Section 4.7.6) runs out. If a DTLS session was set up for the data plane, that one gets shut down and its resources released too. Any timers for the current instance of the state machine get cleared as well 🧹
- AC: this is an invalid state transition for the AC 🚫
DTLS Teardown to Sulking (u): this one shows up when repeated attempts to set up the DTLS connection keep failing 😭
- WTP: the WTP lands here when the FailedDTLSSessionCount or the FailedDTLSAuthFailCount counter hits the value of the MaxFailedDTLSSessionRetry variable (see Section 4.8). The moment it enters this state, the WTP MUST start the SilentInterval timer ⏳ While it's in Sulking, all received CAPWAP and DTLS protocol messages MUST be ignored 🤫
- AC: this is an invalid state transition for the AC 🚫
DTLS Teardown to Dead (w): this is also the "DTLS session has been shut down" transition, but it's the AC's version of the story 💀
- WTP: this is an invalid state transition for the WTP 🚫
- AC: this happens when the AC has finished cleaning up everything tied to the control plane DTLS session, or when the DTLSSessionDelete timer (see Section 4.7.6) expires. If a DTLS session was set up for the data plane, that one is shut down and its resources released as well. Any timers for the current instance of the state machine are cleared too. And the AC's Service thread gets terminated 🧵
2.3.2. CAPWAP/DTLS Interface
This section is all about the DTLS Commands that CAPWAP uses, plus the notifications that DTLS sends back up to the CAPWAP protocol stack 🎀
2.3.2.1. CAPWAP to DTLS Commands
Six commands are defined for the CAPWAP to DTLS API. These "commands" are conceptual, so they may be implemented as one or more function calls 🧩 This API definition exists to make the interactions between the DTLS and CAPWAP components of the integrated CAPWAP state machine clear.
Here's the list of the minimal command APIs:
- DTLSStart is sent to the DTLS component to get a DTLS session established. As soon as DTLSStart is invoked, the WaitDTLS timer starts ⏱️ The WTP is the one that initiates this DTLS command, since the AC never starts DTLS sessions 🙌
- DTLSListen is sent to the DTLS component so it can listen for incoming DTLS session requests 👂
- DTLSAccept is sent to the DTLS component so the DTLS session establishment can carry on successfully 🥂
- DTLSAbortSession is sent to the DTLS component to abort a session that's still being established 🛑 It also gets sent when the WaitDTLS timer expires. When this command runs, the FailedDTLSSessionCount counter goes up by one 📈
- DTLSShutdown is sent to the DTLS component to tear the session down 👋
- DTLSMtuUpdate is sent by the CAPWAP component to change the MTU size the DTLS component uses. Check out Section 3.5 for more on MTU Discovery 🔍 The default size is 1468 bytes 📏
2.3.2.2. DTLS to CAPWAP Notifications
DTLS notifications are defined for the DTLS to CAPWAP API. These "notifications" are conceptual too, and they can be implemented in lots of ways (for example, as function return values) 💅 This API definition is there to clarify the interactions between the DTLS and CAPWAP components of the integrated CAPWAP state machine.
Important tea ☕: the notifications below MAY cause the CAPWAP state machine to jump from one state to another, using a state transition that isn't listed in Section 2.3.1. When one of these notifications happens, the target CAPWAP state shown in Figure 4 becomes the current state 🦘
Here's the list of the API notifications:
- DTLSPeerAuthorize is sent to the CAPWAP component during DTLS session establishment, once the peer's identity has been received 🪪 The CAPWAP component MAY use this notification to authorize the session, based on the peer's identity. The authorization process then leads to the CAPWAP component initiating either the DTLSAccept or DTLSAbortSession commands ✅
- DTLSEstablished is sent to the CAPWAP component to say a secure channel now exists, using the parameters from the DTLS initialization process 🔐 When this notification arrives, the FailedDTLSSessionCount counter resets to zero, and the WaitDTLS timer stops 🎉
- DTLSEstablishFail is sent when DTLS session establishment has failed, either because of a local error or because the peer rejected the session establishment 💔 When this notification arrives, the FailedDTLSSessionCount counter goes up by one.
- DTLSAuthenticateFail is sent when DTLS session establishment has failed because of an authentication error 🚨 When this notification arrives, the FailedDTLSAuthFailCount counter goes up by one.
- DTLSAborted is sent to the CAPWAP component to say that the session abort (the one CAPWAP asked for) is complete 🫡 This happens to confirm a DTLS session abort, or when the WaitDTLS timer expires. When this notification arrives, the WaitDTLS timer stops.
- DTLSReassemblyFailure MAY be sent to the CAPWAP component to indicate that DTLS fragment reassembly failed 🧩
- DTLSDecapFailure MAY be sent to the CAPWAP module to indicate a decapsulation failure. It MAY also be sent to the CAPWAP module to indicate an encryption/authentication failure. This notification is for informative purposes only 📝 It is not meant to cause a change in the CAPWAP state machine (see Section 12.4) 🙅♀️
- DTLSPeerDisconnect is sent to the CAPWAP component to indicate the DTLS session has been torn down 🥀 Heads up: this notification only shows up if the DTLS session was established first.
2.4. Use of DTLS in the CAPWAP Protocol
DTLS is used as a tightly integrated, secure wrapper for the CAPWAP protocol 🎁 In this document, DTLS and CAPWAP are talked about as separate entities, but they're very closely coupled and might even be implemented inseparably 👯 Since there are DTLS library implementations available right now, and since security protocols (for example, IPsec and TLS) often live in widely available acceleration hardware, keeping a modular distinction in this document is both convenient and forward-looking 🔮
This section walks through how the DTLS module and the CAPWAP module interact, step by step. That happens through 'commands' (CAPWAP to DTLS) and 'notifications' (DTLS to CAPWAP), the way they'd show up during normal operation 🎬
2.4.1. DTLS Handshake Processing
The details of the DTLS handshake are specified in [RFC4347]. This section covers how the DTLS session establishment process and the CAPWAP protocol interact 🤝 The conceptual DTLS state is shown below so you can see where the DTLS states transition. In the normal case, the DTLS handshake goes like Figure 5. (NOTE: this example uses certificates, but pre-shared keys are supported too 🔑)
============ ============
WTP AC
============ ============
ClientHello ------>
<------ HelloVerifyRequest
(with cookie)
ClientHello ------>
(with cookie)
<------ ServerHello
<------ Certificate
<------ ServerHelloDone
(WTP callout for AC authorization
occurs in CAPWAP Auth state)
Certificate*
ClientKeyExchange
CertificateVerify*
ChangeCipherSpec
Finished ------>
(AC callout for WTP authorization
occurs in CAPWAP Auth state)
ChangeCipherSpec
<------ Finished
Figure 5: DTLS HandshakeDTLS, as specified, comes with its own retransmit timers that use an exponential back-off ⏳ [RFC4347] doesn't say how long retransmissions should keep going, so timing out incomplete DTLS handshakes is entirely up to the CAPWAP module 🫠
The DTLS implementation used by CAPWAP MUST support TLS Session Resumption 🔁 Session resumption is usually how the DTLS session for the data channel gets set up. Since the data channel uses different port numbers than the control channel, the DTLS implementation on the WTP MUST provide an interface that lets the CAPWAP module request session resumption even with those different port numbers. (TLS implementations usually only try session resumption when connecting to the same IP address and port number, so this part is a little extra 🧐) Heads up: session resumption isn't guaranteed to happen, and a full DTLS handshake may happen instead 🤷♀️
The DTLS implementation used by CAPWAP MUST use replay detection, per Section 3.3 of [RFC4347] 🛡️ The CAPWAP protocol handles retransmissions by re-encrypting lost frames, so any duplicate DTLS frames are either unintentional or malicious, and they should be silently discarded 👀 Bye-bye, duplicates 💅✨
2.4.2. DTLS Session Establishment ✨
Okay so the WTP figures out which AC it's going to connect to, either through the Discovery process or because it was pre-configured that way 🫶. Then it sends the DTLSStart command to ask for a secure connection to that AC 🔐. Before the DTLS handshake even starts, the WTP sets the WaitDTLS timer ⏱️. When the WTP invokes DTLSStart or the AC invokes DTLSListen, each of them sets the WaitDTLS timer, so both sides are on the same clock 💅.
If the DTLSEstablished notification doesn't arrive before the timer runs out, the DTLS session gets aborted by issuing the DTLSAbortSession DTLS command 😭. That notification is what pushes the CAPWAP module into the Idle state 🦋. And once a DTLSEstablished notification does come in, the WaitDTLS timer gets deactivated, so no more timeout drama 🎀.
2.4.3. DTLS Error Handling 💀
If the AC or the WTP doesn't respond to a DTLS handshake message its peer sent, the DTLS specification says that message gets retransmitted 🔁. Here's the tea: during the handshake, when both the AC and the WTP are waiting on more handshake messages, they both retransmit if an expected message hasn't shown up 🙌. (Note that CAPWAP Control messages work differently 🧚: every one of them is either a request or a response, and whoever sent the request is the one responsible for retransmitting it.)
If the WTP or the AC still doesn't get an expected DTLS handshake message after retransmissions, the WaitDTLS timer will eventually expire and the session will be terminated 😭. This can happen if communication between the peers has completely failed, or if one of the peers sent a DTLS Alert message that got lost in transit (DTLS does not retransmit Alert messages, so that one's on its own 💔).
If a cookie fails to validate, that could mean the WTP messed up, or it could mean a DoS attack 🚨. So the AC's resource utilization SHOULD be minimized 🧠. The AC MAY log a message about the failure, and it SHOULD treat the message as though no cookie were present 🙈.
DTLS Handshake messages can be bigger than the maximum record size, which is why DTLS supports fragmenting Handshake messages across multiple records 📦. There are a bunch of ways re-assembly can go wrong, including overlapping and/or lost fragments 😩. The DTLS component MUST send a DTLSReassemblyFailure notification to the CAPWAP component 📣. Whether precise information comes along with that notification is an implementation issue, so it's outside the scope of this document 🤷♀️. When the CAPWAP component gets an error like this, it SHOULD log an appropriate error message 📝. Whether processing continues or the DTLS session gets terminated is implementation dependent 🌸.
DTLS decapsulation errors come in three flavors: decryption errors, authentication errors, and malformed DTLS record headers 🍓. Since DTLS authenticates the data before encapsulation, if decryption fails it's hard to tell without first trying to authenticate the packet 🧩. If authentication fails, a decryption error is likely but not guaranteed 🤔. Rather than deriving (and forcing implementers to build) algorithms for detecting decryption failures, decryption failures are reported as authentication failures, which is so much simpler 💅. The DTLS component MUST provide a DTLSDecapFailure notification to the CAPWAP component whenever these errors occur 🔔. If a malformed DTLS record header is detected, the packets SHOULD be silently discarded, and the receiver MAY log an error message 🤫.
There's currently only one encapsulation error defined: MTU exceeded 📏. As part of DTLS session establishment, the CAPWAP component tells the DTLS component what the MTU size is 📬. That value can be dynamically changed at any time when the CAPWAP component sends the DTLSMtuUpdate command to the DTLS component (see Section 2.3.2.1) 🔄. The value handed to the DTLS stack is the result of the MTU Discovery process, which is described in Section 3.5 🗺️. And whenever a transmission request would produce a packet bigger than the MTU, the DTLS component sends this notification back to the CAPWAP component 🚫.
2.4.4. DTLS Endpoint Authentication and Authorization 🔑
DTLS can authenticate endpoints with certificates or pre-shared keys 🗝️. The TLS algorithm suites for each endpoint authentication method are described below 👑.
2.4.4.1. Authenticating with Certificates 📜
CAPWAP implementations only use cipher suites that are recommended for use with DTLS, so go check [DTLS-DESIGN] 📖. For now, the following algorithm MUST be supported when using certificates for CAPWAP authentication 💪:
TLS_RSA_WITH_AES_128_CBC_SHA[RFC5246]
The following algorithm SHOULD be supported when using certificates 👀:
TLS_DHE_RSA_WITH_AES_128_CBC_SHA[RFC5246]
The following algorithms MAY be supported when using certificates 🌈:
Additional ciphers MAY be defined in subsequent CAPWAP specifications 🔮.
2.4.4.2. Authenticating with Pre-Shared Keys 🫣
Pre-shared keys come with some serious security challenges, so their use is strongly discouraged 🚩. Several methods for authenticating with pre-shared keys are defined [RFC4279], and we're focusing on these two 🎯:
- Pre-Shared Key (PSK) key exchange algorithm: the simplest method, where the ciphersuites only use symmetric key algorithms 🧁.
- DHE_PSK key exchange algorithm: uses a PSK to authenticate a Diffie-Hellman exchange. These ciphersuites give some extra protection against dictionary attacks and also provide Perfect Forward Secrecy (PFS) ✨.
The first approach (plain PSK) is vulnerable to passive dictionary attacks 😱. So while this algorithm MUST be supported, special care should be taken when choosing that method 🧐. Specifically, user-readable passphrases SHOULD NOT be used, and short PSKs SHOULD be strongly discouraged 🙅♀️.
The following cryptographic algorithms MUST be supported when using pre-shared keys 🔐:
The following algorithms MAY be supported when using pre-shared keys 💜:
Additional ciphers MAY be defined in following CAPWAP specifications 🌸.
2.4.4.3. Certificate Usage 🎀
Certificate authorization by the AC and WTP is required so that only an AC can do AC things and only a WTP can do WTP things 🧾. That split means the certificates used by the AC MUST be distinguishable from the certificate used by the WTP 🪪. To make that happen, the x.509 certificates MUST include the Extended Key Usage (EKU) certificate extension [RFC5280] 🏷️.
The EKU field says which purposes a certificate may be used for, and it's a huge part of authorization 💖. Its syntax is described in [RFC5280] and [ISO.9834-1.1993], and it looks like this:
ExtKeyUsageSyntax ::= SEQUENCE SIZE (1..MAX) OF KeyPurposeId
KeyPurposeId ::= OBJECT IDENTIFIERHere we define two KeyPurposeId values: one for the WTP and one for the AC 🧚. If one of these two values is included, the certificate is authorized for use by a WTP or an AC, respectively 🙌. They're formatted as id-kp fields:
id-kp OBJECT IDENTIFIER ::=
{ iso(1) identified-organization(3) dod(6) internet(1)
security(5) mechanisms(5) pkix(7) 3 }
id-kp-capwapAC OBJECT IDENTIFIER ::= { id-kp 18 }
id-kp-capwapWTP OBJECT IDENTIFIER ::= { id-kp 19 }All capwap devices MUST support the ExtendedKeyUsage certificate extension if it's present in a certificate 🛡️. If the extension is present, then the certificate MUST have either the id-kp-capwapAC or the id-kp-anyExtendedKeyUsage keyPurposeID to act as an AC 👑. Similarly, if the extension is present, a device MUST have the id-kp-capwapWTP or id-kp-anyExtendedKeyUsage keyPurposeID to act as a WTP 📡.
Part of CAPWAP certificate validation is making sure the proper EKU is included, and only letting the CAPWAP session get established if the extension properly represents the device 🕵️♀️. For instance, an AC SHOULD NOT accept a connection request from another AC 🙅♀️, so it MUST verify that the id-kp-capwapWTP EKU is present in the certificate 🔍.
CAPWAP implementations MUST support certificates where the common name (CN) for both the WTP and the AC is the MAC address of that device 🏷️. The MAC address MUST be encoded in the PrintableString format, using the well-recognized MAC address format of 01:23:45:67:89:ab 🔤. The CN field MAY contain either the EUI-48 [EUI-48] or EUI-64 [EUI-64] MAC Address formats 🔢. This seemingly unusual use of the CN field is consistent with other standards that rely on device certificates provisioned during manufacturing, like Packet Cable [PacketCable], Cable Labs [CableLabs], and WiMAX [WiMAX] 🏭. See Section 12.8 for more information on using the MAC address in the CN field 📚.
ACs and WTPs MUST authorize (for example, through access control lists) the certificates of devices they're connecting to, based on things like the issuer, MAC address, or organizational information in the certificate 🚪. The identities in the certificates bind a particular DTLS session to a specific pair of mutually authenticated and authorized MAC addresses 💞. How authorization filters get built is up to the implementation, and for the most part it's outside the scope of this specification 🛠️. But at minimum, all devices MUST verify that the appropriate EKU bit is set for the role of the peer device (AC versus WTP), and that the issuer of the certificate is appropriate for the domain in question ✅.
2.4.4.4. PSK Usage 🗝️
When DTLS uses PSK Ciphersuites, the ServerKeyExchange message MUST contain the "PSK identity hint" field, and the ClientKeyExchange message MUST contain the "PSK identity" field 📨. These fields help the WTP pick the right PSK to use with the AC, and then tell the AC which key is being used 🫶. When PSKs get provisioned to WTPs and ACs, both the PSK Hint and the PSK Identity for the key MUST be specified 📝.
The PSK Hint SHOULD uniquely identify the AC, and the PSK Identity SHOULD uniquely identify the WTP 🆔. It is RECOMMENDED that these hints and identities be the ASCII HEX-formatted MAC addresses of the respective devices, since each pairwise combination of WTP and AC SHOULD have a unique PSK 💅. The PSK Hint and Identity SHOULD be sufficient to perform authorization, because simply knowing a PSK doesn't necessarily mean a device is authorized 🚨.
If a single PSK is being used for multiple devices on a CAPWAP network, which is NOT RECOMMENDED 🙈, the PSK Hint and Identity can no longer be a MAC address. So appropriate hints and identities SHOULD be selected to identify the group of devices the PSK is provisioned to 🧸.
3. CAPWAP Transport 🦋
okay so communication between a WTP and an AC gets set up using the standard UDP client/server model 💖 CAPWAP supports both UDP and UDP-Lite [RFC3828] transport protocols. When it runs over IPv4, UDP is used for the CAPWAP Control and Data channels ✨
When it runs over IPv6, the CAPWAP Control channel always uses UDP, while the CAPWAP Data channel may use either UDP or UDP-Lite. UDP-Lite is the default transport protocol for the CAPWAP Data channel 🌸 However, if a middlebox or IPv4 to IPv6 gateway has been discovered, UDP is used for the CAPWAP Data channel instead 💅
This section breaks down how CAPWAP gets carried over IP and UDP/UDP-Lite 🎀 The CAPWAP Transport Protocol message element, Section 4.6.14, is where you find the rules for deciding which transport protocol to use 🧚
Now, middleboxes are a whole thing in CAPWAP land 👀 So that CAPWAP can play nicely with possible middleboxes in the network, CAPWAP implementations MUST send return traffic from the same port on which they received traffic from a given peer. Further, any unsolicited requests generated by a CAPWAP node MUST be sent on the same port 🔥
3.1. UDP Transport 🌈
One of the CAPWAP protocol requirements is letting a WTP live behind a middlebox, firewall, and/or Network Address Translation (NAT) device 🙈 A CAPWAP session is started by the WTP (client) reaching out to the well-known UDP port of the AC (server), so UDP is a super logical choice 💜 When CAPWAP runs over IPv4, the UDP checksum field in CAPWAP packets MUST be set to zero.
CAPWAP protocol control packets sent from the WTP to the AC travel over the CAPWAP Control channel, as defined in Section 1.4 🫶 The CAPWAP control port at the AC is the well-known UDP port 5246. The CAPWAP control port at the WTP can be any port the WTP picks.
CAPWAP protocol data packets sent from the WTP to the AC travel over the CAPWAP Data channel, as defined in Section 1.4 ✨ The CAPWAP data port at the AC is the well-known UDP port 5247. If an AC lets the administrator change the CAPWAP control port, the CAPWAP data port MUST be the next consecutive port number. The CAPWAP data port at the WTP can be any port the WTP picks.
3.2. UDP-Lite Transport 🍓
When CAPWAP runs over IPv6, UDP-Lite is the default transport protocol 🫧 That cuts down on the checksum processing needed for each packet (compared to using UDP over IPv6 [RFC2460]). When UDP-Lite is used, the checksum field MUST have a coverage of 8 [RFC3828].
UDP-Lite uses the same port assignments as UDP 🦋
3.3. AC Discovery 🔍
The AC Discovery phase is how the WTP figures out which ACs are available and picks the best AC to set up a CAPWAP session with 💖 The Discovery phase happens when the WTP enters the optional Discovery state. A WTP doesn't need to finish the AC Discovery phase if it uses a pre-configured AC. This section details the mechanism a WTP uses to dynamically discover candidate ACs 🧚
A WTP and an AC will frequently not live in the same IP subnet (broadcast domain) 🌸 When that happens, the WTP must be capable of discovering the AC without requiring that multicast services are enabled in the network 🙌
When the WTP tries to set up communication with an AC, it sends the Discovery Request message and receives the Discovery Response message from the AC(s) 💅 The WTP MUST send the Discovery Request message to either the limited broadcast IP address (255.255.255.255), the well-known CAPWAP multicast address (224.0.1.140), or the unicast IP address of the AC. For IPv6 networks, broadcast doesn't exist, so the "All ACs multicast address" (FF0X:0:0:0:0:0:0:18C) is used instead 🌈 Once the AC gets the Discovery Request message, it sends a Discovery Response message to the unicast IP address of the WTP, no matter whether the Discovery Request message was sent as a broadcast, multicast, or unicast message 🫶
Whether the WTP uses a limited IP broadcast, multicast, or unicast IP address is implementation dependent 🤷♀️ ACs, on the other hand, MUST support broadcast, multicast, and unicast discovery 🔥
When a WTP sends a Discovery Request message to a unicast address, the WTP must first obtain the IP address of the AC 💜 Any static configuration of an AC's IP address on the WTP's non-volatile storage is implementation dependent. However, additional dynamic schemes are possible, for example:
DHCP: See [RFC5417] for more information on using DHCP to discover AC IP addresses 🎀
DNS: The WTP MAY support using DNS Service Records (SRVs) [RFC2782] to discover the AC address(es) ✨ In this case, the WTP first obtains (e.g., from local configuration) the correct domain name suffix (e.g., "example.com") and performs an SRV lookup with Service name "capwap-control" and Proto "udp". So the name resolved in DNS would be, e.g., _capwap-control._udp.example.com. Note that the SRV record MAY specify a non-default port number for the control channel. The port number for the data channel is the next port number (control channel port + 1) 🍓
An AC MAY also tell the WTP about alternative ACs within the Discovery Response message, through the AC IPv4 List (see Section 4.6.2) and the AC IPv6 List (see Section 4.6.2) 🧚 The addresses in these two message elements are meant to help the WTP find additional ACs by means other than the ones listed above 🌸
The AC Name with Priority message element (see Section 4.6.5) is used to communicate a list of preferred ACs to the WTP 💖 The WTP SHOULD attempt to use the ACs in the order the AC provided them. The Name-to-IP Address mapping is handled through the Discovery message exchange, where ACs give their identity in the AC Name (see Section 4.6.4) message element in the Discovery Response message 👑
Once the WTP has received Discovery Response messages from the candidate ACs, it MAY use other factors to pick the preferred AC 🔍 For instance, each binding defines a WTP Radio Information message element (see Section 2.1), which the AC includes in Discovery Response messages. The presence of one or more of these message elements is used to identify the CAPWAP bindings the AC supports 🦋 A WTP MAY connect to an AC based on the supported bindings advertised 💅
3.4. Fragmentation/Reassembly 🧩
IP already provides fragmentation and reassembly services, but CAPWAP provides them too 🫧 Environments where CAPWAP is used involve firewall, NAT, and "middlebox" devices, which tend to drop IP fragments to minimize possible DoS attacks 🙈 By doing fragmentation and reassembly at the application layer, any fragmentation needed because of the tunneling component of CAPWAP becomes transparent to these intermediate devices ✨ So CAPWAP can be used in any network topology, including ones with firewall, NAT, and middlebox devices 🌈
⚠️ It's important to note that the fragmentation mechanism CAPWAP uses has known limitations and deficiencies, which are similar to those described in [RFC4963]. The limited size of the Fragment ID field (see Section 4.3) can cause the field to wrap, and then fragments from different datagrams can get incorrectly spliced together (known as "mis-associated"). For example, a 100Mpbs link with an MTU of 1500 (causing fragmentation at 1450 bytes) would cause the Fragment ID field to wrap in 8 seconds. So CAPWAP implementers are warned to properly size their buffers for reassembly based on the expected wireless technology throughput 😭
CAPWAP implementations SHOULD perform MTU Discovery (see Section 3.5), which can avoid the need for fragmentation 💅 When this spec was written, most enterprise switching and routing infrastructure could support "mini-jumbo" frames (1800 bytes), which gets rid of the need for fragmentation (assuming the station's MTU is 1500 bytes) 🎀 The need for fragmentation usually still exists when the WTP talks to the AC over a Wide Area Network (WAN). Therefore, future versions of the CAPWAP protocol SHOULD consider either increasing the size of the Fragment ID field or providing alternative extensions 👑
3.5. MTU Discovery 📏
Once a WTP has discovered the AC it wants to set up a CAPWAP session with, it SHOULD perform a Path MTU (PMTU) discovery 💖 One recommendation for doing PMTU discovery is for the WTP to send Discovery Request (see Section 5.1) messages that include the MTU Discovery Padding message element (see Section 4.6.32) 🧚 The actual procedures for PMTU discovery are described in [RFC1191] for IPv4. For IPv6, [RFC1981] SHOULD be used. Alternatively, implementers MAY use the procedures defined in [RFC4821] 🌸 The WTP SHOULD also periodically re-evaluate the PMTU using the guidelines in these two RFCs, using the Primary Discovery Request (see Section 5.3) along with the MTU Discovery Padding message element (see Section 4.6.32) 🫶 When the MTU is initially known, or gets updated when a session already exists, the discovered PMTU is used to configure the DTLS component (see Section 2.3.2.1), while non-DTLS frames need to be fragmented to fit the MTU, as defined in Section 3.4 🔥
4. CAPWAP Packet Formats ✨
okay bestie, this is where we get into the actual packet shapes 💅 A CAPWAP protocol packet is one or more CAPWAP Transport Layer packet headers followed by a CAPWAP message. That message is either type Control, which carries signaling 📣, or type Data, which carries user payloads 🎀. The frame formats for CAPWAP Data packets, and for DTLS encapsulated Data and Control packets, are laid out below.
The CAPWAP Control protocol has two messages that are never protected by DTLS: the Discovery Request and the Discovery Response 🙈 They have to stay in the clear so CAPWAP can identify and process them. The packet looks like this:
CAPWAP Control Packet (Discovery Request/Response):
+-------------------------------------------+
| IP | UDP | CAPWAP | Control | Message |
| Hdr | Hdr | Header | Header | Element(s) |
+-------------------------------------------+Every other CAPWAP Control message MUST be protected via DTLS, which makes sure the packets are both authenticated and encrypted 🔐 These packets include the CAPWAP DTLS Header, which is described in Section 4.2. Here's the shape:
CAPWAP Control Packet (DTLS Security Required):
+------------------------------------------------------------------+
| IP | UDP | CAPWAP | DTLS | CAPWAP | Control| Message | DTLS |
| Hdr | Hdr | DTLS Hdr | Hdr | Header | Header | Element(s)| Trlr |
+------------------------------------------------------------------+
\---------- authenticated -----------/
\------------- encrypted ------------/Protecting data packets with DTLS is optional 🌸 Whether it happens is decided by AC policy. When DTLS is used, the optional CAPWAP DTLS Header shows up, again described in Section 4.2. Check out the two Data packet shapes:
CAPWAP Plain Text Data Packet :
+-------------------------------+
| IP | UDP | CAPWAP | Wireless |
| Hdr | Hdr | Header | Payload |
+-------------------------------+
DTLS Secured CAPWAP Data Packet:
+--------------------------------------------------------+
| IP | UDP | CAPWAP | DTLS | CAPWAP | Wireless | DTLS |
| Hdr | Hdr | DTLS Hdr | Hdr | Hdr | Payload | Trlr |
+--------------------------------------------------------+
\------ authenticated -----/
\------- encrypted --------/Now let's break down each piece 🧩
- UDP Header: every CAPWAP packet gets wrapped in either UDP, or UDP-Lite when it's running over IPv6. Section 3 covers exactly which one is used and how.
- CAPWAP DTLS Header: every DTLS encrypted CAPWAP packet gets a CAPWAP DTLS Header in front (see Section 4.2).
- DTLS Header: this one provides the authentication and encryption for the CAPWAP payload it wraps. It's defined in [RFC4347].
- CAPWAP Header: every CAPWAP packet uses this common header, which sits right after the CAPWAP preamble or DTLS Header. It's defined in Section 4.3.
- Wireless Payload: a CAPWAP packet carrying a wireless payload is a CAPWAP Data packet 📡 CAPWAP doesn't define the wireless payload format; the matching wireless standard does. More info is in Section 4.4.
- Control Header: CAPWAP has a signaling side called the CAPWAP Control protocol. Every CAPWAP Control packet has a Control Header, defined in Section 4.5.1. CAPWAP Data packets don't have a Control Header field, so no drama there 💖
- Message Elements: a CAPWAP Control packet carries one or more message elements, sitting right after the Control Header. They use a Type/Length/Value style header, defined in Section 4.6.
Size check time 📏 A CAPWAP implementation MUST be able to receive a reassembled CAPWAP message of 4096 bytes. If it wants to say it can handle bigger, it MAY indicate that with the Maximum Message Length message element (see Section 4.6.31) in the Join Request or the Join Response message ✨
4.1. CAPWAP Preamble
The CAPWAP preamble is shared by all CAPWAP transport headers, and it tells you which header type comes next 🦋 The whole point is to avoid byte comparisons just to guess whether a frame is DTLS encrypted, which is lowkey genius. It also gives you an extensibility framework for supporting more transport types later. Here's the format:
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|Version| Type |
+-+-+-+-+-+-+-+-+- Version: a 4-bit field with the CAPWAP version used in this packet. For this specification the value is zero (0).
- Type: a 4-bit field that says which payload type comes right after the UDP header. These values are supported:
0 -CAPWAP Header. The CAPWAP Header (see Section 4.3) comes right after the UDP header. If the packet arrives on the CAPWAP Data channel, the CAPWAP stack MUST treat it as a clear text CAPWAP Data packet. If it arrives on the CAPWAP Control channel, the CAPWAP stack MUST treat it as a clear text CAPWAP Control packet. If that Control packet is not a Discovery Request or Discovery Response, the packet MUST be dropped 🚫1 -CAPWAP DTLS Header. The CAPWAP DTLS Header (and the DTLS packet) comes right after the UDP header (see Section 4.2) 🔒
4.2. CAPWAP DTLS Header
The CAPWAP DTLS Header is how a packet announces "hey, I'm DTLS encrypted" 🎀 The first eight bits hold the common CAPWAP Preamble. The remaining 24 bits are padding to keep things 4-byte aligned, and they MAY be used in a future version of the protocol 👀 The DTLS packet [RFC4347] always comes right after this header. Here's the shape:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|CAPWAP Preamble| Reserved |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- CAPWAP Preamble: defined in Section 4.1. Its Payload Type field MUST be set to one (1) 🧚
- Reserved: the 24-bit field is reserved for future use. Every implementation that follows this protocol MUST set to zero any bits that are reserved in the protocol version it supports. Receivers MUST ignore all bits that aren't defined for the version of the protocol they support 💜 Don't touch the reserved bits, bestie, that's the rule 🫶
4.3. CAPWAP Header ✨
okay bestie, every single CAPWAP message wears the same header, whether it's riding the Control channel or the Data channel 💅 but some flags are only valid for certain transports, so check the transport section before you assume anything 🎀
Heads up: the optional fields in this header MUST show up in the exact order below 🧚
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|CAPWAP Preamble| HLEN | RID | WBID |T|F|L|W|M|K|Flags|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Fragment ID | Frag Offset |Rsvd |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| (optional) Radio MAC Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| (optional) Wireless Specific Information |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Payload .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- CAPWAP Preamble: the CAPWAP Preamble lives in Section 4.1 🌸 its Payload Type field MUST be set to zero (0). If the CAPWAP DTLS Header is there too, the version number in both CAPWAP Preambles MUST match. Why the duplicate? So nobody can sneak a change into the version field of the preamble, which isn't encrypted or authenticated 🔒
- HLEN: a 5-bit field with the length of the CAPWAP transport header in 4-byte words, kinda like the IP header length. The length counts the optional headers too 📏
- RID: a 5-bit field holding the Radio ID for this packet, between one (1) and 31. MAC Addresses aren't necessarily unique across physical radios in a WTP, so the RID field tells you which physical radio the message belongs to 📡
- WBID: a 5-bit wireless binding identifier. It tells you what kind of wireless packet goes with the radio. The defined values are:
0- Reserved1- IEEE 802.112- Reserved3- EPCGlobal [EPCGlobal]
- T: the Type bit says what format the frame in the payload is in. When it's set to one (1), the payload uses the native frame format named by WBID. When it's zero (0), the payload is an IEEE 802.3 frame 🦋
- F: the Fragment bit says whether this packet is a fragment. When it's one (1), the packet is a fragment and MUST be combined with the other matching fragments to rebuild the full message the WTP and AC swapped 🧩
- L: the Last bit only matters when F is set. It tells you if this packet is the last fragment in the exchange between the WTP and AC. One (1) means yes, zero (0) means nope, more coming 🏁
- W: the Wireless bit says whether the optional Wireless Specific Information field is in the header. A value of one (1) means it's there ✨
- M: the Radio MAC bit says the optional Radio MAC Address header is present. It's how the MAC address of the receiving radio gets communicated 📮
- K: the Keep-Alive bit says the packet is a Data Channel Keep-Alive packet. It maps the data channel to the control channel for the given Session ID and keeps the data channel feeling fresh 💜 The 'K' bit MUST NOT be set for data packets containing user data, bestie, don't do it 🙅♀️
- Flags: a set of reserved bits for future flags in the CAPWAP Header. Every implementation that follows this protocol MUST set to zero any bits that are reserved in the protocol version it supports. Receivers MUST ignore all bits that aren't defined for the version they support 🫶
- Fragment ID: a 16-bit value given to each group of fragments that make up one complete set. The Fragment ID space is managed separately for each direction, for every WTP/AC pair. It goes up with each new set of fragments and wraps back to zero once the maximum value has been used 🔄
- Fragment Offset: a 13-bit field showing where this fragment goes in the payload when reassembling. It's only valid when F is set to 1. The offset is measured in units of 8 octets (64 bits). The first fragment has offset zero. Also, CAPWAP does not allow overlapping fragments, so don't even try 🙅♀️
- Reserved: a 3-bit field saved for future use. Every implementation that follows this protocol MUST set to zero any bits that are reserved in the protocol version it supports. Receivers MUST ignore all bits not defined for their version 🌈
- Radio MAC Address: this optional field has the MAC address of the radio that got the packet. When wireless frames get converted to IEEE 802.3 format, the WTP radio's MAC address gets lost, so this field saves it for the AC 🥹 It only shows up if the 'M' bit is set. The HLEN field assumes 4-byte alignment, and if this field isn't 4-byte aligned, it MUST be padded with zeroes (0x00) 🎀
The field uses this basic format:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Length | MAC Address
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Length: the length of the MAC address field. The formats and lengths in [EUI-48] and [EUI-64] are supported 💅
- MAC Address: the MAC address of the receiving radio 📱
- Wireless Specific Information: this optional field holds technology-specific info that can carry per-packet wireless details. It only shows up if the 'W' bit is set. The WBID field in the CAPWAP Header tells you which format this field uses. The HLEN field assumes 4-byte alignment, and if this field isn't 4-byte aligned, it MUST be padded with zeroes (0x00) 🫧
The Wireless-Specific Information field uses this format:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Length | Data...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Length: the 8-bit field with the length of the data field, max 255 🌟
- Data: wireless-specific info, defined by the wireless-specific binding named in the CAPWAP Header's WBID field 🦄
- Payload: this field holds the header for a CAPWAP Data Message or CAPWAP Control Message, followed by the data inside that message 💖
4.4. CAPWAP Data Messages 🌸
There are two kinds of CAPWAP Data packets: Data Channel Keep-Alive packets and Data Payload packets. The first one lets the WTP line up the control and data channels and keeps the data channel fresh. The second one carries the user payloads between the AC and WTP. This section covers both packet formats 🧚
Both CAPWAP Data messages go out on the CAPWAP Data channel 📡
4.4.1. CAPWAP Data Channel Keep-Alive 💜
The Data Channel Keep-Alive packet ties the control channel to the data channel and keeps the data channel fresh, so you know it's still working 💖 The WTP sends it whenever the DataChannelKeepAlive timer runs out (see Section 4.7.2). Once it's sent, the WTP starts the DataChannelDeadInterval timer ⏰
In a Data Channel Keep-Alive packet, every field in the CAPWAP Header is set to zero when it's sent, except for the HLEN field and the 'K' bit 🫶 When the AC gets one, it sends a Data Channel Keep-Alive packet right back to the WTP, and the contents match what came in 🔁
When the WTP gets a Data Channel Keep-Alive packet, it cancels the DataChannelDeadInterval timer and resets the DataChannelKeepAlive timer ✨ The WTP retransmits the Data Channel Keep-Alive packet the same way it handles CAPWAP Control messages. If the DataChannelDeadInterval timer expires, the WTP tears down the control DTLS session, plus the data DTLS session if there was one 💀
The Data Channel Keep-Alive packet has this payload right after the CAPWAP Header (see Section 4.3) 🎀
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Element Length | Message Element [0..N] ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Message Element Length: the 16-bit Length field counts the bytes after the CAPWAP Header, with a max size of 65535 📏
- Message Element[0..N]: the message elements carry the info each CAPWAP Data Channel Keep-Alive message needs. These message elements MUST be present in this CAPWAP message:
- Session ID, see Section 4.6.37. 🦋
4.4.2. Data Payload ✨
okay so the Data Payload packet is the one that carries the actual forwarded wireless frame 📦 CAPWAP has two encapsulation modes: IEEE 802.3 and native wireless 🫶 for IEEE 802.3 encapsulation, the 802.11 Integration function has to be done in the WTP (the WTP does the 802.11 Integration work, not the AC) 💅 an IEEE 802.3-encapsulated user payload frame looks like this:
+------------------------------------------------------+
| IP Header | UDP Header | CAPWAP Header | 802.3 Frame |
+------------------------------------------------------+native wireless mode is the other option 🌈 the encapsulated CAPWAP Data frame format follows the rules of the specific wireless technology binding. Each wireless technology binding MUST contain a section entitled "Payload Encapsulation", which defines the format of the wireless payload that gets encapsulated inside CAPWAP Data packets 🎀
for 802.3 payload frames, the 802.3 frame gets encapsulated, but NOT the IEEE 802.3 Preamble, Start Frame Delimiter (SFD), or Frame Check Sequence (FCS) fields 🙈 if the encapsulated frame would be bigger than the transport layer's MTU, the sender is responsible for fragmenting it, as described in Section 3.4 🧚 and CAPWAP can support IEEE 802.3 frames with lengths defined in the IEEE 802.3as specification [FRAME-EXT] 🔥
4.4.3. Establishment of a DTLS Data Channel 🔐
if the AC and WTP are set up to tunnel the data channel over DTLS, the proper DTLS session must be initiated 💖 to avoid making the AC and WTP reauthenticate and reauthorize all over again, the DTLS data channel SHOULD be initiated using the TLS session resumption feature [RFC5246] ✨
the AC DTLS implementation MUST NOT initiate a data channel session for a DTLS session that doesn't have an active control channel session 🚫 no cap, that's a hard rule 💀
4.5. CAPWAP Control Messages 🎀
the CAPWAP Control protocol gives the WTP and the AC a control channel between them 🦋 control messages are split into these message types:
- Discovery: CAPWAP Discovery messages are used to find potential ACs, plus their load and capabilities 🔍
- Join: CAPWAP Join messages are how a WTP asks an AC for service, and how the AC responds to the WTP 🤝
- Control Channel Management: these messages keep the control channel healthy 💅
- WTP Configuration Management: the AC uses these to deliver a specific configuration to the WTP. Messages that pull statistics from a WTP count here too 📊
- Station Session Management: the AC uses these to deliver specific station policies to the WTP 🧑🤝🧑
- Device Management Operations: these are for requesting and delivering a firmware image to the WTP 💾
- Binding-Specific CAPWAP Management Messages: the AC and WTP use these to swap protocol-specific CAPWAP management messages. They may or may not be used to change a station's link state 🌸
Discovery, Join, Control Channel Management, WTP Configuration Management, and Station Session Management CAPWAP Control messages MUST be implemented 👑 Device Management Operations messages MAY be implemented 🙌
CAPWAP Control messages sent from the WTP to the AC show the WTP is still operational, which is an implicit keep-alive for the WTP 💜 and when no other CAPWAP Control messages are going back and forth, the Control Channel Management Echo Request and Echo Response messages act as an explicit keep-alive 🫶
4.5.1. Control Message Format 🧾
all CAPWAP Control messages get sent encapsulated inside the CAPWAP Header (see Section 4.3) 🎁 right after the CAPWAP Header is the control header, which looks like this:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message Type |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Seq Num | Msg Element Length | Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Msg Element [0..N] ...
+-+-+-+-+-+-+-+-+-+-+-+-+4.5.1.1. Message Type 🏷️
the Message Type field tells you what the CAPWAP Control message does 🔎 for extensibility, it's made up of an IANA Enterprise Number [RFC3232] plus an enterprise-specific message type number 🌈 the first three octets hold the IANA Enterprise Number in network byte order, and zero is used for message types this base protocol spec defines 🧚 the last octet is the enterprise-specific message type number, ranging from 0 to 255 💫
the Message Type field is defined as:
Message Type =
IANA Enterprise Number * 256 +
Enterprise Specific Message Type Numberthe CAPWAP reliability mechanism needs messages to come in pairs: a Request and a Response 🤝 the Response message MUST acknowledge the Request message 💯 Message Type Values are always assigned in pairs too 🎀 all Request messages get odd Message Type Values, and all Response messages get even ones 🦋 the Request value MUST be assigned first 🙌 for example, giving a Request a Message Type Value of 3 and its Response a 4 is valid, but giving a Response a 4 and its Request a 5 is invalid 🙅♀️
when a WTP or AC gets a message with a Message Type Value it doesn't recognize, and that value is odd, the value gets incremented by one 💅 then a Response with that incremented value and a Result Code message element set to (Unrecognized Request) goes back to whoever sent the message 💌 if the unknown message type is even, the message just gets ignored 🫥
the valid CAPWAP Control Message Types are in this table:
CAPWAP Control Message Message Type
Value
Discovery Request 1
Discovery Response 2
Join Request 3
Join Response 4
Configuration Status Request 5
Configuration Status Response 6
Configuration Update Request 7
Configuration Update Response 8
WTP Event Request 9
WTP Event Response 10
Change State Event Request 11
Change State Event Response 12
Echo Request 13
Echo Response 14
Image Data Request 15
Image Data Response 16
Reset Request 17
Reset Response 18
Primary Discovery Request 19
Primary Discovery Response 20
Data Transfer Request 21
Data Transfer Response 22
Clear Configuration Request 23
Clear Configuration Response 24
Station Configuration Request 25
Station Configuration Response 264.5.1.2. Sequence Number 🔢
the Sequence Number field is an identifier that matches Request packets with their Response packets 💕 when a CAPWAP packet with a Request Message Type Value shows up, its Sequence Number gets copied into the matching Response message 🫶
whenever a CAPWAP Control message gets sent, the sender's internal sequence number counter goes up monotonically 📈 that makes sure no two pending Request messages share a sequence number 🙅♀️ and the Sequence Number field wraps back to zero when it runs out of room 🔄
4.5.1.3. Message Element Length 📏
the Length field tells you how many bytes come after the Sequence Number field 🧮
4.5.1.4. Flags 🚩
the Flags field MUST be set to zero 0️⃣ no exceptions, periodt 💅
4.5.1.5. Message Element [0..N] 🧩
the message elements carry the info each control message type needs 🎁 every control message in this spec says which message elements it's allowed to have 📋
when a WTP or AC gets a CAPWAP message that's missing a message element marked as mandatory for that message, the CAPWAP message gets discarded 🗑️ and if it was a Request whose Response is supposed to carry message elements, a Response comes back with a Result Code message element saying "Failure - Missing Mandatory Message Element" 😭
when a WTP or AC gets a CAPWAP message with a message element it doesn't recognize, that CAPWAP message gets discarded 🙈 and if it was a Request whose Response carries message elements, the Response comes back with a Result Code message element saying "Failure - Unrecognized Message Element", plus one or more Returned Message Element message elements that contain the unrecognized ones 🫣
⚠️ tbh this part is so important: missing or unrecognized message elements mean the whole message gets thrown out, so always check your mandatory elements first!
4.5.2. Quality of Service 🌟
the CAPWAP base protocol doesn't give any Quality of Service (QoS) recommendations for CAPWAP Data messages 🤷♀️ any wireless-specific CAPWAP binding with QoS requirements MUST define how QoS gets applied to the CAPWAP Data messages 💅
the IP header also has the Explicit Congestion Notification (ECN) bits [RFC3168] 🌬️ Section 9.1.1 of [RFC3168] describes two levels of ECN functionality: full and limited 🥹 CAPWAP ACs and WTPs SHALL implement the limited functionality, and they are RECOMMENDED to implement the full functionality described in [RFC3168] ✨
4.5.2.1. Applying QoS to CAPWAP Control Message 🚦
it is recommended that both the AC and the WTP send CAPWAP Control messages with a suitable Quality-of-Service precedence value 💖 that way, congestion in the network is less likely to knock the CAPWAP Control channel offline 🫶 so a QoS-enabled CAPWAP device SHOULD use these values:
- 802.1Q: The priority tag of 7 SHOULD be used. 🏷️
- DSCP: The CS6 per-hop behavior Service Class SHOULD be used, which is described in [RFC2474]). 🎀
4.5.3. Retransmissions 🔁
okay so the CAPWAP Control protocol is a reliable transport 💅 and honestly it's giving careful. For every Request message there's a Response message defined, and that Response is how the other side says "got it!" 🫶 The control header Sequence Number field is what pairs each Request with its Response (see Section 4.5.1).
Response messages don't get explicitly acknowledged, so if a Response goes missing, the original Request just gets sent again 😭🔁
Implementations MUST keep track of the sequence number of the last received Request message, and MUST cache the corresponding Response message. If a retransmission with the same sequence number shows up, the cached Response message MUST be retransmitted without re-processing the Request. If an older Request message comes in, meaning one where the sequence number is smaller, it MUST be ignored. A newer Request message, meaning one whose sequence number is larger, gets processed as usual ✨
Note: A sequence number is considered "smaller" when s1 is smaller than s2 modulo 256 if and only if (s1<s2 and (s2-s1)<128) or (s1>s2 and (s1-s2)>128). 🧮
Both the WTP and the AC can only have a single request outstanding at any given time. Retransmitted Request messages MUST NOT be altered by the sender. 🚫✏️
After transmitting a Request message, the RetransmitInterval (see Section 4.7) timer and MaxRetransmit (see Section 4.8) variable decide whether the original Request message needs to be retransmitted. The RetransmitInterval timer is used the first time the Request is retransmitted. After that, the timer doubles every subsequent time the same Request message is retransmitted, up to MaxRetransmit but no more than half the EchoInterval timer (see Section 4.7.7). Response messages are not subject to these timers. ⏱️
If the sender stops retransmitting a Request message before reaching MaxRetransmit retransmissions (which leads to transition to DTLS Teardown, as described in Section 2.3.1), it cannot know whether the recipient received and processed the Request or not. In most situations the sender SHOULD NOT do this. Instead, it should keep retransmitting until a Response message is received, or until transition to DTLS Teardown occurs. 🙈 However, if the sender does decide to continue the connection with a new or modified Request message, the new message MUST have a new sequence number and be treated as a new Request message by the receiver. Note that there is a high chance that both the WTP and the AC's sequence numbers will become out of sync. 💀
When a Request message is retransmitted, it MUST be re-encrypted via the DTLS stack. If the peer had received the Request message, and the corresponding Response message was lost, it is necessary to ensure that retransmitted Request messages are not identified as replays by the DTLS stack. Similarly, any cached Response messages that are retransmitted as a result of receiving a retransmitted Request message MUST be re-encrypted via DTLS. 🔐
Duplicate Response messages, identified by the Sequence Number field in the CAPWAP Control message header, SHOULD be discarded upon receipt. 🗑️
4.6. CAPWAP Protocol Message Elements ✨
This section defines the CAPWAP Protocol message elements that are included in CAPWAP protocol control messages. 🎀
Message elements are used to carry information needed in control messages. Every message element is identified by the Type Value field, defined below. The total length of the message elements is indicated in the message element's length field. 💖
All of the message element definitions in this document use a diagram similar to the one below in order to depict its format. Note that to simplify this specification, these diagrams do not include the header fields (Type and Length). The header field values are defined in the message element descriptions. 📐
Unless otherwise specified, a control message that lists a set of supported (or expected) message elements MUST NOT expect the message elements to be in any specific order. The sender MAY include the message elements in any order. Unless otherwise noted, one message element of each type is present in a given control message. 🧩
Unless otherwise specified, any configuration information sent by the AC to the WTP MAY be saved to non-volatile storage (see Section 8.1) for more information). 💾
Additional message elements may be defined in separate IETF documents. 🌈
The format of a message element uses the TLV format shown here: 🧁
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Value ... |
+-+-+-+-+-+-+-+-+The 16-bit Type field identifies the information carried in the Value field, and Length (16 bits) indicates the number of bytes in the Value field. The value of zero (0) is reserved and MUST NOT be used. The rest of the Type field values are allocated as follows: 🎯
Usage Type Values
CAPWAP Protocol Message Elements 1 - 1023
IEEE 802.11 Message Elements 1024 - 2047
Reserved for Future Use 2048 - 3071
EPCGlobal Message Elements 3072 - 4095
Reserved for Future Use 4096 - 65535The table below lists the CAPWAP protocol Message Elements and their Type values. 📋✨
CAPWAP Message Element Type Value
AC Descriptor 1
AC IPv4 List 2
AC IPv6 List 3
AC Name 4
AC Name with Priority 5
AC Timestamp 6
Add MAC ACL Entry 7
Add Station 8
Reserved 9
CAPWAP Control IPV4 Address 10
CAPWAP Control IPV6 Address 11
CAPWAP Local IPV4 Address 30
CAPWAP Local IPV6 Address 50
CAPWAP Timers 12
CAPWAP Transport Protocol 51
Data Transfer Data 13
Data Transfer Mode 14
Decryption Error Report 15
Decryption Error Report Period 16
Delete MAC ACL Entry 17
Delete Station 18
Reserved 19
Discovery Type 20
Duplicate IPv4 Address 21
Duplicate IPv6 Address 22
ECN Support 53
Idle Timeout 23
Image Data 24
Image Identifier 25
Image Information 26
Initiate Download 27
Location Data 28
Maximum Message Length 29
MTU Discovery Padding 52
Radio Administrative State 31
Radio Operational State 32
Result Code 33
Returned Message Element 34
Session ID 35
Statistics Timer 36
Vendor Specific Payload 37
WTP Board Data 38
WTP Descriptor 39
WTP Fallback 40
WTP Frame Tunnel Mode 41
Reserved 42
Reserved 43
WTP MAC Type 44
WTP Name 45
Unused/Reserved 46
WTP Radio Statistics 47
WTP Reboot Statistics 48
WTP Static IP Address Information 494.6.1. AC Descriptor ✨
okay bestie, the AC Descriptor is how the AC spills its current tea 💅 about its own state. here's the layout:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Stations | Limit |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Active WTPs | Max WTPs |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Security | R-MAC Field | Reserved1 | DTLS Policy |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AC Information Sub-Element...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 1 for AC Descriptor 🎀
Length: >= 12
Stations: the number of stations currently served by the AC 📱
Limit: the maximum number of stations supported by the AC
Active WTPs: the number of WTPs currently attached to the AC
Max WTPs: the maximum number of WTPs supported by the AC
Security: an 8-bit mask specifying the authentication credential type supported by the AC (see Section 2.4.4). the field has the following format:
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|Reserved |S|X|R|
+-+-+-+-+-+-+-+-+Reserved: a set of reserved bits for future use. All implementations complying with this protocol MUST set to zero any bits that are reserved in the version of the protocol supported by that implementation. Receivers MUST ignore all bits not defined for the version of the protocol they support.
S: the AC supports the pre-shared secret authentication, as described in Section 12.6. 🔑
X: the AC supports X.509 Certificate authentication, as described in Section 12.7. 📜
R: a reserved bit for future use. All implementations complying with this protocol MUST set to zero any bits that are reserved in the version of the protocol supported by that implementation. Receivers MUST ignore all bits not defined for the version of the protocol they support.
R-MAC Field: the AC supports the optional Radio MAC Address field in the CAPWAP transport header (see Section 4.3). the following enumerated values are supported:
0- Reserved1- Supported2- Not Supported
Reserved: a set of reserved bits for future use. All implementations complying with this protocol MUST set to zero any bits that are reserved in the version of the protocol supported by that implementation. Receivers MUST ignore all bits not defined for the version of the protocol they support.
DTLS Policy: the AC communicates its policy on the use of DTLS for the CAPWAP data channel. The AC MAY communicate more than one supported option, represented by the bit field below. The WTP MUST abide by one of the options communicated by AC. The field has the following format: 🦋
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|Reserved |D|C|R|
+-+-+-+-+-+-+-+-+Reserved: a set of reserved bits for future use. All implementations complying with this protocol MUST set to zero any bits that are reserved in the version of the protocol supported by that implementation. Receivers MUST ignore all bits not defined for the version of the protocol they support.
D: DTLS-Enabled Data Channel Supported
C: Clear Text Data Channel Supported
R: a reserved bit for future use. All implementations complying with this protocol MUST set to zero any bits that are reserved in the version of the protocol supported by that implementation. Receivers MUST ignore all bits not defined for the version of the protocol they support.
AC Information Sub-Element: the AC Descriptor message element contains multiple AC Information sub-elements, and defines two sub-types, each of which MUST be present. The AC Information sub-element has the following format: 🌸
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AC Information Vendor Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AC Information Type | AC Information Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AC Information Data...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+AC Information Vendor Identifier: a 32-bit value containing the IANA-assigned "Structure of Management Information (SMI) Network Management Private Enterprise Codes". 🏢
AC Information Type: vendor-specific encoding of AC information in the UTF-8 format [RFC3629]. the following enumerated values are supported. Both the Hardware and Software Version sub-elements MUST be included in the AC Descriptor message element. the values listed below are used in conjunction with the AC Information Vendor Identifier field, whose value MUST be set to zero (0). This field, combined with the AC Information Vendor Identifier set to a non-zero (0) value, allows vendors to use a private namespace. 🫶
4- Hardware Version: the AC's hardware version number.5- Software Version: the AC's Software (firmware) version number.
AC Information Length: length of vendor-specific encoding of AC information, with a maximum size of 1024.
AC Information Data: vendor-specific encoding of AC information.
4.6.2. AC IPv4 List
the AC IPv4 List message element is used to configure a WTP with the latest list of ACs available for the WTP to join. 🧚
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AC IP Address[] |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 2 for AC IPv4 List
Length: >= 4
AC IP Address: an array of 32-bit integers containing AC IPv4 Addresses, containing no more than 1024 addresses. 🌐
4.6.3. AC IPv6 List
the AC IPv6 List message element is used to configure a WTP with the latest list of ACs available for the WTP to join. 💜
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AC IP Address[] |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AC IP Address[] |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AC IP Address[] |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AC IP Address[] |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 3 for AC IPV6 List
Length: >= 16
AC IP Address: an array of 128-bit integers containing AC IPv6 Addresses, containing no more than 1024 addresses. 🌈
4.6.4. AC Name
the AC Name message element contains an UTF-8 [RFC3629] representation of the AC identity. The value is a variable-length byte string. The string is not zero terminated. 🎀
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| Name ...
+-+-+-+-+-+-+-+-+Type: 4 for AC Name
Length: >= 1
Name: a variable-length UTF-8 encoded string [RFC3629] containing the AC's name, whose maximum size MUST NOT exceed 512 bytes. 🏷️
4.6.5. AC Name with Priority
the AC Name with Priority message element is sent by the AC to the WTP to configure preferred ACs. The number of instances of this message element is equal to the number of ACs configured on the WTP. The WTP also uses this message element to send its configuration to the AC. 👑
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Priority | AC Name...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 5 for AC Name with Priority
Length: >= 2
Priority: a value between 1 and 255 specifying the priority order of the preferred AC. For instance, the value of one (1) is used to set the primary AC, the value of two (2) is used to set the secondary, etc. 🥇
AC Name: a variable-length UTF-8 encoded string [RFC3629] containing the AC name, whose maximum size MUST NOT exceed 512 bytes. 💅
4.6.6. AC Timestamp ⏰
the AC Timestamp message element is sent by the AC to synchronize the WTP clock. 🕰️
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Timestamp |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 6 for AC Timestamp
Length: 4
Timestamp: the AC's current time, allowing all of the WTPs to be time synchronized in the format defined by Network Time Protocol (NTP) in RFC 1305 [RFC1305]. Only the most significant 32 bits of the NTP time are included in this field. ⭐
4.6.7. Add MAC ACL Entry 🙈
the Add MAC Access Control List (ACL) Entry message element is used by an AC to add a MAC ACL list entry on a WTP, ensuring that the WTP no longer provides service to the MAC addresses provided in the message. The MAC addresses provided in this message element are not expected to be saved in non-volatile memory on the WTP. The MAC ACL table on the WTP is cleared every time the WTP establishes a new session with an AC. 🧹
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Num of Entries| Length | MAC Address ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 7 for Add MAC ACL Entry
Length: >= 8
Num of Entries: the number of instances of the Length/MAC Address fields in the array. This value MUST NOT exceed 255. 🔢
Length: the length of the MAC Address field. The formats and lengths specified in [EUI-48] and [EUI-64] are supported.
MAC Address: MAC addresses to add to the ACL. 🚫
4.6.8. Add Station 💖
okay bestie, the Add Station message element is how the AC tells a WTP "hey, forward traffic for this station pls" 🫶 It comes with technology-specific binding information elements, and those can include security parameters. The WTP MUST apply those security parameters for the station, no cap 💅
After station policy has landed on the WTP through Add Station, the AC MAY change any policies by sending a modified Add Station message element 🦋 If a WTP gets an Add Station for a station it already knows about, it MUST override any existing state for that station. latest update wins, iykyk ✨
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Radio ID | Length | MAC Address ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| VLAN Name...
+-+-+-+-+-+-+-+-+Type: 8 for Add Station 🎀Length:>= 8Radio ID: An 8-bit value representing the radio, whose value is between one (1) and 31.Length: The length of the MAC Address field. The formats and lengths specified in [EUI-48] and [EUI-64] are supported.MAC Address: The station's MAC address.VLAN Name: An optional variable-length UTF-8 encoded string [RFC3629], with a maximum length of 512 octets, containing the VLAN Name on which the WTP is to locally bridge user data. Note this field is only valid with WTPs configured in Local MAC mode. 🌸
4.6.9. CAPWAP Control IPv4 Address 🦋
the CAPWAP Control IPv4 Address message element is sent by the AC to the WTP during Discovery. It tells the WTP which interfaces the AC has available and how many WTPs are currently connected to each one 👑 When multiple CAPWAP Control IPV4 Address message elements come back, the WTP SHOULD perform load balancing across the multiple interfaces (see Section 6.1). main character load balancing 💅
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| WTP Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 10 for CAPWAP Control IPv4 AddressLength: 6IP Address: The IP address of an interface.WTP Count: The number of WTPs currently connected to the interface, with a maximum value of 65535.
4.6.10. CAPWAP Control IPv6 Address 🧚
same energy as the IPv4 one, just for IPv6 🌈 The AC sends it during Discovery to show off its interfaces and how many WTPs are connected. This one is handy for the WTP when it's load balancing across multiple interfaces (see Section 6.1). big brain move 🧠
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| WTP Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 11 for CAPWAP Control IPv6 AddressLength: 18IP Address: The IP address of an interface.WTP Count: The number of WTPs currently connected to the interface, with a maximum value of 65535. 💜
4.6.11. CAPWAP Local IPv4 Address 🌸
the CAPWAP Local IPv4 Address message element is sent either by the WTP in the Join Request, or by the AC in the Join Response 💖 It's how a sender announces its own IP address. The receiver then compares that against the source IP address of the packet to figure out whether a middlebox is sitting between the two peers 👀
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 30 for CAPWAP Local IPv4 AddressLength: 4IP Address: The IP address of the sender.
4.6.12. CAPWAP Local IPv6 Address 🦋
this is the IPv6 twin of the last one 🫶 Same deal: the WTP sends it in the Join Request, the AC sends it in the Join Response, and it's used to share the transmitter's IP address. The receiver checks it against the packet's source IP address to see if a middlebox is in the middle ✨
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 50 for CAPWAP Local IPv6 AddressLength: 16IP Address: The IP address of the sender. 🌈
4.6.13. CAPWAP Timers ⏰
the CAPWAP Timers message element is how an AC configures CAPWAP timers on a WTP. It's basically the AC saying "here's how often to do things" 💅
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Discovery | Echo Request |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 12 for CAPWAP TimersLength: 2Discovery: The number of seconds between CAPWAP Discovery messages, when the WTP is in the Discovery phase. This value is used to configure the MaxDiscoveryInterval timer (see Section 4.7.10). 🎀Echo Request: The number of seconds between WTP Echo Request CAPWAP messages. This value is used to configure the EchoInterval timer (see Section 4.7.7). The AC sets its EchoInterval timer to this value, plus the maximum retransmission time as described in Section 4.5.3. the math matters here, bestie 🧮
4.6.14. CAPWAP Transport Protocol 🚀
when CAPWAP runs over IPv6, the UDP-Lite or UDP transports MAY be used (see Section 3) 🌊 The CAPWAP Transport Protocol message element is how either the WTP or the AC signals which transport protocol the CAPWAP data channel should use.
Upon receiving the Join Request, the AC MAY set the CAPWAP Transport Protocol to UDP-Lite in the Join Response message, if the CAPWAP message came in over IPv6, the CAPWAP Local IPv6 Address message element (see Section 4.6.12) is present, and no middlebox was detected (see Section 11). so many conditions, but they're all doing a job 🫠
Upon receiving the Join Response, the WTP MAY set the CAPWAP Transport Protocol to UDP-Lite in the Configuration Status Request or Image Data Request message, if the AC advertised support for UDP-Lite, the message was received over IPv6, the CAPWAP Local IPv6 Address message element (see Section 4.6.12) is present, and no middlebox was detected (see Section 11). Upon receiving either the Configuration Status Request or the Image Data Request, the AC MUST observe the preference indicated by the WTP in the CAPWAP Transport Protocol, as long as it is consistent with what the AC advertised in the Join Response. ✨
For any other condition, the CAPWAP Transport Protocol MUST be set to UDP. 🚨
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| Transport |
+-+-+-+-+-+-+-+-+Type: 51 for CAPWAP Transport ProtocolLength: 1Transport: The transport to use for the CAPWAP Data channel. The following enumerated values are supported:1: UDP-Lite: The UDP-Lite transport protocol is to be used for the CAPWAP Data channel. Note that this option MUST NOT be used if the CAPWAP Control channel is being used over IPv4. 🦋2: UDP: The UDP transport protocol is to be used for the CAPWAP Data channel. 🌸
4.6.15. Data Transfer Data 🐛
the Data Transfer Data message element is how the WTP sends info to the AC for debugging 🔍 It's the "here's the logs, pls help" element 😭
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data Type | Data Mode | Data Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data ....
+-+-+-+-+-+-+-+-+Type: 13 for Data Transfer DataLength:>= 5Data Type: An 8-bit value representing the transfer Data Type. The following enumerated values are supported:1: Transfer data is included.2: Last Transfer Data Block is included (End of File (EOF)).5: An error occurred. Transfer is aborted. 💀
Data Mode: An 8-bit value describing the type of information being transmitted. The following enumerated values are supported:0: Reserved1: WTP Crash Data2: WTP Memory Dump
Data Length: Length of data field, with a maximum size of 65535.Data: Data being transferred from the WTP to the AC, whose type is identified via the Data Mode field. 🎁
4.6.16. Data Transfer Mode 🔎
the Data Transfer Mode message element is how the WTP says what kind of debugging data it's about to send the AC 🫶 Think of it as the label on the box before you open it 🎀
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| Data Mode |
+-+-+-+-+-+-+-+-+Type: 14 for Data Transfer ModeLength: 1Data Mode: An 8-bit value describing the type of information being requested. The following enumerated values are supported:0: Reserved1: WTP Crash Data2: WTP Memory Dump 🍓
4.6.17. Decryption Error Report 🔥
Okay so the Decryption Error Report is how the WTP tells the AC about decryption errors that have popped off since its last report. 💅 Lowkey important: this whole error reporting thing is not used if encryption and decryption are handled in the AC, so check that first! 🫶
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Radio ID |Num Of Entries | Length | MAC Address...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type:
15for Decryption Error Report - Length:
>= 9 - Radio ID: The Radio Identifier refers to an interface index on the WTP, whose value is between
1and31. 📡 - Num of Entries: The number of instances of the Length/MAC Address fields in the array. This field MUST NOT exceed the value of
255. 🔢 - Length: The length of the MAC Address field. The formats and lengths specified in [EUI-48] and [EUI-64] are supported. ✨
- MAC Address: MAC address of the station that has caused decryption errors. 🙈
4.6.18. Decryption Error Report Period 🌸
The Decryption Error Report Period message element is how the AC tells the WTP how often it should send decryption error report messages. ⏰ Same deal as before: this mechanism is not used if encryption and decryption services are provided in the AC. 💖
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Radio ID | Report Interval |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type:
16for Decryption Error Report Period - Length:
3 - Radio ID: The Radio Identifier refers to an interface index on the WTP, whose value is between
1and31. - Report Interval: A 16-bit unsigned integer indicating the time, in seconds. The default value for this message element can be found in Section 4.7.11. 🧁
4.6.19. Delete MAC ACL Entry 🗑️
The Delete MAC ACL Entry message element is how an AC deletes a MAC ACL entry on a WTP, making sure the WTP keeps serving the MAC addresses in the message. 🦋
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Num of Entries| Length | MAC Address ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type:
17for Delete MAC ACL Entry - Length:
>= 8 - Num of Entries: The number of instances of the Length/MAC Address fields in the array. This field MUST NOT exceed the value of
255. - Length: The length of the MAC Address field. The formats and lengths specified in [EUI-48] and [EUI-64] are supported.
- MAC Address: An array of MAC addresses to delete from the ACL. 🫧
4.6.20. Delete Station 👋
The Delete Station message element is how the AC tells a WTP to stop serving a particular station. 💅 The WTP MUST terminate service to the station immediately upon receiving this message element. No hesitating, periodt! 🔥
The Delete Station message element could be sent for various reasons, including administrative reasons, or if the station has roamed to another WTP. 🚶♀️
The WTP MAY send the Delete Station message element, in the WTP Event Request message, to tell the AC that a particular station is no longer being provided service. This could happen because of an Idle Timeout (see section 4.4.43), internal resource shortages, or some other reason. 🧚
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Radio ID | Length | MAC Address...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type:
18for Delete Station - Length:
>= 8 - Radio ID: An 8-bit value representing the radio, whose value is between
1and31. 📻 - Length: The length of the MAC Address field. The formats and lengths specified in [EUI-48] and [EUI-64] are supported.
- MAC Address: The station's MAC address.
4.6.21. Discovery Type 🔍
The Discovery Type message element is how the WTP shows how it found out about the AC it's sending the Discovery Request message to. 👀
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| Discovery Type|
+-+-+-+-+-+-+-+-+- Type:
20for Discovery Type - Length:
1 - Discovery Type: An 8-bit value indicating how the WTP discovered the AC. The following enumerated values are supported:
0- Unknown 🤷♀️1- Static Configuration 🛠️2- DHCP3- DNS4- AC Referral (used when the AC was configured either through the AC IPv4 List or AC IPv6 List message element) 🌈
4.6.22. Duplicate IPv4 Address 👯
The Duplicate IPv4 Address message element is how a WTP tells an AC that it has spotted another IP device using the same IP address the WTP is currently using. Two's a crowd, bestie! 🙅♀️
The WTP MUST transmit this message element with the status set to 1 after it has detected a duplicate IP address. When the WTP detects that the duplicate IP address has been cleared, it MUST send this message element with the status set to 0. ✅
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Status | Length | MAC Address ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type:
21for Duplicate IPv4 Address - Length:
>= 12 - IP Address: The IP address currently used by the WTP.
- Status: The status of the duplicate IP address. The value MUST be set to
1when a duplicate address is detected, and0when the duplicate address has been cleared. 🚦 - Length: The length of the MAC Address field. The formats and lengths specified in [EUI-48] and [EUI-64] are supported.
- MAC Address: The MAC address of the offending device. 😤
4.6.23. Duplicate IPv6 Address 👯♀️
The Duplicate IPv6 Address message element is how a WTP tells an AC that it has found another host using the same IP address the WTP is currently using. Same drama, bigger address! 💀
The WTP MUST transmit this message element with the status set to 1 after it has detected a duplicate IP address. When the WTP detects that the duplicate IP address has been cleared, it MUST send this message element with the status set to 0. ✨
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Status | Length | MAC Address ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type:
22for Duplicate IPv6 Address - Length:
>= 24 - IP Address: The IP address currently used by the WTP.
- Status: The status of the duplicate IP address. The value MUST be set to
1when a duplicate address is detected, and0when the duplicate address has been cleared. 🔁 - Length: The length of the MAC Address field. The formats and lengths specified in [EUI-48] and [EUI-64] are supported.
- MAC Address: The MAC address of the offending device. 🕵️♀️
4.6.24. Idle Timeout ⏳
The Idle Timeout message element is sent by the AC to the WTP to give it the Idle Timeout value that the WTP SHOULD enforce for its active stations. The value applies to all radios on the WTP. 🌟
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Timeout |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type:
23for Idle Timeout - Length:
4 - Timeout: The current Idle Timeout, in seconds, to be enforced by the WTP. The default value for this message element is specified in Section 4.7.8. ⏱️
4.6.25. ECN Support 🎀
The ECN Support message element is sent by both the WTP and the AC to show their support for the Explicit Congestion Notification (ECN) bits, as defined in [RFC3168]. Both sides get to flex! 💪
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| ECN Support |
+-+-+-+-+-+-+-+-+- Type:
53for ECN Support - Length:
1 - ECN Support: An 8-bit value representing the sender's support for ECN, as defined in [RFC3168]. All CAPWAP Implementations MUST support the Limited ECN Support mode. Full ECN Support is used if both the WTP and AC advertise the capability for "Full and Limited ECN" Support; otherwise, Limited ECN Support is used. 🌈 The enumerated values are:
0- Limited ECN Support1- Full and Limited ECN Support
Limited ECN Support is the baseline every CAPWAP implementation has to support, so that one's non-negotiable! 🫶
4.6.26. Image Data 🖼️
The Image Data message element is present in the Image Data Request message sent by the AC and contains the following fields. 📦
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data Type | Data ....
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type:
24for Image Data - Length:
>= 1 - Data Type: An 8-bit value representing the image Data Type. The following enumerated values are supported:
1- Image data is included. 📥2- Last Image Data Block is included (EOF). 🏁5- An error occurred. Transfer is aborted. 💔
- Data: The Image Data field contains up to
1024characters, and its length is inferred from this message element's length field. If the block being sent is the last one, the Data Type field is set to2. The AC MAY opt to abort the data transfer by setting the Data Type field to5. When the Data Type field is5, the Value field has a zero length. 🧃
4.6.27. Image Identifier 💾
okay so the Image Identifier message element is how the AC tells the WTP which firmware version it expects to be running 💅 and the WTP can also send one to ask the AC for a specific version 🦋 (the whole download process lives in Section 9.1 bestie). the value is a variable-length UTF-8 encoded string [RFC3629] and it is not zero terminated 🌸
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Vendor Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 25 for Image Identifier🧚Length: >= 5🍓Vendor Identifier:a 32-bit value holding the IANA-assigned "SMI Network Management Private Enterprise Codes" 🌈Data:a variable-length UTF-8 encoded string [RFC3629] with the firmware identifier the WTP is supposed to run. its length MUST NOT exceed 1024 octets 🙈 the length of this field is inferred from the message element's length field, so no extra counting needed ✨
4.6.28. Image Information 📊
the Image Information message element shows up in the Image Data Response message that the AC sends to the WTP, and it has these fields 🎀
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| File Size |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Hash |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Hash |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Hash |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Hash |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 26 for Image Information💜Length: 20🔥File Size:a 32-bit value with the size of the file, in bytes, that the AC will transfer to the WTP 📦Hash:a 16-octet MD5 hash of the image, made using the procedures in [RFC1321] 🔐
4.6.29. Initiate Download ⬇️
the Initiate Download message element is how the WTP tells the AC that the AC SHOULD start a firmware upgrade 🚀 after that the AC sends an Image Data Request message that includes the Image Data message element. this one carries no data at all, just vibes 🫶
Type: 27 for Initiate Download🌸Length: 0🙈
4.6.30. Location Data 📍
the Location Data message element is a variable-length UTF-8 encoded string [RFC3629] with user-defined location info, like "Next to Fridge" 🧊 the network admin sets it, and it's what lets people figure out where the WTP actually lives 🗺️ the string is not zero terminated 💅
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+-
| Location ...
+-+-+-+-+-+-+-+-+-Type: 28 for Location Data🦋Length: >= 1🍓Location:a non-zero-terminated UTF-8 encoded string [RFC3629] with the WTP location. its maximum size MUST NOT exceed 1024 🙅♀️
4.6.31. Maximum Message Length 📏
the WTP puts the Maximum Message Length message element in the Join Request message to tell the AC the biggest CAPWAP message it can handle 💖 the AC can optionally include it in the Join Response message to tell the WTP its own max size 🧚
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Maximum Message Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 29 for Maximum Message Length✨Length: 2🌈Maximum Message Length: a 16-bit unsigned integer with the max message length 🎀
4.6.32. MTU Discovery Padding 🧩
the MTU Discovery Padding message element is just padding for doing MTU discovery 🔍 it MUST contain octets of value 0xFF, and it can be any length 💜
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| Padding...
+-+-+-+-+-+-+-+-Type: 52 for MTU Discovery Padding🌸Length: Variable🫶Pad:a variable-length pad filled with the value 0xFF 💅
4.6.33. Radio Administrative State 📻
the Radio Administrative State message element tells everyone the state of a particular radio 📡 the AC sends it to change the WTP's state, and the WTP saves the value so it sticks around across WTP resets 🔒 the WTP also shares it during the configuration phase, in the Configuration Status Request message, so the AC always knows the current settings 🧠 it has these fields 🎀
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Radio ID | Admin State |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 31 for Radio Administrative State🦋Length: 2🍓Radio ID:an 8-bit value for the radio to configure, between one (1) and 31 🛜 the Radio ID field MAY also be 0xff, which is how you point at the WTP itself. if an AC wants to change the WTP's administrative state, it puts 0xff in the Radio ID field 👑Admin State:an 8-bit value for the radio's administrative state. the default is listed in Section 4.8.1. these enumerated values are supported:
0 - Reserved
1 - Enabled
2 - Disabled4.6.34. Radio Operational State ⚡
the Radio Operational State message element is sent by the WTP to the AC to share a radio's operational state 💫 the WTP includes it in the Configuration Update Response message if the AC asked it to change the radio's state (via the Radio Administrative State message element) but it couldn't do it 😭 it's also in the Change State Event message when a radio's state changed unexpectedly, like from a hardware failure 🔧 heads up: the operational state is not saved on the WTP, so it does NOT survive WTP resets 🙈 the value has three fields 🌈
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Radio ID | State | Cause |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 32 for Radio Operational State🧚Length: 3🔥Radio ID:the Radio Identifier points to an interface index on the WTP, between one (1) and 31. a value of 0xFF is invalid, since the WTP's operational state can't be changed 🚫State:an 8-bit Boolean value for the radio's state. these enumerated values are supported:
0 - Reserved
1 - Enabled
2 - DisabledCause:when a radio is inoperable, this field says why it's out of service. these enumerated values are supported:
0 - Normal
1 - Radio Failure
2 - Software Failure
3 - Administratively Set4.6.35. Result Code ✅
the Result Code message element is a 32-bit integer that says how the Request message went, matched up with the sequence number in the Response message 🎯
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Result Code |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 33 for Result Code🦋Length: 4🍓Result Code:these enumerated values are defined 💖
0 Success
1 Failure (AC List Message Element MUST Be Present)
2 Success (NAT Detected)
3 Join Failure (Unspecified)
4 Join Failure (Resource Depletion)
5 Join Failure (Unknown Source)
6 Join Failure (Incorrect Data)
7 Join Failure (Session ID Already in Use)
8 Join Failure (WTP Hardware Not Supported)
9 Join Failure (Binding Not Supported)
10 Reset Failure (Unable to Reset)
11 Reset Failure (Firmware Write Error)
12 Configuration Failure (Unable to Apply Requested Configuration
- Service Provided Anyhow)
13 Configuration Failure (Unable to Apply Requested Configuration
- Service Not Provided)
14 Image Data Error (Invalid Checksum)
15 Image Data Error (Invalid Data Length)
16 Image Data Error (Other Error)
17 Image Data Error (Image Already Present)
18 Message Unexpected (Invalid in Current State)
19 Message Unexpected (Unrecognized Request)
20 Failure - Missing Mandatory Message Element
21 Failure - Unrecognized Message Element
22 Data Transfer Error (No Information to Transfer)4.6.36. Returned Message Element 🔙
the WTP sends the Returned Message Element in the Change State Event Request message to tell the AC which message elements in the Configuration Status Response it couldn't apply locally 🙃 it carries a result code saying why the configuration didn't work, and it wraps up the message element that failed 🎁
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reason | Length | Message Element...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 34 for Returned Message Element🌈Length: >= 6🔥Reason:the reason the WTP couldn't apply the configuration in the offending message element. these enumerated values are supported:
0 - Reserved
1 - Unknown Message Element
2 - Unsupported Message Element
3 - Unknown Message Element Value
4 - Unsupported Message Element ValueLength:the length of the Message Element field, which MUST NOT exceed 255 octets 🚫Message Element:this field wraps the message element the AC sent in the Configuration Status Response message that caused the error 💔
4.6.37. Session ID ✨
Okay bestie, the Session ID message element value is just a randomly generated unsigned 128-bit integer. It's giving "random but make it iconic" 🎀
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Session ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Session ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Session ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Session ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type: 35 for Session ID
- Length: 16
- Session ID: a 128-bit unsigned integer used as a random session identifier 🦋
4.6.38. Statistics Timer 🧚
The Statistics Timer message element value is how the AC lets the WTP know how often it wants to get updated statistics. Think of it as the AC saying "send me the tea every so often" ☕
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Statistics Timer |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type: 36 for Statistics Timer
- Length: 2
- Statistics Timer: a 16-bit unsigned integer indicating the time, in seconds. The default value for this timer is specified in Section 4.7.14. ⭐
4.6.39. Vendor Specific Payload 💜
The Vendor Specific Payload message element is for passing vendor-specific info between the WTP and the AC, so it's basically the vendor's private group chat 🫶 The Vendor Specific Payload message element MAY be present in any CAPWAP message. The exchange of vendor-specific data between the MUST NOT modify the behavior of the base CAPWAP protocol and state machine. It uses the following format:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Vendor Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Element ID | Data...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type: 37 for Vendor Specific Payload
- Length: >= 7
- Vendor Identifier: a 32-bit value containing the IANA-assigned "SMI Network Management Private Enterprise Codes" [RFC3232].
- Element ID: a 16-bit Element Identifier that is managed by the vendor.
- Data: variable-length vendor-specific information, whose contents and format are proprietary and understood based on the Element ID field. This field MUST NOT exceed 2048 octets. 💅
4.6.40. WTP Board Data 🍓
The WTP Board Data message element is sent by the WTP to the AC, and it's the WTP spilling the tea on what hardware it's packing 📦
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Vendor Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Board Data Sub-Element...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type: 38 for WTP Board Data
- Length: >=14
- Vendor Identifier: a 32-bit value containing the IANA-assigned "SMI Network Management Private Enterprise Codes", identifying the WTP hardware manufacturer. The Vendor Identifier field MUST NOT be set to zero. 🫶
- Board Data Sub-Element: the WTP Board Data message element contains multiple Board Data sub-elements, some of which are mandatory and some are optional, as described below. The Board Data Type values are not extensible by vendors, and are therefore not coupled along with the Vendor Identifier field. The Board Data sub-element has the following format:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Board Data Type | Board Data Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Board Data Value...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Board Data Type: the Board Data Type field identifies the data being encoded. The CAPWAP protocol defines the following values, and each of these types identify whether their presence is mandatory or optional:
- 0 - WTP Model Number: The WTP Model Number MUST be included in the WTP Board Data message element.
- 1 - WTP Serial Number: The WTP Serial Number MUST be included in the WTP Board Data message element.
- 2 - Board ID: A hardware identifier, which MAY be included in the WTP Board Data message element.
- 3 - Board Revision: A revision number of the board, which MAY be included in the WTP Board Data message element.
- 4 - Base MAC Address: The WTP's Base MAC address, which MAY be assigned to the primary Ethernet interface.
Board Data Length: the length of the data in the Board Data Value field, whose length MUST NOT exceed 1024 octets.
Board Data Value: the data associated with the Board Data Type field for this Board Data sub-element. 🍒
4.6.41. WTP Descriptor 👑
The WTP Descriptor message element is how a WTP shows off its current hardware and software (firmware) configuration. It's the full glow-up reveal ✨ The value contains the following fields:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Max Radios | Radios in use | Num Encrypt |Encryp Sub-Elmt|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Encryption Sub-Element | Descriptor Sub-Element...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Type: 39 for WTP Descriptor
- Length: >= 33
- Max Radios: an 8-bit value representing the number of radios (where each radio is identified via the Radio ID field) supported by the WTP.
- Radios in use: an 8-bit value representing the number of radios in use in the WTP.
- Num Encrypt: the number of 3-byte Encryption sub-elements that follow this field. The value of the Num Encrypt field MUST be between one (1) and 255.
- Encryption Sub-Element: the WTP Descriptor message element MUST contain at least one Encryption sub-element. One sub-element is present for each binding supported by the WTP. The Encryption sub-element has the following format:
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Resvd| WBID | Encryption Capabilities |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- Resvd: the 3-bit field is reserved for future use. All implementations complying with this protocol MUST set to zero any bits that are reserved in the version of the protocol supported by that implementation. Receivers MUST ignore all bits not defined for the version of the protocol they support.
- WBID: a 5-bit field that is the wireless binding identifier. The identifier will indicate the type of wireless packet associated with the radio. The WBIDs defined in this specification can be found in Section 4.3.
- Encryption Capabilities: this 16-bit field is used by the WTP to communicate its capabilities to the AC. A WTP that does not have any encryption capabilities sets this field to zero (0). Refer to the specific wireless binding for further specification of the Encryption Capabilities field. 🔐
Descriptor Sub-Element: the WTP Descriptor message element contains multiple Descriptor sub-elements, some of which are mandatory and some are optional, as described below. The Descriptor sub-element has the following format:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Descriptor Vendor Identifier |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Descriptor Type | Descriptor Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Descriptor Data...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Descriptor Vendor Identifier: a 32-bit value containing the IANA-assigned "SMI Network Management Private Enterprise Codes".
Descriptor Type: the Descriptor Type field identifies the data being encoded. The format of the data is vendor-specific encoded in the UTF-8 format [RFC3629]. The CAPWAP protocol defines the following values, and each of these types identify whether their presence is mandatory or optional. The values listed below are used in conjunction with the Descriptor Vendor Identifier field, whose value MUST be set to zero (0). This field, combined with the Descriptor Vendor Identifier set to a non-zero (0) value, allows vendors to use a private namespace.
- 0 - Hardware Version: The WTP hardware version number MUST be present.
- 1 - Active Software Version: The WTP running software version number MUST be present.
- 2 - Boot Version: The WTP boot loader version number MUST be present.
- 3 - Other Software Version: The WTP non-running software (firmware) version number MAY be present. This type is used to communicate alternate software versions that are available on the WTP's non-volatile storage.
Descriptor Length: length of the vendor-specific encoding of the Descriptor Data field, whose length MUST NOT exceed 1024 octets.
Descriptor Data: vendor-specific data of WTP information encoded in the UTF-8 format [RFC3629]. 🌈
4.6.42. WTP Fallback 🦋
Okay bestie, so the WTP Fallback message element is how the AC tells the WTP to turn automatic CAPWAP fallback on or off ✨. Fallback comes into play when a WTP notices its preferred AC and realises it isn't connected to that one right now.
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| Mode |
+-+-+-+-+-+-+-+-+Type: 40 for WTP Fallback
Length: 1
Mode: This 8-bit value tells you the status of automatic CAPWAP fallback on the WTP 💅. When it's enabled and the WTP sees that its primary AC is available while it's connected somewhere else, the WTP SHOULD automatically disconnect from its current AC and reconnect to its primary AC 🔁. When it's disabled, the WTP only goes back to its primary AC through manual intervention, like a Reset Request message 🙈. The default value for this field is specified in Section 4.8.9. These are the enumerated values:
0- Reserved1- Enabled2- Disabled
4.6.43. WTP Frame Tunnel Mode 🌈
The WTP Frame Tunnel Mode message element lets the WTP tell the AC which tunneling modes it can handle 💜. If a WTP says it supports all of them, the AC gets to pick whichever one fits its local policy. Main character energy for the AC, honestly 👑.
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|Reservd|N|E|L|U|
+-+-+-+-+-+-+-+-+Type: 41 for WTP Frame Tunnel Mode
Length: 1
Reservd: These are reserved bits saved for future use ✨. Every implementation that follows this protocol MUST set to zero any bits that are reserved in the version of the protocol that implementation supports. Receivers MUST ignore all bits that aren't defined for the version of the protocol they support.
N: Native Frame Tunnel mode means the WTP and AC have to wrap all user payloads as native wireless frames, following the wireless binding (see for example Section 4.4) 🫶.
E: The 802.3 Frame Tunnel Mode means the WTP and AC have to wrap all user payloads as native IEEE 802.3 frames (see Section 4.4) 🎀. All user traffic gets tunneled to the AC. This value MUST NOT be used when the WTP MAC Type is set to Split MAC.
L: When Local Bridging is used, the WTP doesn't tunnel user traffic to the AC, and all user traffic gets bridged locally 🍓. This value MUST NOT be used when the WTP MAC Type is set to Split MAC.
R: This is a reserved bit saved for future use 🌸. Every implementation that follows this protocol MUST set to zero any bits that are reserved in the version of the protocol that implementation supports. Receivers MUST ignore all bits that aren't defined for the version of the protocol they support.
4.6.44. WTP MAC Type 💜
The WTP MAC-Type message element is how the WTP tells the AC which mode it operates in 🧚. If a WTP supports both modes, the AC picks whichever one its local policy calls for.
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| MAC Type |
+-+-+-+-+-+-+-+-+Type: 44 for WTP MAC Type
Length: 1
MAC Type: This is the MAC mode of operation the WTP supports 🔥. These are the enumerated values:
0- Local MAC: Local MAC is the default mode, and it MUST be supported by all WTPs 💅. When tunneling is enabled (see Section 4.6.43), the encapsulated frames MUST be in the 802.3 format (see Section 4.4.2), except for a wireless management or control frame, which MAY be in its native format. Any CAPWAP binding needs to specify the format of management and control wireless frames.1- Split MAC: Split MAC support is optional, and it lets the AC receive and process native wireless frames 🦋.2- Both: The WTP can handle both Local MAC and Split MAC ✨.
4.6.45. WTP Name 🎀
The WTP Name message element is a variable-length string of UTF-8 encoded bytes [RFC3629] 📝. It isn't zero terminated, so there's no null at the end.
0
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+-
| WTP Name ...
+-+-+-+-+-+-+-+-+-Type: 45 for WTP Name
Length: >= 1
WTP Name: This is a non-zero-terminated UTF-8 encoded string [RFC3629] holding the WTP name 🌷. Its maximum size MUST NOT exceed 512 bytes.
4.6.46. WTP Radio Statistics 📊
The WTP Radio Statistics message element is sent by the WTP to the AC to share stats about how the radio behaves and why the WTP radio got reset 🫶. These counters never reset on the WTP, so they'll roll over to zero once they hit the maximum size. Okay, that's a lot of numbers, but they're iconic ✨.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Radio ID | Last Fail Type| Reset Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| SW Failure Count | HW Failure Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Other Failure Count | Unknown Failure Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Config Update Count | Channel Change Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Band Change Count | Current Noise Floor |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 47 for WTP Radio Statistics
Length: 20
Radio ID: This is the radio ID of the radio these stats belong to, with a value between one (1) and 31 📡.
Last Failure Type: This is the last WTP failure 💀. These are the enumerated values:
0- Statistic Not Supported1- Software Failure2- Hardware Failure3- Other Failure255- Unknown (e.g., WTP doesn't keep track of info)
Reset Count: How many times the radio has been reset 🔄.
SW Failure Count: How many times the radio has failed for software-related reasons 🐛.
HW Failure Count: How many times the radio has failed for hardware-related reasons 🔧.
Other Failure Count: How many times the radio has failed for known reasons that aren't software or hardware failures 🤷♀️.
Unknown Failure Count: How many times the radio has failed for unknown reasons 🙈.
Config Update Count: How many times the radio configuration has been updated ⚙️.
Channel Change Count: How many times the radio channel has changed 📻.
Band Change Count: How many times the radio has switched frequency bands 🌈.
Current Noise Floor: This is a signed integer showing the noise floor of the radio receiver, measured in dBm 🔊.
4.6.47. WTP Reboot Statistics 🔥
The WTP Reboot Statistics message element is sent by the WTP to the AC to explain why the WTP has rebooted ⭐. Just like the radio stats, these counters never reset on the WTP and will roll over to zero once they reach the maximum size.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Reboot Count | AC Initiated Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Link Failure Count | SW Failure Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| HW Failure Count | Other Failure Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Unknown Failure Count |Last Failure Type|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Type: 48 for WTP Reboot Statistics
Length: 15
Reboot Count: How many reboots happened because the WTP crashed 💥. A value of 65535 means this info isn't available on the WTP.
AC Initiated Count: How many reboots happened at the request of a CAPWAP protocol message, like a configuration change that needed a reboot or an explicit CAPWAP protocol reset request 🎬. A value of 65535 means this info isn't available on the WTP.
Link Failure Count: How many times a CAPWAP protocol connection with an AC failed because of a link failure 🔗.
SW Failure Count: How many times a CAPWAP protocol connection with an AC failed for software-related reasons 🐛.
HW Failure Count: How many times a CAPWAP protocol connection with an AC failed for hardware-related reasons 🔧.
Other Failure Count: How many times a CAPWAP protocol connection with an AC failed for known reasons, other than AC initiated, link, SW or HW failure 🤷♀️.
Unknown Failure Count: How many times a CAPWAP protocol connection with an AC failed for unknown reasons 🙈.
Last Failure Type: The failure type of the most recent WTP failure 😭. These are the enumerated values:
0- Not Supported1- AC Initiated (see Section 9.2)2- Link Failure3- Software Failure4- Hardware Failure5- Other Failure255- Unknown (e.g., WTP doesn't keep track of info)
4.6.48. WTP Static IP Address Information 🌸
The WTP Static IP Address Information message element is how an AC sets up, or clears, a static IP address that was configured earlier on a WTP 🧚. Quick heads-up: IPv6 WTPs are expected to use dynamic addresses 💜.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IP Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Netmask |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Gateway |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Static |
+-+-+-+-+-+-+-+-+Type: 49 for WTP Static IP Address Information
Length: 13
IP Address: The IP address to give the WTP 🏠. This field only counts if the Static field is set to one.
Netmask: The IP Netmask 🎭. This field only counts if the Static field is set to one.
Gateway: The IP address of the gateway 🚪. This field only counts if the Static field is set to one.
Static: This is an 8-bit Boolean that says whether or not the WTP should use a static IP address 🫶. A value of zero turns the static IP address off, and a value of one turns it on.
4.7. CAPWAP Protocol Timers ⏰
This section is where all the CAPWAP timers are defined, so grab your snacks and get comfy 🍿.
4.7.1. ChangeStatePendingTimer ⏳
This is the maximum time, in seconds, that the AC will wait for the Change State Event Request from the WTP after it has sent a successful Configuration Status Response message 💖.
Default: 25 seconds
4.7.2. DataChannelKeepAlive 💜
The DataChannelKeepAlive timer is how the WTP figures out when it's time to send the next Data Channel Keep-Alive, measured in seconds ✨.
Default: 30 seconds
4.7.3. DataChannelDeadInterval ✨
okay so this one is the minimum time (in seconds) a WTP has to wait without getting a Data Channel Keep-Alive packet before it can call the destination for those Keep-Alives dead 💀 the WTP MUST wait that long, and the value MUST be no less than 2*DataChannelKeepAlive seconds and no greater than 240 seconds 🫶
Default: 60 🎀
4.7.4. DataCheckTimer 🌸
this is how many seconds the AC waits for the Data Channel Keep Alive, which the CAPWAP state machine needs in its Data Check state 🧚 if this timer runs out before the state machine moves on to the next state, the AC resets the state machine. bestie, that's a whole reset 😭
Default: 30
4.7.5. DiscoveryInterval 💅
this is the minimum time (in seconds) a WTP MUST wait after it gets a Discovery Response message, before it starts a DTLS handshake. literally a little pause before the vibe check 🦋
Default: 5
4.7.6. DTLSSessionDelete 🍓
this one is the minimum time (in seconds) a WTP MUST wait for DTLS session deletion. the WTP needs to chill for a bit 🙈
Default: 5
4.7.7. EchoInterval 💜
the minimum time (in seconds) between sending Echo Request messages to the AC that the WTP has joined. ngl this is the heartbeat check-in, very relationship-goals 💖
Default: 30
4.7.8. IdleTimeout ⭐
the default Idle Timeout is 300 seconds. five minutes of quiet and then it's over, no cap 🫠
4.7.9. ImageDataStartTimer 🔥
this is how many seconds the WTP waits for its peer to send the Image Data Request. if nothing shows up in time, it's giving ghosted 👻
Default: 30
4.7.10. MaxDiscoveryInterval 🌈
the maximum time (in seconds) allowed between sending Discovery Request messages. this value MUST be no less than 2 seconds and no greater than 180 seconds, so it's got a whole range but not a forever-wait 💅
Default: 20 seconds. 🎀
4.7.11. ReportInterval 🦋
the WTP uses ReportInterval to figure out how often it sends the Decryption Error message elements, so the AC knows about decryption errors. measured in seconds, obviously 🧐
The default Report Interval is 120 seconds. ✨
4.7.12. RetransmitInterval 🍓
this is the minimum time (in seconds) that a non-acknowledged CAPWAP packet waits before it gets retransmitted. it's the "hello?? did you get that??" timer 📱
Default: 3
4.7.13. SilentInterval 🌙
for a WTP, this is the minimum time (in seconds) it MUST wait before it MAY send Discovery Request messages again or try to set up a DTLS session. for an AC, it's the minimum time (in seconds) during which the AC SHOULD ignore all CAPWAP and DTLS packets it gets from a WTP that's in the Sulking state. the silent treatment, but make it protocol 🤐
Default: 30 seconds
4.7.14. StatisticsTimer 💜
the WTP uses StatisticsTimer to decide how often it sends WTP Events Requests to the AC so it can share its statistics, in seconds. the stats are always spilling 📊
Default: 120 seconds
4.7.15. WaitDTLS 🫶
the maximum time (in seconds) a WTP MUST wait without getting a DTLS Handshake message from an AC. this timer MUST be greater than 30 seconds. patience is a virtue, babe 🙏
Default: 60
4.7.16. WaitJoin 👑
the maximum time (in seconds) an AC waits, after the DTLS session is established, until it gets the Join Request from the WTP. this timer MUST be greater than 20 seconds. the AC is waiting for its date to show up 💍
Default: 60
4.8. CAPWAP Protocol Variables 🌈
okay this section is all about the CAPWAP protocol variables, which do various jobs in the protocol 🧠 some are configurable, some are counters, and some have a fixed value. for the non-counter ones, default values are given. BUT if an AC explicitly overrides a WTP's variable configuration, the WTP MUST save the new value. no ignoring the boss 👑
4.8.1. AdminState 🎀
the default Administrative State value is enabled (1). on by default, obviously ✨
4.8.2. DiscoveryCount 🔢
the number of Discovery Request messages a WTP has sent to a single AC. this is a monotonically increasing counter, so it only ever goes up, never down 📈
4.8.3. FailedDTLSAuthFailCount 😤
the number of failed DTLS session establishment attempts caused by authentication failures. ugh, rejected because of the auth 🙅♀️
4.8.4. FailedDTLSSessionCount 💔
the number of failed DTLS session establishment attempts, period. no excuses 😭
4.8.5. MaxDiscoveries 🍓
the maximum number of Discovery Request messages that get sent after a WTP boots.
Default: 10 💅
4.8.6. MaxFailedDTLSSessionRetry 🌸
the maximum number of failed DTLS session establishment attempts before the CAPWAP device goes into a silent period. three strikes and you're in timeout 🙈
Default: 3
4.8.7. MaxRetransmit 🦋
the maximum number of retransmissions for a given CAPWAP packet before the link layer decides the peer is dead 💀
Default: 5
4.8.8. RetransmitCount 📊
the number of retransmissions for a given CAPWAP packet. also a monotonically increasing counter, so it just keeps climbing 🧗♀️
4.8.9. WTPFallBack 🌟
the default WTP Fallback value is enabled (1). fallback on, bestie 🛟
4.9. WTP Saved Variables 💾
okay so in addition to the values in Section 4.8, the following values SHOULD be saved on the WTP in non-volatile memory. CAPWAP wireless bindings MAY define extra values that SHOULD be stored on the WTP too 🫶
4.9.1. AdminRebootCount 🔁
the number of times the WTP has rebooted administratively, defined in Section 4.6.47. 🍓
4.9.2. FrameEncapType 🎁
for WTPs that support multiple Frame Encapsulation Types, it's useful to save the value the AC configured. the Frame Encapsulation Type is defined in Section 4.6.43. 🧚
4.9.3. LastRebootReason 💬
the reason the WTP last rebooted, defined in Section 4.6.47. the receipts 🧾
4.9.4. MacType 🔧
for WTPs that support multiple MAC-Types, it's useful to save the value the AC configured. the MAC-Type is defined in Section 4.6.44. 💜
4.9.5. PreferredACs 🌷
the preferred ACs, with the index, defined in Section 4.6.5. the top picks list 📋
4.9.6. RebootCount 🔄
the number of times the WTP has rebooted, defined in Section 4.6.47. 🌈
4.9.7. Static IP Address 📍
the static IP address assigned to the WTP, as configured by the WTP Static IP address Information message element (see Section 4.6.48). it's the WTP's permanent address era ✨
4.9.8. WTPLinkFailureCount 💥
the number of times the link to the AC has failed, see Section 4.6.47. link drama 🙄
4.9.9. WTPLocation 🗺️
the WTP Location, defined in Section 4.6.30. where's the WTP at? 📍
4.9.10. WTPName 🏷️
the WTP Name, defined in Section 4.6.45. the name tag 💖
5. CAPWAP Discovery Operations 🔍
the Discovery messages are how a WTP figures out which ACs are available to help, plus their capabilities and load. it's the group chat check before picking a plan 🦋
5.1. Discovery Request Message 📣
okay so the Discovery Request message is how the WTP automatically finds potential ACs in the network. it tells the ACs the WTP's main capabilities. a WTP MUST exchange this info so that later exchanges with the ACs match what the WTP can actually do, no mismatch vibes 🫶
Discovery Request messages MUST be sent by a WTP in the Discover state, after it waits a random delay less than MaxDiscoveryInterval, after it first comes up or gets (re)initialized. a WTP MUST send no more than MaxDiscoveries Discovery Request messages (the maximum of them), waiting a random delay less than MaxDiscoveryInterval between each one. 🎲
this is to stop an explosion of WTP Discovery Request messages. the classic example is when a bunch of WTPs get powered on at the same time. chaos energy 💥
If the WTP doesn't get a Discovery Response message after sending the maximum number of Discovery Request messages, it enters the Sulking state and MUST wait for an interval equal to SilentInterval before sending more Discovery Request messages. time out 🙅♀️
When the AC gets a Discovery Request message, it responds with a Discovery Response message sent to the address in the source address of the Discovery Request. once the WTP has a Discovery Response, if it decides to set up a session with the AC that responded, it SHOULD perform an MTU discovery, using the process in Section 3.5. 🔍
it's possible for the AC to get a clear text Discovery Request message while a DTLS session is already active with the WTP. this is most likely if the WTP rebooted, maybe from a software or power failure, but it could also be a DoS attack 🚨 in those cases, no WTP state (including the state machine instance) MUST NOT be cleared until another DTLS session has been successfully established, communicated via the DTLSSessionEstablished DTLS notification (see Section 2.3.2.2). hold your state, babe 🔒
The binding specific WTP Radio Information message element (see Section 2.1) is included in the Discovery Request message to advertise WTP support for one or more CAPWAP bindings. 📡
The Discovery Request message is sent by the WTP when it's in the Discovery state. the AC never transmits this one 🙅♀️
The following message elements MUST be included in the Discovery Request message:
- Discovery Type, see Section 4.6.21
- WTP Board Data, see Section 4.6.40
- WTP Descriptor, see Section 4.6.41
- WTP Frame Tunnel Mode, see Section 4.6.43
- WTP MAC Type, see Section 4.6.44
- WTP Radio Information message element(s) that the WTP supports; these are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1). 🧾
The following message elements MAY be included in the Discovery Request message:
- MTU Discovery Padding, see Section 4.6.32
- Vendor Specific Payload, see Section 4.6.39 🎀
5.2. Discovery Response Message 💌
the Discovery Response message is how an AC advertises its services to WTPs that are asking 🎤
When a WTP gets a Discovery Response message, it MUST wait for an interval not less than DiscoveryInterval to catch any more Discovery Response messages. after DiscoveryInterval runs out, the WTP enters the DTLS-Init state, picks one of the ACs that sent a Discovery Response, and sends a DTLS Handshake to that AC. decision time 💅
One or more binding-specific WTP Radio Information message elements (see Section 2.1) are included in the Discovery Request message to advertise AC support for the CAPWAP bindings. the AC MAY include only the bindings it shares with the WTP (known through the WTP Radio Information message elements in the Discovery Request message), or it MAY include all of the bindings it supports. the WTP MAY use the supported bindings in its AC decision process. and heads up: if the WTP joins an AC that doesn't support a specific CAPWAP binding, service for that binding MUST NOT be provided by the WTP 🚫
The Discovery Response message is sent by the AC when it's in the Idle state. the WTP never transmits this one 🙅♀️
The following message elements MUST be included in the Discovery Response Message:
- AC Descriptor, see Section 4.6.1
- AC Name, see Section 4.6.4
- WTP Radio Information message element(s) that the AC supports; these are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1 for more information).
- One of the following message elements MUST be included in the Discovery Response Message:
- CAPWAP Control IPv4 Address, see Section 4.6.9
- CAPWAP Control IPv6 Address, see Section 4.6.10
The following message elements MAY be included in the Discovery Response message:
- Vendor Specific Payload, see Section 4.6.39 🌸
5.3. Primary Discovery Request Message ✨
okay bestie, so the Primary Discovery Request message is what a WTP sends for two reasons 🦋
- figuring out whether its preferred (or primary) AC is available, or
- doing a Path MTU Discovery (see Section 3.5) 💅
a WTP sends this when it has a primary AC configured and is currently connected to some other AC 🌸 usually that happens after a failover, and the WTP uses this message to notice when its primary AC is back online. the WTP only has one instance of the CAPWAP state machine, so this message goes out while the WTP is in the Run state. the AC never sends this one 🙈
how often should the WTP send these? no more often than the Echo Request message, so the timing is kinda linked 💜
when an AC gets a Primary Discovery Request message, it replies with a Primary Discovery Response message, and that reply goes to the address in the source address of the request 🫶
these message elements MUST be included in the Primary Discovery Request message:
Discovery Type, see Section 4.6.21WTP Board Data, see Section 4.6.40WTP Descriptor, see Section 4.6.41WTP Frame Tunnel Mode, see Section 4.6.43WTP MAC Type, see Section 4.6.44WTP Radio Informationmessage element(s) that the WTP supports; these are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1 for more information).
and these message elements MAY be included:
MTU Discovery Padding, see Section 4.6.32Vendor Specific Payload, see Section 4.6.39
5.4. Primary Discovery Response
the Primary Discovery Response message is how an AC says "hey, I'm available and here's what I offer" 🎀 it goes out to WTPs that have this AC set as their primary AC.
an AC sends this after it receives a Primary Discovery Request message ✨
once a WTP gets a Primary Discovery Response message, it may set up a CAPWAP protocol connection to its primary AC. whether it does depends on how the WTP Fallback Status message element is configured on the WTP 🌈
the AC sends this message while it's in the Idle state, and the WTP never sends it 💀
these message elements MUST be included in the Primary Discovery Response message:
AC Descriptor, see Section 4.6.1AC Name, see Section 4.6.4WTP Radio Informationmessage element(s) that the AC supports; these are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1 for more information).
one of the following message elements MUST be included in the Discovery Response Message:
CAPWAP Control IPv4 Address, see Section 4.6.9CAPWAP Control IPv6 Address, see Section 4.6.10
and these message elements MAY be included:
Vendor Specific Payload, see Section 4.6.39
6. CAPWAP Join Operations 🧚
okay the Join Request is how a WTP asks an AC for service, and it only gets sent after a DTLS connection to that AC is up 🔥 the Join Response is how the AC says whether it will or won't provide that service 💖
6.1. Join Request
the Join Request message is how a WTP requests service through the AC 💅 if the WTP is doing the optional AC Discovery process (see Section 3.3), the join happens after the WTP has gotten one or more Discovery Response messages.
during Discovery, an AC MAY return more than one CAPWAP Control IPv4 Address or CAPWAP Control IPv6 Address message element. when that happens, the WTP SHOULD do "load balancing" by picking the interface that's servicing the fewest WTPs (you can tell from the WTP Count field of the message element) 🍓 note, however, that other load balancing algorithms are also permitted, so it's not the only option 🦋
once the WTP has picked its preferred AC and the interface to connect through, it sets up the DTLS session and sends the Join Request over that secured control channel 🌸 when an AC gets a Join Request, it answers with a Join Response.
after the DTLS handshake finishes and the DTLSEstablished notification comes in, the WTP sends the Join Request message to the AC. when the AC hears about the DTLS session being set up, it doesn't clear the WaitDTLS timer until it has received the Join Request message. at that point it sends a Join Response telling the WTP "success" or "failure" 🎀
one or more WTP Radio Information message elements (see Section 2.1) go in the Join Request so the WTP can ask the AC for service on its CAPWAP bindings. if you include a binding the AC doesn't support, you'll get a failed Join Response 💀
if the AC rejects the Join Request, it sends a Join Response with a failure indication and starts aborting the DTLS session with the DTLSAbort command 😭
if an invalid (i.e., malformed) Join Request message shows up, the AC MUST silently discard it. no response goes back to the WTP, and the AC SHOULD log the event 🙈
the Join Request is sent by the WTP when it's in the Join State, and the AC never transmits this one 💜
these message elements MUST be included in the Join Request message:
Location Data, see Section 4.6.30WTP Board Data, see Section 4.6.40WTP Descriptor, see Section 4.6.41WTP Name, see Section 4.6.45Session ID, see Section 4.6.37WTP Frame Tunnel Mode, see Section 4.6.43WTP MAC Type, see Section 4.6.44WTP Radio Informationmessage element(s) that the WTP supports; these are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1 for more information).ECN Support, see Section 4.6.25
at least one of the following message elements MUST be included in the Join Request message:
CAPWAP Local IPv4 Address, see Section 4.6.11CAPWAP Local IPv6 Address, see Section 4.6.12
and this message element MAY be included:
CAPWAP Transport Protocol, see Section 4.6.14Maximum Message Length, see Section 4.6.31WTP Reboot Statistics, see Section 4.6.47Vendor Specific Payload, see Section 4.6.39
6.2. Join Response
the Join Response is how the AC tells a WTP "yep, I'm capable and willing to serve you" ✨
when the WTP gets a Join Response, it checks whether it's a success or a failure. if it's a success, the WTP clears the WaitDTLS timer for the session and moves on to the Configure state 🌈
if the WaitDTLS Timer runs out before a Join Response shows up, the WTP MUST end the handshake, deallocate the session state, and kick off the DTLSAbort command 😭
if an invalid (malformed) Join Response arrives, the WTP SHOULD log an informative message describing the error. that error MUST be handled the same way as AC non-responsiveness, so the WaitDTLS timer will eventually expire. then the WTP MAY (if it's configured to) try to join a new AC 🔥
if one of the WTP Radio Information message elements (see Section 2.1) in the Join Request asked for support of a CAPWAP binding the AC doesn't do, the AC sets the Result Code message element to "Binding Not Supported" 💅
the AC includes the Image Identifier message element to say which software version it expects the WTP to run. the WTP uses that info to decide whether it MUST change its currently running firmware image or download a new version (see Section 9.1.1) 🍓
the Join Response is sent by the AC while it's in the Join State, and the WTP never transmits this one 🙈
these message elements MUST be included in the Join Response message:
Result Code, see Section 4.6.35AC Descriptor, see Section 4.6.1AC Name, see Section 4.6.4WTP Radio Informationmessage element(s) that the AC supports; these are defined by the individual link layer CAPWAP Binding Protocols (see Section 2.1).ECN Support, see Section 4.6.25
one of the following message elements MUST be included in the Join Response Message:
CAPWAP Control IPv4 Address, see Section 4.6.9CAPWAP Control IPv6 Address, see Section 4.6.10
one of the following message elements MUST be included in the Join Response Message:
CAPWAP Local IPv4 Address, see Section 4.6.11CAPWAP Local IPv6 Address, see Section 4.6.12
and these message elements MAY be included:
AC IPv4 List, see Section 4.6.2AC IPv6 List, see Section 4.6.3CAPWAP Transport Protocol, see Section 4.6.14Image Identifier, see Section 4.6.27Maximum Message Length, see Section 4.6.31Vendor Specific Payload, see Section 4.6.39
7. Control Channel Management 💜
the Control Channel Management messages are how the WTP and AC keep their control communication channel healthy 🫶 control messages like the WTP Event Request (sent from the WTP to the AC) tell the AC that the WTP is still operational. when those control messages aren't being sent, the Echo Request and Echo Response messages step in to keep the channel alive ✨
7.1. Echo Request
the Echo Request is a keep-alive mechanism for CAPWAP control messages 🦋
WTPs in the Image Data or Run state (see Section 2.3) send Echo Requests periodically to find out the state of the control connection between the WTP and the AC. the Echo Request goes out when the EchoInterval timer expires 🌸
the Echo Request is sent by the WTP while it's in the Run state, and the AC never transmits it 💅
the following message elements MAY be included in the Echo Request message:
Vendor Specific Payload, see Section 4.6.39
when an AC receives an Echo Request, it responds with an Echo Response 🎀
7.2. Echo Response
the Echo Response is the acknowledgement for the Echo Request 💖
an AC sends an Echo Response after it receives an Echo Request. after sending the Echo Response, the AC SHOULD reset its EchoInterval timer (see Section 4.7.7). if the AC doesn't receive another Echo Request or any other control message before the timer expires, the AC SHOULD consider the WTP to be no longer reachable 😭
the Echo Response is sent by the AC while it's in the Run state, and the WTP never transmits it 🙈
the following message elements MAY be included in the Echo Response message:
Vendor Specific Payload, see Section 4.6.39
when a WTP receives an Echo Response, it sets the EchoInterval back to the configured value 🌈
8. WTP Configuration Management 🍓
WTP Configuration messages are how the AC and the WTP swap configuration info back and forth 💅✨
8.1. Configuration Consistency 💖
Okay bestie, CAPWAP is super flexible about how a WTP handles its configuration 🎀 So a WTP can behave in one of two ways, and which one it picks is implementation specific:
- The WTP retains no configuration and accepts the configuration provided by the AC.
- The WTP saves the configuration of parameters provided by the AC that are non-default values into local non-volatile memory, and are enforced during the WTP's power up initialization phase.
If the WTP opts to save configuration locally, the CAPWAP protocol state machine has a Configure state 🦋 that lets the two sides swap configuration. In the Configure state, the WTP sends its current configuration overrides to the AC via the Configuration Status Request message. A configuration override is just a non-default parameter 🌸 For example, the default antenna configuration in CAPWAP is internal omni antenna. A WTP that either has no internal antennas, or has been explicitly configured by the AC to use external antennas, sends its antenna configuration during the configure phase, so the AC knows what the WTP is actually running ✨
Once the WTP has told the AC its configuration, the AC sends its own configuration back to the WTP. This is how the WTP gets its configuration and policies from the AC 👑
The AC keeps a copy of each active WTP configuration 💅 There's no need for versioning or any other way to track configuration changes. If a WTP becomes inactive, the AC MAY delete the inactive WTP configuration. And if a WTP fails and connects to a new AC, the WTP hands over its overridden configuration parameters, so the new AC knows the WTP's configuration too 🫶
This model is seriously resilient 😭 If an AC fails, another AC can keep serving the WTP. The new AC gets automatically updated with WTP configuration changes, so there's no need for inter-AC communication, and no need for every AC to know the configuration of every WTP in the network. Iconic, honestly 🌈
Once CAPWAP enters the Run state, the WTPs start providing service 🧚 Admins usually want to change configuration while the network is up and running, so the Configuration Update Request is sent by the AC to the WTP to make those changes at run-time.
8.1.1. Configuration Flexibility 🍓
CAPWAP lets you configure and manage WTPs with all kinds of different design and functional characteristics, which is so cool ✨ When a WTP first discovers an AC, it shares primary functional information about its type of MAC and the nature of the frames to be exchanged. The AC then configures the WTP appropriately, and it also sets up matching internal state for that WTP 💜
8.2. Configuration Status Request 🌸
The Configuration Status Request message is sent by a WTP to deliver its current configuration to the AC 📬
The Configuration Status Request message carries binding-specific message elements. Refer to the appropriate binding for the definition of this structure.
When an AC receives a Configuration Status Request message, it acts upon the content of the message and responds to the WTP with a Configuration Status Response message 🫶
The Configuration Status Request message includes multiple Radio Administrative State message elements: one for the WTP, and one for each radio in the WTP.
The Configuration Status Request message is sent by the WTP when in the Configure State. The AC does not transmit this message 🙈
The following message elements MUST be included in the Configuration Status Request message:
- AC Name, see Section 4.6.4
- Radio Administrative State, see Section 4.6.33
- Statistics Timer, see Section 4.6.38
- WTP Reboot Statistics, see Section 4.6.47
The following message elements MAY be included in the Configuration Status Request message:
- AC Name with Priority, see Section 4.6.5
- CAPWAP Transport Protocol, see Section 4.6.14
- WTP Static IP Address Information, see Section 4.6.48
- Vendor Specific Payload, see Section 4.6.39
8.3. Configuration Status Response 💖
The Configuration Status Response message is sent by an AC, and it gives the AC a way to override a WTP's requested configuration 👑
A Configuration Status Response message is sent by an AC after it receives a Configuration Status Request message.
The Configuration Status Response message carries binding-specific message elements. Refer to the appropriate binding for the definition of this structure.
When a WTP receives a Configuration Status Response message, it acts upon the content of the message, as appropriate. If the Configuration Status Response message includes a Radio Operational State message element that causes a change in the operational state of one of the radios, the WTP transmits a Change State Event to the AC, as an acknowledgement of the change in state 🔥
The Configuration Status Response message is sent by the AC when in the Configure state. The WTP does not transmit this message 💅
The following message elements MUST be included in the Configuration Status Response message:
- CAPWAP Timers, see Section 4.6.13
- Decryption Error Report Period, see Section 4.6.18
- Idle Timeout, see Section 4.6.24
- WTP Fallback, see Section 4.6.42
One or both of the following message elements MUST be included in the Configuration Status Response message:
- AC IPv4 List, see Section 4.6.2
- AC IPv6 List, see Section 4.6.3
The following message element MAY be included in the Configuration Status Response message:
- WTP Static IP Address Information, see Section 4.6.48
- Vendor Specific Payload, see Section 4.6.39
8.4. Configuration Update Request 🌈
Configuration Update Request messages are sent by the AC to provision the WTP while it's in the Run state 🧚 This is how the configuration of a WTP gets modified while it's operational.
When a WTP receives a Configuration Update Request message, it responds with a Configuration Update Response message, which has a Result Code message element telling the result of the configuration request ✨
The AC includes the Image Identifier message element (see Section 4.6.27) to force the WTP to update its firmware while in the Run state. The WTP MAY proceed to download the requested firmware if it determines the version specified in the Image Identifier message element is not in its non-volatile storage. It does that by transmitting an Image Data Request (see Section 9.1.1) that includes the Initiate Download message element (see Section 4.6.29) 📥
The Configuration Update Request is sent by the AC when in the Run state. The WTP does not transmit this message 🙈
One or more of the following message elements MAY be included in the Configuration Update message:
- AC Name with Priority, see Section 4.6.5
- AC Timestamp, see Section 4.6.6
- Add MAC ACL Entry, see Section 4.6.7
- CAPWAP Timers, see Section 4.6.13
- Decryption Error Report Period, see Section 4.6.18
- Delete MAC ACL Entry, see Section 4.6.19
- Idle Timeout, see Section 4.6.24
- Location Data, see Section 4.6.30
- Radio Administrative State, see Section 4.6.33
- Statistics Timer, see Section 4.6.38
- WTP Fallback, see Section 4.6.42
- WTP Name, see Section 4.6.45
- WTP Static IP Address Information, see Section 4.6.48
- Image Identifier, see Section 4.6.27
- Vendor Specific Payload, see Section 4.6.39
8.5. Configuration Update Response 🎀
The Configuration Update Response message is the acknowledgement message for the Configuration Update Request message 💖
The Configuration Update Response message is sent by a WTP after it receives a Configuration Update Request message.
When an AC receives a Configuration Update Response message, the result code tells it whether the WTP successfully accepted the configuration 🫶
The Configuration Update Response message is sent by the WTP when in the Run state. The AC does not transmit this message.
The following message element MUST be present in the Configuration Update message:
- Result Code, see Section 4.6.35
The following message elements MAY be present in the Configuration Update Response message:
- Radio Operational State, see Section 4.6.34
- Vendor Specific Payload, see Section 4.6.39
8.6. Change State Event Request 🦋
The Change State Event Request message is used by the WTP for two main purposes:
- When sent by the WTP following the reception of a Configuration Status Response message from the AC, the WTP uses the Change State Event Request message to provide an update on the WTP radio's operational state and to confirm that the configuration provided by the AC was successfully applied.
- When sent during the Run state, the WTP uses the Change State Event Request message to notify the AC of an unexpected change in the WTP's radio operational state.
When an AC receives a Change State Event Request message, it responds with a Change State Event Response message and updates its data structures for the WTP as needed. The AC MAY decide not to provide service to the WTP if it receives an error, based on local policy, and transition to the Reset state 🔥
The Change State Event Request message is sent by a WTP to acknowledge or report an error condition to the AC for a requested configuration in the Configuration Status Response message. It includes the Result Code message element, which says whether the configuration was successfully applied. If the WTP can't apply a specific configuration request, it flags the failure by including one or more Returned Message Element message elements (see Section 4.6.36) 🙈
The Change State Event Request message is sent by the WTP in the Configure or Run state. The AC does not transmit this message.
The WTP MAY save its configuration to persistent storage prior to transmitting the response. However, this is implementation specific and is not required 💜
The following message elements MUST be present in the Change State Event Request message:
- Radio Operational State, see Section 4.6.34
- Result Code, see Section 4.6.35
One or more of the following message elements MAY be present in the Change State Event Request message:
- Returned Message Element(s), see Section 4.6.36
- Vendor Specific Payload, see Section 4.6.39
8.7. Change State Event Response 🌸
The Change State Event Response message acknowledges the Change State Event Request message ✨
A Change State Event Response message is sent by an AC in response to a Change State Event Request message.
The Change State Event Response message is sent by the AC when in the Configure or Run state. The WTP does not transmit this message.
The following message element MAY be included in the Change State Event Response message:
- Vendor Specific Payload, see Section 4.6.39
The WTP does not take any action upon receipt of the Change State Event Response message 🧚
8.8. Clear Configuration Request 🧹✨
Okay bestie, this is the "wipe everything and go back to factory settings" message 🧹💅 The AC sends it to ask a WTP to reset its configuration to the manufacturing default configuration. It only happens while everyone's in the Run state 🌸
The AC is the only one who sends this. The WTP never transmits it 🙈
The following message element MAY be included in the Clear Configuration Request message:
- Vendor Specific Payload, see Section 4.6.39
When a WTP gets a Clear Configuration Request message, it resets its configuration to the manufacturing default configuration. Full reset, no cap 🔥
8.9. Clear Configuration Response 🫶
The Clear Configuration Response is the WTP's little "all done, babe" 🦋 It gets sent after the WTP receives a Clear Configuration Request and resets its configuration parameters to the manufacturing default values.
This one is also sent by the WTP while in the Run state. The AC never sends it 💖
The Clear Configuration Response message MUST include the following message element:
- Result Code, see Section 4.6.35
The following message element MAY be included in the Clear Configuration Request message:
- Vendor Specific Payload, see Section 4.6.39
Heads up, the original text says "Clear Configuration Request message" in this optional-element spot, even though we're talking about the Response. We're keeping it exactly as written 👀✨
9. Device Management Operations 🎀
This section is all about the CAPWAP operations for debugging, gathering stats, logging, and firmware management 📊 The AC uses these to push or pull info to and from the WTP, or to ask the WTP to reboot 🔁 This section doesn't cover managing the AC itself. It just assumes the AC is up and configured already 💜
9.1. Firmware Management 💾
This section explains the firmware download procedures CAPWAP uses 🌈 Firmware download can happen in either the Image Data state or the Run state. Image Data lets the download happen at boot time. Run lets the AC kick off a download while an active CAPWAP session is already going 🔥
Super important: CAPWAP does not let the AC check whether the firmware info the WTP reports is correct, or whether the WTP is actually storing the firmware properly 🙈 (see Section 12.10 for more information).
Figure 6 is an example of a WTP doing a firmware upgrade in the Image Data state. In this one, the WTP doesn't already have the requested firmware (Image Identifier = x), so it downloads the image from the AC 📥
WTP AC
Join Request
-------------------------------------------------------->
Join Response (Image Identifier = x)
<------------------------------------------------------
Image Data Request (Image Identifier = x,
Initiate Download)
-------------------------------------------------------->
Image Data Response (Result Code = Success,
Image Information = {size,hash})
<------------------------------------------------------
Image Data Request (Image Data = Data)
<------------------------------------------------------
Image Data Response (Result Code = Success)
-------------------------------------------------------->
.....
Image Data Request (Image Data = EOF)
<------------------------------------------------------
Image Data Response (Result Code = Success)
-------------------------------------------------------->
(WTP enters the Reset State)Figure 6: WTP Firmware Download Case 1 💖
Figure 7 shows a case where the WTP already has the image the AC specified in its non-volatile storage, but it's not the image currently running. Here the WTP opts not to download the firmware and immediately resets to the requested image ✨
WTP AC
Join Request
-------------------------------------------------------->
Join Response (Image Identifier = x)
<------------------------------------------------------
(WTP enters the Reset State)Figure 7: WTP Firmware Download Case 2 🦋
Figure 8 is a WTP doing a firmware upgrade while in the Run state. This mode is giving multitasking 💅 The WTP downloads its image while it keeps providing service. It won't reset automatically. It waits until the AC sends a Reset Request message 🫶
WTP AC
Configuration Update Request (Image Identifier = x)
<------------------------------------------------------
Configuration Update Response (Result Code = Success)
-------------------------------------------------------->
Image Data Request (Image Identifier = x,
Initiate Download)
-------------------------------------------------------->
Image Data Response (Result Code = Success,
Image Information = {size,hash})
<------------------------------------------------------
Image Data Request (Image Data = Data)
<------------------------------------------------------
Image Data Response (Result Code = Success)
-------------------------------------------------------->
.....
Image Data Request (Image Data = EOF)
<------------------------------------------------------
Image Data Response (Result Code = Success)
-------------------------------------------------------->
.....
(administratively requested reboot request)
Reset Request (Image Identifier = x)
<------------------------------------------------------
Reset Response (Result Code = Success)
-------------------------------------------------------->Figure 8: WTP Firmware Download Case 3 🔥
Figure 9 is another Run state firmware download, but this time the WTP already has the image the AC specified in its non-volatile storage 🧚 The WTP opts not to download it. It resets when it gets a Reset Request message from the AC 👑
WTP AC
Configuration Update Request (Image Identifier = x)
<------------------------------------------------------
Configuration Update Response (Result Code = Already Have Image)
-------------------------------------------------------->
.....
(administratively requested reboot request)
Reset Request (Image Identifier = x)
<------------------------------------------------------
Reset Response (Result Code = Success)
-------------------------------------------------------->Figure 9: WTP Firmware Download Case 4 🌸
9.1.1. Image Data Request 📦
The Image Data Request message is used to update firmware on the WTP 💫 The AC uses this message and its companion Response message to make sure the image running on each WTP is the right one 🎀
Image Data Request messages go back and forth between the WTP and the AC to download a new firmware image to the WTP. When a WTP or AC gets an Image Data Request message, it sends back an Image Data Response message. The message elements inside the Image Data Request are required to figure out what the request is for 🧠
There are two ways the decision to download new firmware to the WTP can happen 👀
- When the WTP joins the AC, the Join Response message includes the Image Identifier message element. That tells the WTP which firmware it's supposed to run. If the WTP doesn't have the requested firmware version yet, it sends an Image Data Request with the appropriate Image Identifier message element. If the WTP already has the requested firmware in its non-volatile flash but isn't running it, it just resets to run the right firmware 🔁
- Once the WTP is in the Run state, the AC can make the WTP start a firmware download by sending a Configuration Update Request message with the Image Identifier message elements. That makes the WTP send an Image Data Request with the Image Identifier and the Initiate Download message elements. Heads up, when firmware gets downloaded this way, the WTP does not reset automatically once the download is done. It only resets when it receives a Reset Request message from the AC ⚠️ If the WTP already had the requested firmware version in its non-volatile storage, it doesn't send an Image Data Request. It replies with a Configuration Update Response message, with the Result Code set to Image Already Present 💅
No matter how the download got started, once the AC gets an Image Data Request with the Image Identifier message element, it kicks off the transfer by sending an Image Data Request that includes the Image Data message element. This keeps going until the whole firmware image has been transferred 🚀
The Image Data Request message is sent by the WTP or the AC when in the Image Data or Run state.
The following message elements MAY be included in the Image Data Request message:
- CAPWAP Transport Protocol, see Section 4.6.14
- Image Data, see Section 4.6.26
- Vendor Specific Payload, see Section 4.6.39
The following message elements MAY be included in the Image Data Request message when sent by the WTP:
- Image Identifier, see Section 4.6.27
- Initiate Download, see Section 4.6.29
9.1.2. Image Data Response 🦋
The Image Data Response message acknowledges the Image Data Request message 💖
An Image Data Response message is sent in response to a received Image Data Request message. Its job is to acknowledge that the Image Data Request was received. The Result Code is included to show whether a previously sent Image Data Request message was invalid 🫶
The Image Data Response message is sent by the WTP or the AC when in the Image Data or Run state.
The following message element MUST be included in the Image Data Response message:
- Result Code, see Section 4.6.35
The following message element MAY be included in the Image Data Response message:
- Vendor Specific Payload, see Section 4.6.39
The following message element MAY be included in the Image Data Response message when sent by the AC:
- Image Information, see Section 4.6.28
If a WTP gets an Image Data Response message that indicates an error, it MAY retransmit a previous Image Data Request message, or it can give up on the firmware download by moving to the Reset state 🌈 💀
9.2. Reset Request
Okay so the Reset Request is how an AC makes a WTP reboot 🔄✨ It's giving full restart energy.
A Reset Request message is sent by an AC to cause a WTP to reinitialize its operation. If the AC includes the Image Identifier message element (see Section 4.6.27), it's basically telling the WTP that it SHOULD use that version of software when it boots back up 💜
The Reset Request is sent by the AC when in the Run state. The WTP does not transmit this message 🙈
The following message element MUST be included in the Reset Request message:
- Image Identifier, see Section 4.6.27
The following message element MAY be included in the Reset Request message:
- Vendor Specific Payload, see Section 4.6.39
When a WTP gets a Reset Request, it responds with a Reset Response message indicating success and then reinitializes itself. 🫶 Now the tricky bit: if the WTP can't write to its non-volatile storage, it might not be able to make sure it runs the software version named in the Image Identifier message element. In that case it MAY send the appropriate Result Code message element, but it MUST reboot anyway. If the WTP can't reset at all, including a hardware reset, it sends a Reset Response message to the AC with a Result Code message element indicating failure. And then the AC no longer provides service to the WTP 💀
9.3. Reset Response
The Reset Response message acknowledges the Reset Request message. It's the "yep, got it" reply 💅
A Reset Response message is sent by the WTP after receiving a Reset Request message.
The Reset Response is sent by the WTP when in the Run state. The AC does not transmit this message.
The following message elements MAY be included in the Reset Response message.
- Result Code, see Section 4.6.35
- Vendor Specific Payload, see Section 4.6.39
When an AC gets a successful Reset Response message, it's notified that the WTP will reinitialize its operation 🌸 An AC that receives a Reset Response message indicating failure may opt to no longer provide service to the WTP. So it's the AC's call there 👑
9.4. WTP Event Request
The WTP Event Request message is how a WTP sends information up to its AC. ✨ It MAY be sent periodically, or sent in response to an asynchronous event on the WTP. For example, a WTP MAY collect statistics and use the WTP Event Request message to transmit those stats to the AC 📊
When an AC receives a WTP Event Request message, it will respond with a WTP Event Response message.
The presence of the Delete Station message element is how the WTP tells the AC that it's no longer providing service to the station. This could happen because of an Idle Timeout (see Section 4.6.24), because of resource shortages, or for some other reason 🧚
The WTP Event Request message is sent by the WTP when in the Run state. The AC does not transmit this message.
The WTP Event Request message MUST contain one of the message elements listed below, or a message element that is defined for a specific wireless technology. More than one of each message element listed MAY be included in the WTP Event Request message.
- Decryption Error Report, see Section 4.6.17
- Duplicate IPv4 Address, see Section 4.6.22
- Duplicate IPv6 Address, see Section 4.6.23
- WTP Radio Statistics, see Section 4.6.46
- WTP Reboot Statistics, see Section 4.6.47
- Delete Station, see Section 4.6.20
- Vendor Specific Payload, see Section 4.6.39
9.5. WTP Event Response
The WTP Event Response message acknowledges receipt of the WTP Event Request message. Bestie, this is the receipt 🧾💖
A WTP Event Response message is sent by an AC after receiving a WTP Event Request message.
The WTP Event Response message is sent by the AC when in the Run state. The WTP does not transmit this message.
The following message element MAY be included in the WTP Event Response message:
- Vendor Specific Payload, see Section 4.6.39
9.6. Data Transfer
Okay, this section is all about the data transfer procedures used by the CAPWAP protocol 📂 The data transfer mechanism is used to upload information available at the WTP to the AC, like crash or debug information. The data transfer messages can only be exchanged while in the Run state. No other state, no cap 🙅♀️
Figure 10 shows an example of an AC asking the WTP to transfer its latest crash file. Once the WTP acknowledges that it has information to send, via the Data Transfer Response, it sends its own Data Transfer Request. When the AC gets that, it responds with a Data Transfer Response, and the exchange keeps going until the WTP sends a Data Transfer Data message element that indicates an End of File (EOF) 🎀
WTP AC
Data Transfer Request (Data Transfer Mode = Crash Data)
<------------------------------------------------------
Data Transfer Response (Result Code = Success)
-------------------------------------------------------->
Data Transfer Request (Data Transfer Data = Data)
-------------------------------------------------------->
Data Transfer Response (Result Code = Success)
<------------------------------------------------------
.....
Data Transfer Request (Data Transfer Data = EOF)
-------------------------------------------------------->
Data Transfer Response (Result Code = Success)
<------------------------------------------------------
Figure 10: WTP Data Transfer Case 1Figure 11 shows an example of an AC asking the WTP to transfer its latest crash file too. But in this one, the WTP has no crash information to send, so it sends a Data Transfer Response with a Result Code indicating the error 😭
WTP AC
Data Transfer Request (Data Transfer Mode = Crash Data)
<------------------------------------------------------
Data Transfer Response (Result Code = Data Transfer
Error (No Information to Transfer))
-------------------------------------------------------->
Figure 11: WTP Data Transfer Case 29.6.1. Data Transfer Request
The Data Transfer Request message is used to deliver debug information from the WTP to the AC 🔍
Data Transfer Request messages can be sent by either the AC or the WTP. When the AC sends one, it's requesting that data be transmitted from the WTP to the AC, and it includes the Data Transfer Mode message element, which specifies the information the AC wants 💅 When the WTP sends one, it's transferring actual data to the AC through the Data Transfer Data message element.
Since CAPWAP minimizes the need for WTPs to be directly managed, the Data Transfer Request is a big troubleshooting tool 🛠️ The AC uses it to pull information that may be available on the WTP. For instance, some WTP implementations may store crash information to help manufacturers find software faults, and the Data Transfer Request message can send that info from the WTP to the AC. Another possible use is letting a remote debugger function in the WTP use the Data Transfer Request message to send console output to the AC for debugging purposes 🧚
When the WTP or AC receives a Data Transfer Request message, it responds with a Data Transfer Response message. The AC MAY log the information it receives through the Data Transfer Data message element 📝
The Data Transfer Request message is sent by the WTP or AC when in the Run state.
When the AC sends it, the Data Transfer Request message MUST contain the following message element:
- Data Transfer Mode, see Section 4.6.16
When the WTP sends it, the Data Transfer Request message MUST contain the following message element:
- Data Transfer Data, see Section 4.6.15
Regardless of whether the Data Transfer Request is sent by the AC or WTP, the following message element MAY be included in the Data Transfer Request message:
- Vendor Specific Payload, see Section 4.6.39
9.6.2. Data Transfer Response
The Data Transfer Response message acknowledges the Data Transfer Request message 🫶
A Data Transfer Response message is sent in response to a received Data Transfer Request message. Its purpose is to acknowledge receipt of that Data Transfer Request message. When the WTP sends it, the Result Code message element shows whether the data transfer the AC asked for can be completed. When the AC sends it, the Result Code message element shows that it received the data transferred in the Data Transfer Request message.
The Data Transfer Response message is sent by the WTP or AC when in the Run state.
The following message element MUST be included in the Data Transfer Response message:
- Result Code, see Section 4.6.35
The following message element MAY be included in the Data Transfer Response message:
- Vendor Specific Payload, see Section 4.6.39
When a WTP gets a Data Transfer Response message, it transmits more information, if more information is available 🌈
10. Station Session Management ✨
Messages in this section are used by the AC to create, modify, or delete station session state on the WTPs 🦋
10.1. Station Configuration Request
The Station Configuration Request message is used to create, modify, or delete station session state on a WTP. The AC sends it to the WTP, and it MAY contain one or more message elements. The message elements for this CAPWAP Control message include information that is generally highly technology specific, so refer to the appropriate binding document for definitions of the message elements included in this control message 🧠
The Station Configuration Request message is sent by the AC when in the Run state. The WTP does not transmit this message.
The following CAPWAP Control message elements MAY be included in the Station Configuration Request message. More than one of each message element listed MAY be included in the Station Configuration Request message:
- Add Station, see Section 4.6.8
- Delete Station, see Section 4.6.20
- Vendor Specific Payload, see Section 4.6.39
10.2. Station Configuration Response
The Station Configuration Response message is used to acknowledge a previously received Station Configuration Request message 🎀
The Station Configuration Response message is sent by the WTP when in the Run state. The AC does not transmit this message.
The following message element MUST be present in the Station Configuration Response message:
- Result Code, see Section 4.6.35
The following message element MAY be included in the Station Configuration Response message:
- Vendor Specific Payload, see Section 4.6.39
The Result Code message element indicates that the requested configuration was successfully applied, or that an error related to processing the Station Configuration Request message occurred on the WTP 💜
11. NAT Considerations ✨
okay so bestie, NAT is the thing where a whole bunch of private devices hide behind one public address, and CAPWAP has to deal with it. 🌸 There are three situations where that can happen, and each one gets its own vibe.
The first one is when a single WTP sits behind a NAT system. 🦋 This is lowkey the easy mode, because the WTP starts every conversation and all the traffic is IP over two UDP ports, so the protocol slides right through NAT here. 💅
The second one is when two or more WTPs share the same NAT system. 👯 Now the AC gets multiple connection requests from the very same IP address, so it can't just use the WTP's IP address alone to tie the CAPWAP Control and Data channel together. 🙈 That's where the CAPWAP Data Check state comes in. It sets up the data plane connection and carries the CAPWAP Data Channel Keep-Alive, and it includes the Session Identifier message element, which is what binds the control and data plane together. ✨ Thanks to the Session Identifier message element, the AC can match up the control and data plane flows from multiple WTPs behind the same NAT system, even though they all share one IP address. 🔥 On top of that, CAPWAP implementations MUST also use DTLS session information on any encrypted CAPWAP channel to validate the source of both the control and data plane, as described in Section 12.2. 🫶
The third one is when the AC itself is behind a NAT. 🌈 Here the WTP can't reach the AC unless someone configured a specific rule on the NAT to translate the address and redirect CAPWAP messages to the AC. 💀 This setup causes two problems. First, an AC shares its interfaces and the WTP load using the CAPWAP Control IPv4 Address and CAPWAP Control IPv6 Address message elements. 🍓 That message element is mandatory, but the addresses inside it are only valid in the private address space the AC uses, which the WTP can't reach. So the WTP MUST NOT utilize the information in these message elements if it detects a NAT (as described in the CAPWAP Transport Protocol message element in Section 4.6.14). 🙅 Second, since the WTP can't use those addresses, the load-balancing capabilities (see Section 6.1) of CAPWAP basically get switched off. 😭 The other option is for the AC to have a configured NAT'ed address, which it would put in either of the two control address message elements, and then the NAT would need to be set up to match. 🎀
To figure out whether a middlebox is in the way, a WTP or AC looks at the Join Request (see Section 6.1) and the Join Response (see Section 6.2). Both of them include either the CAPWAP Local IPv4 Address (see Section 4.6.11) or the CAPWAP Local IPv6 Address (see Section 4.6.12) message element. 🔍 When one of these messages arrives, if the packet's source IP address is different from the address in either of those message elements, that means a middlebox is present. 🧚
For CAPWAP to play nicely with middleboxes, CAPWAP implementations MUST send return traffic from the same port on which they received traffic from a given peer. 🦋 Also, any unsolicited requests generated by a CAPWAP node MUST be sent on the same port. 💜
Heads up, this middlebox detection isn't foolproof. ⚠️ If the public IP address assigned to the NAT is identical to the private IP address used by the AC, the WTP's detection would fail. 🙈 That failure can lead to all kinds of protocol errors, so deployments need to make sure the NAT's IP address is not the same as the ACs. 🌸
CAPWAP lets all of the AC identities that support a group of WTPs get communicated through the AC List message element. 🎀 This feature MUST be ignored by the WTP when it detects the AC is behind a middlebox. 🙅
CAPWAP also lets an AC configure a static IP address on a WTP using the WTP Static IP Address Information message element. 🌷 This message element SHOULD NOT be used in NAT'ed environments, unless the administrator is familiar with the internal IP addressing scheme within the WTP's private network and does not rely on the public address the AC sees. 🧐
When a WTP detects the duplicate address condition, it sends a message to the AC that includes the Duplicate IP Address message element. 🫠 The IP address inside this message element is different from the public IP address the AC sees. ✨
12. Security Considerations 🔐💀
okay bestie, this part is serious business, so pay attention. 🫡 This section covers the security considerations for the CAPWAP protocol, and it also gives security recommendations for protocols that get used together with CAPWAP. 💜
12.1. CAPWAP Security 🛡️
As it's currently specified, CAPWAP sits between the security mechanisms of the wireless link layer protocol (for example IEEE 802.11i) and Authentication, Authorization, and Accounting (AAA). 🦋 One goal of CAPWAP is to bootstrap trust between the STA and WTP using a series of preestablished trust relationships, and the diagram below shows how that chain works. 👑
STA WTP AC AAA
==============================================
DTLS Cred AAA Cred
<------------><------------->
EAP Credential
<------------------------------------------>
wireless link layer
(e.g., 802.11 PTK)
<--------------> or
<--------------------------->
(derived)
Figure 12: STA Session SetupInside CAPWAP, DTLS secures the link between the WTP and AC. 🔒 On top of protecting control messages, it's also a link in this chain of trust for establishing link layer keys. ✨ So honestly, a lot rests on how secure DTLS is. 😳
In some CAPWAP deployment scenarios there are two channels between the WTP and AC: the control channel, which carries CAPWAP Control messages, and the data channel, which tunnels client data packets between the AC and WTP. 🌈 Typically the control channel is secured by DTLS, while the data channel is not. 🙃
Using parallel protected and unprotected channels deserves special consideration, but it doesn't create a threat. 💅 There are two potential concerns: trying to convert protected data into unprotected data, and trying to convert unprotected data into protected data. 🤔 Both get addressed below.
12.1.1. Converting Protected Data into Unprotected Data 🙅♀️
Since CAPWAP doesn't support authentication-only ciphers (every supported ciphersuite includes both encryption and authentication), it isn't possible to convert protected data into unprotected data. 🔐 Encrypted data is (ideally) indistinguishable from random data, so the probability of an encrypted packet passing for a well-formed packet is effectively zero. 🧮
12.1.2. Converting Unprotected Data into Protected Data (Insertion) 🚫
Message authentication makes it impossible for an attacker to forge protected records. 🛑 That means converting unprotected records into protected records is impossible too. 🙌
12.1.3. Deletion of Protected Records 😱
An attacker could remove protected records from the stream, but it wouldn't go unnoticed, thanks to the built-in reliability of the underlying CAPWAP protocol. 👀 In the worst case, the attacker removes the same record over and over, which leads to a CAPWAP session timeout and restart. 💀 This is effectively a DoS attack, and a man in the middle could pull it off no matter which CAPWAP protocol security mechanisms are chosen. 🚨
12.1.4. Insertion of Unprotected Records 🕵️
An attacker could inject packets into the unprotected channel, but this may become evident if sequence number desynchronization happens as a result. 🫣 Only if the attacker is a man in the middle (MITM) can packets be inserted undetectably. 😬 This comes from that channel's lack of protection, and it isn't a new threat caused by the CAPWAP security mechanism. 🧠
12.1.5. Use of MD5 🧩
The Image Information message element (Section 4.6.28) uses MD5 to compute the hash field. 🖼️ The authenticity and integrity of the image file are protected by DTLS, and in this context MD5 isn't used as a cryptographically secure hash, just as a basic checksum. ✅ So the use of MD5 isn't considered a security vulnerability, and no mechanisms for algorithm agility are provided. 🤷♀️
12.1.6. CAPWAP Fragmentation 🧩💥
RFC 4963 [RFC4963] describes a possible security vulnerability where a malicious entity can "corrupt" a flow by injecting fragments. 😤 By sending "high" fragments (those with offset greater than zero) with a forged source address, the attacker can deliberately cause corruption. 💔 Using DTLS on the CAPWAP Data channel can be used to avoid this possible vulnerability. 🛡️
12.2. Session ID Security 🆔
Since DTLS doesn't export a unique session identifier, there can be no explicit protocol binding between the DTLS layer and the CAPWAP layer. 🙈 Because of that, implementations MUST provide a mechanism for performing this binding. 🔗 For example, an AC MUST NOT associate decrypted DTLS control packets with a particular WTP session based solely on the Session ID in the packet header. 🚫 Instead, identification should be done based on which DTLS session decrypted the packet. 🔑 Otherwise, one authenticated WTP could spoof another authenticated WTP by altering the Session ID in the encrypted CAPWAP Header. 😈
It should be noted that when the CAPWAP Data channel is unencrypted, the WTP Session ID is exposed and possibly known to adversaries and other WTPs. 👀 That would allow forgery of the source of data-channel traffic. 😱 This, however, should not be a surprise for unencrypted data channels. 🤷♀️ When the data channel is encrypted, the Session ID is not exposed, so it can safely be used to associate a data and control channel. 💜 The 128-bit length of the Session ID mitigates online guessing attacks, where an adversarial, authenticated WTP tries to correlate its own data channel with another WTP's control channel. 🧮 Note that for encrypted data channels, the Session ID should only be used for correlation on the first packet immediately after the initial DTLS handshake. ⏳ Future correlation should instead be done by identifying a packet's DTLS session. 🫶
12.3. Discovery or DTLS Setup Attacks 🛡️
okay bestie, this one is about sneaky Discovery Request messages. They go out in the clear, so the AC needs to be careful: receiving one from a WTP does NOT mean that WTP just rebooted 🙅♀️. The AC should NOT tear down active DTLS sessions just because a Discovery Request showed up. Anyone can spoof those, so the AC keeps two separate sets of state for the WTP until the DTLSSessionEstablished notification arrives to confirm the WTP was authenticated. Once the new DTLS session is up, the AC can clear any state tied to the old one 🧹✨
Same energy goes for the DTLS Setup phase. The AC SHOULD NOT assume the WTP has reset just because it's entering that phase, so it shouldn't throw away active state until the new DTLS session is successfully established 💅
HelloVerifyRequest helps against DoS attacks on the AC, but it isn't a full shield 😭 Someone who can receive packets at a valid address (or a WTP that's malfunctioning or misconfigured) can keep trying DTLS handshakes and eat up resources. If either the FailedDTLSSessionCount or the FailedDTLSAuthFailCount counter hits the value of the MaxFailedDTLSSessionRetry variable (see Section 4.8), implementations MAY choose to rate-limit new DTLS handshakes for a while 🌸
If you do rate-limit, it is RECOMMENDED to use a random discard technique rather than copying the WTP's sulking behavior 🙄 That way, messages from legit WTPs still have some chance of getting a response, even during a big DoS attack 🫶
Some CAPWAP implementations might want to only allow DTLS setup from peers that are in the access control list, so only those clients can start a handshake 🎀 Heads up though: this doesn't do much against DoS on the DTLS layer, since DTLS already uses client-side cookies to keep processor consumption attacks in check 🍓
12.4. Interference with a DTLS Session 🦋
If a WTP or AC keeps getting packets that fail DTLS authentication or decryption, that could mean a few things: the DTLS session is out of sync between the AC and WTP, the link is prone to undetectable bit errors, or an attacker is trying to mess with the session 👀
Over in the state machine (section 2.3), a move to the DTLS Tear Down (TD) state can be triggered by a pile of DTLS packets with authentication or decryption errors. Choosing when to flip that switch needs real care 💭 If it's super easy to jump into DTLS TD, you can spot malfunctioning devices quickly, but attackers can exploit that for denial-of-service. If it's hard to get into DTLS TD, you're protected from DoS, but it gets harder to catch and reset a broken session. Implementers should set this policy with care 💖
12.5. CAPWAP Pre-Provisioning 🧚
Before CAPWAP can set up a secure chat with a peer, both the WTP and AC need some pre-provisioning 📝 This section covers the minimum set of configuration parameters.
If you're using pre-shared keys, you need to configure a key for every possible peer you might establish a DTLS session with. To make that work, you can set up one or more entries from the following list on either the AC or WTP:
- Identity: The identity of the peering AC or WTP. This format MAY be in the form of either an IP address or host name (the latter of which needs to be resolved to an IP address using DNS).
- Key: The pre-shared key for use with the peer when establishing the DTLS session (see Section 12.6 for more information).
- PSK Identity: Identity hint associated with the provisioned key (see Section 2.4.4.4 for more information).
If you're using certificates, these need to be pre-provisioned:
- Device Certificate: The local device's certificate (see Section 12.7 for more information).
- Trust Anchor: Trusted root certificate chain used to validate any certificate received from CAPWAP peers. Note that one or more root certificates MAY be configured on a given device.
No matter which authentication method you pick, this one is always needed:
- Access Control List: The access control list table contains the identities of one or more CAPWAP peers, along with a rule. The rule is used to determine whether communication with the peer is permitted (see Section 2.4.4.3 for more information).
12.6. Use of Pre-Shared Keys in CAPWAP 🔐
Pre-shared keys are super convenient for deployment and provisioning, but they come with operational and security worries too 😬 The big issue is that keys usually get typed in by hand, so people tend to pick memorable words or phrases. These are called "low entropy passwords/passphrases", and they're basically catnip for attackers 🙈
Low-entropy pre-shared keys that also rarely get updated really raise exposure. So here are the recommendations:
- When DTLS is used with a pre-shared key (PSK) ciphersuite, each WTP SHOULD have a unique PSK. WTPs will likely be deployed everywhere, so their physical security can't be guaranteed 🏢 If PSKs aren't unique per WTP, then compromising one WTP could compromise the others too 😱
- Generating PSKs from low entropy passwords is NOT RECOMMENDED 🚫
- It is RECOMMENDED that implementations that let an administrator configure the PSK manually also offer a way to generate new random PSKs, taking RFC 4086 [RFC4086] into account 🎲
- Pre-shared keys SHOULD be periodically updated. Implementations MAY make this easier with an administrative interface for automatic key generation and periodic update, or it MAY be done manually instead 🔄
Every pairwise combination of WTP and AC on the network SHOULD have a unique PSK 💜 This stops the domino effect (see "Guidance for Authentication, Authorization, and Accounting (AAA) Key Management" [RFC4962]). If PSKs are tied to specific WTPs, then knowing the PSK implies a binding to an identity that can be authorized 🪪
If PSKs are shared, that binding between device and identity is gone 💔 One compromised WTP can then compromise another, which breaks the CAPWAP security hierarchy. So sharing keys between WTPs is NOT RECOMMENDED 🙅♀️
12.7. Use of Certificates in CAPWAP 📜
For public-key-based DTLS deployments, each device SHOULD have unique credentials, with an extended key usage that authorizes the device to act as either a WTP or AC 🎀 If devices share credentials, then compromising one device could mean every other device using that same credential is considered compromised too 😭
Certificate validation involves checking a ton of things 🥱 Since what you need to validate is often specific to the environment, a lot of it is out of scope for this document. This section just gives some basic guidance on certificate validation.
Each device is responsible for authenticating and authorizing the devices it talks to. Authentication means validating the chain of trust leading to the peer certificate, then validating the peer certificate itself. Implementations SHOULD also provide a secure method for checking that the credential hasn't been revoked 🕵️♀️
Heads up: if the WTP relies on the AC for network connectivity (for example, the AC is a Layer 2 switch the WTP is directly connected to), the WTP might not be able to reach an Online Certificate Status Protocol (OCSP) server or get an up-to-date Certificate Revocation List (CRL) if a compromised AC doesn't explicitly allow it 🚨 The only real fix for that is strong physical security and monitoring at the AC 🔒
Proper certificate validation usually means checking that the certificate hasn't expired yet ⏰ If devices have a real-time clock, they SHOULD verify the certificate validity dates. If there's no real-time clock, the device SHOULD make a best-effort attempt to validate those dates some other way. Skipping the temporal check can leave a device open to man-in-the-middle attacks that use compromised, expired certificates, so devices should make every effort to do this validation 💅
12.8. Use of MAC Address in CN Field 🏷️
The CAPWAP protocol evolved from an existing protocol [LWAPP], which is running on a huge number of ACs and WTPs already deployed in the wild 🌍 Every one of those devices has an X.509 certificate that was provisioned at manufacturing. Those certificates put the device's MAC address in the Common Name (CN) field.
Everyone agrees that stuffing the MAC address into the CN field is less than ideal, and using the SubjectAltName field would be way better 🙌 The catch is that, at the time of publication, there's no URN specification that lets the MAC address go in the SubjectAltName field. Once the IETF publishes such a specification, future versions of the CAPWAP protocol MAY require support for the new URN scheme 🌈
12.9. AAA Security 🔑
The AAA protocol is what hands Extensible Authentication Protocol (EAP) keys out to the ACs, so its security matters a lot for the whole system 💪 When it's used with Transport Layer Security (TLS) or IPsec, the security guidelines in RFC 3539 [RFC3539] SHOULD be followed 📋
In general, the link between the AC and AAA server SHOULD be secured with a strong ciphersuite keyed with mutually authenticated session keys 🛡️ Implementations SHOULD NOT rely solely on Basic RADIUS shared secret authentication, since it's often vulnerable to dictionary attacks 🙅♀️ Instead, they SHOULD use stronger underlying security mechanisms 💜
12.10. WTP Firmware 💾
CAPWAP defines a way for the AC to download new firmware to the WTP ⬇️ During session establishment, the WTP tells the AC what firmware it's currently running, and then the AC decides whether that firmware needs an update. Here's the important bit: the CAPWAP specification explicitly assumes the WTP is reporting the correct firmware version and isn't lying 🤥 Also, during the firmware download, CAPWAP has no mechanism to check whether the WTP is actually storing that firmware for later use 👀
13. Operational Considerations 🛠️✨
okay so bestie, the CAPWAP protocol assumes it is the ONLY configuration interface to the WTP for the parameters that CAPWAP specifies 💅 You can use a separate management protocol to monitor the WTP directly (that MAY be used 👀), but configuring the WTP through a separate management interface is not recommended 🙈 Like, if you configure it through a CLI or SNMP, the AC's state could end up out of sync with the WTP, and that's a whole mess 💀
CAPWAP doesn't handle managing the ACs either 🫶 The AC is assumed to be configured through some separate management interface, which could be a proprietary CLI, SNMP, Network Configuration Protocol (NETCONF), or some other management protocol. Pick your fighter 🧚
Now the vibes on traffic: the control channel is honestly pretty lightweight 🌸 Once the WTP is configured, it sends periodic statistics. The spec also asks for a keep-alive packet on the data channel so any middleboxes (like a NAT) keep their UDP state alive 🦋 The overhead from both channels is not expected to impact network traffic, and it's giving "chill" ✨ That said, you can tweak how often these packets go out using the DataChannelKeepAlive and StatisticsTimer (see Section 4.7.2 and Section 4.7.14, respectively) 💜
14. Transport Considerations 🚛💖
The CAPWAP WG really thought hard about congestion control for both the CAPWAP Control and Data channels 🧠 We're obsessed with that effort, ngl 😭
The control channel is a single-threaded command/response protocol 🎀 and when commands get retransmitted, the spec says an exponential back-off algorithm should be used. When CAPWAP runs in its default mode (Local MAC), the control channel is the only CAPWAP channel 🌈
BUT, CAPWAP can also run in Split MAC mode, and then there's a DTLS-encrypted data channel between each WTP and the AC 🔐 The WG talked through a bunch of options for congestion control on this channel, but here's the tea: TCP performs badly when it runs over another congestion control mechanism, and most of the traffic on the CAPWAP Data channel is probably already congestion-controlled IP traffic 🙃 So the WG decided that specifying a congestion control mechanism for the Data channel would cause more problems than it solves 💅
Because there's no congestion control mechanism specified for the CAPWAP Data channel, it is RECOMMENDED that non-congestion-controlled traffic not be tunneled over CAPWAP 🚫 If a WLAN is expected to carry a significant amount of non-congestion-controlled traffic, the CAPWAP connection between the AC and the WTP for that LAN should be configured to stay in Local MAC mode with Distribution function at the WTP 🫧
The control channel is lock-step, so the firmware download can take a while depending on the round-trip time (RTT) ⏳ This isn't expected to be a problem, though, since CAPWAP lets firmware download while the WTP keeps serving wireless clients/devices 🙌
The WTP and AC need to configure their MTU based on what the path can handle 📏 See Section 3.5 for more info 💜
Also, CAPWAP mandates support for Explicit Congestion Notification (ECN) through a mode called "limited functionality option", which is detailed in section 9.1.1 of [RFC3168] 🌟 Future versions of CAPWAP should consider mandating support for the "full functionality option" 👑
15. IANA Considerations 🦋📋
This section covers what IANA has done to get ready for publication of the spec 🎀 A bunch of registries were created, and their contents, document action (see [RFC5226], and registry format are all included below. Heads up: wherever bit fields come up, the bit numbering goes left to right, and the leftmost bit is labeled bit zero (0) 🔢
For future registration requests that need an Expert Review, a Designated Expert should be consulted, and the responsible IESG Area Director appoints them 🧑⚖️ The goal is that every allocation comes with a published RFC, but since other SDOs might want to build standards on top of CAPWAP, a document the Designated Expert can review is also okay 🫶 IANA should allow allocating values before documents are approved for publication, so the Designated Expert can approve them once publication seems clear ✨ The Designated Expert will post the request to the CAPWAP WG mailing list (or a successor the Area Director designates) for comment and review 📬 Before 30 days have passed, they'll either approve or deny the request and post a notice of the decision to that list (or its successor), and tell IANA too 🗓️ A denial notice must come with an explanation, and where possible, concrete suggestions for how to change the request so it becomes acceptable should be included 💌
15.1. IPv4 Multicast Address
IANA registered a new IPv4 multicast address called "capwap-ac" from the Internetwork Control Block IPv4 multicast address registry 📡 See Section 3.3 🌸
15.2. IPv6 Multicast Address
IANA registered a new organization local multicast address called the "All ACs multicast address" in the Variable Scope IPv6 multicast address registry 🌐 See Section 3.3 ✨
15.3. UDP Port
IANA registered two new UDP ports, which are organization-local multicast addresses, in the registered port numbers registry 🔌 See Section 3.1. Here's what got registered 👇
Keyword Decimal Description References
------- ------- ----------- ----------
capwap-control 5246/udp CAPWAP Control Protocol This Document
capwap-data 5247/udp CAPWAP Data Protocol This Document15.4. CAPWAP Message Types
The Message Type field in the CAPWAP Header (see Section 4.5.1.1) identifies the operation a message performs 💅 There are multiple namespaces, each identified by the first three octets of the field containing the IANA Enterprise Number [RFC5226] 🧩
IANA maintains the CAPWAP Message Types registry for all message types whose Enterprise Number is set to zero (0) 🗂️ The namespace is 8 bits (0-255), and the value zero (0) is reserved and must not be assigned 🙅♀️ Values one (1) through 26 are allocated in this spec, and you can find them in Section 4.5.1.1 🔥 Any new assignment of a CAPWAP Message Type whose Enterprise Number is set to zero (0) requires an Expert Review 🧑⚖️ The registry format looks like this:
CAPWAP Control Message Message Type Reference
Value15.5. CAPWAP Header Flags
The Flags field in the CAPWAP Header (see Section 4.3) is 9 bits long and identifies any special treatment for the message 🚩 This spec defines bits zero (0) through five (5), while bits six (6) through eight (8) are reserved 🫧 Three reserved bits are unused right now, and IANA manages them, with assignments requiring an Expert Review 🔒 IANA created the CAPWAP Header Flags registry, and its format is:
Flag Field Name Bit Position Reference15.6. CAPWAP Control Message Flags
The Flags field in the CAPWAP Control Message header (see Section 4.5.1.4) identifies any special treatment for the control message 🎯 There are currently eight (8) unused, reserved bits 🌙 IANA manages their assignment, and it requires an Expert Review 🧑⚖️ IANA created the CAPWAP Control Message Flags registry, and its format is:
Flag Field Name Bit Position Reference15.7. CAPWAP Message Element Type
The Type field in the CAPWAP Message Element header (see Section 4.6) identifies the data being carried 📦 The namespace is 16 bits (0-65535), and the value zero (0) is reserved and must not be assigned 🙅♀️ Values one (1) through 53 are allocated in this spec, and you can find them in Section 4.5.1.1 🌟
The 16-bit namespace is split into blocks reserved for specific CAPWAP wireless bindings 🧁 These blocks are reserved:
CAPWAP Protocol Message Elements 1 - 1023
IEEE 802.11 Message Elements 1024 - 2047
EPCGlobal Message Elements 3072 - 4095IANA manages this namespace, and assignments require an Expert Review 🧑⚖️ IANA created the CAPWAP Message Element Type registry, and its format is:
CAPWAP Message Element Type Value Reference15.8. CAPWAP Wireless Binding Identifiers
The Wireless Binding Identifier (WBID) field in the CAPWAP Header (see Section 4.3) identifies the wireless technology a packet is associated with 📶 This spec allocates the values one (1) and three (3) 🎀 Because the address space is limited, a new WBID request requires Expert Review 🧐 IANA created the CAPWAP Wireless Binding Identifier registry, and its format is:
CAPWAP Wireless Binding Identifier Type Value Reference15.9. AC Security Types
The Security field in the AC Descriptor message element (see Section 4.6.1) is 8 bits long and identifies the authentication methods available on the AC 🔐 This spec defines bits five (5) and six (6), while bits zero (0) through four (4) and bit seven (7) are reserved and unused 💜 IANA manages those reserved bits, and assignment requires Standards Action 📜 IANA created the AC Security Types registry, and its format is:
AC Security Type Bit Position Reference15.10. AC DTLS Policy
The DTLS Policy field in the AC Descriptor message element (see Section 4.6.1) is 8 bits long and identifies whether the CAPWAP Data Channel is to be secured 🔒 This spec defines bits five (5) and six (6), while bits zero (0) through four (4) and bit seven (7) are reserved and unused 🫶 IANA manages those reserved bits, and assignment requires Standards Action 📜 IANA created the AC DTLS Policy registry, and its format is:
AC DTLS Policy Bit Position Reference15.11. AC Information Type
The Information Type field in the AC Descriptor message element (see Section 4.6.1) represents information about the AC 🧾 The namespace is 16 bits (0-65535), and the value zero (0) is reserved and must not be assigned 🙅♀️ This field, combined with the AC Information Vendor ID, lets vendors use a private namespace 🌈 This spec defines the AC Information Type namespace when the AC Information Vendor ID is set to zero (0), and values four (4) and five (5) are allocated in this spec, which you can find in Section 4.6.1 ✨ IANA manages this namespace, and assignments require an Expert Review 🧑⚖️ IANA created the AC Information Type registry, and its format is:
AC Information Type Type Value Reference15.12. CAPWAP Transport Protocol Types 🦋
okay so the Transport field in the CAPWAP Transport Protocol message element (see Section 4.6.14) is how you pick the transport for the CAPWAP Data Channel 💖 The namespace is 8 bits (0-255), and the value zero (0) is reserved, so it must not be assigned 🙈 Values one (1) and two (2) are already allocated in this spec, and you can find them in Section 4.6.14. IANA manages this namespace and assignments need an Expert Review. IANA made the CAPWAP Transport Protocol Types registry, and it looks like this:
CAPWAP Transport Protocol Type Type Value Reference15.13. Data Transfer Type ✨
the Data Type field is giving main character energy 👑 It shows up in the Data Transfer Data message element (see Section 4.6.15) and the Image Data message element (see Section 4.6.26), and it tells you what kind of data is being carried. The namespace is 8 bits (0-255), and zero (0) is reserved and must not be assigned. Values one (1), two (2), and five (5) are allocated in this spec, and you can find them in Section 4.6.15. IANA manages this one too, and assignments require an Expert Review. IANA created the Data Transfer Type registry, which looks like:
Data Transfer Type Type Value Reference15.14. Data Transfer Mode 🌸
the Data Mode field is in the Data Transfer Data message element (see Section 4.6.15) and the Data Transfer Mode message element (see Section 15.14), and it's also all about describing the data being carried 🫶 The namespace is 8 bits (0-255), and zero (0) is reserved and must not be assigned. Values one (1) and two (2) are allocated in this spec and can be found in Section 15.14. IANA manages it and assignments require an Expert Review. IANA created the Data Transfer Mode registry:
Data Transfer Mode Type Value Reference15.15. Discovery Types 🧚
the Discovery Type field lives in the Discovery Type message element (see Section 4.6.21), and the WTP uses it to tell the AC how it got discovered 👀 The namespace is 8 bits (0-255). Values zero (0) through four (4) are allocated in this spec and can be found in Section 4.6.21. IANA manages it, and assignments require an Expert Review. IANA created the Discovery Types registry:
Discovery Types Type Value Reference15.16. ECN Support 💜
the ECN Support field is in the ECN Support message element (see Section 4.6.25), and the WTP uses it to show its ECN Support 🌈 The namespace is 8 bits (0-255). Values zero (0) and one (1) are allocated in this spec and can be found in Section 4.6.25. IANA manages this and assignments require an Expert Review. IANA created the ECN Support registry:
ECN Support Type Value Reference15.17. Radio Admin State 🎀
the Radio Admin field sits in the Radio Administrative State message element (see Section 4.6.33), and the WTP uses it to show the state of its radios 📡 The namespace is 8 bits (0-255), and zero (0) is reserved and must not be assigned. Values one (1) and two (2) are allocated in this spec and can be found in Section 4.6.33. IANA manages it and assignments require an Expert Review. IANA created the Radio Admin State registry:
Radio Admin State Type Value Reference15.18. Radio Operational State 💅
the State field is in the Radio Operational State message element (see Section 4.6.34), and it's how the WTP shows the operational state of its radios ⭐ The namespace is 8 bits (0-255), and zero (0) is reserved and must not be assigned. Values one (1) and two (2) are allocated in this spec and can be found in Section 4.6.34. IANA manages it and assignments require an Expert Review. IANA created the Radio Operational State registry:
Radio Operational State Type Value Reference15.19. Radio Failure Causes 💀
the Cause field is in the Radio Operational State message element (see Section 4.6.34), and it tells you why a radio may have failed, which is lowkey important 😭 The namespace is 8 bits (0-255), and the values zero (0) through three (3) are allocated in this spec and can be found in Section 4.6.34. IANA manages this and assignments require an Expert Review. IANA created the Radio Failure Causes registry:
Radio Failure Causes Type Value Reference15.20. Result Code 🔥
the Result Code field is in the Result Code message element (see Section 4.6.35), and it's how you know if a CAPWAP Control message worked or flopped 🙌 The namespace is 32 bits (0-4294967295), and the values zero (0) through 22 are allocated in this spec and can be found in Section 4.6.35. IANA manages this and assignments require an Expert Review. IANA created the Result Code registry:
Result Code Type Value Reference15.21. Returned Message Element Reason 🦋
the Reason field in the Returned Message Element message element (see Section 4.6.36) explains why a message element didn't get processed successfully 💔 The namespace is 8 bits (0-255), and zero (0) is reserved and must not be assigned. Values one (1) through four (4) are allocated in this spec and can be found in Section 4.6.36. IANA manages it and assignments require an Expert Review. IANA created the Returned Message Element Reason registry, which looks like:
Returned Message Element Reason Type Value Reference15.22. WTP Board Data Type 🌷
the Board Data Type field is in the WTP Board Data message element (see Section 4.6.40), and it's all about info on the WTP hardware 🛠️ The namespace is 16 bits (0-65535). The WTP Board Data Type values zero (0) through four (4) are allocated in this spec and can be found in Section 4.6.40. IANA manages this and assignments require an Expert Review. IANA created the WTP Board Data Type registry:
WTP Board Data Type Type Value Reference15.23. WTP Descriptor Type 🧸
the Descriptor Type field is in the WTP Descriptor message element (see Section 4.6.41), and it's how the WTP shares info about its software 💻 The namespace is 16 bits (0-65535). This field, paired with the Descriptor Vendor ID, lets vendors have their own private namespace, which is so iconic 🌈 This spec defines the WTP Descriptor Type namespace when the Descriptor Vendor ID is set to zero (0), and the values zero (0) through three (3) are allocated here and can be found in Section 4.6.41. IANA manages this and assignments require an Expert Review. IANA created the WTP Board Data Type registry, which looks like:
WTP Descriptor Type Type Value Reference15.24. WTP Fallback Mode 🛟
the Mode field is in the WTP Fallback message element (see Section 4.6.42), and it tells the WTP which kind of AC fallback mechanism to use 🔁 The namespace is 8 bits (0-255), and zero (0) is reserved and must not be assigned. Values one (1) and two (2) are allocated in this spec and can be found in Section 4.6.42. IANA manages it and assignments require an Expert Review. IANA created the WTP Fallback Mode registry:
WTP Fallback Mode Type Value Reference15.25. WTP Frame Tunnel Mode 🚇
the Tunnel Type field is 8 bits and sits in the WTP Frame Tunnel Mode message element (see Section 4.6.43), and it picks the type of tunneling between the WTP and the AC ✨ This spec defines bits four (4) through six (6). Bits zero (0) through three (3) as well as bit seven (7) are reserved and unused, and they're managed by IANA, with assignment requiring an Expert Review. IANA created the WTP Frame Tunnel Mode registry:
WTP Frame Tunnel Mode Bit Position Reference15.26. WTP MAC Type 🌙
the MAC Type field is in the WTP MAC Type message element (see Section 4.6.44), and it says which MAC to use for tunneled frames between the WTP and the AC 🫧 The namespace is 8 bits (0-255), and the values zero (0) through two (2) are allocated in this spec and can be found in Section 4.6.44. IANA manages this and assignments require an Expert Review. IANA created the WTP MAC Type registry:
WTP MAC Type Type Value Reference15.27. WTP Radio Stats Failure Type 🍓
the Last Failure Type field is in the WTP Radio Statistics message element (see Section 4.6.46), and it shows the last WTP failure 📉 The namespace is 8 bits (0-255), and the values zero (0) through three (3) as well as the value 255 are allocated in this spec and can be found in Section 4.6.46. IANA manages this and assignments require an Expert Review. IANA created the WTP Radio Stats Failure Type registry:
WTP Radio Stats Failure Type Type Value Reference15.28. WTP Reboot Stats Failure Type 🔄
the Last Failure Type field is in the WTP Reboot Statistics message element (see Section 4.6.47), and it shows the last reboot reason 🔌 The namespace is 8 bits (0-255), and the values zero (0) through five (5) as well as the value 255 are allocated in this spec and can be found in Section 4.6.47. IANA manages this and assignments require an Expert Review. IANA created the WTP Reboot Stats Failure Type registry:
WTP Reboot Stats Failure Type Type Value Reference16. Acknowledgments 🫶
the following people get a big thank-you for their contributions to this protocol spec: Puneet Agarwal, Abhijit Choudhury, Pasi Eronen, Saravanan Govindan, Peter Nilsson, David Perkins, and Yong Zhang 💖
Michael Vakulenko contributed text describing how CAPWAP can be used over Layer 3 (IP/UDP) networks, which is so helpful 🙌
17. References 📚
17.1. Normative References ✨
okay bestie, this is the list of docs this one leans on, so here's every single one, exactly as written 🫶
[RFC1191] Mogul, J. and S. Deering, "Path MTU discovery",
RFC 1191, November 1990.
[RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm",
RFC 1321, April 1992.
[RFC1305] Mills, D., "Network Time Protocol (Version 3)
Specification, Implementation", RFC 1305,
March 1992.
[RFC1981] McCann, J., Deering, S., and J. Mogul, "Path MTU
Discovery for IP version 6", RFC 1981,
August 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to
Indicate Requirement Levels", BCP 14, RFC 2119,
March 1997.
[RFC2460] Deering, S. and R. Hinden, "Internet Protocol,
Version 6 (IPv6) Specification", RFC 2460,
December 1998.
[RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black,
"Definition of the Differentiated Services Field
(DS Field) in the IPv4 and IPv6 Headers",
RFC 2474, December 1998.
[RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS
RR for specifying the location of services (DNS
SRV)", RFC 2782, February 2000.
[RFC3168] Ramakrishnan, K., Floyd, S., and D. Black, "The
Addition of Explicit Congestion Notification (ECN)
to IP", RFC 3168, September 2001.
[RFC3539] Aboba, B. and J. Wood, "Authentication,
Authorization and Accounting (AAA) Transport
Profile", RFC 3539, June 2003.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of
ISO 10646", STD 63, RFC 3629, November 2003.
[RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson,
L-E., and G. Fairhurst, "The Lightweight User
Datagram Protocol (UDP-Lite)", RFC 3828,
July 2004.
[RFC4086] Eastlake, D., Schiller, J., and S. Crocker,
"Randomness Requirements for Security", BCP 106,
RFC 4086, June 2005.
[RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key
Ciphersuites for Transport Layer Security (TLS)",
RFC 4279, December 2005.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer
Security (TLS) Protocol Version 1.2", RFC 5246,
August 2008.
[RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport
Layer Security", RFC 4347, April 2006.
[RFC4821] Mathis, M. and J. Heffner, "Packetization Layer
Path MTU Discovery", RFC 4821, March 2007.
[RFC4963] Heffner, J., Mathis, M., and B. Chandler, "IPv4
Reassembly Errors at High Data Rates", RFC 4963,
July 2007.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for
Writing an IANA Considerations Section in RFCs",
BCP 26, RFC 5226, May 2008.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen,
S., Housley, R., and W. Polk, "Internet X.509
Public Key Infrastructure Certificate and
Certificate Revocation List (CRL) Profile",
RFC 5280, May 2008.
[ISO.9834-1.1993] International Organization for Standardization,
"Procedures for the operation of OSI registration
authorities - part 1: general procedures",
ISO Standard 9834-1, 1993.
[RFC5416] Calhoun, P., Ed., Montemurro, M., Ed., and D.
Stanley, Ed., "Control And Provisioning of
Wireless Access Points (CAPWAP) Protocol Binding
for IEEE 802.11", RFC 5416, March 2009.
[RFC5417] Calhoun, P., "Control And Provisioning of Wireless
Access Points (CAPWAP) Access Controller DHCP
Option", RFC 5417, March 2009.
[FRAME-EXT] IEEE, "IEEE Standard 802.3as-2006", 2005.17.2. Informative References 🌸
these ones are the extra reading, the background stuff that's giving context 📚
[RFC3232] Reynolds, J., "Assigned Numbers: RFC 1700 is
Replaced by an On-line Database", RFC 3232,
January 2002.
[RFC3753] Manner, J. and M. Kojo, "Mobility Related
Terminology", RFC 3753, June 2004.
[RFC4564] Govindan, S., Cheng, H., Yao, ZH., Zhou, WH., and
L. Yang, "Objectives for Control and Provisioning
of Wireless Access Points (CAPWAP)", RFC 4564,
July 2006.
[RFC4962] Housley, R. and B. Aboba, "Guidance for
Authentication, Authorization, and Accounting
(AAA) Key Management", BCP 132, RFC 4962,
July 2007.
[LWAPP] Calhoun, P., O'Hara, B., Suri, R., Cam Winget, N.,
Kelly, S., Williams, M., and S. Hares,
"Lightweight Access Point Protocol", Work in
Progress, March 2007.
[SLAPP] Narasimhan, P., Harkins, D., and S. Ponnuswamy,
"SLAPP: Secure Light Access Point Protocol", Work
in Progress, May 2005.
[DTLS-DESIGN] Modadugu, et al., N., "The Design and
Implementation of Datagram TLS", Feb 2004.
[EUI-48] IEEE, "Guidelines for use of a 48-bit Extended
Unique Identifier", Dec 2005.
[EUI-64] IEEE, "GUIDELINES FOR 64-BIT GLOBAL IDENTIFIER
(EUI-64) REGISTRATION AUTHORITY".
[EPCGlobal] "See http://www.epcglobalinc.org/home".
[PacketCable] "PacketCable Security Specification PKT-SP-SEC-
I12-050812", August 2005, <PacketCable>.
[CableLabs] "OpenCable System Security Specification OC-SP-
SEC-I07-061031", October 2006, <CableLabs>.
[WiMAX] "WiMAX Forum X.509 Device Certificate Profile
Approved Specification V1.0.1", April 2008,
<WiMAX>.
[RFC5418] Kelly, S. and C. Clancy, "Control And Provisioning
for Wireless Access Points (CAPWAP) Threat
Analysis for IEEE 802.11 Deployments", RFC 5418,
March 2009.Editors' Addresses 💅
and finally, who to contact about this one, the editors' details 💖
Pat R. Calhoun (editor)
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134
Phone: +1 408-902-3240
EMail: pcalhoun@cisco.com
Michael P. Montemurro (editor)
Research In Motion
5090 Commerce Blvd
Mississauga, ON L4W 5M4
Canada
Phone: +1 905-629-4746 x4999
EMail: mmontemurro@rim.com
Dorothy Stanley (editor)
Aruba Networks
1322 Crossman Ave
Sunnyvale, CA 94089
Phone: +1 630-363-1389
EMail: dstanley@arubanetworks.com📦 where this page comes from
- ietf: rfc5415 2009-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms