Monday, April 8, 2013

Integrating ELC into your community

Introduction


This article will explain how you can integrate the ELC system into your community - using MegaDownloader 0.8
For an overall view of the ELC system, please refer to the article: "Understanding mega:// links", section "ELC links".
Required knowledge: This article presupposes you have some knowledge about cryptography, hashing, BD, and HTTP protocol.

Server validation

ELC requires a server to perform two actions:
- Validate users, so only users of your community will be able to download the files.
- Encode or decode the internal password that will allow users to download the files.

Two pages are required:
- One page to show the users of your community HOW to configure their MegaDownloader/MegaUploader ELC account.
- One page to validate the data and perform the password encode/decode.

User validation

Each user will have two unique codes that will let them identify into your system. You have to provide them to your users using the first page.
The first code is the "Username", a public code that will identify which user wants to download the files.
The second code is the "API-Key", a private code that will validate the user as a valid member of your community.
Apart of that, you should also display to the user the URL of the second page (the one that validates the data).

This API-Key should NOT be the user's password. Using the user's password represents a security issue, because if you don't use SSL, the data will travel unencrypted.
The API-Key should be a code that validates the user for the ELC usage, and nothing else. If a third person gets the user's API-Key, he shouldn't be able to modify the user's account, or anything like that. An API-Key should also be regenerated when the user changes his password.

A good API-Key would be, for example, the hash generated from concatenating  the username and the hashed password stored in your system - normally you store a hash, not the plain password of the user. If the user changes his password, the API-Key will be changed, because the hashed password has been changed.
If you also add a random salt when generating the hash, then security is increased.
Normally communities use a CMS or forum, with their own tables where user data is stored.

For example, if your community DB has a table called "user", with two columns "username" and "password", you could do something like:
1) Get the value of the username and his (hashed) password.
2) Concatenate a random salt string to the username and the (hashed) password (optional but recommended).
3) Generate a hash (preferably a SHA256 or SHA512, it's longer but also more secure than MD5).

This final hash could be the API-Key.

Data process

So, in your first page, the one that displays the user's data to configure his ELC account, you should generate and display the API-Key. The page should also display the Username and the URL of the second page.

The second page will be used internally by MegaDownloader. You can find here a PHP example of this page.
Of course, if your system doesn't use PHP but another language (Java, .NET, etc) you should adapt the example to that language.
This page will receive HTTP POST petitions, so this page should not allow GET petitions - if a user puts this URL in his browser, an error should be displayed because this page is designed to be accesed with a POST petition.

Input
MegaDownloader and MegaUploader will send 4 POST parameters when generating an ELC or when reading an ELC:

- Parameter "USER": Will contain the user's code.
- Parameter "APIKEY": Will contain the user's API-Key.
- Parameter "OPERATION_TYPE": Two possible values: E or C.
- Parameter "DATA": a string containing the data to process.

The first two parameters are used for validating the user; the other two parameters are used for processing the data.


Output
The page will return, in all cases, a JSON response.

If there is an error (invalid user access, invalid data, etc), the page will return this structure:

{"e": "'ERROR DESCRIPTION", "d": ""}

If there is no error, the page will return this structure:

{"e": "", "d": "PROCESSED DATA"}

As you can see, only two parameters are returned: e (error) and d (data). One must be empty and the other filled.





The page will perform two different actions:

- First, it will validate the user by using the data contained in the "USER" and "APIKEY" parameters. If the user is not validated, then an error will be returned and the page won't continue with the second action.

- Once the user has been validated, then the page will process the data (by using the other two parameters "OPERATION_TYPE" and "DATA".

"OPERATION_TYPE" parameter will contain E or C (any other value will cause an error to be returned). E means Encrypt, and D means Decrypt. So basically, you will take the data contained in the "DATA" parameter, and will encrypt it or decrypt it depending on the value of "OPERATION_TYPE".
It's very important to emphasise that the input data of the E operation must be equal to the output data of the D operation, when the E output and the D input is the same. The encryption process must be simmetric!!

The way to implement the encryption/decryption process is up to you. But if you just want "something that works", then you can use the example provided previously.

The example page doesn't contain a "good" implementation of the first action: it just compares the USER and APIKEY values with a constant text. This is because depending on how your community works, you can make one implementation or another; the general idea of how it should work was provided in the previous paragraphs.

However, the second action is fully implemented. In the example, an AES cipher is performed to the data provided. You can use this example "as is", just changing the password at the beginning of the code.
If you prefer, you can implement the proces on another way. You can store the input data in your DB, and return the numeric ID of the inserted row. The decrypt process will receive the numeric ID, and you will retrieve the original information. It's perfectly valid - just take into account that this requires DB access, most resource consuming than performing an AES "on the fly".

How can you test this page?
The simplest way is by using Firefox  + an extension called "POSTER". You can also create a basic HTML form that POST the data to that URL, and open it with a browser. It's up to you.

Easy ELC configuration - Just click!

For users with little knowledge about computers, configuring the ELC can be confusing/difficult. For that reason, a "click once configuration" method has been created.

The idea is that the user click on a link, and MegaDownloader automatically configures the ELC account for the first time. That's all! The user has to do nothing else :D

In the page where you show the ELC information to the user, you should implement a mega:// link to do that. This mega:// link should be like this (copying the link also works if MegaDownloader is configured to detect links from clipboard):
mega://configelc?http%3A%2F%2Ftest.com%2Felc%3Fa%3D1%26b%3D2:User%20Name:Api%20Key:Account%20Alias

As you can see, it's a mega:// link with the "configelc?" code. After that, there should be 4 parameters, each one separated with a ":" character:
- Parameter 1: The ELC URL of your site, URI encoded (you can do it with Javascript using encodeURIComponent). In this example, the URL is "http://test.com/elc?a=1&b=2" (note you can use & or ? if you need it)
- Parameter 2: The user name of the user, URI encoded. In this example "User name" (note it supports spaces and other strange characters).
- Parameter 3: The API-Key of the user, URI encoded. In this example "Api key" (note it supports spaces and other strange characters).
- Parameter 4: This is an optional parameter, you can specify the Alias of the ELC account, URI encoded - in this example "Account alias".

When the user clicks on the link, MegaDownloader will ask the user if he wants to create/update the ELC account. If he says "Yes", then the ELC account configuration will be imported - and he has to enter no data at all!

Conclusion

For users, adding an ELC account should be easy - just clicking on a link.
For developers, creating the ELC pages should be also easy - the ciphering method is provided in the example, and only an user validation system has to be implemented.

Using ELC is a solid and robust system to protect your MEGA links so they can't be reported, and people outside your community can't download them.