DTL_LicenseServer — Reference Manual

Preface

DTL_LicenseServer is a lightweight license-management service for Windows applications. It centralizes license creation, machine authorization, online validation, and revocation, while keeping server secrets and direct database access out of distributed software.

This manual is the product’s descriptive reference. It defines its responsibilities, architecture, data, interfaces, and guarantees. It is intended for technical owners, developers, operators, and people evaluating the system.

Context and scope

Purpose

The service associates a usage entitlement with a product, an email address, and a maximum number of machines. It decides whether a machine may receive or retain an activation and produces a signed token attesting that decision.

Trust boundaries

• The client application knows the public URL and license credentials, but never the private signing key or MariaDB credentials.
• The administration utility holds an API key reserved for license creation.
• The PHP server owns the authorization logic and signs tokens.
• MariaDB holds the authoritative state of products, licenses, activations, and events.

Excluded responsibilities

DTL_LicenseServer is not a payment system, customer portal, or identity directory. It provides no graphical administration interface and does not replace access control, backup, or hosting supervision.

Architecture

License lifecycle

Creation

A license belongs to a product and has a reference email, a status, an optional expiry, and an activation ceiling. The plaintext key is returned only on creation; only its SHA-256 digest is subsequently retained.

Activation and refresh

The server checks the product, key, email, status, expiry, and quota. A first machine receives an activation row and an Ed25519 token. A later request from the same non-revoked machine refreshes its information without consuming another slot.

Deactivation and reactivation

Deactivation records the activation’s revocation time, after which its token is invalid. If the same machine later presents the license credentials again and a slot is available, the server reuses its row, clears the revocation time, and issues a new token. The quota is checked before reactivation.

Statuses

Data model

Activation token

The signed token binds a decision to a product, license, activation, and machine. Its payload contains the format version, product_code, license_id, activation_id, machine_id_hash, and issued_at. Its signature protects integrity; current state remains subject to server-side validation.

Functional capabilities

• Creation of a license for an active product, with quota and optional expiry.
• Initial activation, refresh of a known machine, and controlled reactivation of a revoked machine.
• Online validation of the signature, machine, activation, and license.
• Machine deactivation and invalidation of its token.
• Logging of significant events and service health diagnostics.
• English and French messages for the supplied Python tools.

The schema’s example product uses the code MYPRODUCT and the name MyProduct. It illustrates the service’s generic nature and does not prescribe the licensed software’s name.

Service interface

All responses use JSON. The interface separates health observation, activation-related operations, and administrative creation.

Response classes

Ordinary successes use HTTP classes 200 and 201. Invalid requests, missing authentication, license refusals, unknown objects, and quota conflicts use the 400 classes. Configuration, signing, and database failures use the 500 classes. Responses contain a success indicator and, for refusals, a stable error code.

Security model

• Transport: HTTPS protects exchange confidentiality and authenticity.
• Signature: Ed25519 makes token alteration detectable.
• Minimization: plaintext license keys and raw hardware identifiers are not stored by the server; their SHA-256 digests are.
• Administration: license creation is separated and protected by X-Admin-Key.
• Secrets: server/config.php contains MariaDB credentials, the administration key, and the private key; it belongs inside the hosting trust boundary.
• Traceability: events record the decision type and the IP address received by PHP, among other details.

Internal components

Invariants

• A product must exist and be active before a license can be issued for its code.
• A non-revoked activation occupies a quota slot; a revoked activation does not.
• The token, machine, and activation row must refer to one another consistently.
• A plaintext license key cannot be recovered from the database after creation.

Known limitations

• The supplied client stores next_check_days and offline_grace_days, but does not yet make its own offline authorization decision.
• Activation-attempt window and limit settings exist in configuration, but the current scripts do not enforce them.
• The administration utility creates licenses; it does not yet provide list, suspend, revoke, or reactivate commands.
• The supplied client is Windows-specific.
• The repository does not yet contain an automated test suite.

The service version is 1.0.6. Any change to the protocol, schema, or token payload must preserve compatibility or explicitly declare its break.

Glossary