~ubuntu-branches/ubuntu/trusty/dante/trusty-proposed : revision 5

1

2

3

4

5

6

7

Network Working Group M. Leech

8

Request for Comments: 1928 Bell-Northern Research Ltd

9

Category: Standards Track M. Ganis

10

International Business Machines

11

Y. Lee

12

NEC Systems Laboratory

13

R. Kuris

14

Unify Corporation

15

D. Koblas

16

Independent Consultant

17

L. Jones

18

Hewlett-Packard Company

19

March 1996

20

21

22

SOCKS Protocol Version 5

23

24

Status of this Memo

25

26

This document specifies an Internet standards track protocol for the

27

Internet community, and requests discussion and suggestions for

28

improvements. Please refer to the current edition of the "Internet

29

Official Protocol Standards" (STD 1) for the standardization state

30

and status of this protocol. Distribution of this memo is unlimited.

31

32

Acknowledgments

33

34

This memo describes a protocol that is an evolution of the previous

35

version of the protocol, version 4 [1]. This new protocol stems from

36

active discussions and prototype implementations. The key

37

contributors are: Marcus Leech: Bell-Northern Research, David Koblas:

38

Independent Consultant, Ying-Da Lee: NEC Systems Laboratory, LaMont

39

Jones: Hewlett-Packard Company, Ron Kuris: Unify Corporation, Matt

40

Ganis: International Business Machines.

41

42

1. Introduction

43

44

The use of network firewalls, systems that effectively isolate an

45

organizations internal network structure from an exterior network,

46

such as the INTERNET is becoming increasingly popular. These

47

firewall systems typically act as application-layer gateways between

48

networks, usually offering controlled TELNET, FTP, and SMTP access.

49

With the emergence of more sophisticated application layer protocols

50

designed to facilitate global information discovery, there exists a

51

need to provide a general framework for these protocols to

52

transparently and securely traverse a firewall.

53

54

55

56

57

58

Leech, et al Standards Track [Page 1]

59

60

RFC 1928 SOCKS Protocol Version 5 March 1996

61

62

63

There exists, also, a need for strong authentication of such

64

traversal in as fine-grained a manner as is practical. This

65

requirement stems from the realization that client-server

66

relationships emerge between the networks of various organizations,

67

and that such relationships need to be controlled and often strongly

68

authenticated.

69

70

The protocol described here is designed to provide a framework for

71

client-server applications in both the TCP and UDP domains to

72

conveniently and securely use the services of a network firewall.

73

The protocol is conceptually a "shim-layer" between the application

74

layer and the transport layer, and as such does not provide network-

75

layer gateway services, such as forwarding of ICMP messages.

76

77

2. Existing practice

78

79

There currently exists a protocol, SOCKS Version 4, that provides for

80

unsecured firewall traversal for TCP-based client-server

81

applications, including TELNET, FTP and the popular information-

82

discovery protocols such as HTTP, WAIS and GOPHER.

83

84

This new protocol extends the SOCKS Version 4 model to include UDP,

85

and extends the framework to include provisions for generalized

86

strong authentication schemes, and extends the addressing scheme to

87

encompass domain-name and V6 IP addresses.

88

89

The implementation of the SOCKS protocol typically involves the

90

recompilation or relinking of TCP-based client applications to use

91

the appropriate encapsulation routines in the SOCKS library.

92

93

Note:

94

95

Unless otherwise noted, the decimal numbers appearing in packet-

96

format diagrams represent the length of the corresponding field, in

97

octets. Where a given octet must take on a specific value, the

98

syntax X'hh' is used to denote the value of the single octet in that

99

field. When the word 'Variable' is used, it indicates that the

100

corresponding field has a variable length defined either by an

101

associated (one or two octet) length field, or by a data type field.

102

103

3. Procedure for TCP-based clients

104

105

When a TCP-based client wishes to establish a connection to an object

106

that is reachable only via a firewall (such determination is left up

107

to the implementation), it must open a TCP connection to the

108

appropriate SOCKS port on the SOCKS server system. The SOCKS service

109

is conventionally located on TCP port 1080. If the connection

110

request succeeds, the client enters a negotiation for the

111

112

113

114

Leech, et al Standards Track [Page 2]

115

116

RFC 1928 SOCKS Protocol Version 5 March 1996

117

118

119

authentication method to be used, authenticates with the chosen

120

method, then sends a relay request. The SOCKS server evaluates the

