DTL_LicenseServer — Guide utilisateur

Installation du service et intégration détaillée dans une application Windows.

versionv1.0-6date21 juillet 2026publicadministrateurs et développeurslangueEnglishlicenceMIT

Objet et public

Ce guide explique comment mettre DTL_LicenseServer en œuvre : préparer MariaDB et PHP, protéger les secrets, déployer l’API, créer les licences et intégrer le client dans un logiciel Windows. Il s’adresse aux administrateurs du serveur et aux développeurs de l’application cliente.

La description des responsabilités, données et garanties du système figure dans le Manuel de référence.

Rappel fonctionnel

DTL_LicenseServer centralise la création, l’activation, la validation et la désactivation de licences limitées à un nombre de machines. L’API PHP signe les jetons avec Ed25519, MariaDB conserve l’état de référence et le client Windows n’envoie qu’une empreinte SHA-256 de la machine. Une machine désactivée peut être réactivée lorsque le quota le permet.

Préparer l’environnement

Prérequis serveur

serveur Web HTTPS capable d’exécuter PHP 8.1 ou supérieur ;
extensions PHP pdo_mysql, sodium et mbstring ;
base MariaDB avec tables InnoDB et encodage utf8mb4 ;
compte MariaDB dédié au service ;
Python 3.10 ou supérieur sur le poste d’administration et dans l’application cliente.

Adresse d’exemple. Toutes les commandes utilisent https://licenses.example.org/api/licenses. Remplacez-la par l’adresse HTTPS réelle de votre installation.

Créer le schéma MariaDB

Créez une base vide et un compte dédié dont les droits sont limités à cette base.
Importez database/netdtl_licenses.sql avec l’outil de votre hébergeur ou le client MariaDB.
Vérifiez la présence des tables products, licenses, activations, license_events et admin_users, ainsi que de la vue license_status.
Conservez le produit d’exemple MYPRODUCT pour les essais ou créez votre propre produit actif.

mariadb.exe -h DB_HOST -u DB_USER -p DB_NAME < database\netdtl_licenses.sql

Le script ne contient ni CREATE DATABASE ni USE : la base cible doit donc être sélectionnée lors de l’import.

Créer la configuration privée

Copy-Item .\server\config.example.php .\server\config.php

Modifiez ensuite server/config.php. Remplacez toutes les valeurs CHANGE_ME et adaptez le produit par défaut.

Clé	Valeur attendue
db.host / port	Adresse et port MariaDB, généralement 3306.
db.name / user / password	Base et compte dédiés au service.
db.charset	`utf8mb4`.
admin_api_key	Secret long, aléatoire et réservé à l’administration.
signing_*_key_b64	Paire Ed25519 encodée en Base64.
default_product_code	Code actif présent dans `products`, par exemple `MYPRODUCT`.

config.php ne doit jamais être placé dans Git, transmis au client ou servi comme texte. Les paramètres activation_attempt_* sont réservés à une limitation future et ne sont pas encore appliqués automatiquement.

Générer les clés Ed25519

php .\server\generate_signing_keys.php

Copiez la valeur signing_public_key_b64 dans la configuration.
Copiez la valeur signing_secret_key_b64 dans la configuration protégée.
Sauvegardez la clé privée dans un emplacement chiffré et séparé.
Retirez immédiatement generate_signing_keys.php du dossier Web public.

Changer ultérieurement cette paire invalide les jetons déjà émis et impose une nouvelle activation des clients.

Déployer l’API

Le dossier HTTPS public doit contenir uniquement activate.php, validate.php, deactivate.php, health.php, admin_create_license.php, lib.php et le config.php privé. Ne publiez ni les outils Python, ni le schéma, ni les sauvegardes, ni le générateur de clés.

Protégez particulièrement admin_create_license.php : en plus de X-Admin-Key, utilisez si possible une restriction d’adresse IP, une authentification du serveur Web ou un nom d’URL non public.

Contrôler le service

Ouvrez https://licenses.example.org/api/licenses/health.php. Une installation fonctionnelle renvoie un JSON contenant notamment :

{ "success": true, "service": "DTL_LicenseServer", "version": "1.0.6", "database": "ok" }

Un statut HTTP 503 avec DATABASE_UNAVAILABLE signifie que PHP répond, mais que la connexion MariaDB ou le schéma n’est pas opérationnel.

Configurer l’administration

Exécutez l’outil depuis la racine du projet afin que le catalogue bilingue soit importable. Placez l’adresse et la clé dans la session PowerShell ; la clé peut être omise pour être saisie sans écho.

$env:NETDTL_LICENSE_API = 'https://licenses.example.org/api/licenses' $env:NETDTL_ADMIN_KEY = 'secret-identique-a-config.php' $env:DTL_LANGUAGE = 'fr'

Les options globales --base-url et --admin-key doivent précéder la sous-commande create. Évitez --admin-key sur un poste partagé, car sa valeur peut rester dans l’historique.

Créer une licence

python -m admin.DTLlicense create ` --email 'client@example.org' ` --customer-name 'Client exemple' ` --product 'MYPRODUCT' ` --machines 2 ` --expires '2027-12-31 23:59:59' ` --notes 'Commande 2026-001'

