Combu 3.0 beta

Hi folks, Combu 3.0 beta has been released, since it’s a closed beta (we like to test deeper before releasing to the public) you need to apply here in order to get the free access to this package, we appreciate the help of anyone willing to take part to the closed beta.

This version is not just a simple update, it’s a huge refactor of both server side scripts and client code, and a great improvement in security! Let’s see the new features and how the code changed (we recommend to use this version on a temporary test environment created ad hoc, not on the live production server of your current game/app).

 

PHP version 5.5 or later

The minimum version of PHP required to run the Combu server code is now 5.5, it was released back in 2013 so all providers should theoretically have at least this version installed nowadays. We also got rid of short PHP tags from all PHP files, so from this version and later you will not need to edit php.ini to enable short_open_tag any more!

If you are using XAMPP or any other package for local machine development (or you want to know what version is installed on your hosting) then create a new PHP file and paste the following code:

<?php
// Edit file: phpinfo.php
phpinfo();
?>

You should see something like this screenshot (any version equal or greater 5.5 should be fine, if you’re running older version of PHP then you must upgrade it to the latest stable or at least 5.5):

 

Compatibility with Composer

We severely refactored the server side scripts and library of Combu, the version 3 implements the compatibility with Composer. If you don’t know Composer, it’s becoming a pretty standard dependency manager in PHP programming and allows to easily manage your code by autoloading the classes upon use (just type “use MyNamespace\MyClass;” at the top of your PHP file and the Composer autoloader will magically include the class file on-the-fly without the need to “manually” include/require the source file). Another cool feature of Composer is the ability to install other open source libraries from the Packagist repository with a simple command on a prompt shell, for example we added the newest PHPMailer (the library that we use to send emails from web) and phpseclib (the library we use now to encrypt data, read below).

The installation of a library from the public Packagist repository is only matter of executing the following command in the prompt shell from the root folder of your Combu server:

composer require <vendor_name>/<package_name>

For example, we used the following command to install PHPMailer: composer require phpmailer/phpmailer

By running this command, Composer creates the following hierarchy tree in the folder where you run the command:

  • vendor (all libraries installed through composer require are installed inside this folder)
    • bin (you could use this folder for binary files for download, for example the installation setup of your game/app)
    • composer (contains the core files of Composer autoloader)
    • <other vendor folders>/<package folders> (all packages in Composer have a vendor name and a package name, for example: phpmailer/phpmailer)

Once you have installed the library with Composer, you only need to use its classes:

<?php
use Combu\Utils;
Utils::EchoJson(array("key"=>"value"), TRUE);
?>

Note: in order to use Composer autoloader, you’ll need to include it before using with “include_once ‘vendor/autoload.php’;” (you can see this line was added in our /lib/api.php).

 

Namespace, Classes, Database and Setup

Part of the server side refactoring involved the creation of the namespace \Combu in our server library (the library is now located in /vendor/skaredcreations/combu) and all our classes have been added into this namespace for cleaner coding. Also we renamed all our classes and table names by removing the “CB_” prefix (for example: CB_Account was renamed to Account), but in version 2.1.13 we added a constant for prefix of table names so all you have to do in order to use the old table names is to add the following line in your /lib/config.php (though we also created a new table to store the RSA/AES keys of each client connection, we will provide a SQL script to upgrade your database later when this version will be released to the public):

define ("GAME_DB_PREFIX", "CB_");

Another cool change was the creation of a web page to create the config.php content and the database SQL script on-the-fly, so by now you will navigate to http://localhost/combu/_setup (or similar URL on your local/production server) to create the configuration content (to copy&paste in your config.php) and the SQL statements (to copy&paste in your phpMyAdmin or other MySql manager):

    

We recommend to delete the folder /_setup after you have created the configuration content and the database script (you could keep it in your local development server, in case you’ll need to make changes to the config or add prefix to table names and recreate the database script). Anyway if your /lib folder has write permission then you can save the configuration file directly from the /setup pages, and consequently (after having saved the configuration) you can also execute the query script to create the tables on database from there.

The database functions (to connect and execute queries) have been also refactored and now are using mysqli_* instead of the deprecated mysql_*, though we also developed an experimental version DatabasePDO class that uses PDO for even more support to other database engine (anyway we officially support only MySql at this moment, but we’re planning to add support to other database engine in the future). You can select to use mysqli or PDO within the configuration page (set the define GAME_DB_USE_PDO to TRUE or FALSE).

 

Security: RSA + AES encryption

Many users (including myself) are always concerned about security to limit the possibility to read (and eventually change) on-the-fly the request data sent from clients to web services, and we’re always looking for the optimal way to improve the security. So we finally chose to implement a generally common way to improve it: RSA + AES encryption.

