Set the SDK label to protect the specified functions/code/String
In project coding process, Virbox provides SDK label API to developer to mark the specified functions/code/string to compile, and protect those critical function/algorithm/string later.
SDK Label API, String Encryption
Virbox Protector provides SDK lable API which can be used by developer to set the label in project coding process, Virbox provides different kind of API to set the label to protect these critical function, method, algorithm, sensative code, license key/data, or other critical string with multiple protection option: Encryption, Obfustication, Virtualization etc.
In this section, we introduce how to use Virbox SDK label API to set label in project code process, sample provided. Developer also can find more sample case, head file in the installation directory in the Virbox Protector.
How to use SDK Label in Project coding
Introduction
Virbox Protector supports developer to protect software application to against static attack and dynamic attack.
Besides to overall protection option setting to application , Virbox Protector supports developer to protect software application to functions/methods level (with most fine grained protection) by select function name and set a label to those critical and important function, methods or code section.
Developer will has 2 ways to set the protection option to these critical functions/method/code section:
Use Virbox Protector GUI tool to set protection option in "Function Option" tab: Click & Select;
For those function/methods or code section which is critical, Developer may also use the Virbox Protector SDK label API to mark it during coding process. then when the project has been compiled into executive or dll libs, or drag the application into the Virbox GUI tool or use Virbox Protector CLI to protect it. Virbox Protector will automatically recognize these label set to these functions/method/critical code section and protect them with the protection option set by SDK label.
In general, Developer may use the Virbox SDK label API (provided by Virbox Protector) to mark to those function/methods or the code section (for example: license key data, critical string etc) which need to be protected, then developer build and compile the code and generate a executive program;
When Developer use Virbox Protector to parse the applications with these labels, Virbox Protector will capable to parse the application and recognize those function/method or code section has been marked. it will help developer to find these critical code location. and protect those marked functions, string with relavted SDK lable API accordingly.
Support coding language:
C\C++\C#\oc\swift\Java
System Environment & Prerequisites
Install Virbox Protector into your machine;
After installation, you will find the SDK label's static API and dynamic API in following directory:
demo case, developer may find demo in below directory:
Application supported by use of SDK Label API
Use SDK label API to Native application
The Native application means the executive file or dynamic linked library which compiled in Windows, Linux, ARM Linux, Android and macOS environment.
After you installed the Virbox Protector to your machine, you will find the "head file" which contain the SDK label APIs:
C:\Program Files\senseshield\Virbox Protector 3\sdk\inc\virbox.h
The sample case to SDL label API can be found:
C:\Program Files\senseshield\Virbox Protector 3\example\sdk\C
Set SDK Label API to mark and protect the "functions"
Developer may use SDK Label API to set a Label to encrypt/obfuscate/virtualize those critical function/methods in the applications, following SDK Label API can be used:
1. API for Conventional Protection
Protection Mode Setting:
Set to Convention protection (On default protection mode is Virtualization), which require in pair used and ending with:
VBProtectEnd
Sample:
2. API for Virtualization Protection
int VB_API_CALL VBVirtualizeBegin(const char *tag);
Protection mode setting: Code of Virtualization, which required in pair used and ending with: VBProtectEnd
Sample:
3. API for Code of Obfuscation
int VB_API_CALL VBMutateBegin(const char *tag);
Protection mode setting:
Code of Obfuscation, which require in pair used and ending with: VBProtectEnd
Sample:
4. API for Code of Snippet
(Valid for Virbox Protector LM only. not applied for Virbox Protector Standalone)
int VB_API_CALL VBSnippetBegin(const char *tag);
Protection mode setting:
Set to code of snippet. which valid for Virbox Protector Standalone only. which require in pair used and ending with: VBProtectEnd
Sample:
5. API to end of SDK label
void VB_API_CALL VBProtectEnd(void);
use this API to end SDK label API, pair used required.
Besides of SDK label API in pair use above, Virbox also provides SDK API in single use in below:
6. API For Functions of Virtualization (single use, no need pair use)
int VB_API_CALL VBVirtualizeFunction(const char *tag);
Protection Mode:
Function of Virtualization, (single use, not for pair used, no end API required) :
Sample:
7. API for Code of Obfuscation (single use)
int VB_API_CALL VBMutateFunction(const char *tag);
Protection Mode:
set to Code of Virtualization, (single use, not for pair used, no end API required) :
Sample:
8. API for Memory Check
int VB_API_CALL VBProtectVerifyImage(void);
Protection mode setting:
Set to "Memory Check"
Sample:
9. Attention & Remark
Virbox Protector supports to load SDK label API with static only, it doesn't support to load dynamically dll (i.e. LoadLibrary);
For the String parameter imported by:
VBProtectBegin
,VBVirtualizeBegin
,VBSnippetBegin
,VBMutateBegin
it can't be shared with other functions.Make sure the imported string to be the ASCII code, then the correct function's name will be shown and displayed when Virbox Protector GUI tool parsing, otherwise it will show messy code and unreadable.
Every
begin
must be follow and match withend
, use thebegin
andend
in pair used, and only one pair is allowed to mark for one function only.If the protection mode set by the label inconsistent with the protection mode saved in the project configuration file (.ssp file), the system will use the protection mode saved in the project configuration file.
The code in between the
Begin
andEnd
is better to more than 3 lines. which to make sure the protected code will be shown in the GUI of Virbox Protector. (it will not be shown in the GUI of Virbox Protector for the instruction less 15 bytes)SDK Label API provides 32bit and 64bit dll libs, you do need to use these libs accordingly.
Use Virbox SDK label API to protect Critical Strings: String Encryption & Decryption
Besides of to use Virbox SDK Lable to mark "functions", "method" with specified "protection" modes (Virtualization, Obfuscation, Encryptions) to protect those "functions", Developer may use SDK Label API to set label to encrypt these Critical string in the applications, following SDK Label API can be used:
1. API for String Encryption
void *VB_API_CALL VBProtectDecrypt(void *dst, const void *src, int size);
Protection Mode Setting:
String encryption, when application executed, the encrypted string will be kept in the caller memory and it will Not be released.
Sample:
Note: The buffer size of encrypted string must be a multiple of 16;
2. API For String Encryption
const void* VB_API_CALL VBDecryptData(const void *data, int size);
Protection mode setting:
String Encryption, usually, Developer may use this API to encrypt the key data (such as private key data), and the data and length must be a constant value, when application executed, the encrypted data kept in the heap memory.
This API can be used together with the API "VBFreeData
", the purpose to use “VBFreeData
” is to release the Heap memory which to prevent the debug tool find the string in the heap.
Sample:
3. API for String Encryption:
#define VBDecryptStringA(_X_) ((char*)VBDecryptData(_X_, sizeof(_X_)))
Protection mode setting:
Refers to Standard String encryption, which can be used as long as it is static variable or a global variable, and the encrypted string must be a constant.
VBDecryptStringA
is the encapsulation of VBDecryptData
, and you only need to use VBDecryptStringA
when using it.
Developer may combine use this API with the VBFreeString
to release the heap memory, to prevent the debug tool to search the string in the heap memory accordingly.
Sample:
1)To encrypt the string directly
2)Local Static variable
3)Global variable:
4)If the program to be encrypted is too complicated and the data to be encrypted can’t be parsed, it will report error when you use Virbox Protector to protect the software, it is recommended to make the program less complicate. Usually it mostly happened to the Linux program in 32 bits which compiled with –fpic or –fpie with O2.
5)The compiler may merge or combine the multiple and same constant strings to be one string, if only one of these string is encrypted, an error would be reported:
Sample:
In this sample case, messy code would be shown when you print string “a”.
4. API to wide string encryption (wchar_t
)
#define VBDecryptStringW(_X_) ((wchar_t*)VBDecryptData(_X_, sizeof(_X_)))
Protection mode Setting:
Refers to wide string (wchar_t
) encryption, as long as it is a static variable or a global variable can use wide string encryption
it can be used and the encrypted string must be a constant. VBDecryptStringW
is the encapsulation of VBDecryptData
, and you only need to use VBDecryptStringW
when using it.
Sample:
Developer may combine use with the API VBFreeString
to release the heap memory, to prevent the debug tool to search the string in the heap memory accordingly.
5. API to release heap memory
void VB_API_CALL VBFreeData(const void *data);
#define VBFreeString(_X_) VBFreeData(_X_)
Protection mode setting:
VBFreeData
will release the heap memory only, because, when developer use VBDecryptData to decrypt data
. If the heap memory is not released in time, the decrypted string can be seen/leaked through dynamic debugging with tools such as OD\ida;
VBFreeString
is a basic encapsulation to VBFreeData
. Use the VBFreeString
macro to pass the string pointer to the VBFreeData
function to release the corresponding memory space. You only need to use VBFreeString
when using it.
Use Virbox SDK Label API to set "General Protection Option" to application
API for Memory integrity
int VB_API_CALL VBProtectVerifyImage(void);
Protection mode setting:
User this API to verify the memory integrity, memory check, if memory integrity verification failed, then the application will quit the process execution directly;
Sample:
void timeit(void (*f)()) {
VBProtectVerifyImage();//detect & verify memory integrity
clock_t start = clock();
f();
cout << double(clock() - start) / CLOCKS_PER_SEC <<"second" << endl;
}
API for for Memory Integrity
int VB_API_CALL VBVerifyImage(void);
Protection mode:
User this API to verify the memory integrity, memory check, if memory integrity verification failed, then it wil return with non zero value;
Usage:
When the compiled application (contained this API) has been protected by Virbox Protector, if detected memory has been modified, the protected application will returned with non zero value, and no impact to application execution.
if developer use: VBSafeExit
, then the application will quit.
Sample:
API to detect debug tools
int VB_API_CALL VBDetectDebugger(void);
Protection mode:
Use this API to detect if your application whether or not to be debugged by debug tools, when detected, then it will returned with non zero value;
Usage:
When the compiled application (contained this API) has been protected by Virbox Protector, if detected memory has been modified, the protected application will returned with non zero value, and no impact to application execution. If call VBSafeExit
, then application will quit execution,
Sample:
API to detect the VM
int VB_API_CALL VBDetectVirtualMachine(void);
Protection mode:
To detect if the application execution environment is VM envrionment or not;
Usage:
When the compiled application (contained this API) has been protected by Virbox Protector, if VM environment has been detected , the protected application will returned with non zero value, and no impact to application execution. If call VBSafeExit
, then application will quit execution,
Sample:
API to quit application execution and clear current stack frame
void VB_API_CALL VBSafeExit(int code);
Protection
Quit application execution
Usage:
Call this API and combine use with following API:
VBVerifyImage
VBDetectDebugger
VBDetectVirtualMachine
When use this API directly, then the application protected by Virbox Protector will stop execution directly.
Use SDK Label API in macOS applications
The SDK Label API used in the macOS environment and the SDK label used in the native is same API. the only different thing is, it is necessary to make a configuration to Xcode when compiling the project. Here we brief the process for OC and Swift when using the SDK label.
1. OC Language
1)Frist step is add virbox.h
into the project, use the Xcode to open the project, and add the virbox.h
into the project;
2)Select the TARGETS->Build Settings->Architectures
, to view and check the project's Architecture: ARM64 or FAT format. see screenshot below:
3)Add the related and corresponding the libvirbox64.dylib
from the installation directory of Virbox Protector: sdk/darwin
, and select the option from: TARGETS->Build Phases->Link Binary
, to add the libvirbox64.dylib
4)Import the virbox.h
in your code project and add the SDK label API
Code sample as shown as below:
2.Swift language
1)Add virbox.h
into your project, Use Xcode to open the proejct and add virbox.h
into the project, and set the virbox.h
to be bridging file;
TARGETS->Build Settings->Swift Compiler->Object-C Bridging Header->Project name/virbox.h
2)Check the Project's Architecture: Select the TARGETS->Build Settings->Architectures
, to view the project's Architecture: ARM64 or FAT format. see screenshot below:
3)Find and Add the related and corresponding the libvirbox64.dylib
from the installation director of Virbox Protector: sdk/darwin
, and select the option from: TARGETS->Build Phases->Link Binary
, to add the libvirbox64.dylib
4)Add the SDK label API in the code directly. and add the variable name to SDK Lael API is also required.
Code Sample:
3. Execute the application
1)After compiling completed, the application execution require to dependent to the libvirbox64.dylib
, means you need to copy the libvirbox64.dylib
which corresponding to the application architecture to /usr/local/lib/libvirbox64.dylib
, and then to execute the compiled application.
If not copied the libvirbox64.dylib
, the following error will be reported
Note:
For the libvirbox64.dylib
in ARM architecture and FAT format, it is necessary to sign first and then copy libvirbox64.dylib
later,
2)Drag the compiled application into Virbox Protector GUI tool, then you can find the functions/method which marked by SDK label API in the "Function Option" tab;
Then, Protect your project, the protected application can executed and without dependent on thelibvirbox64.dylib
Use SDK Label API to .NET applications
To use and add the SDK label API into the .NET application, it is support following protection option to be set and protect the functions/methods:
Code of Encryption,
Code of Obfuscation.
Code of Virtualization.
To add the SDK label API in the project, it is consistent with Microsoft syntax, and when .NET project compiled completed. drag the the .NET application into the Virbox Protector GUI tools, then The protection option marked by SDK label API will be displayed in the "Function Option" tab.
Sample Code:
C:\Program Files\senseshield\Virbox Protector 3\example\sdk\dotnet_sdk_demo
Sample syntax:
Note:
SDK Label API can be added before the class name, and if SDK label also has been set to methods, then the SDK label set to methods will be displayed first.
The SDK label marked to Function and "Name of obfuscation" can Not be added into the code directly, it only can be added in front of class name and method names.
Use SDK label API to Java Applications
For Java Project, Virbox Protector support to use SDK label API with "Code of Virtualization", add the annotation VBVirtualize
in the Java code, and import it in the methods, when Java project compiled completed, drag the compiled Java project into Virbox Protector GUI tools, then Virbox Protector will display the protection option set to function/method by SDK label API.
Note: the filename must be the VBVirtualize, and the package name must virbox, otherwise the Virbox Protector will not recognized the SDK label marked.
Create
VBVirtualize.java
, the content shown as below
How to import
Use SDK Label API in Android applications
Applicable Scenario
When you use the Virtualized SDK label API to mark the "Class" or "Methods", Drag the compiled Android Apk/AAB package into Virbox Protector GUI tool, The GUI tool will parse and display the class and method which marked by SDK label.
When developer use Proguard to obfuscate Android project, probably it may not parse the method/function name successfully;
When you use the “Virtualization" API to mark the class and methods, then it will not necessary to find and view the corresponding method's name or class's name.
Sample case path at:
C:\Program Files\senseshield\Virbox Protector 3\example\sdk\APK
Protection Process
Open the Android Project and create a new directory, name with "virbox"
Create >Java Class:
Select >Interface and name as: VBVirtualize;
Add the following code in the "VBVirtualize.class":
Import
VBVirtualize
from other class:
If @VBVirtualize is placed on (above) the the "class",
When you enable "Proguard" to obfuscate the project code; it means the SDK label will be marked to this class and retain the class name (not obfuscated by Proguard); and the name of the other class which not marked by Virbox SDK label, will not be retained (obfuscated by Proguard);
When you disable the "Proguard" option, it means Virbox SDK label will be marked to this class;
If @VBVirtualize is placed on (above) the the "method";
When you enable "Proguard" to obfuscate the project code; it means the SDK label will marked to this method and retain the method name (not obfuscated by Proguard); and the name of the other method which not marked by Virbox SDK label, will not be retained (obfuscated by Proguard);
When you disable the "Proguard" option, it means Virbox SDK label will be marked to this class;
All sample to call SDK Label API can be found in the Virbox Protector installation directory
All Head file for SDK Label API can be found in the Virbox Protector installation directory
FAQ
Q: For SDK Label API, map and pdb file, which one will be the first priority when Virbox Protector to protect the application?
A: SDK Label API will be the first priority when Virbox Protector parse and protect the Application in protection process;
Q: Will Virbox SDK label also support to be set and used to the ARX file (the compiled file is ARX)
A: Yes, Virbox SDK label support to set the SDK label to compiled to arx file.
Q: Does global variables can be protected by SDK Label?
A: Yes, Global variable can be set and protected by
VBDecryptStringA
, for PE, elf and machO application.Q:
begin
end
is the function body that only processes the current function. If function A calls function B, and function B uses the SDK label, then function A can also use the SDK label again. does this case means nested?A: No, It is not the nested case;
Q: In a c++ program, after protecting the the sdk label by using String Encryption, can it be seen using the OD debugger?
A: It can be found and seen in the heap memory using OD. You can call
VBFreeString(xxx)
to release it after each use, and it will no longer be found in the heap memory.Q: For C# program, By using String Encryption, does it can prevent strings from being dumped from memory? Can the OllyDbg see it?
A: It cannot prevent the string from being dumped from the memory. But the OllyDbg cannot scan the memory directly. only If you find the place where the string is actually used and break point, then you can see the sting encrypted.
Last updated