-
Notifications
You must be signed in to change notification settings - Fork 52
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:
- Create a core.tcpsocket object
- 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.
- Write an init XMPP stream message to the socket.
- Read an init XMPP response from the server.
- At this point prepareSecure should be called on the socket
- Write a starttls message to the socket.
- Read a proceed response on the socket
- Call secure on the socket
- 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.
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();
});