> For the complete documentation index, see [llms.txt](https://easyauth.papelship.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://easyauth.papelship.com/documentation/plugins/binary-trace.md).

# Binary Trace

{% hint style="info" %}
**BinaryTrace** is an official forensic watermarking and leak-attribution plugin for EasyAuth. It embeds encrypted metadata (file UUIDs, distributor/customer hierarchy trees, and auto-login credentials) directly into the executable image, enabling developers to pinpoint the exact customer or reseller who leaked a binary.
{% endhint %}

## Required Files

To use BinaryTrace in your project:

* **Header**: `include/qPapelEasyAuthBinaryTrace.h`
* **Static Lib**: `lib/x64/Release/qPapelEasyAuthBinaryTrace.lib`

## Quick Setup & Usage

{% stepper %}
{% step %}

## Include the required headers

```cpp
#include "qPapelEasyAuth.h"
#include "qPapelEasyAuthBinaryTrace.h"
#include <iostream>
```

{% endstep %}

{% step %}

## Set the logging level

```cpp
easyauth::plugins::set_trace_log_level(easyauth::plugins::trace_log_level::verbose);
```

{% endstep %}

{% step %}

## Load the BinaryTrace plugin

```cpp
if (!easyauth::plugins::load_binary_trace_plugin()) {
    std::cerr << "[-] Failed to load BinaryTrace plugin.\n";
    return 1;
}
```

{% endstep %}

{% step %}

## Initialize EasyAuth

```cpp
easyauth::initialize();
```

{% endstep %}

{% step %}

## Inspect watermark metadata

```cpp
if (easyauth::plugins::is_trace_watermarked()) {
    std::cout << "[+] Binary is Watermarked!\n";
    std::cout << "    -> File UUID     : " << easyauth::plugins::get_trace_file_uuid() << "\n";
    std::cout << "    -> Auto-Login Key: " << easyauth::plugins::get_trace_auto_login_key() << "\n";
}
```

{% endstep %}
{% endstepper %}

```cpp
#include "qPapelEasyAuth.h"
#include "qPapelEasyAuthBinaryTrace.h"
#include <iostream>

int main() {
    // 1. Set logging level
    easyauth::plugins::set_trace_log_level(easyauth::plugins::trace_log_level::verbose);

    // 2. Load the BinaryTrace plugin
    if (!easyauth::plugins::load_binary_trace_plugin()) {
        std::cerr << "[-] Failed to load BinaryTrace plugin.\n";
        return 1;
    }

    // 3. Initialize EasyAuth
    easyauth::initialize();

    // 4. Inspect Watermark Metadata
    if (easyauth::plugins::is_trace_watermarked()) {
        std::cout << "[+] Binary is Watermarked!\n";
        std::cout << "    -> File UUID     : " << easyauth::plugins::get_trace_file_uuid() << "\n";
        std::cout << "    -> Auto-Login Key: " << easyauth::plugins::get_trace_auto_login_key() << "\n";
    }

    return 0;
}
```

## Binary Trace Information (`binary_trace_info`)

```cpp
struct binary_trace_info {
    std::string file_uuid;              // Unique cryptographic build/customer UUID
    std::vector<int> hierarchy;         // Reseller/User distribution hierarchy tree
    std::string auto_login_key;         // Embedded auto-login license key
    bool is_watermarked = false;        // true if executable contains valid watermark
    bool is_blocked = false;            // true if server revoked this specific binary build
    std::string blocked_reason;         // Revocation reason from server
};
```

## API Functions

### `easyauth::plugins::get_trace_file_uuid`

Retrieves the unique binary identifier assigned during generation.

```cpp
std::string get_trace_file_uuid();
```

### `easyauth::plugins::get_trace_hierarchy`

Returns the multi-level distributor and customer ID path (e.g. `[101, 2045, 89012]`).

```cpp
std::vector<int> get_trace_hierarchy();
```

### `easyauth::plugins::get_trace_auto_login_key`

Retrieves the encrypted auto-login license key bound into the binary.

```cpp
std::string get_trace_auto_login_key();
```