Guide de l'utilisateur du SDK de chiffrement DRM-X 5.0

1Contenu du package SDK

Après avoir extrait l'archive DRM-X5.0_Encryption_SDK, le répertoire contient les fichiers suivants :

Les arguments de ligne de commande sont identiques sur les trois plateformes — seul le nom du fichier de programme diffère.

2Aperçu du flux de travail de chiffrement

Pourquoi appeler d'abord le service web DRM-X 5.0 ?L'argument -profile du programme de chiffrement n'est pas l'ID numérique du profil de licence — c'est une chaîne chiffrée liée à votre compte (ProfileEncryptedParam). Cette chaîne ne peut pas être générée localement ; elle ne peut être obtenue que via le service web. Elle correspond un à un à un ProfileID, et une fois obtenue, elle peut être mise en cache et réutilisée — vous n'avez pas besoin d'appeler le service web pour chaque fichier. Les valeurs Base64 des chemins d'entrée / sortie, en revanche, doivent être encodées localement dans votre programme (voir section 6) — aucun appel au service web n'est nécessaire pour elles.

3Prérequis

3.1 Informations de compte DRM-X 5.0 (obtenues depuis la console d'administration DRM-X)

3.2 Exigences relatives à l'environnement serveur

Rappel de sécurité : WebServiceAuthStr équivaut à une clé de compte. Il doit être stocké uniquement côté serveur — ne le placez jamais dans des pages web front-end, des logiciels clients ou des dépôts publics.

4Étape un : Appeler le service web DRM-X 5.0 pour obtenir les paramètres de chiffrement

4.1 Informations sur le service web

Le point de terminaison doit correspondre à l'édition de votre compte : les comptes internationaux utilisent 5.drm-x.com (ligne de commande : -server_domain com) ; les comptes Chine utilisent 5.drm-x.cn (ligne de commande : -server_domain cn). Utiliser la mauvaise édition entraînera l'échec de l'authentification, ou des fichiers chiffrés illisibles.

4.2 Paramètres de requête

4.3 Correspondance entre les champs de réponse et les arguments de ligne de commande (essentiel)

4.4 Exemple d'invocation (PHP / SoapClient)

Ce service web est un service standard SOAP 1.1 qui peut être appelé depuis n'importe quel langage, de la même manière uniforme : envoyez une enveloppe SOAP par POST au point de terminaison indiqué en 4.1 (ou faites-la générer automatiquement par un client SOAP à partir de ?WSDL), passez les paramètres de 4.2, puis lisez les trois champs de 4.3 dans la réponse. Bibliothèques clientes SOAP courantes par langage :

L'exemple suivant utilise SoapClient de PHP pour démontrer l'appel complet. Enregistrez le code sous get_params.php sur votre serveur et exécutez-le (PHP 7.4+ avec l'extension soap activée) — il affiche les trois valeurs d'arguments de ligne de commande :

<?php
// ========== Configuration (edit to match your account) ==========
$wsdl              = 'https://5.drm-x.com/haihaisoftlicenseservice.asmx?WSDL';  // China edition: https://5.drm-x.cn/...
$adminEmail        = 'admin@example.com';
$webServiceAuthStr = 'YOUR_AUTH_STRING';
$profileID         = '1001';
$input             = '/home/video/course01.mp4';
$output            = '/home/video/encrypted/course01_P.mp4';

// ========== Create a SoapClient (WSDL mode; the SOAP envelope is generated automatically) ==========
$client = new SoapClient($wsdl, [
    'soap_version'       => SOAP_1_1,
    'connection_timeout' => 20,
    'trace'              => true,          // enables __getLastRequest() for inspecting the raw request
]);

// ========== Call the method: the method name is the WSDL operation; arguments are an associative array ==========
$resp = $client->GetPackagerEncryptedParams([
    'AdminEmail'            => $adminEmail,
    'WebServiceAuthStr'     => $webServiceAuthStr,
    'ProfileID'             => $profileID,
    'Input'                 => $input,
    'Output'                => $output,
    'ProfileEncryptedParam' => '',
    'enc_Input'             => '',
    'enc_Output'            => '',
]);

// ========== The response is mapped to a stdClass object; read the fields directly ==========
$result  = $resp->GetPackagerEncryptedParamsResult;
$profile = $resp->ProfileEncryptedParam;   // this is the -profile argument value

if ($profile === '') {
    die("Call failed: $result\n");   // e.g. authentication errors appear here
}

// -profile: one call per ProfileID is enough. Cache it and reuse it —
//           do not call the Web Service again for every file you encrypt.
echo "-profile = $profile\n";

// Input / output paths: Base64-encode them locally (UTF-8). No Web Service call needed.
// If your PHP source file is saved as UTF-8, the strings are already UTF-8.
// Other languages work the same way: convert to UTF-8 bytes first, then Base64.
// (The service also returns enc_Input / enc_Output with the same values — either source is fine.)
$encIn  = base64_encode($input);
$encOut = base64_encode($output);
echo "-input_file_utf8_base64_encoded = $encIn\n";
echo "-output_file_utf8_base64_encoded = $encOut\n";

5Étape deux : Exécuter la commande de chiffrement

5.1 Première utilisation (Linux / macOS)

Dans un terminal, placez-vous dans le répertoire du programme et accordez d'abord la permission d'exécution :

# Linux
chmod +x drm-x5-encrypt-sdk-linux-x86_64

# macOS (pick the one matching your architecture)
chmod +x drm-x5-encrypt-sdk-macos-x86_64
chmod +x drm-x5-encrypt-sdk-macos-arm64

5.2 Modèles de commande de chiffrement d'un seul fichier

Windows (cmd / PowerShell):

drm-x5-encrypt-sdk.exe -server_domain com -profile <ProfileEncryptedParam value> -input_file_utf8_base64_encoded <Base64 of the input path> -output_file_utf8_base64_encoded <Base64 of the output path>

Linux:

./drm-x5-encrypt-sdk-linux-x86_64 -server_domain com -profile <ProfileEncryptedParam value> -input_file_utf8_base64_encoded <Base64 of the input path> -output_file_utf8_base64_encoded <Base64 of the output path>

macOS:

./drm-x5-encrypt-sdk-macos-arm64 -server_domain com -profile <ProfileEncryptedParam value> -input_file_utf8_base64_encoded <Base64 of the input path> -output_file_utf8_base64_encoded <Base64 of the output path>

5.3 Référence des arguments

5.4 Exemples complets

Windows:

drm-x5-encrypt-sdk.exe -server_domain com -profile UMuAZfLDToYGfmigBsRbklanDHRBoRrLrsTkI_W52KVnPcC-ZL-KU4UssGDA8Uja-4URQqsxw7WPsZL-CPWYQQj1jdwQsSbLri9_Q3YvPysCfMNtXKBHZvhrWlcsmNMg8FVqm7KFgr4ODrSQxAXgFV -input_file_utf8_base64_encoded RDpcSmFzb25caW5wdXRcMDEtdGVzdFZpZGVvLm1wNA== -output_file_utf8_base64_encoded RDpcSmFzb25cb3V0cHV0XDAxLXRlc3RWaWRlb19QLm1wNA==

Ici RDpcSmFzb25c... se décode en D:\Jason\input\01-testVideo.mp4.

Linux:

./drm-x5-encrypt-sdk-linux-x86_64 -server_domain com -profile s5Gls5QDAz4LyC_USkG9rY0fyDU4cN90HhgvOe6-67OUn92UFWRFdv4N_7Qx-Ipxa_M5d123ZQEesB1BPnGkUs-HkFTwI1pZEwaj133IRLhaxuUfOpBBROkKZpPk_QxBKvoxiX4NVL-Rs6g457jWsV -input_file_utf8_base64_encoded Li9pbnB1dC8wMS1saW51eC1lbmNyeXB0LXZpZGVvLm1wNA== -output_file_utf8_base64_encoded Li9vdXRwdXQvMDEtbGludXgtZW5jcnlwdC12aWRlbzJfUC5tcDQ=

Cela chiffre ./input/01-linux-encrypt-video.mp4 → ./output/01-linux-encrypt-video2_P.mp4.

5.5 Vérification du résultat

• Lorsque le programme se termine, vérifiez qu'un fichier chiffré a été créé dans le répertoire de sortie (un suffixe _P est recommandé pour le distinguer, par exemple course01_P.mp4) ;
• Le chiffrement nécessite un accès réseau au serveur DRM-X. Assurez-vous que votre pare-feu / groupe de sécurité autorise l'accès sortant à 5.drm-x.com ou 5.drm-x.cn ;
• Il est recommandé de vérifier le flux de travail complet avec une petite vidéo de test avant de chiffrer en lot le contenu de production.

6Encodage Base64 des chemins d'entrée / sortie (encodage local recommandé)

Pratique recommandée : générez les valeurs de -input_file_utf8_base64_encoded / -output_file_utf8_base64_encoded en les encodant dans votre propre programme — il n'est pas nécessaire d'appeler le service web une fois par fichier. La règle d'encodage : convertissez d'abord la chaîne de chemin en octets UTF-8, puis appliquez l'encodage Base64 standard. Remarque : vos fichiers sources doivent être enregistrés en UTF-8 (cela est particulièrement important pour les chemins non ASCII ; sous Windows, n'utilisez pas l'encodage ANSI / GBK). Exemples par langage :

Pour réitérer : il n'existe aucun moyen de générer l'argument -profile localement. C'est une chaîne chiffrée liée à votre compte et elle ne peut être obtenue que via le service web GetPackagerEncryptedParams.

7Exemples d'automatisation côté serveur

Enchaîner « obtenir les paramètres + invoquer le programme de chiffrement » permet un chiffrement en un clic depuis le back-office de votre site web, ou un chiffrement par lots planifié. L'exemple PHP suivant invoque le programme de chiffrement Linux (suite du code de la section 4.4 ; à l'exécution, $profile doit d'abord être lu depuis le cache, et le service web de 4.4 ne doit être appelé que lorsqu'aucune valeur en cache n'existe) :

<?php
// ...continuing from Section 4.4, with $profile / $encIn / $encOut already obtained:

$packager = '/opt/drmx5/drm-x5-encrypt-sdk-linux-x86_64';   // absolute path to the encryption program
$domain   = 'com';                                        // com = International, cn = China

// Make sure the output directory exists (the program does not create it)
$outDir = dirname(base64_decode($encOut));
if (!is_dir($outDir)) { mkdir($outDir, 0755, true); }

// Assemble and execute the command (escapeshellarg prevents injection; the argument
// values are Base64 and contain no spaces, so this is double protection)
$cmd = $packager
     . ' -server_domain '   . escapeshellarg($domain)
     . ' -profile '         . escapeshellarg($profile)
     . ' -input_file_utf8_base64_encoded '  . escapeshellarg($encIn)
     . ' -output_file_utf8_base64_encoded ' . escapeshellarg($encOut);

exec($cmd, $outLines, $exitCode);
echo 'Exit code: ' . $exitCode . PHP_EOL . implode(PHP_EOL, $outLines);

Exemple de script shell de chiffrement par lots (Linux — encode les chemins localement, puis chiffre chaque fichier) :

#!/bin/bash
# batch_encrypt.sh — batch-encrypt all mp4 files under ./input into ./output
ADMIN_EMAIL="admin@example.com"
AUTH_STR="YOUR_AUTH_STRING"
PROFILE_ID="1001"
PACKAGER="./drm-x5-encrypt-sdk-linux-x86_64"
DOMAIN="com"   # China edition: change to cn

mkdir -p ./output
for f in ./input/*.mp4; do
  name=$(basename "$f" .mp4)
  out="./output/${name}_P.mp4"
  # Base64-encode the paths locally (UTF-8)
  in_b64=$(printf '%s' "$f"  | base64 -w0)
  out_b64=$(printf '%s' "$out" | base64 -w0)
  # The -profile string should be obtained once by your server via the Web Service
  # and cached — the same ProfileID's value can be reused for every file.
  "$PACKAGER" -server_domain "$DOMAIN" -profile "$PROFILE_ENC" \
      -input_file_utf8_base64_encoded "$in_b64" \
      -output_file_utf8_base64_encoded "$out_b64"
  echo "[done] $out"
done

Pratique recommandée : récupérez le ProfileEncryptedParam pour un ProfileID donné une fois via le service web et mettez-le en cache pour le réutiliser — n'appelez pas le service web une fois par fichier chiffré. Générez les équivalents de enc_Input / enc_Output directement en encodant en Base64 (UTF-8) les chemins sur votre serveur (en PHP : base64_encode($path), voir section 6) — aucun appel au service web nécessaire. Lors du chiffrement par lots, limitez la concurrence (par exemple 2-4 processus de chiffrement par serveur) pour éviter de saturer la bande passante et le CPU.

8Foire aux questions (FAQ)

Q1 : Le service web renvoie « Your XML web service login info is not correct... »

AdminEmail ou WebServiceAuthStr est incorrect. Vérifiez les deux dans la console d'administration DRM-X ; assurez-vous que les valeurs n'ont pas d'espaces en début ou en fin. Notez également que même pour cette erreur, le code d'état HTTP reste 200 — votre programme doit déterminer le succès en inspectant les champs de réponse, et non le code d'état HTTP.

Q2 : Passer l'ID numérique (par exemple 1001) directement à -profile provoque une erreur

-profile doit être la chaîne chiffrée complète ProfileEncryptedParam renvoyée par le service web — pas l'ID numérique du profil. L'ID numérique n'est utilisé que lors de l'appel au service web.

Q3 : Le chemin contient des caractères non ASCII ou des espaces et le chiffrement échoue ?

Les chemins sont transportés en Base64, et les caractères non ASCII et les espaces sont entièrement pris en charge. La clé est que l'encodage doit utiliser UTF-8 : sous Windows, le Bloc-notes / cmd peuvent utiliser par défaut l'encodage ANSI (GBK), ce qui corrompt le chemin après le décodage Base64. Encodez les chemins en UTF-8 dans votre programme comme décrit à la section 6 (avec un fichier source PHP enregistré en UTF-8, un simple base64_encode() fonctionne directement ; les chaînes héritées encodées en GBK peuvent d'abord être converties avec iconv('GBK', 'UTF-8', $path) ou mb_convert_encoding() avant l'encodage).

Q4 : Le programme signale un échec de sortie / ne trouve pas le répertoire de sortie

Le répertoire parent du fichier de sortie doit être créé à l'avance (par exemple mkdir -p ./output). Vérifiez également que l'utilisateur exécutant le programme dispose de la permission d'écriture sur ce répertoire.

Q5 : macOS indique que le programme « cannot be opened because the developer cannot be verified »

Le programme n'est pas notarié par Apple, donc Gatekeeper bloque le premier lancement. Choisissez l'une ou l'autre des solutions : ① Exécutez xattr -d com.apple.quarantine ./drm-x5-encrypt-sdk-macos-arm64 dans un terminal pour supprimer l'indicateur de quarantaine ; ② Ou cliquez sur « Ouvrir quand même » dans Réglages Système → Confidentialité et sécurité.

Q6 : Sous Linux, le programme ne peut pas s'exécuter (Permission denied ou erreur de format)

Exécutez d'abord chmod +x drm-x5-encrypt-sdk-linux-x86_64. Si vous obtenez « cannot execute binary file », confirmez que le serveur est x86_64 (uname -m). Le package actuel ne fournit que des builds x86_64 ; pour les serveurs ARM, veuillez contacter Haihaisoft.

Q7 : Dois-je utiliser com ou cn ? Que se passe-t-il si je choisis le mauvais ?

Cela doit correspondre à la plateforme de votre compte DRM-X : les comptes internationaux utilisent com (et appellent 5.drm-x.com), les comptes Chine utilisent cn (et appellent 5.drm-x.cn). Une inadéquation provoque un échec d'authentification, ou des paramètres de chiffrement qui ne correspondent pas à la plateforme.

Q8 : Comment vérifier les fichiers chiffrés ?

Ouvrez les fichiers de sortie dans le lecteur de démonstration DRM-X 5.0 / votre lecteur intégré et confirmez : la lecture est bloquée sans licence, et fonctionne normalement après avoir autorisé un utilisateur test dans la console d'administration. Vérifiez à petite échelle avant le chiffrement de production en masse.

9Remarques et bonnes pratiques

• Conservez les fichiers originaux : écrivez la sortie dans un nouvel emplacement ou avec un nouveau nom de fichier (par exemple avec un suffixe _P) afin que les vidéos originales ne soient jamais écrasées.
• Petit avant grand : lorsque vous utilisez un nouveau profil ou un nouveau serveur pour la première fois, exécutez une courte vidéo de test à travers tout le flux « récupérer les paramètres → chiffrer → lecture sous licence » avant le traitement par lots.
• Ne modifiez jamais les arguments à la main : -profile est une chaîne chiffrée en Base64 — copiez-la intégralement (pas d'espaces supplémentaires en début/fin, pas de troncature par retour à la ligne).
• Gardez la chaîne d'authentification secrète : WebServiceAuthStr appartient uniquement à la configuration côté serveur ; ne déployez pas d'outils web de démonstration comme GetPackagerEncryptedParams.php sur l'internet public.
• Exigence réseau : pendant le chiffrement, le serveur doit pouvoir atteindre les serveurs DRM-X (International 5.drm-x.com / Chine 5.drm-x.cn) ; autorisez le port sortant 443 si un pare-feu est présent.