-
Notifications
You must be signed in to change notification settings - Fork 2
/
rfc6455.xml
3842 lines (3178 loc) · 157 KB
/
rfc6455.xml
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
<?xml version='1.0' encoding='utf-8'?>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC1928 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.1928.xml">
<!ENTITY RFC2119 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2616 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC2817 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2817.xml">
<!ENTITY RFC2818 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2818.xml">
<!ENTITY RFC3629 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3629.xml">
<!ENTITY RFC3864 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3864.xml">
<!ENTITY RFC3986 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC3987 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3987.xml">
<!ENTITY RFC4086 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4086.xml">
<!ENTITY RFC4648 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY RFC5226 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5226.xml">
<!ENTITY RFC5234 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5234.xml">
<!ENTITY RFC5246 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5246.xml">
<!ENTITY RFC6066 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6066.xml">
<!ENTITY RFC6454 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6454.xml">
<!ENTITY RFC4122 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4122.xml">
<!ENTITY RFC4270 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4270.xml">
<!ENTITY RFC5321 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5321.xml">
<!ENTITY RFC6202 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6202.xml">
<!ENTITY RFC6265 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6265.xml">
<!ENTITY W3C.REC-wsc-ui-20100812 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml4/reference.W3C.REC-wsc-ui-20100812.xml">
]>
<rfc submissionType="IETF" number="6455" category="std" consensus="yes">
<!-- Generated by id2xml 1.4.4 on 2018-12-17T05:52:29Z -->
<?rfc compact="yes"?>
<?rfc text-list-symbols="o*+-"?>
<?rfc subcompact="no"?>
<?rfc sortrefs="no"?>
<?rfc symrefs="yes"?>
<?rfc strict="yes"?>
<?rfc toc="yes"?>
<front>
<title>The WebSocket Protocol</title>
<author fullname="Ian Fette" initials="I." surname="Fette">
<organization>Google, Inc.</organization>
<address><email>ifette+ietf@google.com</email>
<uri>http://www.ianfette.com/</uri>
</address>
</author>
<author fullname="Alexey Melnikov" initials="A." surname="Melnikov">
<organization>Isode Ltd.</organization>
<address><postal><street>5 Castle Business Village</street>
<street>36 Station Road</street>
<street>Hampton, Middlesex TW12 2BX</street>
<street>UK</street>
</postal>
<email>Alexey.Melnikov@isode.com</email>
</address>
</author>
<date month="December" year="2011"/>
<abstract><t>
The WebSocket Protocol enables two-way communication between a client
running untrusted code in a controlled environment to a remote host
that has opted-in to communications from that code. The security
model used for this is the origin-based security model commonly used
by web browsers. The protocol consists of an opening handshake
followed by basic message framing, layered over TCP. The goal of
this technology is to provide a mechanism for browser-based
applications that need two-way communication with servers that does
not rely on opening multiple HTTP connections (e.g., using
XMLHttpRequest or <iframe>s and long polling).</t>
</abstract>
</front>
<middle>
<section title="Introduction" anchor="section-1"><section title="Background" anchor="section-1.1"><t>
_This section is non-normative._</t>
<t>
Historically, creating web applications that need bidirectional
communication between a client and a server (e.g., instant messaging
and gaming applications) has required an abuse of HTTP to poll the
server for updates while sending upstream notifications as distinct
HTTP calls <xref target="RFC6202"/>.</t>
<t>
This results in a variety of problems:</t>
<t><list style="symbols"><t>The server is forced to use a number of different underlying TCP
connections for each client: one for sending information to the
client and a new one for each incoming message.</t>
<t>The wire protocol has a high overhead, with each client-to-server
message having an HTTP header.</t>
<t>The client-side script is forced to maintain a mapping from the
outgoing connections to the incoming connection to track replies.</t>
</list>
</t>
<t>
A simpler solution would be to use a single TCP connection for
traffic in both directions. This is what the WebSocket Protocol
provides. Combined with the WebSocket API <xref target="WSAPI"/>, it provides an
alternative to HTTP polling for two-way communication from a web page
to a remote server.</t>
<t>
The same technique can be used for a variety of web applications:
games, stock tickers, multiuser applications with simultaneous
editing, user interfaces exposing server-side services in real time,
etc.</t>
<t>
The WebSocket Protocol is designed to supersede existing
bidirectional communication technologies that use HTTP as a transport
layer to benefit from existing infrastructure (proxies, filtering,
authentication). Such technologies were implemented as trade-offs
between efficiency and reliability because HTTP was not initially
meant to be used for bidirectional communication (see <xref target="RFC6202"/> for
further discussion). The WebSocket Protocol attempts to address the
goals of existing bidirectional HTTP technologies in the context of
the existing HTTP infrastructure; as such, it is designed to work
over HTTP ports 80 and 443 as well as to support HTTP proxies and
intermediaries, even if this implies some complexity specific to the
current environment. However, the design does not limit WebSocket to
HTTP, and future implementations could use a simpler handshake over a
dedicated port without reinventing the entire protocol. This last
point is important because the traffic patterns of interactive
messaging do not closely match standard HTTP traffic and can induce
unusual loads on some components.</t>
</section>
<section title="Protocol Overview" anchor="section-1.2"><t>
_This section is non-normative._</t>
<t>
The protocol has two parts: a handshake and the data transfer.</t>
<t><list style="hanging" hangIndent="-1"><t hangText="The handshake from the client looks as follows:">
<vspace blankLines="0"/>
</t>
</list>
</t>
<figure><artwork><![CDATA[
GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Origin: http://example.com
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Version: 13
The handshake from the server looks as follows:
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat
]]></artwork>
</figure>
<t>
The leading line from the client follows the Request-Line format.
The leading line from the server follows the Status-Line format. The
Request-Line and Status-Line productions are defined in <xref target="RFC2616"/>.</t>
<t>
An unordered set of header fields comes after the leading line in
both cases. The meaning of these header fields is specified in
Section 4 of this document. Additional header fields may also be
present, such as cookies <xref target="RFC6265"/>. The format and parsing of
headers is as defined in <xref target="RFC2616"/>.</t>
<t>
Once the client and server have both sent their handshakes, and if
the handshake was successful, then the data transfer part starts.
This is a two-way communication channel where each side can,
independently from the other, send data at will.</t>
<t>
After a successful handshake, clients and servers transfer data back
and forth in conceptual units referred to in this specification as
"messages". On the wire, a message is composed of one or more
frames. The WebSocket message does not necessarily correspond to a
particular network layer framing, as a fragmented message may be
coalesced or split by an intermediary.</t>
<t>
A frame has an associated type. Each frame belonging to the same
message contains the same type of data. Broadly speaking, there are
types for textual data (which is interpreted as UTF-8 <xref target="RFC3629"/>
text), binary data (whose interpretation is left up to the
application), and control frames (which are not intended to carry
data for the application but instead for protocol-level signaling,
such as to signal that the connection should be closed). This
version of the protocol defines six frame types and leaves ten
reserved for future use.</t>
</section>
<section title="Opening Handshake" anchor="section-1.3"><t>
_This section is non-normative._</t>
<t>
The opening handshake is intended to be compatible with HTTP-based
server-side software and intermediaries, so that a single port can be
used by both HTTP clients talking to that server and WebSocket
clients talking to that server. To this end, the WebSocket client's
handshake is an HTTP Upgrade request:</t>
<figure><artwork><![CDATA[
GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Origin: http://example.com
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Version: 13
]]></artwork>
</figure>
<t>
In compliance with <xref target="RFC2616"/>, header fields in the handshake may be
sent by the client in any order, so the order in which different
header fields are received is not significant.</t>
<t>
The "Request-URI" of the GET method <xref target="RFC2616"/> is used to identify the
endpoint of the WebSocket connection, both to allow multiple domains
to be served from one IP address and to allow multiple WebSocket
endpoints to be served by a single server.</t>
<t>
The client includes the hostname in the |Host| header field of its
handshake as per <xref target="RFC2616"/>, so that both the client and the server
can verify that they agree on which host is in use.</t>
<t>
Additional header fields are used to select options in the WebSocket
Protocol. Typical options available in this version are the
subprotocol selector (|Sec-WebSocket-Protocol|), list of extensions
support by the client (|Sec-WebSocket-Extensions|), |Origin| header
field, etc. The |Sec-WebSocket-Protocol| request-header field can be
used to indicate what subprotocols (application-level protocols
layered over the WebSocket Protocol) are acceptable to the client.
The server selects one or none of the acceptable protocols and echoes
that value in its handshake to indicate that it has selected that
protocol.</t>
<t><list hangIndent="5" style="hanging"><t>
Sec-WebSocket-Protocol: chat</t>
</list>
</t>
<t>
The |Origin| header field <xref target="RFC6454"/> is used to protect against
unauthorized cross-origin use of a WebSocket server by scripts using
the WebSocket API in a web browser. The server is informed of the
script origin generating the WebSocket connection request. If the
server does not wish to accept connections from this origin, it can
choose to reject the connection by sending an appropriate HTTP error
code. This header field is sent by browser clients; for non-browser
clients, this header field may be sent if it makes sense in the
context of those clients.</t>
<t>
Finally, the server has to prove to the client that it received the
client's WebSocket handshake, so that the server doesn't accept
connections that are not WebSocket connections. This prevents an
attacker from tricking a WebSocket server by sending it carefully
crafted packets using XMLHttpRequest <xref target="XMLHttpRequest"/> or a form
submission.</t>
<t>
To prove that the handshake was received, the server has to take two
pieces of information and combine them to form a response. The first
piece of information comes from the |Sec-WebSocket-Key| header field
in the client handshake:</t>
<t><list hangIndent="5" style="hanging"><t>
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==</t>
</list>
</t>
<t>
For this header field, the server has to take the value (as present
in the header field, e.g., the base64-encoded <xref target="RFC4648"/> version minus
any leading and trailing whitespace) and concatenate this with the
Globally Unique Identifier (GUID, <xref target="RFC4122"/>) "258EAFA5-E914-47DA-95CA-C5AB0DC85B11" in string form, which is unlikely to be used by
network endpoints that do not understand the WebSocket Protocol. A
SHA-1 hash (160 bits) <xref target="FIPS.180-3"/>, base64-encoded (see Section 4 of
<xref target="RFC4648"/>), of this concatenation is then returned in the server's
handshake.</t>
<t>
Concretely, if as in the example above, the |Sec-WebSocket-Key|
header field had the value "dGhlIHNhbXBsZSBub25jZQ==", the server
would concatenate the string "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
to form the string "dGhlIHNhbXBsZSBub25jZQ==258EAFA5-E914-47DA-95CA-C5AB0DC85B11". The server would then take the SHA-1 hash of this,
giving the value 0xb3 0x7a 0x4f 0x2c 0xc0 0x62 0x4f 0x16 0x90 0xf6
0x46 0x06 0xcf 0x38 0x59 0x45 0xb2 0xbe 0xc4 0xea. This value is
then base64-encoded (see Section 4 of <xref target="RFC4648"/>), to give the value
"s3pPLMBiTxaQ9kYGzzhZRbK+xOo=". This value would then be echoed in
the |Sec-WebSocket-Accept| header field.</t>
<t>
The handshake from the server is much simpler than the client
handshake. The first line is an HTTP Status-Line, with the status
code 101:</t>
<t><list hangIndent="5" style="hanging"><t>
HTTP/1.1 101 Switching Protocols</t>
</list>
</t>
<t>
Any status code other than 101 indicates that the WebSocket handshake
has not completed and that the semantics of HTTP still apply. The
headers follow the status code.</t>
<t>
The |Connection| and |Upgrade| header fields complete the HTTP
Upgrade. The |Sec-WebSocket-Accept| header field indicates whether
the server is willing to accept the connection. If present, this
header field must include a hash of the client's nonce sent in
|Sec-WebSocket-Key| along with a predefined GUID. Any other value
must not be interpreted as an acceptance of the connection by the
server.</t>
<figure><artwork><![CDATA[
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
]]></artwork>
</figure>
<t>
These fields are checked by the WebSocket client for scripted pages.
If the |Sec-WebSocket-Accept| value does not match the expected
value, if the header field is missing, or if the HTTP status code is
not 101, the connection will not be established, and WebSocket frames
will not be sent.</t>
<t>
Option fields can also be included. In this version of the protocol,
the main option field is |Sec-WebSocket-Protocol|, which indicates
the subprotocol that the server has selected. WebSocket clients
verify that the server included one of the values that was specified
in the WebSocket client's handshake. A server that speaks multiple
subprotocols has to make sure it selects one based on the client's
handshake and specifies it in its handshake.</t>
<t><list hangIndent="5" style="hanging"><t>
Sec-WebSocket-Protocol: chat</t>
</list>
</t>
<t>
The server can also set cookie-related option fields to _set_
cookies, as described in <xref target="RFC6265"/>.</t>
</section>
<section title="Closing Handshake" anchor="section-1.4"><t>
_This section is non-normative._</t>
<t>
The closing handshake is far simpler than the opening handshake.</t>
<t>
Either peer can send a control frame with data containing a specified
control sequence to begin the closing handshake (detailed in
<xref target="section-5.5.1"/>). Upon receiving such a frame, the other peer sends a
Close frame in response, if it hasn't already sent one. Upon
receiving _that_ control frame, the first peer then closes the
connection, safe in the knowledge that no further data is
forthcoming.</t>
<t>
After sending a control frame indicating the connection should be
closed, a peer does not send any further data; after receiving a
control frame indicating the connection should be closed, a peer
discards any further data received.</t>
<t>
It is safe for both peers to initiate this handshake simultaneously.</t>
<t>
The closing handshake is intended to complement the TCP closing
handshake (FIN/ACK), on the basis that the TCP closing handshake is
not always reliable end-to-end, especially in the presence of
intercepting proxies and other intermediaries.</t>
<t>
By sending a Close frame and waiting for a Close frame in response,
certain cases are avoided where data may be unnecessarily lost. For
instance, on some platforms, if a socket is closed with data in the
receive queue, a RST packet is sent, which will then cause recv() to
fail for the party that received the RST, even if there was data
waiting to be read.</t>
</section>
<section title="Design Philosophy" anchor="section-1.5"><t>
_This section is non-normative._</t>
<t>
The WebSocket Protocol is designed on the principle that there should
be minimal framing (the only framing that exists is to make the
protocol frame-based instead of stream-based and to support a
distinction between Unicode text and binary frames). It is expected
that metadata would be layered on top of WebSocket by the application
layer, in the same way that metadata is layered on top of TCP by the
application layer (e.g., HTTP).</t>
<t>
Conceptually, WebSocket is really just a layer on top of TCP that
does the following:</t>
<t><list style="symbols"><t>adds a web origin-based security model for browsers</t>
<t>adds an addressing and protocol naming mechanism to support
multiple services on one port and multiple host names on one IP
address</t>
<t>layers a framing mechanism on top of TCP to get back to the IP
packet mechanism that TCP is built on, but without length limits</t>
<t>includes an additional closing handshake in-band that is designed
to work in the presence of proxies and other intermediaries</t>
</list>
</t>
<t>
Other than that, WebSocket adds nothing. Basically it is intended to
be as close to just exposing raw TCP to script as possible given the
constraints of the Web. It's also designed in such a way that its
servers can share a port with HTTP servers, by having its handshake
be a valid HTTP Upgrade request. One could conceptually use other
protocols to establish client-server messaging, but the intent of
WebSockets is to provide a relatively simple protocol that can
coexist with HTTP and deployed HTTP infrastructure (such as proxies)
and that is as close to TCP as is safe for use with such
infrastructure given security considerations, with targeted additions
to simplify usage and keep simple things simple (such as the addition
of message semantics).</t>
<t>
The protocol is intended to be extensible; future versions will
likely introduce additional concepts such as multiplexing.</t>
</section>
<section title="Security Model" anchor="section-1.6"><t>
_This section is non-normative._</t>
<t>
The WebSocket Protocol uses the origin model used by web browsers to
restrict which web pages can contact a WebSocket server when the
WebSocket Protocol is used from a web page. Naturally, when the
WebSocket Protocol is used by a dedicated client directly (i.e., not
from a web page through a web browser), the origin model is not
useful, as the client can provide any arbitrary origin string.</t>
<t>
This protocol is intended to fail to establish a connection with
servers of pre-existing protocols like SMTP <xref target="RFC5321"/> and HTTP, while
allowing HTTP servers to opt-in to supporting this protocol if
desired. This is achieved by having a strict and elaborate handshake
and by limiting the data that can be inserted into the connection
before the handshake is finished (thus limiting how much the server
can be influenced).</t>
<t>
It is similarly intended to fail to establish a connection when data
from other protocols, especially HTTP, is sent to a WebSocket server,
for example, as might happen if an HTML "form" were submitted to a
WebSocket server. This is primarily achieved by requiring that the
server prove that it read the handshake, which it can only do if the
handshake contains the appropriate parts, which can only be sent by a
WebSocket client. In particular, at the time of writing of this
specification, fields starting with |Sec-| cannot be set by an
attacker from a web browser using only HTML and JavaScript APIs such
as XMLHttpRequest <xref target="XMLHttpRequest"/>.</t>
</section>
<section title="Relationship to TCP and HTTP" anchor="section-1.7"><t>
_This section is non-normative._</t>
<t>
The WebSocket Protocol is an independent TCP-based protocol. Its
only relationship to HTTP is that its handshake is interpreted by
HTTP servers as an Upgrade request.</t>
<t>
By default, the WebSocket Protocol uses port 80 for regular WebSocket
connections and port 443 for WebSocket connections tunneled over
Transport Layer Security (TLS) <xref target="RFC2818"/>.</t>
</section>
<section title="Establishing a Connection" anchor="section-1.8"><t>
_This section is non-normative._</t>
<t>
When a connection is to be made to a port that is shared by an HTTP
server (a situation that is quite likely to occur with traffic to
ports 80 and 443), the connection will appear to the HTTP server to
be a regular GET request with an Upgrade offer. In relatively simple
setups with just one IP address and a single server for all traffic
to a single hostname, this might allow a practical way for systems
based on the WebSocket Protocol to be deployed. In more elaborate
setups (e.g., with load balancers and multiple servers), a dedicated
set of hosts for WebSocket connections separate from the HTTP servers
is probably easier to manage. At the time of writing of this
specification, it should be noted that connections on ports 80 and
443 have significantly different success rates, with connections on
port 443 being significantly more likely to succeed, though this may
change with time.</t>
</section>
<section title="Subprotocols Using the WebSocket Protocol" anchor="section-1.9"><t>
_This section is non-normative._</t>
<t>
The client can request that the server use a specific subprotocol by
including the |Sec-WebSocket-Protocol| field in its handshake. If it
is specified, the server needs to include the same field and one of
the selected subprotocol values in its response for the connection to
be established.</t>
<t>
These subprotocol names should be registered as per <xref target="section-11.5"/>. To
avoid potential collisions, it is recommended to use names that
contain the ASCII version of the domain name of the subprotocol's
originator. For example, if Example Corporation were to create a
Chat subprotocol to be implemented by many servers around the Web,
they could name it "chat.example.com". If the Example Organization
called their competing subprotocol "chat.example.org", then the two
subprotocols could be implemented by servers simultaneously, with the
server dynamically selecting which subprotocol to use based on the
value sent by the client.</t>
<t>
Subprotocols can be versioned in backward-incompatible ways by
changing the subprotocol name, e.g., going from
"bookings.example.net" to "v2.bookings.example.net". These
subprotocols would be considered completely separate by WebSocket
clients. Backward-compatible versioning can be implemented by
reusing the same subprotocol string but carefully designing the
actual subprotocol to support this kind of extensibility.</t>
</section>
</section>
<section title="Conformance Requirements" anchor="section-2"><t>
All diagrams, examples, and notes in this specification are non-
normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.</t>
<t>
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 <xref target="RFC2119"/>.</t>
<t>
Requirements phrased in the imperative as part of algorithms (such as
"strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word
("MUST", "SHOULD", "MAY", etc.) used in introducing the algorithm.</t>
<t>
Conformance requirements phrased as algorithms or specific steps MAY
be implemented in any manner, so long as the end result is
equivalent. (In particular, the algorithms defined in this
specification are intended to be easy to follow and not intended to
be performant.)</t>
<section title="Terminology and Other Conventions" anchor="section-2.1"><t>
_ASCII_ shall mean the character-encoding scheme defined in
<xref target="ANSI.X3-4.1986"/>.</t>
<t>
This document makes reference to UTF-8 values and uses UTF-8
notational formats as defined in STD 63 <xref target="RFC3629"/>.</t>
<t>
Key terms such as named algorithms or definitions are indicated like
_this_.</t>
<t>
Names of header fields or variables are indicated like |this|.</t>
<t>
Variable values are indicated like /this/.</t>
<t>
This document references the procedure to _Fail the WebSocket
Connection_. This procedure is defined in <xref target="section-7.1.7"/>.</t>
<t>
_Converting a string to ASCII lowercase_ means replacing all
characters in the range U+0041 to U+005A (i.e., LATIN CAPITAL LETTER
A to LATIN CAPITAL LETTER Z) with the corresponding characters in the
range U+0061 to U+007A (i.e., LATIN SMALL LETTER A to LATIN SMALL
LETTER Z).</t>
<t>
Comparing two strings in an _ASCII case-insensitive_ manner means
comparing them exactly, code point for code point, except that the
characters in the range U+0041 to U+005A (i.e., LATIN CAPITAL LETTER
A to LATIN CAPITAL LETTER Z) and the corresponding characters in the
range U+0061 to U+007A (i.e., LATIN SMALL LETTER A to LATIN SMALL
LETTER Z) are considered to also match.</t>
<t>
The term "URI" is used in this document as defined in <xref target="RFC3986"/>.</t>
<t>
When an implementation is required to _send_ data as part of the
WebSocket Protocol, the implementation MAY delay the actual
transmission arbitrarily, e.g., buffering data so as to send fewer IP
packets.</t>
<t>
Note that this document uses both <xref target="RFC5234"/> and <xref target="RFC2616"/> variants of
ABNF in different sections.</t>
</section>
</section>
<section title="WebSocket URIs" anchor="section-3"><t>
This specification defines two URI schemes, using the ABNF syntax
defined in RFC 5234 <xref target="RFC5234"/>, and terminology and ABNF productions
defined by the URI specification RFC 3986 <xref target="RFC3986"/>.</t>
<figure><artwork><![CDATA[
ws-URI = "ws:" "//" host [ ":" port ] path [ "?" query ]
wss-URI = "wss:" "//" host [ ":" port ] path [ "?" query ]
host = <host, defined in [RFC3986], Section 3.2.2>
port = <port, defined in [RFC3986], Section 3.2.3>
path = <path-abempty, defined in [RFC3986], Section 3.3>
query = <query, defined in [RFC3986], Section 3.4>
]]></artwork>
</figure>
<t>
The port component is OPTIONAL; the default for "ws" is port 80,
while the default for "wss" is port 443.</t>
<t>
The URI is called "secure" (and it is said that "the secure flag is set") if the scheme component matches "wss" case-insensitively.</t>
<t>
The "resource-name" (also known as /resource name/ in <xref target="section-4.1"/>)
can be constructed by concatenating the following:</t>
<t><list style="symbols"><t>"/" if the path component is empty</t>
<t>the path component</t>
<t>"?" if the query component is non-empty</t>
<t>the query component</t>
</list>
</t>
<t>
Fragment identifiers are meaningless in the context of WebSocket URIs
and MUST NOT be used on these URIs. As with any URI scheme, the
character "#", when not indicating the start of a fragment, MUST be
escaped as %23.</t>
</section>
<section title="Opening Handshake" anchor="section-4"><section title="Client Requirements" anchor="section-4.1"><t>
To _Establish a WebSocket Connection_, a client opens a connection
and sends a handshake as defined in this section. A connection is
defined to initially be in a CONNECTING state. A client will need to
supply a /host/, /port/, /resource name/, and a /secure/ flag, which
are the components of a WebSocket URI as discussed in <xref target="section-3"/>,
along with a list of /protocols/ and /extensions/ to be used.
Additionally, if the client is a web browser, it supplies /origin/.</t>
<t>
Clients running in controlled environments, e.g., browsers on mobile
handsets tied to specific carriers, MAY offload the management of the
connection to another agent on the network. In such a situation, the
client for the purposes of this specification is considered to
include both the handset software and any such agents.</t>
<t>
When the client is to _Establish a WebSocket Connection_ given a set
of (/host/, /port/, /resource name/, and /secure/ flag), along with a
list of /protocols/ and /extensions/ to be used, and an /origin/ in
the case of web browsers, it MUST open a connection, send an opening
handshake, and read the server's handshake in response. The exact
requirements of how the connection should be opened, what should be
sent in the opening handshake, and how the server's response should
be interpreted are as follows in this section. In the following
text, we will use terms from <xref target="section-3"/>, such as "/host/" and
"/secure/ flag" as defined in that section.</t>
<t><list style="numbers"><t>The components of the WebSocket URI passed into this algorithm
(/host/, /port/, /resource name/, and /secure/ flag) MUST be
valid according to the specification of WebSocket URIs specified
in <xref target="section-3"/>. If any of the components are invalid, the client
MUST _Fail the WebSocket Connection_ and abort these steps.</t>
<t>If the client already has a WebSocket connection to the remote
host (IP address) identified by /host/ and port /port/ pair, even
if the remote host is known by another name, the client MUST wait
until that connection has been established or for that connection
to have failed. There MUST be no more than one connection in a
CONNECTING state. If multiple connections to the same IP address
are attempted simultaneously, the client MUST serialize them so
that there is no more than one connection at a time running
through the following steps.<vspace blankLines="1"/>
If the client cannot determine the IP address of the remote host
(for example, because all communication is being done through a
proxy server that performs DNS queries itself), then the client
MUST assume for the purposes of this step that each host name
refers to a distinct remote host, and instead the client SHOULD
limit the total number of simultaneous pending connections to a
reasonably low number (e.g., the client might allow simultaneous
pending connections to a.example.com and b.example.com, but if
thirty simultaneous connections to a single host are requested,
that may not be allowed). For example, in a web browser context,
the client needs to consider the number of tabs the user has open
in setting a limit to the number of simultaneous pending
connections.
<vspace blankLines="1"/>
NOTE: This makes it harder for a script to perform a denial-of-
service attack by just opening a large number of WebSocket
connections to a remote host. A server can further reduce the
load on itself when attacked by pausing before closing the
connection, as that will reduce the rate at which the client
reconnects.
<vspace blankLines="1"/>
NOTE: There is no limit to the number of established WebSocket
connections a client can have with a single remote host. Servers
can refuse to accept connections from hosts/IP addresses with an
excessive number of existing connections or disconnect resource-
hogging connections when suffering high load.
</t>
<t>_Proxy Usage_: If the client is configured to use a proxy when
using the WebSocket Protocol to connect to host /host/ and port
/port/, then the client SHOULD connect to that proxy and ask it
to open a TCP connection to the host given by /host/ and the port
given by /port/.<vspace blankLines="1"/>
EXAMPLE: For example, if the client uses an HTTP proxy for all
traffic, then if it was to try to connect to port 80 on server
example.com, it might send the following lines to the proxy
server:
<vspace blankLines="1"/>
CONNECT example.com:80 HTTP/1.1
Host: example.com
<list style="hanging" hangIndent="-1"><t hangText="If there was a password, the connection might look like:">
<vspace blankLines="0"/>
</t>
</list>
</t>
</list>
</t>
<figure><artwork><![CDATA[
CONNECT example.com:80 HTTP/1.1
Host: example.com
Proxy-authorization: Basic ZWRuYW1vZGU6bm9jYXBlcyE=
]]></artwork>
</figure>
<t><list hangIndent="4" style="hanging"><t>
If the client is not configured to use a proxy, then a direct TCP
connection SHOULD be opened to the host given by /host/ and the
port given by /port/.</t>
</list>
</t>
<t><list hangIndent="4" style="hanging"><t>
NOTE: Implementations that do not expose explicit UI for
selecting a proxy for WebSocket connections separate from other
proxies are encouraged to use a SOCKS5 <xref target="RFC1928"/> proxy for
WebSocket connections, if available, or failing that, to prefer
the proxy configured for HTTPS connections over the proxy
configured for HTTP connections.</t>
</list>
</t>
<t><list hangIndent="4" style="hanging"><t>
For the purpose of proxy autoconfiguration scripts, the URI to
pass the function MUST be constructed from /host/, /port/,
/resource name/, and the /secure/ flag using the definition of a
WebSocket URI as given in <xref target="section-3"/>.</t>
</list>
</t>
<t><list hangIndent="4" style="hanging"><t>
NOTE: The WebSocket Protocol can be identified in proxy
autoconfiguration scripts from the scheme ("ws" for unencrypted
connections and "wss" for encrypted connections).</t>
</list>
</t>
<t><list style="numbers"><t>If the connection could not be opened, either because a direct
connection failed or because any proxy used returned an error,
then the client MUST _Fail the WebSocket Connection_ and abort
the connection attempt.</t>
<t>If /secure/ is true, the client MUST perform a TLS handshake over
the connection after opening the connection and before sending
the handshake data <xref target="RFC2818"/>. If this fails (e.g., the server's
certificate could not be verified), then the client MUST _Fail
the WebSocket Connection_ and abort the connection. Otherwise,
all further communication on this channel MUST run through the
encrypted tunnel <xref target="RFC5246"/>.<vspace blankLines="1"/>
Clients MUST use the Server Name Indication extension in the TLS
handshake <xref target="RFC6066"/>.
</t>
</list>
</t>
<t>
Once a connection to the server has been established (including a
connection via a proxy or over a TLS-encrypted tunnel), the client
MUST send an opening handshake to the server. The handshake consists
of an HTTP Upgrade request, along with a list of required and
optional header fields. The requirements for this handshake are as
follows.</t>
<t><!--
rfc6455.txt(989): Warning: Found unexpected sublist to a compact list: '
13.'
--><list style="numbers"><t> The handshake MUST be a valid HTTP request as specified by
<xref target="RFC2616"/>.</t>
<t> The method of the request MUST be GET, and the HTTP version MUST
be at least 1.1.<vspace blankLines="1"/>
For example, if the WebSocket URI is "ws://example.com/chat",
the first line sent should be "GET /chat HTTP/1.1".
</t>
<t> The "Request-URI" part of the request MUST match the /resource
name/ defined in <xref target="section-3"/> (a relative URI) or be an absolute
http/https URI that, when parsed, has a /resource name/, /host/,
and /port/ that match the corresponding ws/wss URI.</t>
<t> The request MUST contain a |Host| header field whose value
contains /host/ plus optionally ":" followed by /port/ (when not
using the default port).</t>
<t> The request MUST contain an |Upgrade| header field whose value
MUST include the "websocket" keyword.</t>
<t> The request MUST contain a |Connection| header field whose value
MUST include the "Upgrade" token.</t>
<t> The request MUST include a header field with the name
|Sec-WebSocket-Key|. The value of this header field MUST be a
nonce consisting of a randomly selected 16-byte value that has
been base64-encoded (see Section 4 of <xref target="RFC4648"/>). The nonce
MUST be selected randomly for each connection.<vspace blankLines="1"/>
NOTE: As an example, if the randomly selected value was the
sequence of bytes 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09
0x0a 0x0b 0x0c 0x0d 0x0e 0x0f 0x10, the value of the header
field would be "AQIDBAUGBwgJCgsMDQ4PEC=="
</t>
<t> The request MUST include a header field with the name |Origin|
<xref target="RFC6454"/> if the request is coming from a browser client. If
the connection is from a non-browser client, the request MAY
include this header field if the semantics of that client match
the use-case described here for browser clients. The value of
this header field is the ASCII serialization of origin of the
context in which the code establishing the connection is
running. See <xref target="RFC6454"/> for the details of how this header field
value is constructed.<vspace blankLines="1"/>
As an example, if code downloaded from www.example.com attempts
to establish a connection to ww2.example.com, the value of the
header field would be "http://www.example.com".
</t>
<t> The request MUST include a header field with the name
|Sec-WebSocket-Version|. The value of this header field MUST be</t>
<t><vspace blankLines="1"/>
NOTE: Although draft versions of this document (-09, -10, -11,
and -12) were posted (they were mostly comprised of editorial
changes and clarifications and not changes to the wire
protocol), values 9, 10, 11, and 12 were not used as valid
values for Sec-WebSocket-Version. These values were reserved in
the IANA registry but were not and will not be used.
</t>
<t>The request MAY include a header field with the name
|Sec-WebSocket-Protocol|. If present, this value indicates one
or more comma-separated subprotocol the client wishes to speak,
ordered by preference. The elements that comprise this value
MUST be non-empty strings with characters in the range U+0021 to
U+007E not including separator characters as defined in
<xref target="RFC2616"/> and MUST all be unique strings. The ABNF for the
value of this header field is 1#token, where the definitions of
constructs and rules are as given in <xref target="RFC2616"/>.</t>
<t>The request MAY include a header field with the name
|Sec-WebSocket-Extensions|. If present, this value indicates
the protocol-level extension(s) the client wishes to speak. The
interpretation and format of this header field is described in
<xref target="section-9.1"/>.</t>
<t>The request MAY include any other header fields, for example,
cookies <xref target="RFC6265"/> and/or authentication-related header fields
such as the |Authorization| header field <xref target="RFC2616"/>, which are
processed according to documents that define them.</t>
</list>
</t>
<t>
Once the client's opening handshake has been sent, the client MUST
wait for a response from the server before sending any further data.
The client MUST validate the server's response as follows:</t>
<t><list style="numbers"><t>If the status code received from the server is not 101, the
client handles the response per HTTP <xref target="RFC2616"/> procedures. In
particular, the client might perform authentication if it
receives a 401 status code; the server might redirect the client
using a 3xx status code (but clients are not required to follow
them), etc. Otherwise, proceed as follows.</t>
<t>If the response lacks an |Upgrade| header field or the |Upgrade|
header field contains a value that is not an ASCII case-
insensitive match for the value "websocket", the client MUST
_Fail the WebSocket Connection_.</t>
<t>If the response lacks a |Connection| header field or the
|Connection| header field doesn't contain a token that is an
ASCII case-insensitive match for the value "Upgrade", the client
MUST _Fail the WebSocket Connection_.</t>
<t>If the response lacks a |Sec-WebSocket-Accept| header field or
the |Sec-WebSocket-Accept| contains a value other than the
base64-encoded SHA-1 of the concatenation of the |Sec-WebSocket-
Key| (as a string, not base64-decoded) with the string "258EAFA5-E914-47DA-95CA-C5AB0DC85B11" but ignoring any leading and
trailing whitespace, the client MUST _Fail the WebSocket
Connection_.</t>
<t>If the response includes a |Sec-WebSocket-Extensions| header
field and this header field indicates the use of an extension
that was not present in the client's handshake (the server has
indicated an extension not requested by the client), the client
MUST _Fail the WebSocket Connection_. (The parsing of this
header field to determine which extensions are requested is
discussed in <xref target="section-9.1"/>.)</t>
<t>If the response includes a |Sec-WebSocket-Protocol| header field
and this header field indicates the use of a subprotocol that was
not present in the client's handshake (the server has indicated a
subprotocol not requested by the client), the client MUST _Fail
the WebSocket Connection_.</t>
</list>
</t>
<t>
If the server's response does not conform to the requirements for the
server's handshake as defined in this section and in <xref target="section-4.2.2"/>,
the client MUST _Fail the WebSocket Connection_.</t>
<t>
Please note that according to <xref target="RFC2616"/>, all header field names in
both HTTP requests and HTTP responses are case-insensitive.</t>
<t>
If the server's response is validated as provided for above, it is
said that _The WebSocket Connection is Established_ and that the
WebSocket Connection is in the OPEN state. The _Extensions In Use_
is defined to be a (possibly empty) string, the value of which is
equal to the value of the |Sec-WebSocket-Extensions| header field
supplied by the server's handshake or the null value if that header
field was not present in the server's handshake. The _Subprotocol In