Hercules API – Developer guides

HerculesPlugin Classes and APIs

This is the list of basic APIs.
All APIs can be used after the Hive SDK is initialized.

IsJailbrokenDevice (iOS)

- Checks if the iOS device is jailbroken.

uint IsJailbrokenDevice();         // C#
uint HerculesIsJailbrokenDevice(); // C, C++

1 2	uint IsJailbrokenDevice(); // C# uint HerculesIsJailbrokenDevice(); // C, C++

Return Value
- Returns 0 if it is in the original firmware state, and non-zero if it is a jailbroken device.
Parameters
- None

IsRootedDevice (Android)

- Checks if the Android device is rooted.

uint IsRootedDevice();         // C#
uint HerculesIsRootedDevice(); // C, C++

1 2	uint IsRootedDevice(); // C# uint HerculesIsRootedDevice(); // C, C++

Return Value
- Returns 0 if not rooted, non-zero if the device is rooted.
Parameters
- None

IsEmulator (Android)

- Checks if the Android device is an emulator.

uint IsEmulator();         // C#
uint HerculesIsEmulator(); // C, C++

1 2	uint IsEmulator(); // C# uint HerculesIsEmulator(); // C, C++

Return Value
- Returns 0 for mobile devices, non-zero for emulators.
- Emulators disguise themselves as mobile devices, so 0 may be returned for some emulators.
Parameters
- None

IsUnofficialBuild (iOS)

- Checks whether the iOS build is an unofficial build (a build not downloaded from the App Store)
- It checks that the build is Fairplay encrypted and signed. The builds downloaded from AppStore and TestFlight are assumed to be the official builds.

uint IsUnofficialBuild();         // C#
uint HerculesIsUnofficialBuild(); // C, C++

1 2	uint IsUnofficialBuild(); // C# uint HerculesIsUnofficialBuild(); // C, C++

Return Value
- 0 for the official builds, 1 for the externally installed builds. Returns 2 or higher value if it failed to check the build.
Parameters
- None

GetFunnels (Android)

- Gets the funnel where the app is installed.

string GetFunnels();               // C#
const char * HerculesGetFunnels(); // C, C++

1 2	string GetFunnels(); // C# const char * HerculesGetFunnels(); // C, C++

Return Value
- A value such as ADB, Google Play Store, or Amazon Appstore is returned as the path where the app is installed, or the package name of the installed app is returned if it was installed via another market or file explorer app.

GetCertDesc (Android, iOS)

- Gets the signed app’s certificate information.

string GetCertDesc();              // C#
const char* HerculesGetCertDesc(); // C, C++

1 2	string GetCertDesc(); // C# const char* HerculesGetCertDesc(); // C, C++

Return Value
- Android: Returns the Common Name of the APK keystore.
- iOS: Returns the certificate information associated with the provisioning profile. Builds downloaded from the App Store will return an empty value. If the app is cracked, the name of the crack developer’s certificate or the user’s personal certificate name is displayed depending on the installation method.
Parameters
- None

GetTeamId (iOS)

- Gets the team ID of the provisioning profile owner account.

string GetTeamId();              // C#
const char* HerculesGetTeamId(); // C, C++

1 2	string GetTeamId(); // C# const char* HerculesGetTeamId(); // C, C++

Return Value
- The team ID of the Apple developer account that signed the app. A combination of alphabets and numbers.
- If the app is cracked, it may be re-signed with a different account and may differ from the values shown in bold below.

GetCertHash (Android)

- Get the signature hash applied to the APK.

string GetCertHash();              // C#
const char* HerculesGetCertHash(); // C, C++

1 2	string GetCertHash(); // C# const char* HerculesGetCertHash(); // C, C++

Return Value
- APK signature hash value. SHA1 hash, a 40-digit string in hexadecimal format.
- The signing key may change after uploading to Google Play Store or Amazon. After checking the hash values of the signature keys used, you can compare them. If they differ from the previously checked hashes, this can be regarded as repackaging.

