-
Notifications
You must be signed in to change notification settings - Fork 0
/
rfc3489.txt
2635 lines (1859 loc) · 115 KB
/
rfc3489.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Network Working Group J. Rosenberg
Request for Comments: 3489 J. Weinberger
Category: Standards Track dynamicsoft
C. Huitema
Microsoft
R. Mahy
Cisco
March 2003
STUN - Simple Traversal of User Datagram Protocol (UDP)
Through Network Address Translators (NATs)
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved.
Abstract
Simple Traversal of User Datagram Protocol (UDP) Through Network
Address Translators (NATs) (STUN) is a lightweight protocol that
allows applications to discover the presence and types of NATs and
firewalls between them and the public Internet. It also provides the
ability for applications to determine the public Internet Protocol
(IP) addresses allocated to them by the NAT. STUN works with many
existing NATs, and does not require any special behavior from them.
As a result, it allows a wide variety of applications to work through
existing NAT infrastructure.
Table of Contents
1. Applicability Statement ................................... 3
2. Introduction .............................................. 3
3. Terminology ............................................... 4
4. Definitions ............................................... 5
5. NAT Variations ............................................ 5
6. Overview of Operation ..................................... 6
7. Message Overview .......................................... 8
8. Server Behavior ........................................... 10
8.1 Binding Requests .................................... 10
Rosenberg, et al. Standards Track [Page 1]
RFC 3489 STUN March 2003
8.2 Shared Secret Requests .............................. 13
9. Client Behavior ........................................... 14
9.1 Discovery ........................................... 15
9.2 Obtaining a Shared Secret ........................... 15
9.3 Formulating the Binding Request ..................... 17
9.4 Processing Binding Responses ........................ 17
10. Use Cases ................................................. 19
10.1 Discovery Process ................................... 19
10.2 Binding Lifetime Discovery .......................... 21
10.3 Binding Acquisition ................................. 23
11. Protocol Details .......................................... 24
11.1 Message Header ...................................... 25
11.2 Message Attributes .................................. 26
11.2.1 MAPPED-ADDRESS .............................. 27
11.2.2 RESPONSE-ADDRESS ............................ 27
11.2.3 CHANGED-ADDRESS ............................. 28
11.2.4 CHANGE-REQUEST .............................. 28
11.2.5 SOURCE-ADDRESS .............................. 28
11.2.6 USERNAME .................................... 28
11.2.7 PASSWORD .................................... 29
11.2.8 MESSAGE-INTEGRITY ........................... 29
11.2.9 ERROR-CODE .................................. 29
11.2.10 UNKNOWN-ATTRIBUTES .......................... 31
11.2.11 REFLECTED-FROM .............................. 31
12. Security Considerations ................................... 31
12.1 Attacks on STUN ..................................... 31
12.1.1 Attack I: DDOS Against a Target ............. 32
12.1.2 Attack II: Silencing a Client ............... 32
12.1.3 Attack III: Assuming the Identity of a Client 32
12.1.4 Attack IV: Eavesdropping .................... 33
12.2 Launching the Attacks ............................... 33
12.2.1 Approach I: Compromise a Legitimate
STUN Server ................................. 33
12.2.2 Approach II: DNS Attacks .................... 34
12.2.3 Approach III: Rogue Router or NAT ........... 34
12.2.4 Approach IV: MITM ........................... 35
12.2.5 Approach V: Response Injection Plus DoS ..... 35
12.2.6 Approach VI: Duplication .................... 35
12.3 Countermeasures ..................................... 36
12.4 Residual Threats .................................... 37
13. IANA Considerations ....................................... 38
14. IAB Considerations ........................................ 38
14.1 Problem Definition .................................. 38
14.2 Exit Strategy ....................................... 39
14.3 Brittleness Introduced by STUN ...................... 40
14.4 Requirements for a Long Term Solution ............... 42
14.5 Issues with Existing NAPT Boxes ..................... 43
14.6 In Closing .......................................... 43
Rosenberg, et al. Standards Track [Page 2]
RFC 3489 STUN March 2003
15. Acknowledgments ........................................... 44
16. Normative References ...................................... 44
17. Informative References .................................... 44
18. Authors' Addresses ........................................ 46
19. Full Copyright Statement................................... 47
1. Applicability Statement
This protocol is not a cure-all for the problems associated with NAT.
It does not enable incoming TCP connections through NAT. It allows
incoming UDP packets through NAT, but only through a subset of
existing NAT types. In particular, STUN does not enable incoming UDP
packets through symmetric NATs (defined below), which are common in
large enterprises. STUN's discovery procedures are based on
assumptions on NAT treatment of UDP; such assumptions may prove
invalid down the road as new NAT devices are deployed. STUN does not
work when it is used to obtain an address to communicate with a peer
which happens to be behind the same NAT. STUN does not work when the
STUN server is not in a common shared address realm. For a more
complete discussion of the limitations of STUN, see Section 14.
2. Introduction
Network Address Translators (NATs), while providing many benefits,
also come with many drawbacks. The most troublesome of those
drawbacks is the fact that they break many existing IP applications,
and make it difficult to deploy new ones. Guidelines have been
developed [8] that describe how to build "NAT friendly" protocols,
but many protocols simply cannot be constructed according to those
guidelines. Examples of such protocols include almost all peer-to-
peer protocols, such as multimedia communications, file sharing and
games.
To combat this problem, Application Layer Gateways (ALGs) have been
embedded in NATs. ALGs perform the application layer functions
required for a particular protocol to traverse a NAT. Typically,
this involves rewriting application layer messages to contain
translated addresses, rather than the ones inserted by the sender of
the message. ALGs have serious limitations, including scalability,
reliability, and speed of deploying new applications. To resolve
these problems, the Middlebox Communications (MIDCOM) protocol is
being developed [9]. MIDCOM allows an application entity, such as an
end client or network server of some sort (like a Session Initiation
Protocol (SIP) proxy [10]) to control a NAT (or firewall), in order
to obtain NAT bindings and open or close pinholes. In this way, NATs
and applications can be separated once more, eliminating the need for
embedding ALGs in NATs, and resolving the limitations imposed by
current architectures.
Rosenberg, et al. Standards Track [Page 3]
RFC 3489 STUN March 2003
Unfortunately, MIDCOM requires upgrades to existing NAT and
firewalls, in addition to application components. Complete upgrades
of these NAT and firewall products will take a long time, potentially
years. This is due, in part, to the fact that the deployers of NAT
and firewalls are not the same people who are deploying and using
applications. As a result, the incentive to upgrade these devices
will be low in many cases. Consider, for example, an airport
Internet lounge that provides access with a NAT. A user connecting
to the NATed network may wish to use a peer-to-peer service, but
cannot, because the NAT doesn't support it. Since the administrators
of the lounge are not the ones providing the service, they are not
motivated to upgrade their NAT equipment to support it, using either
an ALG, or MIDCOM.
Another problem is that the MIDCOM protocol requires that the agent
controlling the middleboxes know the identity of those middleboxes,
and have a relationship with them which permits control. In many
configurations, this will not be possible. For example, many cable
access providers use NAT in front of their entire access network.
This NAT could be in addition to a residential NAT purchased and
operated by the end user. The end user will probably not have a
control relationship with the NAT in the cable access network, and
may not even know of its existence.
Many existing proprietary protocols, such as those for online games
(such as the games described in RFC 3027 [11]) and Voice over IP,
have developed tricks that allow them to operate through NATs without
changing those NATs. This document is an attempt to take some of
those ideas, and codify them into an interoperable protocol that can
meet the needs of many applications.
The protocol described here, Simple Traversal of UDP Through NAT
(STUN), allows entities behind a NAT to first discover the presence
of a NAT and the type of NAT, and then to learn the addresses
bindings allocated by the NAT. STUN requires no changes to NATs, and
works with an arbitrary number of NATs in tandem between the
application entity and the public Internet.
3. Terminology
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119
[1] and indicate requirement levels for compliant STUN
implementations.
Rosenberg, et al. Standards Track [Page 4]
RFC 3489 STUN March 2003
4. Definitions
STUN Client: A STUN client (also just referred to as a client)
is an entity that generates STUN requests. A STUN client can
execute on an end system, such as a user's PC, or can run in a
network element, such as a conferencing server.
STUN Server: A STUN Server (also just referred to as a server)
is an entity that receives STUN requests, and sends STUN
responses. STUN servers are generally attached to the public
Internet.
5. NAT Variations
It is assumed that the reader is familiar with NATs. It has been
observed that NAT treatment of UDP varies among implementations. The
four treatments observed in implementations are:
Full Cone: A full cone NAT is one where all requests from the
same internal IP address and port are mapped to the same external
IP address and port. Furthermore, any external host can send a
packet to the internal host, by sending a packet to the mapped
external address.
Restricted Cone: A restricted cone NAT is one where all requests
from the same internal IP address and port are mapped to the same
external IP address and port. Unlike a full cone NAT, an external
host (with IP address X) can send a packet to the internal host
only if the internal host had previously sent a packet to IP
address X.
Port Restricted Cone: A port restricted cone NAT is like a
restricted cone NAT, but the restriction includes port numbers.
Specifically, an external host can send a packet, with source IP
address X and source port P, to the internal host only if the
internal host had previously sent a packet to IP address X and
port P.
Symmetric: A symmetric NAT is one where all requests from the
same internal IP address and port, to a specific destination IP
address and port, are mapped to the same external IP address and
port. If the same host sends a packet with the same source
address and port, but to a different destination, a different
mapping is used. Furthermore, only the external host that
receives a packet can send a UDP packet back to the internal host.
Rosenberg, et al. Standards Track [Page 5]
RFC 3489 STUN March 2003
Determining the type of NAT is important in many cases. Depending on
what the application wants to do, it may need to take the particular
behavior into account.
6. Overview of Operation
This section is descriptive only. Normative behavior is described in
Sections 8 and 9.
/-----\
// STUN \\
| Server |
\\ //
\-----/
+--------------+ Public Internet
................| NAT 2 |.......................
+--------------+
+--------------+ Private NET 2
................| NAT 1 |.......................
+--------------+
/-----\
// STUN \\
| Client |
\\ // Private NET 1
\-----/
Figure 1: STUN Configuration
The typical STUN configuration is shown in Figure 1. A STUN client
is connected to private network 1. This network connects to private
network 2 through NAT 1. Private network 2 connects to the public
Internet through NAT 2. The STUN server resides on the public
Internet.
STUN is a simple client-server protocol. A client sends a request to
a server, and the server returns a response. There are two types of
requests - Binding Requests, sent over UDP, and Shared Secret
Requests, sent over TLS [2] over TCP. Shared Secret Requests ask the
server to return a temporary username and password. This username
and password are used in a subsequent Binding Request and Binding
Response, for the purposes of authentication and message integrity.
Rosenberg, et al. Standards Track [Page 6]
RFC 3489 STUN March 2003
Binding requests are used to determine the bindings allocated by
NATs. The client sends a Binding Request to the server, over UDP.
The server examines the source IP address and port of the request,
and copies them into a response that is sent back to the client.
There are some parameters in the request that allow the client to ask
that the response be sent elsewhere, or that the server send the
response from a different address and port. There are attributes for
providing message integrity and authentication.
The trick is using STUN to discover the presence of NAT, and to learn
and use the bindings they allocate.
The STUN client is typically embedded in an application which needs
to obtain a public IP address and port that can be used to receive
data. For example, it might need to obtain an IP address and port to
receive Real Time Transport Protocol (RTP) [12] traffic. When the
application starts, the STUN client within the application sends a
STUN Shared Secret Request to its server, obtains a username and
password, and then sends it a Binding Request. STUN servers can be
discovered through DNS SRV records [3], and it is generally assumed
that the client is configured with the domain to use to find the STUN
server. Generally, this will be the domain of the provider of the
service the application is using (such a provider is incented to
deploy STUN servers in order to allow its customers to use its
application through NAT). Of course, a client can determine the
address or domain name of a STUN server through other means. A STUN
server can even be embedded within an end system.
The STUN Binding Request is used to discover the presence of a NAT,
and to discover the public IP address and port mappings generated by
the NAT. Binding Requests are sent to the STUN server using UDP.
When a Binding Request arrives at the STUN server, it may have passed
through one or more NATs between the STUN client and the STUN server.
As a result, the source address of the request received by the server
will be the mapped address created by the NAT closest to the server.
The STUN server copies that source IP address and port into a STUN
Binding Response, and sends it back to the source IP address and port
of the STUN request. For all of the NAT types above, this response
will arrive at the STUN client.
When the STUN client receives the STUN Binding Response, it compares
the IP address and port in the packet with the local IP address and
port it bound to when the request was sent. If these do not match,
the STUN client is behind one or more NATs. In the case of a full-
cone NAT, the IP address and port in the body of the STUN response
are public, and can be used by any host on the public Internet to
send packets to the application that sent the STUN request. An
application need only listen on the IP address and port from which
Rosenberg, et al. Standards Track [Page 7]
RFC 3489 STUN March 2003
the STUN request was sent. Any packets sent by a host on the public
Internet to the public address and port learned by STUN will be
received by the application.
Of course, the host may not be behind a full-cone NAT. Indeed, it
doesn't yet know what type of NAT it is behind. To determine that,
the client uses additional STUN Binding Requests. The exact
procedure is flexible, but would generally work as follows. The
client would send a second STUN Binding Request, this time to a
different IP address, but from the same source IP address and port.
If the IP address and port in the response are different from those
in the first response, the client knows it is behind a symmetric NAT.
To determine if it's behind a full-cone NAT, the client can send a
STUN Binding Request with flags that tell the STUN server to send a
response from a different IP address and port than the request was
received on. In other words, if the client sent a Binding Request to
IP address/port A/B using a source IP address/port of X/Y, the STUN
server would send the Binding Response to X/Y using source IP
address/port C/D. If the client receives this response, it knows it
is behind a full cone NAT.
STUN also allows the client to ask the server to send the Binding
Response from the same IP address the request was received on, but
with a different port. This can be used to detect whether the client
is behind a port restricted cone NAT or just a restricted cone NAT.
It should be noted that the configuration in Figure 1 is not the only
permissible configuration. The STUN server can be located anywhere,
including within another client. The only requirement is that the
STUN server is reachable by the client, and if the client is trying
to obtain a publicly routable address, that the server reside on the
public Internet.
7. Message Overview
STUN messages are TLV (type-length-value) encoded using big endian
(network ordered) binary. All STUN messages start with a STUN
header, followed by a STUN payload. The payload is a series of STUN
attributes, the set of which depends on the message type. The STUN
header contains a STUN message type, transaction ID, and length. The
message type can be Binding Request, Binding Response, Binding Error
Response, Shared Secret Request, Shared Secret Response, or Shared
Secret Error Response. The transaction ID is used to correlate
requests and responses. The length indicates the total length of the
STUN payload, not including the header. This allows STUN to run over
TCP. Shared Secret Requests are always sent over TCP (indeed, using
TLS over TCP).
Rosenberg, et al. Standards Track [Page 8]
RFC 3489 STUN March 2003
Several STUN attributes are defined. The first is a MAPPED-ADDRESS
attribute, which is an IP address and port. It is always placed in
the Binding Response, and it indicates the source IP address and port
the server saw in the Binding Request. There is also a RESPONSE-
ADDRESS attribute, which contains an IP address and port. The
RESPONSE-ADDRESS attribute can be present in the Binding Request, and
indicates where the Binding Response is to be sent. It's optional,
and when not present, the Binding Response is sent to the source IP
address and port of the Binding Request.
The third attribute is the CHANGE-REQUEST attribute, and it contains
two flags to control the IP address and port used to send the
response. These flags are called "change IP" and "change port"
flags. The CHANGE-REQUEST attribute is allowed only in the Binding
Request. The "change IP" and "change port" flags are useful for
determining whether the client is behind a restricted cone NAT or
restricted port cone NAT. They instruct the server to send the
Binding Responses from a different source IP address and port. The
CHANGE-REQUEST attribute is optional in the Binding Request.
The fourth attribute is the CHANGED-ADDRESS attribute. It is present
in Binding Responses. It informs the client of the source IP address
and port that would be used if the client requested the "change IP"
and "change port" behavior.
The fifth attribute is the SOURCE-ADDRESS attribute. It is only
present in Binding Responses. It indicates the source IP address and
port where the response was sent from. It is useful for detecting
twice NAT configurations.
The sixth attribute is the USERNAME attribute. It is present in a
Shared Secret Response, which provides the client with a temporary
username and password (encoded in the PASSWORD attribute). The
USERNAME is also present in Binding Requests, serving as an index to
the shared secret used for the integrity protection of the Binding
Request. The seventh attribute, PASSWORD, is only found in Shared
Secret Response messages. The eight attribute is the MESSAGE-
INTEGRITY attribute, which contains a message integrity check over
the Binding Request or Binding Response.
The ninth attribute is the ERROR-CODE attribute. This is present in
the Binding Error Response and Shared Secret Error Response. It
indicates the error that has occurred. The tenth attribute is the
UNKNOWN-ATTRIBUTES attribute, which is present in either the Binding
Error Response or Shared Secret Error Response. It indicates the
mandatory attributes from the request which were unknown. The
eleventh attribute is the REFLECTED-FROM attribute, which is present
in Binding Responses. It indicates the IP address and port of the
Rosenberg, et al. Standards Track [Page 9]
RFC 3489 STUN March 2003
sender of a Binding Request, used for traceability purposes to
prevent certain denial-of-service attacks.
8. Server Behavior
The server behavior depends on whether the request is a Binding
Request or a Shared Secret Request.
8.1 Binding Requests
A STUN server MUST be prepared to receive Binding Requests on four
address/port combinations - (A1, P1), (A2, P1), (A1, P2), and (A2,
P2). (A1, P1) represent the primary address and port, and these are
the ones obtained through the client discovery procedures below.
Typically, P1 will be port 3478, the default STUN port. A2 and P2
are arbitrary. A2 and P2 are advertised by the server through the
CHANGED-ADDRESS attribute, as described below.
It is RECOMMENDED that the server check the Binding Request for a
MESSAGE-INTEGRITY attribute. If not present, and the server requires
integrity checks on the request, it generates a Binding Error
Response with an ERROR-CODE attribute with response code 401. If the
MESSAGE-INTEGRITY attribute was present, the server computes the HMAC
over the request as described in Section 11.2.8. The key to use
depends on the shared secret mechanism. If the STUN Shared Secret
Request was used, the key MUST be the one associated with the
USERNAME attribute present in the request. If the USERNAME attribute
was not present, the server MUST generate a Binding Error Response.
The Binding Error Response MUST include an ERROR-CODE attribute with
response code 432. If the USERNAME is present, but the server
doesn't remember the shared secret for that USERNAME (because it
timed out, for example), the server MUST generate a Binding Error
Response. The Binding Error Response MUST include an ERROR-CODE
attribute with response code 430. If the server does know the shared
secret, but the computed HMAC differs from the one in the request,
the server MUST generate a Binding Error Response with an ERROR-CODE
attribute with response code 431. The Binding Error Response is sent
to the IP address and port the Binding Request came from, and sent
from the IP address and port the Binding Request was sent to.
Assuming the message integrity check passed, processing continues.
The server MUST check for any attributes in the request with values
less than or equal to 0x7fff which it does not understand. If it
encounters any, the server MUST generate a Binding Error Response,
and it MUST include an ERROR-CODE attribute with a 420 response code.
Rosenberg, et al. Standards Track [Page 10]
RFC 3489 STUN March 2003
That response MUST contain an UNKNOWN-ATTRIBUTES attribute listing
the attributes with values less than or equal to 0x7fff which were
not understood. The Binding Error Response is sent to the IP address
and port the Binding Request came from, and sent from the IP address
and port the Binding Request was sent to.
Assuming the request was correctly formed, the server MUST generate a
single Binding Response. The Binding Response MUST contain the same
transaction ID contained in the Binding Request. The length in the
message header MUST contain the total length of the message in bytes,
excluding the header. The Binding Response MUST have a message type
of "Binding Response".
The server MUST add a MAPPED-ADDRESS attribute to the Binding
Response. The IP address component of this attribute MUST be set to
the source IP address observed in the Binding Request. The port
component of this attribute MUST be set to the source port observed
in the Binding Request.
If the RESPONSE-ADDRESS attribute was absent from the Binding
Request, the destination address and port of the Binding Response
MUST be the same as the source address and port of the Binding
Request. Otherwise, the destination address and port of the Binding
Response MUST be the value of the IP address and port in the
RESPONSE-ADDRESS attribute.
The source address and port of the Binding Response depend on the
value of the CHANGE-REQUEST attribute and on the address and port the
Binding Request was received on, and are summarized in Table 1.
Let Da represent the destination IP address of the Binding Request
(which will be either A1 or A2), and Dp represent the destination
port of the Binding Request (which will be either P1 or P2). Let Ca
represent the other address, so that if Da is A1, Ca is A2. If Da is
A2, Ca is A1. Similarly, let Cp represent the other port, so that if
Dp is P1, Cp is P2. If Dp is P2, Cp is P1. If the "change port"
flag was set in CHANGE-REQUEST attribute of the Binding Request, and
the "change IP" flag was not set, the source IP address of the
Binding Response MUST be Da and the source port of the Binding
Response MUST be Cp. If the "change IP" flag was set in the Binding
Request, and the "change port" flag was not set, the source IP
address of the Binding Response MUST be Ca and the source port of the
Binding Response MUST be Dp. When both flags are set, the source IP
address of the Binding Response MUST be Ca and the source port of the
Binding Response MUST be Cp. If neither flag is set, or if the
CHANGE-REQUEST attribute is absent entirely, the source IP address of
the Binding Response MUST be Da and the source port of the Binding
Response MUST be Dp.
Rosenberg, et al. Standards Track [Page 11]
RFC 3489 STUN March 2003
Flags Source Address Source Port CHANGED-ADDRESS
none Da Dp Ca:Cp
Change IP Ca Dp Ca:Cp
Change port Da Cp Ca:Cp
Change IP and
Change port Ca Cp Ca:Cp
Table 1: Impact of Flags on Packet Source and CHANGED-ADDRESS
The server MUST add a SOURCE-ADDRESS attribute to the Binding
Response, containing the source address and port used to send the
Binding Response.
The server MUST add a CHANGED-ADDRESS attribute to the Binding
Response. This contains the source IP address and port that would be
used if the client had set the "change IP" and "change port" flags in
the Binding Request. As summarized in Table 1, these are Ca and Cp,
respectively, regardless of the value of the CHANGE-REQUEST flags.
If the Binding Request contained both the USERNAME and MESSAGE-
INTEGRITY attributes, the server MUST add a MESSAGE-INTEGRITY
attribute to the Binding Response. The attribute contains an HMAC
[13] over the response, as described in Section 11.2.8. The key to
use depends on the shared secret mechanism. If the STUN Shared
Secret Request was used, the key MUST be the one associated with the
USERNAME attribute present in the Binding Request.
If the Binding Request contained a RESPONSE-ADDRESS attribute, the
server MUST add a REFLECTED-FROM attribute to the response. If the
Binding Request was authenticated using a username obtained from a
Shared Secret Request, the REFLECTED-FROM attribute MUST contain the
source IP address and port where that Shared Secret Request came
from. If the username present in the request was not allocated using
a Shared Secret Request, the REFLECTED-FROM attribute MUST contain
the source address and port of the entity which obtained the
username, as best can be verified with the mechanism used to allocate
the username. If the username was not present in the request, and
the server was willing to process the request, the REFLECTED-FROM
attribute SHOULD contain the source IP address and port where the
request came from.
The server SHOULD NOT retransmit the response. Reliability is
achieved by having the client periodically resend the request, each
of which triggers a response from the server.
Rosenberg, et al. Standards Track [Page 12]
RFC 3489 STUN March 2003
8.2 Shared Secret Requests
Shared Secret Requests are always received on TLS connections. When
the server receives a request from the client to establish a TLS
connection, it MUST proceed with TLS, and SHOULD present a site
certificate. The TLS ciphersuite TLS_RSA_WITH_AES_128_CBC_SHA [4]
SHOULD be used. Client TLS authentication MUST NOT be done, since
the server is not allocating any resources to clients, and the
computational burden can be a source of attacks.
If the server receives a Shared Secret Request, it MUST verify that
the request arrived on a TLS connection. If it did not receive the
request over TLS, it MUST generate a Shared Secret Error Response,
and it MUST include an ERROR-CODE attribute with a 433 response code.
The destination for the error response depends on the transport on
which the request was received. If the Shared Secret Request was
received over TCP, the Shared Secret Error Response is sent over the
same connection the request was received on. If the Shared Secret
Request was receive over UDP, the Shared Secret Error Response is
sent to the source IP address and port that the request came from.
The server MUST check for any attributes in the request with values
less than or equal to 0x7fff which it does not understand. If it
encounters any, the server MUST generate a Shared Secret Error
Response, and it MUST include an ERROR-CODE attribute with a 420
response code. That response MUST contain an UNKNOWN-ATTRIBUTES
attribute listing the attributes with values less than or equal to
0x7fff which were not understood. The Shared Secret Error Response
is sent over the TLS connection.
All Shared Secret Error Responses MUST contain the same transaction
ID contained in the Shared Secret Request. The length in the message
header MUST contain the total length of the message in bytes,
excluding the header. The Shared Secret Error Response MUST have a
message type of "Shared Secret Error Response" (0x0112).
Assuming the request was properly constructed, the server creates a
Shared Secret Response. The Shared Secret Response MUST contain the
same transaction ID contained in the Shared Secret Request. The
length in the message header MUST contain the total length of the
message in bytes, excluding the header. The Shared Secret Response
MUST have a message type of "Shared Secret Response". The Shared
Secret Response MUST contain a USERNAME attribute and a PASSWORD
attribute. The USERNAME attribute serves as an index to the
password, which is contained in the PASSWORD attribute. The server
can use any mechanism it chooses to generate the username. However,
the username MUST be valid for a period of at least 10 minutes.
Validity means that the server can compute the password for that
Rosenberg, et al. Standards Track [Page 13]
RFC 3489 STUN March 2003
username. There MUST be a single password for each username. In
other words, the server cannot, 10 minutes later, assign a different
password to the same username. The server MUST hand out a different
username for each distinct Shared Secret Request. Distinct, in this
case, implies a different transaction ID. It is RECOMMENDED that the
server explicitly invalidate the username after ten minutes. It MUST
invalidate the username after 30 minutes. The PASSWORD contains the
password bound to that username. The password MUST have at least 128
bits. The likelihood that the server assigns the same password for
two different usernames MUST be vanishingly small, and the passwords
MUST be unguessable. In other words, they MUST be a
cryptographically random function of the username.
These requirements can still be met using a stateless server, by
intelligently computing the USERNAME and PASSWORD. One approach is
to construct the USERNAME as:
USERNAME = <prefix,rounded-time,clientIP,hmac>
Where prefix is some random text string (different for each shared
secret request), rounded-time is the current time modulo 20 minutes,
clientIP is the source IP address where the Shared Secret Request
came from, and hmac is an HMAC [13] over the prefix, rounded-time,
and client IP, using a server private key.
The password is then computed as:
password = <hmac(USERNAME,anotherprivatekey)>
With this structure, the username itself, which will be present in
the Binding Request, contains the source IP address where the Shared
Secret Request came from. That allows the server to meet the
requirements specified in Section 8.1 for constructing the
REFLECTED-FROM attribute. The server can verify that the username
was not tampered with, using the hmac present in the username.
The Shared Secret Response is sent over the same TLS connection the
request was received on. The server SHOULD keep the connection open,
and let the client close it.
9. Client Behavior
The behavior of the client is very straightforward. Its task is to
discover the STUN server, obtain a shared secret, formulate the
Binding Request, handle request reliability, and process the Binding
Responses.
Rosenberg, et al. Standards Track [Page 14]
RFC 3489 STUN March 2003
9.1 Discovery
Generally, the client will be configured with a domain name of the
provider of the STUN servers. This domain name is resolved to an IP
address and port using the SRV procedures specified in RFC 2782 [3].
Specifically, the service name is "stun". The protocol is "udp" for
sending Binding Requests, or "tcp" for sending Shared Secret
Requests. The procedures of RFC 2782 are followed to determine the
server to contact. RFC 2782 spells out the details of how a set of
SRV records are sorted and then tried. However, it only states that
the client should "try to connect to the (protocol, address,
service)" without giving any details on what happens in the event of
failure. Those details are described here for STUN.
For STUN requests, failure occurs if there is a transport failure of
some sort (generally, due to fatal ICMP errors in UDP or connection
failures in TCP). Failure also occurs if the transaction fails due
to timeout. This occurs 9.5 seconds after the first request is sent,
for both Shared Secret Requests and Binding Requests. See Section
9.3 for details on transaction timeouts for Binding Requests. If a
failure occurs, the client SHOULD create a new request, which is
identical to the previous, but has a different transaction ID and
MESSAGE INTEGRITY attribute (the HMAC will change because the
transaction ID has changed). That request is sent to the next
element in the list as specified by RFC 2782.
The default port for STUN requests is 3478, for both TCP and UDP.
Administrators SHOULD use this port in their SRV records, but MAY use
others.
If no SRV records were found, the client performs an A record lookup
of the domain name. The result will be a list of IP addresses, each
of which can be contacted at the default port.
This would allow a firewall admin to open the STUN port, so hosts
within the enterprise could access new applications. Whether they
will or won't do this is a good question.
9.2 Obtaining a Shared Secret
As discussed in Section 12, there are several attacks possible on
STUN systems. Many of these are prevented through integrity of
requests and responses. To provide that integrity, STUN makes use of
a shared secret between client and server, used as the keying
material for an HMAC used in both the Binding Request and Binding
Response. STUN allows for the shared secret to be obtained in any
way (for example, Kerberos [14]). However, it MUST have at least 128
Rosenberg, et al. Standards Track [Page 15]
RFC 3489 STUN March 2003
bits of randomness. In order to ensure interoperability, this
specification describes a TLS-based mechanism. This mechanism,
described in this section, MUST be implemented by clients and
servers.
First, the client determines the IP address and port that it will
open a TCP connection to. This is done using the discovery
procedures in Section 9.1. The client opens up the connection to
that address and port, and immediately begins TLS negotiation [2].
The client MUST verify the identity of the server. To do that, it
follows the identification procedures defined in Section 3.1 of RFC
2818 [5]. Those procedures assume the client is dereferencing a URI.
For purposes of usage with this specification, the client treats the
domain name or IP address used in Section 9.1 as the host portion of
the URI that has been dereferenced.
Once the connection is opened, the client sends a Shared Secret
request. This request has no attributes, just the header. The
transaction ID in the header MUST meet the requirements outlined for
the transaction ID in a binding request, described in Section 9.3
below. The server generates a response, which can either be a Shared
Secret Response or a Shared Secret Error Response.
If the response was a Shared Secret Error Response, the client checks
the response code in the ERROR-CODE attribute. Interpretation of
those response codes is identical to the processing of Section 9.4
for the Binding Error Response.
If a client receives a Shared Secret Response with an attribute whose
type is greater than 0x7fff, the attribute MUST be ignored. If the
client receives a Shared Secret Response with an attribute whose type
is less than or equal to 0x7fff, the response is ignored.
If the response was a Shared Secret Response, it will contain a short
lived username and password, encoded in the USERNAME and PASSWORD
attributes, respectively.
The client MAY generate multiple Shared Secret Requests on the
connection, and it MAY do so before receiving Shared Secret Responses
to previous Shared Secret Requests. The client SHOULD close the
connection as soon as it has finished obtaining usernames and
passwords.
Section 9.3 describes how these passwords are used to provide
integrity protection over Binding Requests, and Section 8.1 describes
how it is used in Binding Responses.
Rosenberg, et al. Standards Track [Page 16]
RFC 3489 STUN March 2003
9.3 Formulating the Binding Request
A Binding Request formulated by the client follows the syntax rules
defined in Section 11. Any two requests that are not bit-wise
identical, and not sent to the same server from the same IP address
and port, MUST carry different transaction IDs. The transaction ID
MUST be uniformly and randomly distributed between 0 and 2**128 - 1.
The large range is needed because the transaction ID serves as a form
of randomization, helping to prevent replays of previously signed
responses from the server. The message type of the request MUST be
"Binding Request".
The RESPONSE-ADDRESS attribute is optional in the Binding Request.
It is used if the client wishes the response to be sent to a
different IP address and port than the one the request was sent from.
This is useful for determining whether the client is behind a
firewall, and for applications that have separated control and data
components. See Section 10.3 for more details. The CHANGE-REQUEST
attribute is also optional. Whether it is present depends on what
the application is trying to accomplish. See Section 10 for some
example uses.
The client SHOULD add a MESSAGE-INTEGRITY and USERNAME attribute to
the Binding Request. This MESSAGE-INTEGRITY attribute contains an
HMAC [13]. The value of the username, and the key to use in the
MESSAGE-INTEGRITY attribute depend on the shared secret mechanism.
If the STUN Shared Secret Request was used, the USERNAME must be a
valid username obtained from a Shared Secret Response within the last
nine minutes. The shared secret for the HMAC is the value of the
PASSWORD attribute obtained from the same Shared Secret Response.
Once formulated, the client sends the Binding Request. Reliability
is accomplished through client retransmissions. Clients SHOULD
retransmit the request starting with an interval of 100ms, doubling
every retransmit until the interval reaches 1.6s. Retransmissions
continue with intervals of 1.6s until a response is received, or a
total of 9 requests have been sent. If no response is received by 1.6
seconds after the last request has been sent, the client SHOULD
consider the transaction to have failed. In other words, requests
would be sent at times 0ms, 100ms, 300ms, 700ms, 1500ms, 3100ms,
4700ms, 6300ms, and 7900ms. At 9500ms, the client considers the
transaction to have failed if no response has been received.
9.4 Processing Binding Responses
The response can either be a Binding Response or Binding Error
Response. Binding Error Responses are always received on the source
address and port the request was sent from. A Binding Response will
Rosenberg, et al. Standards Track [Page 17]
RFC 3489 STUN March 2003
be received on the address and port placed in the RESPONSE-ADDRESS
attribute of the request. If none was present, the Binding Responses
will be received on the source address and port the request was sent
from.
If the response is a Binding Error Response, the client checks the
response code from the ERROR-CODE attribute of the response. For a
400 response code, the client SHOULD display the reason phrase to the
user. For a 420 response code, the client SHOULD retry the request,
this time omitting any attributes listed in the UNKNOWN-ATTRIBUTES
attribute of the response. For a 430 response code, the client
SHOULD obtain a new shared secret, and retry the Binding Request with
a new transaction. For 401 and 432 response codes, if the client had
omitted the USERNAME or MESSAGE-INTEGRITY attribute as indicated by
the error, it SHOULD try again with those attributes. For a 431
response code, the client SHOULD alert the user, and MAY try the
request again after obtaining a new username and password. For a 500
response code, the client MAY wait several seconds and then retry the
request. For a 600 response code, the client MUST NOT retry the
request, and SHOULD display the reason phrase to the user. Unknown
attributes between 400 and 499 are treated like a 400, unknown
attributes between 500 and 599 are treated like a 500, and unknown
attributes between 600 and 699 are treated like a 600. Any response
between 100 and 399 MUST result in the cessation of request
retransmissions, but otherwise is discarded.
If a client receives a response with an attribute whose type is
greater than 0x7fff, the attribute MUST be ignored. If the client
receives a response with an attribute whose type is less than or
equal to 0x7fff, request retransmissions MUST cease, but the entire
response is otherwise ignored.
If the response is a Binding Response, the client SHOULD check the
response for a MESSAGE-INTEGRITY attribute. If not present, and the
client placed a MESSAGE-INTEGRITY attribute into the request, it MUST
discard the response. If present, the client computes the HMAC over
the response as described in Section 11.2.8. The key to use depends
on the shared secret mechanism. If the STUN Shared Secret Request
was used, the key MUST be same as used to compute the MESSAGE-
INTEGRITY attribute in the request. If the computed HMAC differs
from the one in the response, the client MUST discard the response,
and SHOULD alert the user about a possible attack. If the computed