دليل مستخدم DRM-X 5.0 Encryption SDK

1محتويات حزمة SDK

بعد استخراج أرشيف DRM-X5.0_Encryption_SDK، يحتوي الدليل على الملفات التالية:

وسائط سطر الأوامر متطابقة عبر جميع المنصات الثلاث — يختلف فقط اسم ملف البرنامج.

2نظرة عامة على سير عمل التشفير

لماذا تستدعي خدمة ويب DRM-X 5.0 أولاً؟وسيطة -profile في برنامج التشفير ليست المعرّف الرقمي لملف ترخيص الحساب — بل هي سلسلة مشفرة مرتبطة بحسابك (ProfileEncryptedParam). لا يمكن إنشاء هذه السلسلة محلياً؛ يمكن الحصول عليها فقط من خلال خدمة الويب. وهي ترتبط بنسبة واحدة لواحد مع ProfileID، وبمجرد الحصول عليها يمكن تخزينها وإعادة استخدامها — لا تحتاج لاستدعاء خدمة الويب لكل ملف. أما قيم Base64 لمسارات الإدخال / الإخراج، فيجب ترميزها محلياً في برنامجك (راجع القسم 6) — لا حاجة لاستدعاء خدمة الويب من أجلها.

3المتطلبات الأساسية

3.1 معلومات حساب DRM-X 5.0 (تُستخرج من وحدة تحكم إدارة DRM-X)

3.2 متطلبات بيئة الخادم

تذكير أمني: WebServiceAuthStr يعادل مفتاح حساب. يجب تخزينه على جانب الخادم فقط — لا تضعه أبداً في صفحات الويب الأمامية أو برامج العميل أو المستودعات العامة.

4الخطوة الأولى: استدعاء خدمة ويب DRM-X 5.0 للحصول على معلمات التشفير

4.1 معلومات خدمة الويب

يجب أن تتطابق نقطة النهاية مع إصدار حسابك: الحسابات الدولية تستخدم 5.drm-x.com (سطر الأوامر: -server_domain com)؛ حسابات الصين تستخدم 5.drm-x.cn (سطر الأوامر: -server_domain cn). استخدام الإصدار الخاطئ سيؤدي إلى فشل المصادقة، أو جعل الملفات المشفرة غير قابلة للتشغيل.

4.2 معلمات الطلب

4.3 التعيين بين حقول الاستجابة ووسائط سطر الأوامر (الأساسية)

4.4 مثال الاستدعاء (PHP / SoapClient)

خدمة الويب هذه هي خدمة SOAP 1.1 قياسية يمكن استدعاؤها من أي لغة، بنفس الطريقة الموحدة: أرسل POST لظرف SOAP إلى نقطة النهاية المذكورة في 4.1 (أو اجعل عميل SOAP يُنشئه تلقائياً من ?WSDL)، مرر المعلمات من 4.2، ثم اقرأ الحقول الثلاثة من 4.3 في الاستجابة. مكتبات عميل SOAP الشائعة حسب اللغة:

يستخدم المثال التالي SoapClient في PHP لعرض الاستدعاء الكامل. احفظ الكود باسم get_params.php على خادمك وقم بتشغيله (PHP 7.4+ مع تمكين امتداد soap) — سيطبع قيم وسائط سطر الأوامر الثلاث:

<?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الخطوة الثانية: تشغيل أمر التشفير

5.1 الاستخدام الأول (Linux / macOS)

في الطرفية، انتقل إلى دليل البرنامج وامنح إذن التنفيذ أولاً:

# 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 قوالب أوامر تشفير الملف الواحد

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 مرجع الوسائط

5.4 أمثلة كاملة

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==

هنا RDpcSmFzb25c... تفك ترميزها إلى 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=

هذا يشفر ./input/01-linux-encrypt-video.mp4 → ./output/01-linux-encrypt-video2_P.mp4.

5.5 التحقق من النتيجة

