Secure Variable – Developer guides

Introduction

This page describes the secure variable feature of Hercules.
Before using the secure variable feature, you first have to setup the Hive SDK beforehand.

A secure variable has the following characteristics:

It is a encrypted value in memory so that it cannot be retrieved by external tools.
Even if the encrypted value is tampered with, it will be verified when it is read.
The supported languages include C/C++ and C# (Unity).

How to Use Secure Variable

C# (Unity)

Basically, the data types available in C# can be used as a Generic class.
There are secure data types that match each data type as follows.
Since all basic types are cast to 8-byte types, it is recommended to use 8-byte types, such as using long instead of int and double instead of float.

Basic Type	Secured Type	Basic Type	Secured Type
bool	HerculesVar<bool>	int	HerculesVar<int>
char	HerculesVar<char>	uint	HerculesVar<uint>
sbyte	HerculesVar<sbyte>	long	HerculesVar<long>
byte	HerculesVar<byte>	ulong	HerculesVar<ulong>
short	HerculesVar<short>	float	HerculesVar<float>
ushort	HerculesVar<ushort>	double	HerculesVar<double>
string	HerculesString

C# Example

// The two codes below do the same thing and allocate a new object.
     HerculesVar x = 100;
     HerculesVar y = new HerculesVar(100);

int a = x;   
// The value is copied from the secure variable to the normal variable.
y = 300;    
// The old object allocated to y is released and the new object is re-allocated to y.
y.Set(300);  
// Change the value of y. (y should already have been assigned with an object, and this type of allocation is faster than the above one.)

y = (int)x;   
// y is reassigned as the value of x. Both x and y starts to refer a different object other than the original object assigned to x.
y = x;       
// caution: y will refer to x. If you use the Set function, the both values are replaced.
// If a build error occurs when directly operating an unsigned type secure variable
// U must be specified after a constant or you should use explicit casting. (as 1U or (uint)1)
// For the frequently updated values, it is advantageous to use it as obj.Set(v); form for better performance.

// A string can be used like this: Only in-memory strings are protected.
// When assigning a static string like “TEST”, the original string may be exposed to the code.
HerculesString securityString = <A string value downloaded from the server or generated dynamically>;
string plainString = securityString;

// The two codes below do the same thing and allocate a new object.

HerculesVar x = 100;

HerculesVar y = new HerculesVar(100);

int a = x;

// The value is copied from the secure variable to the normal variable.

y = 300;

// The old object allocated to y is released and the new object is re-allocated to y.

y.Set(300);

// Change the value of y. (y should already have been assigned with an object, and this type of allocation is faster than the above one.)

y = (int)x;

// y is reassigned as the value of x. Both x and y starts to refer a different object other than the original object assigned to x.

y = x;

// caution: y will refer to x. If you use the Set function, the both values are replaced.

// If a build error occurs when directly operating an unsigned type secure variable

// U must be specified after a constant or you should use explicit casting. (as 1U or (uint)1)

// For the frequently updated values, it is advantageous to use it as obj.Set(v); form for better performance.

// A string can be used like this: Only in-memory strings are protected.

// When assigning a static string like “TEST”, the original string may be exposed to the code.

HerculesString securityString = <A string value downloaded from the server or generated dynamically>;

string plainString = securityString;

iOS, Android

In case of C, whenever you save or read the value of a variable, you must directly call the API, so it is recommended to use C++. C++ has a template class defined.
If possible, it is recommended to use the secure variable as a global variable or to use it after placing it in a place where allocation and deallocation are not performed too frequently.
Do not put #include statements inside an exteren "C" block.
It should be used after the Hive SDK is initialized.

C++

#include "Hercules.h"

class CUserInfo {
public:
    CHercules hp;
    CHercules mp;
    CHercules critical;
};
// If it is used as a global variable, an issue occurs because the variable is tried to be initialized before the Hive SDK is initialized.
// CHercules g_temp;

// When using it as a global variable, declare it in the form of a pointer as follows.
CUserInfo *g_user;
CHercules *g_var;
CHerculesString *g_string;

void BeginBattle) {
    // Creates a secure variable. (Example: at the start of a battle in a game)
    g_user = new CUserInfo;
    g_var = new CHercules;
    g_string = new CHerculesString(<A string value downloaded from the server or generated dynamically>);
}

void EndBattle) {
     // Deletes the secure variable. (Example: at the end of a battle in a game)
     delete g_user;
delete g_var;
delete g_string;
g_user = nullptr;
…
}

void Sample()
{
    // Assignments can be made in any form as shown below.
    int localvar = 0;
    CHercules x = localvar;
    *g_var = localvar;
    *g_var = x + 2;
    g_user->hp = 100;

    // When assigning a static string like “TEST”, the original string may be exposed to the code.
CHerculesString localSecurityString1 = <A new string downloaded from the server or generated dynamically>; // initialize to string
CHerculesString localSecurityString2 = *g_securityString; // Initialize to a CHerculesString object
     std::string localString = *g_securityString; // CHerculesString to std::string
 localSecurityString2 = localSecurityString1; // CHerculesString to CHerculesString
 localSecurityString1 = localString.c_str(); // std::string to CHerculesString
}

