prepareSecure API Usage

Some protocols (e.g. XMPP, but not HTTP) use STARTSSL to upgrade to secure mid-connection. In order to make these secure sockets on Chrome, users of Freedom's core.tcpsocket API must make use of the .prepareSecure method. prepareSecure works in Chrome by setting a socket to be paused after the next read, so that the tcpsocket .secure method can be called following the read.

For example, in the standard XMPP starttls flow users of a core.tcpsocket would do the following:

1. Create a core.tcpsocket object
2. Call .connect on the socket to connect to the XMPP server. Note that when using secure sockets, the socket must be connected using a domain name and not an IP address.
3. Write an init XMPP stream message to the socket.
4. Read an init XMPP response from the server.
5. At this point prepareSecure should be called on the socket
6. Write a starttls message to the socket.
7. Read a proceed response on the socket
8. Call secure on the socket
9. Now the socket has been upgraded to use a TLS connection

prepareSecure was implemented as a workaround for issues in chrome.sockets.tcp.setPaused. The Chrome team is investigating how to fix setPaused in https://code.google.com/p/chromium/issues/detail?id=467677. Once this is resolved and new versions of Chrome are available, the prepareSecure method can be removed.

Calling prepareSecure for non-Chrome sockets (e.g. freedom-for-firefox or freedom-for-node) is safe to do and will have no effect.

Usage

socket.connect(host, port).then(function() {
  socket.once('onData', function() {
    socket.secure();
  });
  // prepareSecure must be called one 'message' before secure(), to
  // provide an alert to the underlying system that it may need to pause
  // its read loop.
  return socket.prepareSecure();
});