GetProxyStatus (Android, iOS)

- Returns whether a proxy is set up in the device settings.

uint GetProxyStatus();         // C#
uint HerculesGetProxyStatus(); // C, C++

1 2	uint GetProxyStatus(); // C# uint HerculesGetProxyStatus(); // C, C++

Return Value
- Returns 1 if the proxy is set, 0 otherwise.

GetVPNStatus (Android, iOS)

- Returns whether a VPN connection is established.

uint GetVPNStatus();         // C#
uint HerculesGetVPNStatus(); // C, C++

1 2	uint GetVPNStatus(); // C# uint HerculesGetVPNStatus(); // C, C++

Return Value
- Returns 1 if VPN is connected, otherwise 0.

HerculesPrefs Class and API

An encrypted version of the Unity engine’s PlayerPrefs class.
Unlike Unity, it is not automatically saved when you exit the game, so you must call the Save function.
If you move game data to another device after backing up your device, encrypted data may be copied as well.

Reference URL: https://docs.unity3d.com/kr/530/ScriptReference/PlayerPrefs.html

GetInt, GetFloat, GetString

- Gets the value stored in the encrypted setting file.

// C#
int GetInt(string key, int defaultValue = 0);
float GetFloat(string key, float defaultValue = 0.0f);
string GetString(string key, string defaultValue = "");

// C++
int HerculesPrefsGetInt(const char *key, int defaultValue = 0);
float HerculesPrefsGetFloat(const char *key, float defaultValue = 0);
char* HerculesPrefsGetString(const char *key, const char *defaultValue = "");

// C#

int GetInt(string key, int defaultValue = 0);

float GetFloat(string key, float defaultValue = 0.0f);

string GetString(string key, string defaultValue = "");

// C++

int HerculesPrefsGetInt(const char *key, int defaultValue = 0);

float HerculesPrefsGetFloat(const char *key, float defaultValue = 0);

char* HerculesPrefsGetString(const char *key, const char *defaultValue = "");

Return Value
- The stored value. If there is no stored value or the value has been tampered with, defaultValue is returned.
- Buffers returned by C/ C++’s HerculesPrefsGetString API must be freed with HerculesFreeMem API.
Parameters
- key : The key of the value to be retrieved.
- defaultValue : Default value to be returned if there is no value.

SetInt, SetFloat, SetString

- Encrypts and stores the key and value.
- If you exit the app without calling the Save API, the settings will be lost.

// C#
void SetInt(string key, int value);
void SetFloat(string key, float value);
void SetString(string key, string value);

// C++
void HerculesPrefsSetInt(const char *key, int value);
void HerculesPrefsSetFloat(const char *key, float value);
void HerculesPrefsSetString(const char *key, const char *value);

// C#

void SetInt(string key, int value);

void SetFloat(string key, float value);

void SetString(string key, string value);

// C++

void HerculesPrefsSetInt(const char *key, int value);

void HerculesPrefsSetFloat(const char *key, float value);

void HerculesPrefsSetString(const char *key, const char *value);

Return Value
- None
Parameters
- key : The key of the value to be stored.
- value : The value to be stored.

HasKey

- Checks if there’s a key.

bool HasKey(string key);                   // C#
uint HerculesPrefsHasKey(const char *key); // C, C++

1 2	bool HasKey(string key); // C# uint HerculesPrefsHasKey(const char *key); // C, C++