#include "Hercules.h"

class CUserInfo {

public:

CHercules hp;

CHercules mp;

CHercules critical;

};

// If it is used as a global variable, an issue occurs because the variable is tried to be initialized before the Hive SDK is initialized.

// CHercules g_temp;

// When using it as a global variable, declare it in the form of a pointer as follows.

CUserInfo *g_user;

CHercules *g_var;

CHerculesString *g_string;

void BeginBattle) {

// Creates a secure variable. (Example: at the start of a battle in a game)

g_user = new CUserInfo;

g_var = new CHercules;

g_string = new CHerculesString(<A string value downloaded from the server or generated dynamically>);

}

void EndBattle) {

// Deletes the secure variable. (Example: at the end of a battle in a game)

delete g_user;

delete g_var;

delete g_string;

g_user = nullptr;

…

}

void Sample()

{

// Assignments can be made in any form as shown below.

int localvar = 0;

CHercules x = localvar;

*g_var = localvar;

*g_var = x + 2;

g_user->hp = 100;

// When assigning a static string like “TEST”, the original string may be exposed to the code.

CHerculesString localSecurityString1 = <A new string downloaded from the server or generated dynamically>; // initialize to string

CHerculesString localSecurityString2 = *g_securityString; // Initialize to a CHerculesString object

std::string localString = *g_securityString; // CHerculesString to std::string

localSecurityString2 = localSecurityString1; // CHerculesString to CHerculesString

localSecurityString1 = localString.c_str(); // std::string to CHerculesString

}

C Example

#include "Hercules.h"

HERCULES g_x;
HERCULES g_y;
HERCULES g_str;

void callbackint error, const char *message)
{
    // puts"Detected !");
}

void StartApp) {
     // Creates a secure variable.
     // Can be used by putting basic types and structure variables.
     int var = 0;
     g_x = HerculesAddVar(&var, sizeof(var));
g_y = HerculesAddVar(&var, sizeof(var));
// When assigning a static string like “TEST”, the original string may be exposed to the code.
g_str = HerculesAddVar(<A string downloaded from the server or generated dynamically>);
}

void Sample()
{
    // Gets the value of x and store it in y. At this time, the second parameter set in each function
    // must be a variable with the same size as the size set when calling HerculesAddVar.
    int var;
    HerculesGetVar(g_x, &var);
    HerculesSetVar(g_y, &var);

    // After you get the secured string as a regular string, you need to free it with the HerculesFreeMem function.
    char *str = HerculesGetString(g_str);
    HerculesFreeMem(str);

    // Before assigning a new string variable, it must be deleted using the HerculesRemoveVar function.
    HerculesRemoveVar(g_str);
    g_str = HerculesAddString(<A new string downloaded from the server or generated dynamically>);
}

#include "Hercules.h"

HERCULES g_x;

HERCULES g_y;

HERCULES g_str;

void callbackint error, const char *message)

{

// puts"Detected !");

}

void StartApp) {

// Creates a secure variable.

// Can be used by putting basic types and structure variables.

int var = 0;

g_x = HerculesAddVar(&var, sizeof(var));

g_y = HerculesAddVar(&var, sizeof(var));

// When assigning a static string like “TEST”, the original string may be exposed to the code.

g_str = HerculesAddVar(<A string downloaded from the server or generated dynamically>);

}

void Sample()

{

// Gets the value of x and store it in y. At this time, the second parameter set in each function

// must be a variable with the same size as the size set when calling HerculesAddVar.

int var;

HerculesGetVar(g_x, &var);

HerculesSetVar(g_y, &var);

// After you get the secured string as a regular string, you need to free it with the HerculesFreeMem function.

char *str = HerculesGetString(g_str);

HerculesFreeMem(str);

// Before assigning a new string variable, it must be deleted using the HerculesRemoveVar function.

HerculesRemoveVar(g_str);

g_str = HerculesAddString(<A new string downloaded from the server or generated dynamically>);

}

Reference (C++)

Use it when the secure variable is initialized with a value. (the status that an object is allocated)
Use it as assigning the final result, which is generated after all the necessary calculations are completed.
Refer to the example below. (C++ has operator overloading.)
Recommended:

// CHercules *securityVar = ...

int var = 0;
int values[5] = {5, 4, 6, 8, 11};

forint i = 0; i < 5; i++)
    sum += values[i];

*securityVar += sum;

// CHercules *securityVar = ...

int var = 0;

int values[5] = {5, 4, 6, 8, 11};

forint i = 0; i < 5; i++)

sum += values[i];

*securityVar += sum;

Not Recommended (Frequent Access)

// CHercules *securityVar = ...

int values[5] = {5, 4, 6, 8, 11};

forint i = 0; i < 5; i++)
    *securityVar += values[i];

// CHercules *securityVar = ...

int values[5] = {5, 4, 6, 8, 11};

forint i = 0; i < 5; i++)

*securityVar += values[i];

Introduction

How to Use Secure Variable

C# (Unity)

iOS, Android

Reference (C++)

SDK Development

Console Guide

Download

API Guide

Support