Combu 3 Release Notes

Here is the release notes of Combu 3, we appreciated the help of everyone who took 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!

 

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 than 5.5 is 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 to download, for example the 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:

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.

 

mysqli or PDO

The database functions have been also refactored and now the server is using mysqli instead of the deprecated mysql, though we also developed a version DatabasePDO class that uses PDO for future support to other database engines (anyway we officially support only MySql at this moment, but we’re planning to add support to other engines in the future like MS SQL Server or NoSql).

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 database 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.

 

Multiple Apps

The new system allows you to create a games-hub by using the same database for multiple games, sharing the same player accounts but different Inventory (stored per App) and eventually also some Leaderboards, Achievements or News (these can have a single App or Any App as scope).

With this feature you can allow your players to have a single account for all your games in the hub. In Unity the old “Secret Key” of Combu 2.x has been replaced with two new properties: App Id and App Secret, you will get these values after creating a new App in the section Apps of the web administration.

 

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 of the component CombuManager, 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.

 

Web Administration theme

You can customize the CSS styles of the web administration area by creating a file called custom.css in  the folder /admin/css, if this file exists then it’ll be automatically loaded as last stylesheet so you will be able to modify any CSS style you like.

For example, if you have uploaded your game logo in the folder /admin/images and want to display it instead of the Combu logo at top left of each page, create the file /admin/css/custom.css and put the following content into it:

#logo-title {background-image: url('../images/your_logo.png');}

The administration website is currently using a jQueryUI theme (mainly for buttons and other forms stuff), so you can also generate your own color template at their site and paste the content into your custom.css to customize the forms.

You can also add your own JS code by creating a new file called custom.js in the folder /admin/js, if this file exists then it will be added to the HTML output in the header of every page in the administration website.

 

Upgrade from 2.x to 3.0

If you are going to upgrade your existing project from version 2 to 3 please follow the instructions at here.