Option	Rôle
--email	Courriel associé à la licence ; demandé si absent.
--customer-name	Nom facultatif du client.
--product	Code actif de la table `products`.
--machines	Nombre autorisé de machines, de 1 à 1000.
--expires	Échéance MariaDB facultative au format indiqué.
--notes	Note administrative libre.

Clé unique. La clé en clair n’est affichée qu’une fois. Enregistrez-la immédiatement dans un gestionnaire de secrets ou transmettez-la par un canal approprié.

Intégrer le client Windows

Copiez client/dtl_license_client.py dans les sources de l’application. Avant tout essai, remplacez ses valeurs spécifiques par celles de votre produit :

PRODUCT_CODE = "MYPRODUCT" CLIENT_VERSION = "1.0.2" DEFAULT_API_BASE = "https://licenses.example.org/api/licenses" TOKEN_FILE = Path(os.environ.get("PROGRAMDATA", ".")) / "Vendor" / "MyProduct" / "license.json"

Adaptez également le préfixe des messages %DTL4U-... si l’application affiche ces diagnostics. Le code produit doit correspondre exactement à une ligne active de products. Le module n’utilise que la bibliothèque standard de Python.

Déclencher l’activation

Votre écran d’activation doit recueillir le courriel et la clé, puis appeler :

from dtl_license_client import activate result = activate( email=email_saisi, license_key=cle_saisie, app_version=APP_VERSION, api_base="https://licenses.example.org/api/licenses", )

En cas de succès, le module écrit le jeton, l’empreinte de la machine, la date de validation et les valeurs de planification dans TOKEN_FILE. Ne journalisez jamais la clé en clair. Affichez les erreurs LicenseError à l’utilisateur sans exposer de trace technique.

Valider au démarrage

from dtl_license_client import LicenseError, validate try: validate(api_base="https://licenses.example.org/api/licenses") except LicenseError as exc: afficher_erreur_licence(str(exc)) fermer_application()

La validation vérifie d’abord que le fichier local existe et appartient à la machine courante, puis interroge le serveur. Appelez-la avant de rendre disponibles les fonctions protégées. Le client fourni mémorise next_check_days et offline_grace_days, mais n’implémente pas encore une décision hors ligne : tant que votre application n’ajoute pas cette politique, considérez l’échec réseau comme un échec de validation.

Désactiver une installation

from dtl_license_client import deactivate deactivate(api_base="https://licenses.example.org/api/licenses")

Après confirmation de l’utilisateur, cet appel révoque l’activation côté serveur puis supprime le jeton local. S’il n’existe aucun fichier local, il se termine sans erreur et indique qu’aucune désactivation n’a eu lieu.

Réactiver une machine

Une machine désactivée se réactive avec le même courriel et la même clé en repassant par activate(). Le serveur recompte d’abord les activations non révoquées. Si une place est libre, il réutilise la ligne existante, efface sa date de révocation et émet un nouveau jeton ; sinon il renvoie ACTIVATION_LIMIT_REACHED.

Mise en production

imposez HTTPS et un certificat valide ;
limitez les droits du compte MariaDB à la base du service ;
protégez config.php, la clé privée et les sauvegardes ;
restreignez le point d’administration et surveillez license_events ;
protégez les droits NTFS du dossier contenant le jeton local ;
conservez ensemble la base et la clé privée dans le plan de reprise ;
ne présentez pas le mode hors ligne comme disponible tant qu’il n’est pas implémenté dans le produit.

Recette minimale

Vérifiez que health.php annonce la base opérationnelle.
Créez une licence d’essai limitée à une machine.
Activez et validez la première machine.
Vérifiez qu’une deuxième machine est refusée.
Désactivez la première et vérifiez que son ancien jeton est refusé.
Réactivez-la et vérifiez que le même identifiant d’activation est réutilisé.
Contrôlez les événements correspondants dans MariaDB.

Le dépôt ne contient pas encore de tests automatisés ; effectuez cette recette sur une base et un service de test avant la production.

Dépannage

Message	Contrôle
SERVER_NOT_CONFIGURED	Présence et lisibilité de `server/config.php`.
DATABASE_UNAVAILABLE	Hôte, port, identifiants, droits et import du schéma.
SODIUM_NOT_AVAILABLE	Activation de l’extension Sodium dans PHP.
INVALID_SIGNING_KEY	Valeurs Base64 complètes et paire de clés cohérente.
PRODUCT_NOT_FOUND	Code présent et actif dans `products`.
UNAUTHORIZED	Égalité entre `NETDTL_ADMIN_KEY` et `admin_api_key`.
ACTIVATION_LIMIT_REACHED	Nombre d’activations non révoquées et quota de la licence.
ACTIVATION_REVOKED	Ancien jeton désactivé ; recommencer une activation avec les justificatifs.

Aide-mémoire des fichiers

Serveur

server/*.phpdatabase/netdtl_licenses.sql

API, configuration privée, générateur ponctuel et schéma MariaDB.

Administration

admin/DTLlicense.pydtl_licenseserver_i18n.py

Création des licences et messages bilingues.

Application

client/dtl_license_client.py%ProgramData%\Vendor\MyProduct\license.json

Client à adapter et jeton local créé après activation.