So here is the new flow that the client-server communication follows by now:

  1. When the client starts, it calls a web service on the server to initialize the session
  2. The server generates a new session token and RSA public/private keys (2048-bit by default, configurable in config.php) for that client, stores the data in the new table SessionToken and returns the token and RSA public key to the client
  3. The client generates new AES (256-bit) Key/IV and send them to the server, Key and IV are sent encrypted with the RSA public key that was previously received from server so a potential attacker is not able to decrypt these keys (in RSA you can encrypt with the public key, but you require the private key to decrypt: the private key is never sent to the client, only the server knows the private key and it is generated on-the-fly for each client upon connection, so every client has different public/private keys!)
  4. From now on, all the request data sent from client to server are encrypted with the AES Key/IV and decrypted from server

Here is the difference between the old and new link to the server info web service:

// Old link
http://localhost/combu/server.php?action=info

// New link
http://localhost/combu/server.php?token=Q0ItNThhNmQzNjVlMzlkYTguMTIzNTgxNDc%3d&data=2h9Ta4X9Rfdt2HhfqyMdMutsNAWjE%2fsglMh1JBUhS3vnSDO3KqJ7zxZo1icXQ%2fNxHvbbC1lc%2fHsvWsWjxJ4Csg%3d%3d

By adding a define for RESPONSE_ENCRYPTED with a value of TRUE in your config.php, you can enable the encryption of server responses too, here is the difference:

// RESPONSE_ENCRYPTED undefined or FALSE
{success:true, message:"OK"}

// RESPONSE_ENCRYPTED defined as TRUE
{"t":"2017-04-18 20:32:09","d":"vWH4DEOwj+GI34QOgHzuYWR\/ujyCknkXolco17eeA8NbSDeGJkMARvZtgLP5Nuc5T8+K4OiHPbTnFVcdX+oEEzBilF5UlKVwVyYtF2Xh4M3v12OEs8WivlPwiF8sHg5\/DMZ85h0wJOP979aIebGxNaJMJI\/qT5DJ2WzLDkLZPjI7IT7OmpX8THKQIYegpXWdb\/6Gsb9o0IVzFgcvT9Tq0Anl3unBgQp9tZ7Yem2Vak6+QOsBS4qJkqiNvovoQ3Hpyfq5t2q0Xi4N\/e8rqqlG7hOZxW5nQYzPG6Cv4aQ6BNY4L4T5LruFZALLWgk6lvkMC5gIy2K9dCBlLq1R0QI6mQEFvxNmip28zjOT4eytTAU="}

As you can see, the request and response data are no more readable unless you have the correct keys to decrypt.

 

Localized error messages

We implemented the localization of the error messages sent to clients from web services, the messages are defined in the files errors_<language>.php inside the folder /error_messages on the web server (for example errors_en.php), while /lib/constants.php contains all the error code constants that are used as key of the $errors associative array.

The language is sent from client by setting the new property language that you can set in the inspector of the component CombuManager (or programmatically), the value of this property must be the <language> of the language filename that must exist in the folder of the server (for example: if you set en then there must be a filename called errors_en.php in the folder /error_messages on the web).

You can also customize the default text by creating a file in /error_messages with the name of the language that you want to override and adding “_custom“, for example to override the text of the error ERROR_LOGIN_INVALID_CREDENTIALS (that is displayed when a login fails because of wrong username/password credentials) for the language “en” (english) then you need to create a file called errors_en_custom.php in the web folder and add the following PHP code:

<?php
$errors[ERROR_LOGIN_INVALID_CREDENTIALS] = "This is my custom error message";

To add support to more languages you only need to create a new file errors_<language>.php, copy the content of errors_en.php into it and translate all the string values (not the constants inside the brackets [], but only the strings inside the double-quotes): for example, to add support for german you will create a file called errors_de.php in /error_messages and then you will be able to set the property CombuManager.language to “de”.

By default we officially support two languages: english (CombuManager.language=”en”) and italian (CombuManager.language=”it”), but we will add more in the future to support more languages by default.

 

Remember credentials and auto-login

The authentication of latest login info has been completely rewritten and optimized for security, and you can take benefits from the new built-in auto-login feature. First of all, you need to set to true the property Remember Credentials in the inspector of your CombuManager object (or programmatically by accessing CombuManager.instance.rememberCredentials): this way every successful login will store in PlayerPref both the username and the encrypted password. Finally, call the static method User.AutoLogin() and pass a callback to handle the response.

 

Change-log

You can follow the change-log of this beta version on our forum in the dedicated topic.

 

Apply to the closed beta

If you are willing to help us in this testing phase, please apply from here, we’d really appreciate!  🙂

 

2 comments on “Combu 3.0 beta

Leave a Reply