Implementing Advanced Extensions
1. Implementing Custom Extension
| Step | Detail |
|---|
| Naming | Reverse DNS, e.g. com.example.encrypt |
| Negotiate | Server echoes back from offer |
| Transform | Modify payload on send/recv |
| Inverse | Symmetric on peer |
Warning: Browsers do not support custom WS extensions — only server-to-server (Node, Java, etc.) can.
| Bit | Use |
|---|
| RSV1 | permessage-deflate flag |
| RSV2/RSV3 | Reserved for ext use |
| Opcode | Must remain spec-defined |
| Transform | Example |
|---|
| Compression | deflate / brotli |
| Encryption | AES-GCM per frame |
| Encoding swap | JSON → msgpack |
| Signing | HMAC append |
4. Negotiating Extension Parameters
Example: Extension offer with params
Sec-WebSocket-Extensions: com.example.encrypt; alg=AES-GCM; kid=42, permessage-deflate
// server selects
Sec-WebSocket-Extensions: com.example.encrypt; alg=AES-GCM; kid=42
| Token | Detail |
|---|
| name | Extension identifier |
| param=value | Configuration |
| ; separator | Between params |
| , separator | Between extensions |
5. Handling Extension Conflicts
| Conflict | Resolution |
|---|
| Two use RSV1 | Server picks one only |
| Order matters | Define apply / reverse order |
| Incompatible | Reject one in negotiation |
6. Implementing Custom Framing
Note: Custom framing on top of WS frames (not modifying WS frames). Use TLV with opcodes for app-level multiplexing.
| Element | Width |
|---|
| Stream ID | 2-4 bytes |
| Type | 1 byte |
| Flags | 1 byte (END_STREAM, etc.) |
| Length | 2-4 bytes |
| Payload | variable |
7. Testing Extension Compatibility
| Test | Detail |
|---|
| Both peers support | Round-trip successful |
| One unsupported | Falls back gracefully |
| Param mismatch | Server picks compatible set |
| Frame corruption | Close 1002 |
8. Documenting Extension Behavior
| Section | Contents |
|---|
| Name + version | Identifier scheme |
| Negotiation | Headers exchanged |
| Frame transform | Apply / reverse |
| Errors | Failure modes + close codes |
| Interactions | Compat with permessage-deflate |
9. Versioning Extensions
| Strategy | Detail |
|---|
| Suffix in name | com.x.encrypt.v2 |
| Param version | ; v=2 |
| Multiple offers | Server picks newest both support |
10. Understanding Extension Security
| Risk | Mitigation |
|---|
| Compression oracle | Avoid mixing secret + attacker data (CRIME-style) |
| Custom crypto pitfalls | Use vetted libs (libsodium) |
| Replay | Nonce / counter in frame |
| Downgrade | Server enforces required extension |