0
# UDP Frame Handling
1

2
SOCKS v5 UDP frame creation and parsing functionality for use with the ASSOCIATE command. This enables UDP data transmission through SOCKS proxies with proper frame encapsulation.
3

4
## Capabilities
5

6
### UDP Frame Creation
7

8
Creates a properly formatted SOCKS v5 UDP frame for transmission through a SOCKS proxy.
9

10
```typescript { .api }
11
/**
12
 * Creates a SOCKS UDP Frame for SOCKS v5 ASSOCIATE command
13
 * @param options - Frame configuration including remote host and data
14
 * @returns Buffer containing the formatted UDP frame
15
 */
16
static createUDPFrame(options: SocksUDPFrameDetails): Buffer;
17

18
interface SocksUDPFrameDetails {
19
  /** Frame number identifier (optional) */
20
  frameNumber?: number;
21
  /** Remote host information (destination) */
22
  remoteHost: SocksRemoteHost;
23
  /** UDP packet data to encapsulate */
24
  data: Buffer;
25
}
26

27
interface SocksRemoteHost {
28
  /** IPv4, IPv6 address, or hostname */
29
  host: string;
30
  /** Port number (0-65535) */
31
  port: number;
32
}
33
```
34

35
**Usage Example:**
36

37
```typescript
38
import { SocksClient } from "socks";
39

40
const udpData = Buffer.from("Hello UDP!");
41
const frame = SocksClient.createUDPFrame({
42
  frameNumber: 1,
43
  remoteHost: {
44
    host: "example.com",
45
    port: 53
46
  },
47
  data: udpData
48
});
49

50
// Send frame through established ASSOCIATE connection
51
associateSocket.write(frame);
52
```
53

54
### UDP Frame Parsing
55

56
Parses a received SOCKS v5 UDP frame to extract the remote host information and data payload.
57

58
```typescript { .api }
59
/**
60
 * Parses a SOCKS UDP frame received from a SOCKS proxy
61
 * @param data - Buffer containing the UDP frame data
62
 * @returns Parsed frame details including remote host and payload
63
 */
64
static parseUDPFrame(data: Buffer): SocksUDPFrameDetails;
65
```
66

67
**Usage Example:**
68

69
```typescript
70
import { SocksClient } from "socks";
71

72
// Receive UDP frame from SOCKS proxy
73
associateSocket.on('data', (frameData: Buffer) => {
74
  const parsedFrame = SocksClient.parseUDPFrame(frameData);
75
  
76
  console.log('Frame number:', parsedFrame.frameNumber);
77
  console.log('From:', parsedFrame.remoteHost.host, ':', parsedFrame.remoteHost.port);
78
  console.log('Data:', parsedFrame.data.toString());
79
});
80
```
81

82
## UDP Frame Structure
83

84
SOCKS v5 UDP frames follow this binary structure:
85

86
```
87
+------+------+------+----------+----------+----------+
88
| RSV  | FRAG | ATYP | DST.ADDR | DST.PORT |   DATA   |
89
+------+------+------+----------+----------+----------+
90
|  2   |  1   |  1   | Variable |    2     | Variable |
91
+------+------+------+----------+----------+----------+
92
```
93

94
- **RSV (2 bytes)**: Reserved, must be 0x0000
95
- **FRAG (1 byte)**: Fragment number (frameNumber parameter)
96
- **ATYP (1 byte)**: Address type (IPv4=0x01, Hostname=0x03, IPv6=0x04)
97
- **DST.ADDR (Variable)**: Destination address
98
- **DST.PORT (2 bytes)**: Destination port in network byte order
99
- **DATA (Variable)**: UDP payload data
100

101
## Address Type Handling
102

103
The frame creation and parsing automatically handles different address types:
104

105
- **IPv4 addresses**: Encoded as 4-byte binary representation
106
- **IPv6 addresses**: Encoded as 16-byte binary representation  
107
- **Hostnames**: Encoded as length-prefixed strings (max 255 bytes)
108

109
## Complete ASSOCIATE Example
110

111
```typescript
112
import { SocksClient } from "socks";
113

114
// Establish ASSOCIATE connection
115
const info = await SocksClient.createConnection({
116
  proxy: {
117
    host: '127.0.0.1',
118
    port: 1080,
119
    type: 5
120
  },
121
  command: 'associate',
122
  destination: {
123
    host: '0.0.0.0',  // Placeholder for UDP
124
    port: 0
125
  }
126
});
127

128
const udpSocket = info.socket;
129

130
// Create and send UDP frame
131
const frame = SocksClient.createUDPFrame({
132
  frameNumber: 1,
133
  remoteHost: {
134
    host: "8.8.8.8",
135
    port: 53
136
  },
137
  data: Buffer.from([/* DNS query bytes */])
138
});
139

140
udpSocket.write(frame);
141

142
// Parse received UDP frames
143
udpSocket.on('data', (data: Buffer) => {
144
  const parsedFrame = SocksClient.parseUDPFrame(data);
145
  console.log('UDP response from:', parsedFrame.remoteHost.host);
146
  // Process parsedFrame.data
147
});
148
```