Hướng dẫn sử dụng DRM-X 5.0 Encryption SDK

1Nội dung gói SDK

Sau khi giải nén kho lưu trữ DRM-X5.0_Encryption_SDK, thư mục chứa các tệp sau:

Các đối số dòng lệnh giống hệt nhau trên cả ba nền tảng — chỉ khác tên tệp chương trình.

2Tổng quan về quy trình mã hóa

Tại sao phải gọi dịch vụ web DRM-X 5.0 trước?Đối số -profile của chương trình mã hóa không phải là ID số của hồ sơ giấy phép — mà là một chuỗi mã hóa gắn với tài khoản của bạn (ProfileEncryptedParam). Chuỗi này không thể tạo cục bộ; chỉ có thể lấy được thông qua dịch vụ web. Nó ánh xạ một-một với ProfileID, và một khi đã lấy được thì có thể lưu vào bộ nhớ đệm và tái sử dụng — bạn không cần gọi dịch vụ web cho mỗi tệp. Ngược lại, các giá trị Base64 của đường dẫn đầu vào / đầu ra nên được mã hóa cục bộ trong chương trình của bạn (xem Phần 6) — không cần gọi dịch vụ web cho chúng.

3Điều kiện tiên quyết

3.1 Thông tin tài khoản DRM-X 5.0 (lấy từ bảng điều khiển quản trị DRM-X)

3.2 Yêu cầu môi trường máy chủ

Nhắc nhở bảo mật: WebServiceAuthStr tương đương với khóa tài khoản. Phải được lưu trữ chỉ ở phía máy chủ — không bao giờ đặt nó trong các trang web giao diện người dùng, phần mềm khách hoặc kho lưu trữ công khai.

4Bước một: Gọi dịch vụ web DRM-X 5.0 để lấy tham số mã hóa

4.1 Thông tin dịch vụ web

Điểm cuối phải khớp với phiên bản tài khoản của bạn: tài khoản quốc tế sử dụng 5.drm-x.com (dòng lệnh: -server_domain com); tài khoản Trung Quốc sử dụng 5.drm-x.cn (dòng lệnh: -server_domain cn). Sử dụng sai phiên bản sẽ khiến xác thực thất bại, hoặc các tệp đã mã hóa không thể phát được.

4.2 Tham số yêu cầu

4.3 Ánh xạ giữa các trường phản hồi và đối số dòng lệnh (Cốt lõi)

4.4 Ví dụ gọi (PHP / SoapClient)

Dịch vụ web này là dịch vụ SOAP 1.1 tiêu chuẩn, có thể được gọi từ bất kỳ ngôn ngữ nào, theo cùng một cách thống nhất: POST một phong bì SOAP đến điểm cuối được liệt kê trong 4.1 (hoặc để máy khách SOAP tự động tạo nó từ ?WSDL), truyền các tham số từ 4.2, sau đó đọc ba trường từ 4.3 trong phản hồi. Các thư viện máy khách SOAP phổ biến theo ngôn ngữ:

Ví dụ sau sử dụng SoapClient của PHP để minh họa cuộc gọi đầy đủ. Lưu mã dưới dạng get_params.php trên máy chủ của bạn và chạy nó (PHP 7.4+ với tiện ích mở rộng soap được bật) — nó in ra ba giá trị đối số dòng lệnh:

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

5Bước hai: Chạy lệnh mã hóa

5.1 Sử dụng lần đầu (Linux / macOS)

Trong terminal, chuyển vào thư mục của chương trình và cấp quyền thực thi trước:

# 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 Mẫu lệnh mã hóa một tệp

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 Tham chiếu đối số

5.4 Ví dụ đầy đủ

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

Ở đây RDpcSmFzb25c... giải mã thành 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=

Điều này mã hóa ./input/01-linux-encrypt-video.mp4 → ./output/01-linux-encrypt-video2_P.mp4.

5.5 Xác minh kết quả

