Technical Documentation

This documentation is only for Merchants who want to welcome users from the Homing Space eco-system. Regular users need not read this.

Read the main Docs+FAQ if you have not done earlier, and only then,read this. 

The word "ÿou" in this document represents the merchant or his/her tech representative


Initial steps

You or someone responsible from your organization should FIRST create his/her own Homing Space on his/her smartphone.  

It may be a good idea to invest in an inexpensive smartphone, and do this creation of the Homing Space inside that phone. (This does not need SIM card or any calling capability) Then keep such a "Homing" phone at a safe location with some responsible person of the organization.

This can be done in a few minutes. Note that when creating the homing space, you can get 7 persona names that can be used. Ideally, you should choose names that are very close to your names of the websties where you are going to implement Homing Space.

Summary of what needs to be done: 
Here is the flow that explains what happens:

The merchant gets the username, then signs an OTP with the username, current time and a secret sauce, formulates an endpoint query string -- and sends all of that to our internal API -- Our API then encrypts the data further with the user's public key and sends it to the user to welcome the user to the merchant's site.  Our API silently added the fingerprint to the endpoint that the authenticated user will visit. Once the user reaches the merchant's endpoint -- the merchant can retreive both the $_GET params as well as the $_POST params and the rest of the work is all up to that merchant! 

The next steps below describes this flow in great detail. You can always chat with us on our Gitter channel, if you want more help

Second step

Now head over to the utilities section,  select the "reveal keys" page and get the secret (private) keys revealed to you -- both for the box pair and the sign-pair.  This obviously has to be done in the same phone browser where you created your Homing Space (as explained in the Initial steps)

Homing Space uses the excellent NaCl cryptography system. It is a cryptographically audited system. That system needs one pair for the encryption using the secret-box system, and another pair for cryptographic signatures. 

Hence you need to create two files at proper location on your server where Homing Space users are to be welcomed. The names suggested in that "reveal" page is the one that you should ideally used -- as we used the same name in the example PHP code. Study the file in the fifth setp, and make sure that the secret keys are picked up properly from your website.

Third step

Once you have created the text files on the website server; you need to pick up your Secret Sauce -- which is the clever name that we gave for the "secret salt"  which is used to generate an OTP between you and our own website.  This is done using one of the utility pages. Select "Secret Sauce (For Merchants)" option -- it will list your earlier secret-sauces and also allow you to create more.

You should create a new secret-sauce for each website you use. Each secret-sauce has its own analytics and its own trial period -- so it would be very easy for you to manage your sites.  This secret-sauce has to be entered into the first sample file (See below)

Fourth step

We have 3 sample PHP files that you can copy and paste from the sample page here.

In this technical documentation, we are assuming that you are using PHP -- Obviously, you could implement the same logic using other languages too -- This system crucially needs the libsodium (NaCL) cryptography library and so you must have that library in your backend server language too) The algorithms used are quite straight-forward procedural programming. Not rocket science!

The first file in samples is the main entry page. It is called "merchant.php" But you can call it whatever you want, obviously. Study that carefully. 

This file is where you would be asking everyone to supply their Homing Space persona username.  i.e. it has  a form with just one INPUT tag asking for the user's username. The second field should be hidden (or readonly) and its value should be supplied; as per instructions given below.

The action of this form will be handled as a POST request by the second PHP file.  If you want you can add a captcha to the form if you think robots will keep putting up automated form submissions! 

Make sure you mention your own Homing Space persona username that you had used for this particular website -- the reason being that the same name would be shown to the user during the authentication process. He/she has to have the confidence that indeed he/she is coming to he same website back after the authentication.

A hidden field (or a readonly field) in this first file's form should mention the "scopes" as its value. 

What is a scope? It is some piece of data that your website wants from the user. These scopes are mentioned is a string. It is given as the value of that hidden field, in a special format. 