• عند انتهاء البرنامج، تحقق من إنشاء ملف مشفر في دليل الإخراج (يُوصى بإضافة لاحقة _P للتمييز، مثلاً course01_P.mp4)؛
• يتطلب التشفير وصولاً إلى شبكة خادم DRM-X. تأكد من أن جدار الحماية / مجموعة الأمان يسمح بالوصول الصادر إلى 5.drm-x.com أو 5.drm-x.cn؛
• يُوصى بالتحقق من سير العمل الكامل باستخدام مقطع فيديو تجريبي صغير قبل تشفير المحتوى الإنتاجي دفعة واحدة.

6ترميز Base64 لمسارات الإدخال / الإخراج (يُوصى بالترميز المحلي)

الممارسة الموصى بها: أنشئ قيم -input_file_utf8_base64_encoded / -output_file_utf8_base64_encoded عن طريق ترميزها في برنامجك الخاص — لا حاجة لاستدعاء خدمة الويب لكل ملف. قاعدة الترميز: حوّل أولاً سلسلة المسار إلى بايتات UTF-8، ثم طبّق ترميز Base64 القياسي. ملاحظة: يجب حفظ ملفات المصدر الخاصة بك بصيغة UTF-8 (هذا مهم خصوصاً للمسارات غير ASCII؛ على Windows، لا تستخدم ترميز ANSI / GBK). أمثلة حسب اللغة:

للتأكيد مرة أخرى: لا توجد طريقة لإنشاء وسيطة -profile محلياً. إنها سلسلة مشفرة مرتبطة بحسابك ولا يمكن الحصول عليها إلا من خلال خدمة ويب GetPackagerEncryptedParams.

7أمثلة على الأتمتة من جهة الخادم

يُتيح ربط "الحصول على المعلمات + استدعاء برنامج التشفير" تشفيراً بنقرة واحدة من لوحة تحكم موقعك، أو تشفيراً مجدولاً دفعة واحدة. يستدعي مثال PHP التالي برنامج تشفير Linux (متابعةً للكود في القسم 4.4؛ في وقت التشغيل، يجب قراءة $profile من ذاكرة التخزين المؤقت أولاً، واستدعاء خدمة الويب في 4.4 فقط عند عدم وجود قيمة مخزنة):

<?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);

مثال على سكريبت Shell لتشفير دفعة (Linux — يرمز المسارات محلياً، ثم يشفر كل ملف):

#!/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

الممارسة الموصى بها: اجلب ProfileEncryptedParam لملف ترخيص الحساب (ProfileID) معين مرة واحدة عبر خدمة الويب وخزّنه لإعادة الاستخدام — لا تستدعي خدمة الويب لكل ملف مشفر. أنشئ مكافئات enc_Input / enc_Output مباشرةً عن طريق ترميز المسارات بـ Base64 (UTF-8) على خادمك (في PHP: base64_encode($path)، راجع القسم 6) — لا حاجة لاستدعاء خدمة الويب. عند التشفير الدفعي، حدّ من التزامن (مثلاً 2-4 عمليات تشفير لكل خادم) لتجنب إشباع النطاق الترددي ووحدة المعالجة المركزية.

8الأسئلة الشائعة (FAQ)

س1: تُعيد خدمة الويب رسالة "Your XML web service login info is not correct..."

AdminEmail أو WebServiceAuthStr غير صحيح. تحقق من كليهما في وحدة تحكم إدارة DRM-X؛ تأكد من أن القيم لا تحتوي على مسافات بادئة أو لاحقة. لاحظ أيضاً أنه حتى مع هذا الخطأ فإن رمز حالة HTTP لا يزال 200 — يجب على برنامجك تحديد النجاح من خلال فحص حقول الاستجابة، وليس رمز حالة HTTP.

س2: تمرير المعرّف الرقمي (مثلاً 1001) مباشرةً إلى -profile يسبب خطأً

-profile يجب أن يكون سلسلة ProfileEncryptedParam المشفرة الكاملة المُعادة بواسطة خدمة الويب — وليس المعرّف الرقمي لـ ProfileID. يُستخدم المعرّف الرقمي فقط عند استدعاء خدمة الويب.

س3: يحتوي المسار على أحرف غير ASCII أو مسافات ويفشل التشفير؟