• Khi chương trình kết thúc, hãy kiểm tra xem một tệp đã mã hóa đã được tạo trong thư mục đầu ra chưa (nên dùng hậu tố _P để phân biệt, ví dụ course01_P.mp4);
• Mã hóa yêu cầu quyền truy cập mạng đến máy chủ DRM-X. Đảm bảo tường lửa / nhóm bảo mật của bạn cho phép truy cập ra ngoài đến 5.drm-x.com hoặc 5.drm-x.cn;
• Nên xác minh toàn bộ quy trình với một video thử nghiệm nhỏ trước khi mã hóa hàng loạt nội dung sản xuất.

6Mã hóa Base64 cho đường dẫn đầu vào / đầu ra (Nên mã hóa cục bộ)

Thực tiễn được khuyến nghị: tạo các giá trị của -input_file_utf8_base64_encoded / -output_file_utf8_base64_encoded bằng cách mã hóa chúng trong chương trình của riêng bạn — không cần gọi dịch vụ web một lần cho mỗi tệp. Quy tắc mã hóa: trước tiên chuyển đổi chuỗi đường dẫn thành byte UTF-8, sau đó áp dụng mã hóa Base64 tiêu chuẩn. Lưu ý: các tệp nguồn của bạn phải được lưu dưới dạng UTF-8 (điều này đặc biệt quan trọng đối với đường dẫn không phải ASCII; trên Windows, không sử dụng mã hóa ANSI / GBK). Ví dụ theo ngôn ngữ:

Để nhấn mạnh lại: không có cách nào tạo đối số -profile cục bộ. Đây là một chuỗi mã hóa gắn với tài khoản của bạn và chỉ có thể lấy được thông qua dịch vụ web GetPackagerEncryptedParams.

7Ví dụ tự động hóa phía máy chủ

Chuỗi "lấy tham số + gọi chương trình mã hóa" cho phép mã hóa một cú nhấp từ back office trang web của bạn, hoặc mã hóa hàng loạt theo lịch. Ví dụ PHP sau gọi chương trình mã hóa Linux (tiếp tục từ mã trong Phần 4.4; khi chạy, $profile nên được đọc từ bộ nhớ đệm trước, và dịch vụ web trong 4.4 chỉ được gọi khi không có giá trị được lưu trong bộ nhớ đệm):

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

Ví dụ script shell mã hóa hàng loạt (Linux — mã hóa đường dẫn cục bộ, sau đó mã hóa từng tệp):

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

Thực tiễn được khuyến nghị: lấy ProfileEncryptedParam cho một ProfileID nhất định một lần thông qua dịch vụ web và lưu vào bộ nhớ đệm để tái sử dụng — không gọi dịch vụ web một lần cho mỗi tệp đã mã hóa. Tạo các giá trị tương đương enc_Input / enc_Output trực tiếp bằng cách mã hóa Base64 (UTF-8) các đường dẫn trên máy chủ của bạn (trong PHP: base64_encode($path), xem Phần 6) — không cần gọi dịch vụ web. Khi mã hóa hàng loạt, hãy giới hạn đồng thời (ví dụ 2-4 tiến trình mã hóa mỗi máy chủ) để tránh làm bão hòa băng thông và CPU.

8Câu hỏi thường gặp (FAQ)

Q1: Dịch vụ web trả về "Your XML web service login info is not correct..."

AdminEmail hoặc WebServiceAuthStr không chính xác. Kiểm tra lại cả hai trong bảng điều khiển quản trị DRM-X; đảm bảo các giá trị không có dấu cách ở đầu hoặc cuối. Cũng lưu ý rằng ngay cả với lỗi này, mã trạng thái HTTP vẫn là 200 — chương trình của bạn phải xác định thành công bằng cách kiểm tra các trường phản hồi, không phải mã trạng thái HTTP.

Q2: Truyền ID dạng số (ví dụ 1001) trực tiếp vào -profile gây ra lỗi

-profile phải là chuỗi mã hóa ProfileEncryptedParam đầy đủ do dịch vụ web trả về — không phải ID Profile dạng số. ID dạng số chỉ được sử dụng khi gọi dịch vụ web.

Q3: Đường dẫn chứa ký tự không phải ASCII hoặc dấu cách và mã hóa thất bại?

