Subject: [hybi] failed TLS handshake: which close code?

From: Tobias Oberstein <[email-masked]>
Date: Mon, 24 Oct 2011 00:58:13 -0700

Hybi-17:

"""
4. Opening Handshake
...
4.1. Client Requirements
...
   5.  If /secure/ is true, the client MUST perform a TLS handshake over
       the connection after opening the connection and before sending
       the handshake data [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.  [RFC5246]
"""

When the client fails the TLS handshake (i.e. because of invalid server certificate),
which close status code would be appropriate to use for signaling that specific
reason to the caller?

Is it supposed to use a close status code from the following range?

"""
   3000-3999

      Status codes in the range 3000-3999 are reserved for use by
      libraries, frameworks and application.  These status codes are
      registered directly with IANA.  The interpretation of these codes
      is undefined by this protocol.
"""

Or are those only for "use on wire" not for signaling the caller?

For example, Firefox currently provides the calling JavaScript with a "1006 Abnormal Connection Close":

"""
  1006

      1006 is a reserved value and MUST NOT be set as a status code in a
      Close control frame by an endpoint.  It is designated for use in
      applications expecting a status code to indicate that the
      connection was closed abnormally, e.g. without sending or
      receiving a Close control frame.
"""

However, this could be multiple things and is not giving the real reason to the JS.
The JS thus can't react specifically ..

---

From: Alexey Melnikov <[email-masked]>
Date: Mon, 24 Oct 2011 14:04:29 +0100

That was supposed to be sent to the mailing list. The WG should consider
adding multiple codes if needed.

---------- Forwarded message ----------
From: Alexey Melnikov <[email-masked]>
Date: Mon, Oct 24, 2011 at 1:34 PM
Subject: Re: [hybi] failed TLS handshake: which close code?
To: Tobias Oberstein <[email-masked]>

Hi Tobias,

> The JS thus can't react specifically ..

TLS handshake probably deserves a separate 1XXX close code.

---

From: Alexey Melnikov <[email-masked]>
Date: Mon, 24 Oct 2011 14:09:54 +0100

On a second thought: TLS fails before WebSocket connection is established,
so (unless I am missing something) TLS related close codes will never be
sent on the wire. However reserving some WebSocket codes is still a good
idea.

On Mon, Oct 24, 2011 at 2:04 PM, Alexey Melnikov
<[email-masked]>wrotetL

---

From: Peter Thorson <[email-masked]>
Date: Mon, 24 Oct 2011 08:09:54 -0500

On Oct 24, 2011, at 8:04 , Alexey Melnikov wrote:

> That was supposed to be sent to the mailing list. The WG should consider adding multiple codes if needed.
> 

What is the procedure right now for adding more 1XXX close codes? In addition to TLS stuff, I still think (and a few here have agreed) that we also need a 1XXX code similar in meaning to HTTP 500/"internal server error"

---

From: Alexey Melnikov <[email-masked]>
Date: Mon, 24 Oct 2011 14:19:38 +0100

On Mon, Oct 24, 2011 at 2:09 PM, Peter Thorson <[email-masked]>wrote:

> What is the procedure right now for adding more 1XXX close codes?

People should suggest specific close codes on the mailing list and, ideally,
suggest their description.

For codes recommended this week or next (basically before the final RFC is
published), there is a good chance that they can be included directly into
the RFC-to-be.

Close codes suggested later can still be added to the registry (they will
need a review by a yet-to-be-appointed Expert Reviewer -- IESG will take
care of this), but they will not appear in the RFC.