121

request, and either establishes the appropriate connection or denies

122

it.

123

124

Unless otherwise noted, the decimal numbers appearing in packet-

125

format diagrams represent the length of the corresponding field, in

126

octets. Where a given octet must take on a specific value, the

127

syntax X'hh' is used to denote the value of the single octet in that

128

field. When the word 'Variable' is used, it indicates that the

129

corresponding field has a variable length defined either by an

130

associated (one or two octet) length field, or by a data type field.

131

132

The client connects to the server, and sends a version

133

identifier/method selection message:

134

135

+----+----------+----------+

136

|VER | NMETHODS | METHODS |

137

+----+----------+----------+

138

| 1 | 1 | 1 to 255 |

139

+----+----------+----------+

140

141

The VER field is set to X'05' for this version of the protocol. The

142

NMETHODS field contains the number of method identifier octets that

143

appear in the METHODS field.

144

145

The server selects from one of the methods given in METHODS, and

146

sends a METHOD selection message:

147

148

+----+--------+

149

|VER | METHOD |

150

+----+--------+

151

| 1 | 1 |

152

+----+--------+

153

154

If the selected METHOD is X'FF', none of the methods listed by the

155

client are acceptable, and the client MUST close the connection.

156

157

The values currently defined for METHOD are:

158

159

o X'00' NO AUTHENTICATION REQUIRED

160

o X'01' GSSAPI

161

o X'02' USERNAME/PASSWORD

162

o X'03' to X'7F' IANA ASSIGNED

163

o X'80' to X'FE' RESERVED FOR PRIVATE METHODS

164

o X'FF' NO ACCEPTABLE METHODS

165

166

The client and server then enter a method-specific sub-negotiation.

167

168

169

170

Leech, et al Standards Track [Page 3]

171

172

RFC 1928 SOCKS Protocol Version 5 March 1996

173

174

175

Descriptions of the method-dependent sub-negotiations appear in

176

separate memos.

177

178

Developers of new METHOD support for this protocol should contact

179

IANA for a METHOD number. The ASSIGNED NUMBERS document should be

180

referred to for a current list of METHOD numbers and their

181

corresponding protocols.

182

183

Compliant implementations MUST support GSSAPI and SHOULD support

184

USERNAME/PASSWORD authentication methods.

185

186

4. Requests

187

188

Once the method-dependent subnegotiation has completed, the client

189

sends the request details. If the negotiated method includes

190

encapsulation for purposes of integrity checking and/or

191

confidentiality, these requests MUST be encapsulated in the method-

192

dependent encapsulation.

193

194

The SOCKS request is formed as follows:

195

196

+----+-----+-------+------+----------+----------+

197

|VER | CMD | RSV | ATYP | DST.ADDR | DST.PORT |

198

+----+-----+-------+------+----------+----------+

199

| 1 | 1 | X'00' | 1 | Variable | 2 |

200

+----+-----+-------+------+----------+----------+

201

202

Where:

203

204

o VER protocol version: X'05'

205

o CMD

206

o CONNECT X'01'

207

o BIND X'02'

208

o UDP ASSOCIATE X'03'

209

o RSV RESERVED

210

o ATYP address type of following address

211

o IP V4 address: X'01'

212

o DOMAINNAME: X'03'

213

o IP V6 address: X'04'

214

o DST.ADDR desired destination address

215

o DST.PORT desired destination port in network octet

216

order

217

218

The SOCKS server will typically evaluate the request based on source

219

and destination addresses, and return one or more reply messages, as

220

appropriate for the request type.

221

222

223

224

225

226

Leech, et al Standards Track [Page 4]

227

228

RFC 1928 SOCKS Protocol Version 5 March 1996

229

230

231

5. Addressing

232

233

In an address field (DST.ADDR, BND.ADDR), the ATYP field specifies

234

the type of address contained within the field:

235

236

o X'01'

237

238

the address is a version-4 IP address, with a length of 4 octets

239

240

o X'03'

241

242

the address field contains a fully-qualified domain name. The first

243

octet of the address field contains the number of octets of name that

244

follow, there is no terminating NUL octet.

245

246

o X'04'

247

248

the address is a version-6 IP address, with a length of 16 octets.

249

250

6. Replies

251

252

The SOCKS request information is sent by the client as soon as it has

253

established a connection to the SOCKS server, and completed the

254

authentication negotiations. The server evaluates the request, and

255

returns a reply formed as follows:

