Social Stream Presence REST API

Social Stream Presence provides a secure mechanism to access to his REST API over HTTP.
By default the access to the Social Stream Presence REST API will be performed with basic access, that it's perfectly valid (and recommended) to work in local mode or to work in remote mode when traffic between Web and Xmpp server is exchanged by trust networks.
If you want to open your REST API to thirds or if traffic between your own Web and Xmpp server isn't exchanged by trust networks, you probably want, and in this case it's highly recommended, to enable secure access to Social Stream Presence REST API.

1. Enabling Secure Access to Social Stream Presence Rest Api
2. Social Stream Presence Rest Api Scheme
3. Writing Requests to Social Stream Presence Rest Api

 

Enabling Secure Access to the Social Stream Presence Rest Api

Install OpenSSL Libraries

In order to allow encryption and decryption features we need to install the following libraries in the Web Server and the Xmpp Server :

sudo apt-get install openssl

sudo apt-get install libopenssl-ruby

Generating RSA Keys

If you execute the automatic installation with secure access enabled, the RSA Keys have already been generated.

Otherwise, you can generate it automatically executing the following rake task in the Web Server:
rake presence:install:generate_RSA_keys
 

Generated Folders and Files:
 
Web Server Keys Path: social_stream/presence/rsa_keys/
Xmpp Server Keys Path: scripts_path/rsa_keys/

WebServerKeysPath/web_rsa_key_public.pem
WebServerKeysPath/web_rsa_key_private.pem
WebServerKeysPath/xmpp_rsa_key_public.pem

XmppServerKeysPath/xmpp_rsa_key_public.pem 
XmppServerKeysPath/xmpp_rsa_key_private.pem 
XmppServerKeysPath/web_rsa_key_public.pem 

In the Web Server: Change Social Stream Presence initializer:

  #Uncomment to enable REST API Security
  config.secure_rest_api = true

In the Xmpp Server: Change ssconfig.cfg

#True to enable REST API Security
secure_rest_api=true

 

Social Stream Presence Rest Api Scheme

 
Depending if the secure access is enabled or not, we have two different types of requests:

• In non secure mode we only can include non-encrypted parameters in the request. The password is sent in clear too.
• In secure mode we can include in the request clear parameters, encrypted parameters, or a combination of both.
• The stamp split is #####.
• The timestamp format is UTC.
• The hash function is non-standard, the implementation is as follows:

                 Params Hash function implementation
       
        Where request_params = {:key1=>value1,:key2=>value2,...,:encrypted_params=>encryptedValue}

• Secure mode protects data exchanged between Xmpp and Web server.
• Secure mode protects against Man-In-The-Middle attack.

 

Secure mode is transparent to the API methods, their implementation not be affected.
The parameters received by the API method are as if they had sent in clear.

API methods return a string that contains "Ok" when the request has been processed properly.

Writing Requests to Social Stream Presence Rest Api

Social Stream presence provides an script located in scripts_path/rest_api_client_script to make HTTP requests to the Social Stream Presence API.
The script will performs the basic access or secure access type requests depending on the configuration established.
We can write our own api calls in a easy way using rest_api_client_script:

def myHook(param1,param2)
    log($script_title,"Call #{getMethodName}(#{param1},#{param2})")
    url = "http://" + getWebDomainUrlFromDomain(domain) + "/xmpp/hookRoute"

    params = {}
    encrypted_params = {}
    #Add params to sent in clear
    params[:param1_in_server]=param1
    #Add params to sent cipher
    encrypted_params[:param2_in_server]=param2

    return [getMethodName,generic_api_call(url,params,encrypted_params)]
end

In encrypted_params we must include the params wanted to be cipher, anyway, if secure access is disable, encrypted_params will be send in clear.
Also, we must replace "/xmpp/hookRoute" by the route mapped to our desired API method.

To execute the call we must execute:
./rest_api_client_script myHook param1 param2