See the example carefully to understand the format of the string. It has two sections, both separated by the pipe (|) character. The first section is a semi-colon separated list of scope names. So is the second section. The first section are the mandatory scopes that the user HAS to give to the merchant after authentication. The second section lists  the optional scopes. That is also semicolon delimited.

If you want to ask no additional information from the user; give the value of this hidden field as "|" (Just a pipe character!)

There are several standard scopes that can  found in Homing Spaces of users. You MUST use the correct spelling and case, for those scopes that you want for your website. The current list is here.

It would be a good idea and gesture to actually provide some tips on all the scopes that you are collecting from the user -- that way, when a user wants to enter your site; he/she is fully aware that he/she is expected to give those data, quite clearly. 

(The example file does not do this too well, BTW. We were lazy and so we just used a readonly field to show the scope string directly. Some users may not understand the syntax)

You should NOT collect ANY OTHER information from the user at this point. If you do, it will violate the terms and conditions of Homing Space and we may retract the secret sauce given to you. 

Fifth step

This second  file in the aforementioned sample page is where the main logic of asymmetric encryption using the libsodium library of PHP would be carried out. In our example; it is called homingentry-sign.php 

It has all the documentation. Copy this file from the sample page and study it carefully in your editor. Maybe print it out and go line by line.

Make sure that all the configurable variables are given values as per your context -- do not use the sample values given in the sample file! (obviously!) 

Sixth step

This third and last file in the above sample page,  becomes the ending point where the user will reach if he/she successfully negotiated the Homing Space verification. In our example; we have simply used an OTP that is a MD5 hash on the concat of the usename+timestamp+some-salt.  See how that OTP was setup in the file used in the fifth step.

This OTP is now checked at your end, when the user finally ends up at this end point -- so that you are sure it was indeed the right user. To prevent replay of the same endpoint URL and query string, you could check the current time and ensures that the endpoint was invoked within say 10 seconds (or whatever time limit you want to impose)

What you do with the user once he/she reaches this endpoint is all upto you and your website -- you may, for example; enter the OTP into a session variable and use that as your internal code to retain the user's session. Or enter the OTP into a database and use that to store the work of the user.

Or, you can even pass this OTP from page to page as the user does the work on your site through a query string varialbe (if you do NOT want to use a cookie at all) or there could be other ways too on what happens to your site's workflow after the user reaches this endpoint. 

A good idea would be to store the value of the special scope: f_in_g of a new user. That is the fingerprint of the user. This is explained in detail below.

Special value passed by us on the endpoint querystring 
Before the user reaches the endpoint, the "fingerprint" of the user is also sent by our code at Homing space. An extra field would be added to the other field passed on by the above endpoint query_string. This special field is called: "f_in_g" The merchant can make use of its value for its own housekeeping!

The merchant can check if the same user is coming under a different persona name. How does this work?

Remember a user can have 7 personas in Homing Space? 

Internally all would have same fingerprint! The merchant can choose to disallow the same person taking more than one accounts at the same site of the merchant. For e.g. if there is a merchant offering some 10Gb space free, some people may want to get 20 Gb by registering twice there. But this f_in_g can catch many of such attempts

Though this does NOT prevent a complete prevention of fake, sybil (sock-puppet) accounts, it can surely reduce a large number of them 

BOTH query_string ($_GET) as well as $_POST are sent at that endpoint
Note that the parameters you had added in step 5 to that endpoint would be passed on verbatim on the query_string (Along with our special f_in_g) However, the endpoint also has POST data. So make sure your code picks up both. Primarily, the POSTed data at the end point would be the scope values given by the user in the dynamic form. These scope variables would have the letters "sc_" prepended to the field names. So watch out for that.

Seventh step

Go live! There is nothing more to be done!  

Notice that there is NO separate logic for registration and another one for login. Homing Space users, once they get authenticated; they are transparently registered if they did not exist earlier at a website! So obviously, it is likely that there would be some database activity after the endpoint.

There are a million things that software architects can do once a user has succesfully registered/login at the site!

All the best and let us know if you get stuck somewhere, chat with us at our Gitter room