All of the codes will be seen in the IANA registry (<
http://www.iana.org/assignments/websocket/websocket.xml>)

> In addition to TLS stuff, I still think (and a few here have agreed) that
> we also need a 1XXX code similar in meaning to HTTP 500/"internal server
> error"

Agreed.

---

From: "Richard L. Barnes" <[email-masked]>
Date: Mon, 24 Oct 2011 09:22:13 -0400

+1

It's silly to require the WS implementation to send a close frame in plaintext after the TLS connection fails.  I don't even think this sort of thing would be supported by standard TLS libraries.

--Richard

On Oct 24, 2011, at 9:09 AM, Alexey Melnikov wrote:

> On a second thought: TLS fails before WebSocket connection is established, so (unless I am missing something) TLS related close codes will never be sent on the wire. However reserving some WebSocket codes is still a good idea.
> 
> On Mon, Oct 24, 2011 at 2:04 PM, Alexey Melnikov <[email-masked]> wrotetL
> On Mon, Oct 24, 2011 at 3:58 AM, Tobias Oberstein <[email-masked]> wrote:
> Hybi-17:
> 
> """
> 4. Opening Handshake
> ...
> 4.1. Client Requirements
> ...
> _______________________________________________
> hybi mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/hybi

---

From: Alexey Melnikov <[email-masked]>
Date: Mon, 24 Oct 2011 14:29:24 +0100

Hi Richard,

On Mon, Oct 24, 2011 at 2:22 PM, Richard L. Barnes <[email-masked]> wrote:

> +1
>
> It's silly to require the WS implementation to send a close frame in
> plaintext after the TLS connection fails.  I don't even think this sort of
> thing would be supported by standard TLS libraries.
>
Right. But the TLS-related code(s) might have to be allocated for use in the
WebSocket API.

> > On a second thought: TLS fails before WebSocket connection is
> established, so (unless I am missing something) TLS related close codes will
> never be sent on the wire. However reserving some WebSocket codes is still a
> good idea.
> >

---

From: "Richard L. Barnes" <[email-masked]>
Date: Mon, 24 Oct 2011 09:53:28 -0400

To quote the WebSocket API:
"
If the user agent was required to fail the websocket connection or the WebSocket connection is closed with prejudice, fire a simple event named error at the WebSocket object.
"

So if TLS fails and the client has to _Fail the WebSocket Connection_, then the API only reports an error; it does not provide a close code.  Which is appropriate, because the existence of a close code presumes the existence of an established WS connection, which does not exist in this case.

--Richard

On Oct 24, 2011, at 9:29 AM, Alexey Melnikov wrote:

> Right. But the TLS-related code(s) might have to be allocated for use in the WebSocket API. 
> 
> --Richard
> 
> 
>

---

From: Peter Thorson <[email-masked]>
Date: Mon, 24 Oct 2011 09:02:42 -0500

On Oct 24, 2011, at 8:19 , Alexey Melnikov wrote:

> On Mon, Oct 24, 2011 at 2:09 PM, Peter Thorson <[email-masked]> wrote:
> 
> People should suggest specific close codes on the mailing list and, ideally, suggest their description.
> 
> For codes recommended this week or next (basically before the final RFC is published), there is a good chance that they can be included directly into the RFC-to-be.
> 
> Close codes suggested later can still be added to the registry (they will need a review by a yet-to-be-appointed Expert Reviewer -- IESG will take care of this), but they will not appear in the RFC.
> 
> All of the codes will be seen in the IANA registry (<http://www.iana.org/assignments/websocket/websocket.xml>)
>   
> In addition to TLS stuff, I still think (and a few here have agreed) that we also need a 1XXX code similar in meaning to HTTP 500/"internal server error"
> Agreed.

I that case like to propose the following code:

1011/Internal Endpoint Error

1011 indicates that an endpoint is terminating the connection due to an unexpected condition that prevents it from safely continuing. The condition is the result of an internal logic error and not the fault of the remote peer except tangentially (i.e. in cases where the remote peer sent a valid frame that the terminating endpoint could not understand). More information about the error may be available in the terminating endpoint's log files.

---

From: Tobias Oberstein <[email-masked]>
Date: Mon, 24 Oct 2011 07:55:24 -0700

Yep, its not about _sending_ a close frame (which would be silly). Its about signaling the application.

There are already two close code which must not be used on the wire and are
only there for signaling errors to the application: 1005 and 1006.

The spec says they must not be used on wire, the spec does not speak about
whether the codes must only be used when a WS connection previsously existed ..

Von: [email-masked] [mailto:[email-masked]] Im Auftrag von Alexey Melnikov
Gesendet: Montag, 24. Oktober 2011 15:29
An: Richard L. Barnes
Cc: [email-masked]
Betreff: Re: [hybi] failed TLS handshake: which close code?

Hi Richard,
On Mon, Oct 24, 2011 at 2:22 PM, Richard L. Barnes <[email-masked]<mailto:[email-masked]>> wrote:
+1

--Richard

On Oct 24, 2011, at 9:09 AM, Alexey Melnikov wrote:

> On Mon, Oct 24, 2011 at 2:04 PM, Alexey Melnikov <[email-masked]<mailto:[email-masked]>> wrotetL
> From: Alexey Melnikov <[email-masked]<mailto:[email-masked]>>
> To: Tobias Oberstein <[email-masked]<mailto:[email-masked]>>
>
>
> Hi Tobias,
>
> On Mon, Oct 24, 2011 at 3:58 AM, Tobias Oberstein <[email-masked]<mailto:[email-masked]>> wrote:
> Hybi-17:
>
> """
> 4. Opening Handshake
> ...
> 4.1. Client Requirements
> ...
> [email-masked]<mailto:[email-masked]>

---

From: Tobias Oberstein <[email-masked]>
Date: Mon, 24 Oct 2011 07:57:11 -0700

> If the user agent was required to fail the websocket connection or the
> WebSocket connection is closed with prejudice, fire a simple event named
> error at the WebSocket object.
> "
> 
> So if TLS fails and the client has to _Fail the WebSocket Connection_, then
> the API only reports an error; it does not provide a close code.  Which is
> appropriate, because the existence of a close code presumes the existence
> of an established WS connection, which does not exist in this case.
> 

But the text of above (step 2) spec continues (with step 3):

"
Create an event that uses the CloseEvent interface, with the event name close, which does not bubble, is not cancelable, has no default action, whose wasClean attribute is initialized to true if the connection closed cleanly and false otherwise, whose code attribute is initialized to the WebSocket connection close code, and whose reason attribute is initialized to the WebSocket connection close reason decoded as UTF-8, with error handling, and dispatch the event at the WebSocket object.
"

I'm not sure: does step 2 prevent doing step 3?

In any case:

a) Firefox currently fires "close" with 1006 "Abormal Close" on TLS invalid cert. failure