Return Value
- Returns true(C#) or 1(C/C++) if there’s a key.
Parameters
- key : The key to be tested.

DeleteKey

- Deletes the key.

void DeleteKey(string key);                   // C#
void HerculesPrefsDeleteKey(const char *key); // C, C++

1 2	void DeleteKey(string key); // C# void HerculesPrefsDeleteKey(const char *key); // C, C++

Return Value
- None
Parameters
- key : The key to be deleted.

DeleteAll

- Deletes all keys.

void DeleteAll();              // C#
void HerculesPrefsDeleteAll(); // C, C++

1 2	void DeleteAll(); // C# void HerculesPrefsDeleteAll(); // C, C++

Return Value
- None
Parameters
- None

Save

- The changed content is encrypted again and saved as a file. The saved contents are loaded when the module is initialized.

void Save();         // C#
void HerculesSave(); // C, C++

1 2	void Save(); // C# void HerculesSave(); // C, C++

Return Value
- None
Parameters
- None

Secure Variable API (C/C++ only)

This is a secure variable API that can only be used in C/C++.
In C#, it is called internally when using the secure variable class (HerculesVar).
It is recommended to refer to the security variable guide for how to use it.

AddString (C/C++ Only)

- Adds Hercules secure variable of string form. (Allocated)

HERCULES HerculesAddStringconst char *str();

1	HERCULES HerculesAddStringconst char *str();

Return Value
- the ID of the created secure variable. Returns 0 if it fails to create variables.
Parameters
- str : The pointer for the original string.

AddVar (C/C++ Only)

- Adds Hercules secure variable. (Allocated)

HERCULES HerculesAddVar(const void *data, uint length);

1	HERCULES HerculesAddVar(const void *data, uint length);

Return Value
- the ID of the created secure variable. Returns 0 if it fails to create variables.
Parameters
- data : The address of the initial value to be referred when creating a variable.
- length : The size of the variable to be created. Sets the size of the data parameter.

FreeMem (C/C++ Only)

- Free the buffer allocated by the HerculesGetString API.

void HerculesFreeMem(void *ptr);

1	void HerculesFreeMem(void *ptr);

Return Value
- None
Parameters
- ptr : Address of a buffer allocated by some APIs.

GetString (C/C++ Only)

- Reads the value of the Hercules secure string. (Read)
- In C++ template classes, it is automatically called when the value of a variable is referenced.
- If the tampering of a value is detected when the string is read, the callback function which was set during initialization is called. (This depends on the policy.)

char* HerculesGetString(HERCULES seq);

1	char* HerculesGetString(HERCULES seq);

Return Value
- Returns a string buffer if the value is read successfully, or returns nullptr if unsuccessful.
- The returned buffer must be freed via the HerculesFreeMem function
Parameters
- seq : the ID of the secure variable.

GetVar (C/C++ Only)

- Reads the value of the Hercules secure variable. (Read)
- In C++ template classes, it is automatically called when the value of a variable is referenced.
- When a variable is read, if the tampering of its value is detected, the callback function which was set during initialization is called. (This depends on the policy.)

int HerculesGetVar(HERCULES seq, void *data);

1	int HerculesGetVar(HERCULES seq, void *data);

Return Value
- Returns 0 if the value is read successfully, a positive number for invalid parameters, and a negative number if tampering is detected.
- If you did not set a callback function at the initialization stage, you can refer to this return value.
Parameters
- seq : the ID of the secure variable.
- data : the address of the data buffer to be read. You must set a buffer with the same size as the size set when creating the variable.

RemoveVar (C/C++ Only)

- Removes the Hercules secure variable. (Release)
- In C++ template classes, it is automatically called when a variable is freed.

void HerculesRemoveVar(HERCULES seq);

1	void HerculesRemoveVar(HERCULES seq);

Return Value
- None
Parameters
- seq : the ID of the variable to be released.

SetVar (C/C++ Only)

- Sets the value of the Hercules secure variable. (Write)
- In C++ template classes, it is automatically called when assigning a value to a variable.

void HerculesSetVar(HERCULES seq, const void *data);

1	void HerculesSetVar(HERCULES seq, const void *data);

Return Value
- None
Parameters
- seq : the ID of the secure variable.
- data : the address of the data buffer to be set. You must set a buffer with the same size as the size set when creating the variable.