Đường dẫn được vận chuyển dưới dạng Base64, và các ký tự không phải ASCII và dấu cách được hỗ trợ đầy đủ. Điều quan trọng là mã hóa phải sử dụng UTF-8: trên Windows, Notepad / cmd có thể mặc định sử dụng mã hóa ANSI (GBK), làm hỏng đường dẫn sau khi giải mã Base64. Mã hóa đường dẫn dưới dạng UTF-8 trong chương trình của bạn như mô tả trong Phần 6 (với tệp nguồn PHP được lưu dưới dạng UTF-8, base64_encode() thuần hoạt động trực tiếp; các chuỗi mã hóa GBK cũ có thể được chuyển đổi trước bằng iconv('GBK', 'UTF-8', $path) hoặc mb_convert_encoding() trước khi mã hóa).

Q4: Chương trình báo lỗi đầu ra / không thể tìm thấy thư mục đầu ra

Thư mục cha của tệp đầu ra phải được tạo trước (ví dụ mkdir -p ./output). Cũng xác minh rằng người dùng chạy chương trình có quyền ghi cho thư mục đó.

Q5: macOS báo chương trình "cannot be opened because the developer cannot be verified"

Chương trình không được Apple công chứng, vì vậy Gatekeeper chặn lần khởi chạy đầu tiên. Chọn một trong hai cách khắc phục: ① Chạy xattr -d com.apple.quarantine ./drm-x5-encrypt-sdk-macos-arm64 trong terminal để xóa cờ cách ly; ② Hoặc nhấp "Open Anyway" trong System Settings → Privacy & Security.

Q6: Trên Linux chương trình không thể thực thi (Permission denied hoặc lỗi định dạng)

Chạy chmod +x drm-x5-encrypt-sdk-linux-x86_64 trước. Nếu bạn nhận được "cannot execute binary file", xác nhận máy chủ là x86_64 (uname -m). Gói hiện tại chỉ cung cấp bản dựng x86_64; đối với máy chủ ARM, vui lòng liên hệ Haihaisoft.

Q7: Tôi nên sử dụng com hay cn? Điều gì xảy ra nếu tôi chọn sai?

Phải khớp với nền tảng tài khoản DRM-X của bạn: tài khoản quốc tế sử dụng com (và gọi 5.drm-x.com), tài khoản Trung Quốc sử dụng cn (và gọi 5.drm-x.cn). Sự không khớp gây ra lỗi xác thực, hoặc tham số mã hóa không khớp với nền tảng.

Q8: Làm thế nào để xác minh các tệp đã mã hóa?

Mở các tệp đầu ra trong trình phát demo DRM-X 5.0 / trình phát tích hợp của bạn và xác nhận: phát lại bị chặn nếu không có giấy phép và phát bình thường sau khi ủy quyền cho người dùng thử nghiệm trong bảng điều khiển quản trị. Xác minh ở quy mô nhỏ trước khi mã hóa sản xuất hàng loạt.

9Ghi chú và thực tiễn tốt nhất

• Giữ các tệp gốc: ghi đầu ra vào một vị trí mới hoặc tên tệp mới (ví dụ với hậu tố _P) để các video gốc không bao giờ bị ghi đè.
• Nhỏ trước lớn: khi sử dụng hồ sơ mới hoặc máy chủ mới lần đầu tiên, hãy chạy một video thử nghiệm ngắn qua toàn bộ quy trình "lấy tham số → mã hóa → phát lại có giấy phép" trước khi xử lý hàng loạt.
• Không bao giờ chỉnh sửa đối số bằng tay: -profile là chuỗi mã hóa Base64 — sao chép đầy đủ (không có dấu cách thừa ở đầu/cuối, không bị cắt do ngắt dòng).
• Giữ bí mật chuỗi xác thực: WebServiceAuthStr chỉ thuộc cấu hình phía máy chủ; không triển khai các công cụ web demo như GetPackagerEncryptedParams.php lên internet công khai.
• Yêu cầu mạng: trong quá trình mã hóa, máy chủ phải tiếp cận được các máy chủ DRM-X (Quốc tế 5.drm-x.com / Trung Quốc 5.drm-x.cn); cho phép cổng ra 443 nếu có tường lửa.