Push Socket Protocol

NOTE: Sockets are implemented using socket.io. For documentation beyond the protocol structure, visit http://socket.io/docs/ #Connect to Server from the Client

1. Open a connection with the server

   var socket = ioClient.connect({"server_url"});

2. Once a connection is established, push the clients authentication credentials to the server with message title "authentication"

   socket.on('connect', function (data) {
       socket.emit('authentication', { username:{"auth_username"}, password:{"auth_password"};
   });

   • auth_username is of the form base64(identityKey)|deviceId where base64(identityKey) is your longterm public key base 64 encoded and deviceId is the device ID of the device you are making the request from.
   • auth_password is of the form timestamp|signature(timestamp) where timestamp is the current unix time as an integer and signature(timestamp) is a signature of the unix time from your longterm private key.

3. After pushing the authentication message and credentials, the client will receive one of two responses back from the server:

   1. The server will push an authorized message. It is not necessary to take further action upon receipt of this message, but it is provided as a notification that authorization succeeded. It can be received in the following way:

      socket.on('authorized', function(data) {
          //lets you know that socket.emit('authentication'... was successful
      });

   2. The server will push a not authorized message. This message will include data that will detail why authorization failed and help the client make a valid request on subsequent attempts. This message can be received in the following way:

      socket.on('not authorized', function(data) {
          var reasonForFailure = data.message;
          if (reasonforfailure == "time") {
              var serverTime = data.serverTime;
          }
          //proceede based on reasonForFailure
      });

      • data.message can take the following values:
        • "badly formed credentials" indicates that the submitted auth_username and/or auth_password were missing or had the wrong format
        • "revoked" indicates that the identity key submitted as part of auth_username has been revoked
        • "signature" indicates that the signature submitted as part of auth_password could not be verified
        • "not registered" indicates that the identityKey/deviceId combo submitted as auth_username has not yet been registered with the key server
        • "time" indicates that the timestamp submitted as part of auth_password is either out of sync with the server or too stale to accept. In this case, there is also a data.serverTime value which contains a timestamp from the server in unix time as an integer. This timestamp can be signed to create a valid password.

#Receive Messages from the Server Once a connection is created and the client is authorized successfully, messages are received in the following way:

socket.on('message', function(messageData) {
    //confirm reception of message
    socket.emit('recieved', {messageId: messageData.id});
    
    var messageHeader = messageData.header; //same header that was sent to server
    var messageBody = messageData.body;     //same body that was sent to server

    // do something with messageData here
    // ...    
});

• messageData.header is a base64 encoded string that contains the header of the out-band message
• messageData.body is a base64 encoded string that contains the body of the out-band message