256

257

+----+-----+-------+------+----------+----------+

258

|VER | REP | RSV | ATYP | BND.ADDR | BND.PORT |

259

+----+-----+-------+------+----------+----------+

260

| 1 | 1 | X'00' | 1 | Variable | 2 |

261

+----+-----+-------+------+----------+----------+

262

263

Where:

264

265

o VER protocol version: X'05'

266

o REP Reply field:

267

o X'00' succeeded

268

o X'01' general SOCKS server failure

269

o X'02' connection not allowed by ruleset

270

o X'03' Network unreachable

271

o X'04' Host unreachable

272

o X'05' Connection refused

273

o X'06' TTL expired

274

o X'07' Command not supported

275

o X'08' Address type not supported

276

o X'09' to X'FF' unassigned

277

o RSV RESERVED

278

o ATYP address type of following address

279

280

281

282

Leech, et al Standards Track [Page 5]

283

284

RFC 1928 SOCKS Protocol Version 5 March 1996

285

286

287

o IP V4 address: X'01'

288

o DOMAINNAME: X'03'

289

o IP V6 address: X'04'

290

o BND.ADDR server bound address

291

o BND.PORT server bound port in network octet order

292

293

Fields marked RESERVED (RSV) must be set to X'00'.

294

295

If the chosen method includes encapsulation for purposes of

296

authentication, integrity and/or confidentiality, the replies are

297

encapsulated in the method-dependent encapsulation.

298

299

CONNECT

300

301

In the reply to a CONNECT, BND.PORT contains the port number that the

302

server assigned to connect to the target host, while BND.ADDR

303

contains the associated IP address. The supplied BND.ADDR is often

304

different from the IP address that the client uses to reach the SOCKS

305

server, since such servers are often multi-homed. It is expected

306

that the SOCKS server will use DST.ADDR and DST.PORT, and the

307

client-side source address and port in evaluating the CONNECT

308

request.

309

310

BIND

311

312

The BIND request is used in protocols which require the client to

313

accept connections from the server. FTP is a well-known example,

314

which uses the primary client-to-server connection for commands and

315

status reports, but may use a server-to-client connection for

316

transferring data on demand (e.g. LS, GET, PUT).

317

318

It is expected that the client side of an application protocol will

319

use the BIND request only to establish secondary connections after a

320

primary connection is established using CONNECT. In is expected that

321

a SOCKS server will use DST.ADDR and DST.PORT in evaluating the BIND

322

request.

323

324

Two replies are sent from the SOCKS server to the client during a

325

BIND operation. The first is sent after the server creates and binds

326

a new socket. The BND.PORT field contains the port number that the

327

SOCKS server assigned to listen for an incoming connection. The

328

BND.ADDR field contains the associated IP address. The client will

329

typically use these pieces of information to notify (via the primary

330

or control connection) the application server of the rendezvous

331

address. The second reply occurs only after the anticipated incoming

332

connection succeeds or fails.

333

334

335

336

337

338

Leech, et al Standards Track [Page 6]

339

340

RFC 1928 SOCKS Protocol Version 5 March 1996

341

342

343

In the second reply, the BND.PORT and BND.ADDR fields contain the

344

address and port number of the connecting host.

345

346

UDP ASSOCIATE

347

348

The UDP ASSOCIATE request is used to establish an association within

349

the UDP relay process to handle UDP datagrams. The DST.ADDR and

350

DST.PORT fields contain the address and port that the client expects

351

to use to send UDP datagrams on for the association. The server MAY

352

use this information to limit access to the association. If the

353

client is not in possesion of the information at the time of the UDP

354

ASSOCIATE, the client MUST use a port number and address of all

355

zeros.

356

357

A UDP association terminates when the TCP connection that the UDP

358

ASSOCIATE request arrived on terminates.

359

360

In the reply to a UDP ASSOCIATE request, the BND.PORT and BND.ADDR

361

fields indicate the port number/address where the client MUST send

362

UDP request messages to be relayed.

363

364

Reply Processing

365

366

When a reply (REP value other than X'00') indicates a failure, the

367

SOCKS server MUST terminate the TCP connection shortly after sending

368

the reply. This must be no more than 10 seconds after detecting the

369

condition that caused a failure.

370

371

If the reply code (REP value of X'00') indicates a success, and the

372

request was either a BIND or a CONNECT, the client may now start

373

passing data. If the selected authentication method supports

374

