Licensing¶

The GVA LDM SDK requires a valid licence for operation. This guide explains how to obtain, install, and manage your licence.

Security Architecture¶

The licence system uses a three-layer defence to prevent tampering and forgery:

1. HMAC-SHA256 Signature - Signs entire payload, requires server secret
2. Encrypted Protected Data - Critical fields (expiry, MAC addresses) are encrypted
3. Embedded Key Verification - Binary key stored inside encrypted blob must match

Attack Prevention¶

Obtaining a Licence¶

Contact Astute Systems to obtain your licence:

• 📧 Email: [email protected]
• 🌐 Website: https://astutesys.com

When requesting a licence, please provide:

1. Your organisation name
2. Contact email address
3. Intended use (evaluation, development, production)
4. Number of installations required
5. MAC address(es) for hardware locking (optional)

Installing the Licence File¶

The licence file must be placed at:

/usr/local/share/astutesystems/license.json

Installation Steps¶

1. Create the directory (if it doesn't exist):

   sudo mkdir -p /usr/local/share/astutesystems
   

2. Copy your licence file:

   sudo cp license.json /usr/local/share/astutesystems/license.json
   

3. Set appropriate permissions:

   sudo chmod 644 /usr/local/share/astutesystems/license.json
   

4. Verify installation by running an application:

   gva-qt6-hmi --version
   

Updating Your Licence¶

When you receive a new licence file (for renewal or upgrade), follow these steps:

Backup Existing Licence¶

sudo cp /usr/local/share/astutesystems/license.json /usr/local/share/astutesystems/license.json.backup

Install New Licence¶

sudo cp new_license.json /usr/local/share/astutesystems/license.json

Verify the Update¶

Restart your application to verify the new licence is working:

gva-qt6-hmi --version

Licence Types¶

Time-Limited Licence¶

A standard licence with a set expiration date. The application will stop working after the expiry date.

• Has a specific expiry date
• perpetual is set to false
• Suitable for annual subscriptions

Perpetual Licence¶

A licence that never expires.

• perpetual is set to true
• expiry field is ignored
• One-time purchase, lifetime use

MAC-Locked Licence¶

A licence tied to specific hardware by MAC address.

• Contains an allowed_macs array with permitted MAC addresses
• Validates against the machine's network interfaces
• Prevents licence sharing across machines
• Can be combined with time-limited or perpetual licences

Example Licence File¶

Here is an example of a valid licence file structure:

{
    "allowed_mac_addresses_display": [
        "00:11:22:33:44:55"
    ],
    "binary_key": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "company_name": "Example Company Ltd",
    "employee_email": "[email protected]",
    "expiry_display": "2026-12-31T00:00:00",
    "holder": "John Smith",
    "issued_at": "2025-01-15T09:30:00",
    "license_id": 1001,
    "perpetual": false,
    "protected_data": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "schema_version": 3,
    "signature": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "signature_algorithm": "HMAC-SHA256"
}

Licence Fields¶

Runtime Validation¶

Using the Runtime Library¶

Applications use the licence runtime library for validation:

#include <LicenseRuntime.h>

int main(int argc, char* argv[]) {
    // Parse --license argument if provided
    auto args = ldm::license::ConsumeRuntimeArguments(argc, argv);

    // Validate licence
    auto result = ldm::license::EnforceRuntimeLicence(args);
    if (!result.success) {
        qCritical() << "Licence error:" << result.message;
        return 1;
    }

    qInfo() << "Licence valid:" << result.licensePath;
    // Continue with application logic
}

Runtime Options¶

ldm::license::RuntimeOptions options;
options.lockToMac = true;       // Verify MAC address binding
options.requireSignature = true; // Require valid signature

auto result = ldm::license::EnforceRuntimeLicence(args, options);

Licence Validation¶

On startup, applications validate:

1. File exists at the expected location
2. Signature is valid using HMAC-SHA256
3. Expiry date has not passed (unless perpetual)
4. MAC address matches (if MAC-locked)

If validation fails, the application will display an error message explaining why.

Troubleshooting¶

"Licence file not found"¶

Ensure the file is at /usr/local/share/astutesystems/license.json and readable.

ls -la /usr/local/share/astutesystems/license.json

"Invalid licence signature"¶

The licence file may have been corrupted or modified. Request a new licence file.

"Licence has expired"¶

Contact Astute Systems to renew your licence.

"MAC address not authorised"¶

Your hardware doesn't match the MAC-locked licence. Contact support at [email protected] to update your allowed MAC addresses.

Licence Support¶

For any licence-related issues, questions, or requests, please email:

📧 [email protected]

Our support team can help with:

• Licence installation issues
• Licence renewals and upgrades
• MAC address updates for hardware-locked licences
• Transferring licences to new machines
• General licence enquiries