Secure variable
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 |
// The two codes below do the same thing and allocate a new object.
HerculesVar x = 100;
HerculesVar y = new HerculesVar(100);
// The value is copied from the secure variable to the normal variable.
int a = x;
// The old object allocated to y is released and the new object is re-allocated to y.
y = 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.Set(300);
// 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 = (int)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.
y = x;
// 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.
#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 localString1 = <A new string downloaded from the server or generated dynamically>; // initialize to string
CHerculesString localString2 = *g_securityString; // Initialize to a CHerculesString object
std::string localString = *g_securityString; // CHerculesString to std::string
localString2 = localString1; // CHerculesString to CHerculesString
localString1 = localString.c_str(); // std::string to CHerculesString
}
#include "Hercules.h"
HERCULES g_x;
HERCULES g_y;
HERCULES g_str;
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 = HerculesAddString(<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.)