يتم نقل المسارات كـ Base64، وتُدعم الأحرف غير ASCII والمسافات بالكامل. المفتاح هو أن الترميز يجب أن يستخدم UTF-8: على Windows، قد يستخدم Notepad / cmd ترميز ANSI (GBK) افتراضياً، مما يُتلف المسار بعد فك ترميز Base64. رمّز المسارات بصيغة UTF-8 في برنامجك كما هو موضح في القسم 6 (مع ملف مصدر PHP محفوظ بصيغة UTF-8، base64_encode() العادية تعمل مباشرةً؛ يمكن تحويل السلاسل المرمزة بـ GBK القديمة أولاً باستخدام iconv('GBK', 'UTF-8', $path) أو mb_convert_encoding() قبل الترميز).

س4: يُبلغ البرنامج عن فشل الإخراج / عدم العثور على دليل الإخراج

يجب إنشاء الدليل الأصلي لملف الإخراج مقدماً (مثلاً mkdir -p ./output). تحقق أيضاً من أن المستخدم الذي يُشغل البرنامج لديه إذن الكتابة في ذلك الدليل.

س5: يقول macOS إن البرنامج "لا يمكن فتحه لأنه لا يمكن التحقق من المطور"

البرنامج غير معتمد من Apple، لذا يمنع Gatekeeper التشغيل الأول. اختر أحد الحلين: ① نفّذ xattr -d com.apple.quarantine ./drm-x5-encrypt-sdk-macos-arm64 في الطرفية لإزالة علامة الحجر الصحي؛ ② أو انقر على "فتح بأي حال" في إعدادات النظام → الخصوصية والأمان.

س6: على Linux لا يمكن تنفيذ البرنامج (Permission denied أو خطأ في التنسيق)

نفّذ chmod +x drm-x5-encrypt-sdk-linux-x86_64 أولاً. إذا حصلت على "cannot execute binary file"، تأكد من أن الخادم x86_64 (uname -m). الحزمة الحالية تحتوي على إصدارات x86_64 فقط؛ لخوادم ARM يرجى الاتصال بـ Haihaisoft.

س7: هل يجب أن أستخدم com أم cn؟ ماذا يحدث إذا اخترت الخاطئ؟

يجب أن يتطابق مع منصة حساب DRM-X: الحسابات الدولية تستخدم com (وتستدعي 5.drm-x.com)، حسابات الصين تستخدم cn (وتستدعي 5.drm-x.cn). عدم التطابق يسبب فشل المصادقة، أو معلمات تشفير لا تتطابق مع المنصة.

س8: كيف أتحقق من الملفات المشفرة؟

افتح ملفات الإخراج في مشغل عرض DRM-X 5.0 التجريبي / مشغلك المدمج وتأكد: التشغيل محظور بدون ترخيص، ويعمل بشكل طبيعي بعد تفويض مستخدم تجريبي في وحدة التحكم الإدارية. تحقق على نطاق صغير قبل التشفير الإنتاجي بالجملة.

9ملاحظات وأفضل الممارسات

• احتفظ بالملفات الأصلية: اكتب الإخراج إلى موقع جديد أو اسم ملف جديد (مثلاً بإضافة لاحقة _P) حتى لا تُستبدل مقاطع الفيديو الأصلية أبداً.
• الصغير قبل الكبير: عند استخدام ملف ترخيص جديد أو خادم جديد لأول مرة، شغّل مقطع فيديو تجريبي قصير عبر سير العمل الكامل "جلب المعلمات → تشفير → تشغيل مرخص" قبل المعالجة الدفعية.
• لا تعدّل الوسائط يدوياً أبداً: -profile سلسلة Base64 مشفرة — انسخها بالكامل (بدون مسافات إضافية بادئة/لاحقة، بدون اقتطاع بسبب التفاف الأسطر).
• احتفظ بسرية سلسلة المصادقة: WebServiceAuthStr يخص تكوين الخادم فقط؛ لا تنشر أدوات ويب تجريبية مثل GetPackagerEncryptedParams.php على الإنترنت العام.
• متطلبات الشبكة: أثناء التشفير، يجب أن يصل الخادم إلى خوادم DRM-X (الدولية 5.drm-x.com / الصين 5.drm-x.cn)؛ اسمح بمنفذ 443 الصادر إذا كان هناك جدار حماية.