encapsulation for the purposes of integrity, authentication and/or

375

confidentiality, the data are encapsulated using the method-dependent

376

encapsulation. Similarly, when data arrives at the SOCKS server for

377

the client, the server MUST encapsulate the data as appropriate for

378

the authentication method in use.

379

380

7. Procedure for UDP-based clients

381

382

A UDP-based client MUST send its datagrams to the UDP relay server at

383

the UDP port indicated by BND.PORT in the reply to the UDP ASSOCIATE

384

request. If the selected authentication method provides

385

encapsulation for the purposes of authenticity, integrity, and/or

386

confidentiality, the datagram MUST be encapsulated using the

387

appropriate encapsulation. Each UDP datagram carries a UDP request

388

header with it:

389

390

391

392

393

394

Leech, et al Standards Track [Page 7]

395

396

RFC 1928 SOCKS Protocol Version 5 March 1996

397

398

399

+----+------+------+----------+----------+----------+

400

401

+----+------+------+----------+----------+----------+

402

| 2 | 1 | 1 | Variable | 2 | Variable |

403

+----+------+------+----------+----------+----------+

404

405

The fields in the UDP request header are:

406

407

o RSV Reserved X'0000'

408

o FRAG Current fragment number

409

o ATYP address type of following addresses:

410

o IP V4 address: X'01'

411

o DOMAINNAME: X'03'

412

o IP V6 address: X'04'

413

o DST.ADDR desired destination address

414

o DST.PORT desired destination port

415

o DATA user data

416

417

When a UDP relay server decides to relay a UDP datagram, it does so

418

silently, without any notification to the requesting client.

419

Similarly, it will drop datagrams it cannot or will not relay. When

420

a UDP relay server receives a reply datagram from a remote host, it

421

MUST encapsulate that datagram using the above UDP request header,

422

and any authentication-method-dependent encapsulation.

423

424

The UDP relay server MUST acquire from the SOCKS server the expected

425

IP address of the client that will send datagrams to the BND.PORT

426

given in the reply to UDP ASSOCIATE. It MUST drop any datagrams

427

arriving from any source IP address other than the one recorded for

428

the particular association.

429

430

The FRAG field indicates whether or not this datagram is one of a

431

number of fragments. If implemented, the high-order bit indicates

432

end-of-fragment sequence, while a value of X'00' indicates that this

433

datagram is standalone. Values between 1 and 127 indicate the

434

fragment position within a fragment sequence. Each receiver will

435

have a REASSEMBLY QUEUE and a REASSEMBLY TIMER associated with these

436

fragments. The reassembly queue must be reinitialized and the

437

associated fragments abandoned whenever the REASSEMBLY TIMER expires,

438

or a new datagram arrives carrying a FRAG field whose value is less

439

than the highest FRAG value processed for this fragment sequence.

440

The reassembly timer MUST be no less than 5 seconds. It is

441

recommended that fragmentation be avoided by applications wherever

442

possible.

443

444

Implementation of fragmentation is optional; an implementation that

445

does not support fragmentation MUST drop any datagram whose FRAG

446

field is other than X'00'.

447

448

449

450

Leech, et al Standards Track [Page 8]

451

452

RFC 1928 SOCKS Protocol Version 5 March 1996

453

454

455

The programming interface for a SOCKS-aware UDP MUST report an

456

available buffer space for UDP datagrams that is smaller than the

457

actual space provided by the operating system:

458

459

o if ATYP is X'01' - 10+method_dependent octets smaller

460

o if ATYP is X'03' - 262+method_dependent octets smaller

461

o if ATYP is X'04' - 20+method_dependent octets smaller

462

463

8. Security Considerations

464

465

This document describes a protocol for the application-layer

466

traversal of IP network firewalls. The security of such traversal is

467

highly dependent on the particular authentication and encapsulation

468

methods provided in a particular implementation, and selected during

469

negotiation between SOCKS client and SOCKS server.

470

471

Careful consideration should be given by the administrator to the

472

selection of authentication methods.

473

474

9. References

475

476

[1] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Security Symposium.

477

478

Author's Address

479

480

Marcus Leech

481

Bell-Northern Research Ltd

482

P.O. Box 3511, Stn. C,

483

Ottawa, ON

484

CANADA K1Y 4H7

485

486

Phone: (613) 763-9145

487

EMail: mleech@bnr.ca

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

Leech, et al Standards Track [Page 9]

507