b) If no WS close code will be reserved for "TLS invalid cert", then what alternative is there to signal that specific error condition to the app?

c) Why is it so bad to have a code never used on wire, but used to signal an error that happened before a WS connection was established?

---

From: Tobias Oberstein <[email-masked]>
Date: Mon, 24 Oct 2011 08:06:41 -0700

> 1011 indicates that an endpoint is terminating the connection due to an unexpected condition that prevents it from safely continuing. The condition is the result of an internal logic error and not the fault of the remote peer except tangentially (i.e. in cases where the > > remote peer sent a valid frame that the terminating endpoint could not understand). More information about the error may be available in the terminating endpoint's log files.

+1

1012/Service Restart
1012 indicates that the service is restarted. a client may reconnect, and if it choses to do, should reconnect using a randomized delay of 5 - 30s.

Use case:
restart a service with 100k clients connected
clients present an informative user notification ("service restarting .. reconnecting in N secs) 
clients should not reconnect all at exactly the same time .. thus the randomized delay

1013/Service Overload
1013 indicates that the service is experiencing overload. a client should only connect to a different IP (when there are multiple for the target) or reconnect to the same IP upon user action.

Use case:
clients present an informative user notification ("service overload .. try later or try different IP)

---

From: Tobias Oberstein <[email-masked]>
Date: Mon, 24 Oct 2011 08:24:42 -0700

TLS handshake failure codes proposal:

1014/ TLS Handshake Failed By Client : The TLS handshake was failed by the client (unspecific).

1015/TLS Handshake Failed By Server : The TLS handshake was failed by the server (unspecific).

1016/TLS Handshake Failed By Client - Invalid Server Certificate :  The TLS handshake was failed by the client due to the server certificate being invalid or not accepted.

1017/TLS Handshake Failed By Server - Invalid Client Certificate : The TLS handshake, where the server requested a client certificate, was failed by the client due to the client certificate being invalid or not accepted.

---

From: "Richard L. Barnes" <[email-masked]>
Date: Mon, 24 Oct 2011 12:07:33 -0400

This is pointless.  These codes are not needed by the WS API, since a TLS failure does not provide a close code.  These codes are not needed by the WS protocol, since neither party will send a close frame (since there's no TLS channel).  

--Richard

---

From: Tobias Oberstein <[email-masked]>
Date: Mon, 24 Oct 2011 09:25:41 -0700

> This is pointless.  These codes are not needed by the WS API, since a TLS
> failure does not provide a close code. 

Well, both Chrome (16.0.912.10 canary) and Firefox (10.0a1 (2011-10-24))
_do_ fire the onclose() event handler with 1006 when the WS connection cannot
even be established (host unreachable).

Firefox fires the onclose() with 1006 also for WSS when the server cert is invalid.
Chrome currently does not check WSS server cert (unrelated beh./bug).

So both browsers are wrong?

Anyway: what is your recommendation for WS API for _apps_ (JavaScript) to recognize "invalid server cert"?

---

From: John Tamplin <[email-masked]>
Date: Mon, 24 Oct 2011 12:28:11 -0400

> recognize "invalid server cert"?

As this doesn't have anything to do with the wire protocol, that question
would be better asked on the WHATWG list for the WS API.

-- 
John A. Tamplin
Software Engineer (GWT), Google

---

From: "Richard L. Barnes" <[email-masked]>
Date: Mon, 24 Oct 2011 12:29:32 -0400

+1, I was about to say the same thing.
--Richard

On Oct 24, 2011, at 12:28 PM, John Tamplin wrote:

> On Mon, Oct 24, 2011 at 12:25 PM, Tobias Oberstein <[email-masked]> wrote:
> As this doesn't have anything to do with the wire protocol, that question would be better asked on the WHATWG list for the WS API.
> 
> -- 
> John A. Tamplin

---

From: "Richard L. Barnes" <[email-masked]>
Date: Mon, 24 Oct 2011 12:30:53 -0400

Quoting the same part of the WS API spec as I did earlier:
"
If the user agent was required to fail the websocket connection or the WebSocket connection is closed with prejudice, fire a simple event named error at the WebSocket object.
"

A TLS failure requires the UA to fail the websocket connection, and should result in an error event, not a close event.  So it seems that Chrome and Firefox are not following the spec in this regard.

--Richard

---

From: Gabriel Montenegro <[email-masked]>
Date: Mon, 24 Oct 2011 23:40:20 +0000

I believe the discussion on WS API is held at the W3C webapps WG:
http://www.w3.org/2008/webapps/

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf Of
> Richard L. Barnes
> Sent: Monday, October 24, 2011 09:30
> To: John Tamplin
> Cc: [email-masked]; Peter Thorson
> Subject: Re: [hybi] Fwd: failed TLS handshake: which close code?
>