Upgrade from 2.x to 3.0

The main focus of Combu 3.0 was the improvement of security to deny malicious users to sniff the HTTP traffic and change the data sent from the server to the client.

The security of connections and client-server communications in the version 3 was achieved through RSA+AES keys handshaking:

  1. the client asks the server for a session token at launch
  2. the server generates RSA private+public keys on the fly and sends the public key to the client
  3. the client generates AES keys on the fly and sends them encrypted with the RSA received to the server
  4. from now on, every client-server call request will be encrypted with the AES keys, as well as every response server-client will be also encrypted with the same AES keys if RESPONSE_ENCRYPTED is defined as TRUE in your config.php

New tables were also created to handle the new security and features, so upgrading from version 2.x to 3.0 involves making changes both to the database and to your own custom web services.

For a detailed list of what’s new and what’s changed in Combu 3 please click here.

N.B.: this procedure is to upgrade from 2.x to 3.0, so you will need to upgrade later from 3.0 to the latest version available.

 

Make a backup

First of all, like for every update, let’s make a backup of everything regarding Combu: database, web files, Unity files.

Now you can delete all files inside both the web and Unity folders of Combu (keep your database, of course), so you will have empty folders to start with. This is especially important for the server files, because we completely rewrote the server code and reorganized the files in a different directory tree.

 

Upgrade your database

To upgrade your database, execute the following SQL statements:

DROP TABLE `CB_Session`;

CREATE TABLE `CB_AppId` (
  `Id` bigint(20) NOT NULL AUTO_INCREMENT,
  `AppId` varchar(255) NOT NULL,
  `Secret` varchar(255) NOT NULL,
  `DateCreated` datetime NOT NULL,
  `Active` tinyint(1) NOT NULL,
  `Name` varchar(45) NOT NULL,
  `Description` text,
  PRIMARY KEY (`Id`),
  UNIQUE KEY `AppId_UNIQUE` (`AppId`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

CREATE TABLE `CB_Account_App` (
  `IdAccount` BIGINT(20) NOT NULL,
  `IdApp` BIGINT(20) NOT NULL,
  `DateCreated` DATETIME NOT NULL,
  `DateUpdated` DATETIME NOT NULL,
  PRIMARY KEY (`IdAccount`, `IdApp`)
) ENGINE = InnoDB DEFAULT CHARSET=utf8;

CREATE TABLE `CB_SessionToken` (
  `Token` varchar(255) NOT NULL,
  `IdApp` bigint(20) NOT NULL,
  `IPAddress` varchar(45) NOT NULL,
  `Created` datetime NOT NULL,
  `RSA_PrivateKey` text NOT NULL,
  `RSA_PublicKey` text NOT NULL,
  `AES_Key` varchar(255) NOT NULL,
  `AES_IV` varchar(255) NOT NULL,
  `IdAccount` bigint(20) NOT NULL,
  `Updated` datetime NOT NULL,
  PRIMARY KEY (`Token`) USING BTREE,
  KEY `IX_SessionToken_Account` (`IdAccount`,`Updated`),
  KEY `SessionToken_App` (`IdApp`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE `CB_LeaderBoard`
  ADD COLUMN `IdApp` BIGINT(20) NOT NULL AFTER `Id`,
  ADD INDEX `LeaderBoard_App` USING BTREE (`IdApp` ASC);

ALTER TABLE `CB_Achievement`
  ADD COLUMN `IdApp` BIGINT(20) NOT NULL AFTER `Id`,
  ADD INDEX `Achievement_App` USING BTREE (`IdApp` ASC);

ALTER TABLE `CB_News`
  ADD COLUMN `IdApp` BIGINT(20) NOT NULL AFTER `Id`,
  ADD INDEX `News_App` USING BTREE (`IdApp` ASC);

ALTER TABLE `CB_Newsletter`
  ADD COLUMN `IdApp` BIGINT(20) NOT NULL AFTER `IdAccount`,
  ADD INDEX `Newsletter_App` USING BTREE (`IdApp` ASC);

ALTER TABLE `CB_Inventory`
  ADD COLUMN `IdApp` BIGINT(20) NOT NULL AFTER `IdAccount`,
  ADD INDEX `Inventory_App` USING BTREE (`IdApp` ASC);

 

Upgrade your server

Let’s install the new server scripts: you should already have deleted the old 2.x files, uncompressed the new 3.x files somewhere and moved the new content (what’s inside the folder “combu” extracted from the zip file) into the folder where you had the version 2.x server.

So now you can use the new easy “way” of configuring the server:

  • navigate to http://yourserver/your-combu-path/_setup on your web browser
  • Click the first link (Create the configuration file) and apply your favorite settings (this page basically allows you to set every define that you can have in config.php)
    • since in version 2.x the tables had a prefix hardcoded then remember to set “CB_” in Prefix for table names in the section Database connection
    • if you had custom email templates then you need to reapply your changes to the new templates located in /email_templates
  • When you’re satisfied with the settings, hit the button Go
  • You’ll see the content to paste into your /lib/config.php file with two buttons: Copy to clipboard (copies the content into clipboard so you can just paste into the config file) and Save to file (if the config file is writable, it will automatically update the configuration file)
  • After having updated the configuration file, you can delete the folder _setup (since you’re upgrading, you don’t need to create the database tables that is the second link in the setup homepage)

 

 

If you followed the two steps above correctly, then now you should be able to navigate to http://yourserver/your-combu-path/admin and access with your administrator credentials.

 

Create your App

Once you’re logged in the web administration, go to the section Apps from the menu and create a new App (after saving you will be given the App Id and Secret Key to set in the inspector of CombuManager component on Unity). You can use the same database for multiple games sharing the same player accounts but different Inventory, Leaderboards, Achievements and News, or you can also share some Leaderboards, Achievements or News across all your Apps.

Once you have created your app you will see the Id number (not App Id) in the App data, now you must assign all your Leaderboards and Achievements to this App (unless you want to let them available to any App) so execute the following SQL statements on your database with phpMyAdmin or any other database manager you have:

UPDATE `CB_LeaderBoard` SET IdApp = YOUR_ID_APP;
UPDATE `CB_Achievement` SET IdApp = YOUR_ID_APP;

 

Upgrade your custom web services

If you have implemented any custom (or third-party) web service then it will need to be upgraded as well to support the new security layer.

If your PHP web service made any use of Combu classes (like including api.php) then you need to declare the usage of such classes at top of your script, and anything you had in $_REQUEST (or filter_input) now you should check in the global variable $WS_REQUEST:

<?php
include "lib/api.php";
use Combu\Utils;
if ($WS_REQUEST["action"] == "save") {
   // do your stuff
   Utils::EchoJson(array("success"=>TRUE), TRUE, TRUE);
}

Previously in Unity the method CombuManager.instance.CreateForm() returned a WWWForm, while in version 3.x it returns a CombuForm that is a new class created to handle the encryption of request data (though it’s implicitly casted to a WWWForm to be used as parameter of CombuManager.instance.CallWebservice). So you only need to change the type of your variables to which you assigned CreateForm from WWWForm to CombuForm or var.

 

Get support

If anything went wrong or you’re having any issue please use the forum.