Guía del usuario del SDK de cifrado DRM-X 5.0

1Contenido del paquete SDK

Tras extraer el archivo DRM-X5.0_Encryption_SDK, el directorio contiene los siguientes archivos:

Los argumentos de la línea de comandos son idénticos en las tres plataformas — solo difiere el nombre del archivo del programa.

2Descripción general del flujo de trabajo de cifrado

¿Por qué llamar primero al servicio web de DRM-X 5.0?El argumento -profile del programa de cifrado no es el ID numérico del perfil de licencia — es una cadena cifrada vinculada a su cuenta (ProfileEncryptedParam). Esta cadena no se puede generar localmente; solo se puede obtener a través del servicio web. Se asigna uno a uno a un ProfileID, y una vez obtenida se puede guardar en caché y reutilizar — no necesita llamar al servicio web por cada archivo. Los valores Base64 de las rutas de entrada / salida, en cambio, deben codificarse localmente en su programa (véase la sección 6) — no se necesita ninguna llamada al servicio web para ellos.

3Requisitos previos

3.1 Información de la cuenta DRM-X 5.0 (obtenida de la consola de administración de DRM-X)

3.2 Requisitos del entorno del servidor

Recordatorio de seguridad: WebServiceAuthStr equivale a una clave de cuenta. Debe almacenarse únicamente en el lado del servidor — nunca la coloque en páginas web de front-end, software de cliente ni repositorios públicos.

4Paso uno: Llamar al servicio web de DRM-X 5.0 para obtener los parámetros de cifrado

4.1 Información del servicio web

El punto de conexión debe coincidir con la edición de su cuenta: las cuentas internacionales usan 5.drm-x.com (línea de comandos: -server_domain com); las cuentas de China usan 5.drm-x.cn (línea de comandos: -server_domain cn). Usar la edición incorrecta provocará que la autenticación falle, o que los archivos cifrados no se puedan reproducir.

4.2 Parámetros de la solicitud

4.3 Correspondencia entre los campos de respuesta y los argumentos de la línea de comandos (núcleo)

4.4 Ejemplo de invocación (PHP / SoapClient)

Este servicio web es un servicio estándar SOAP 1.1 que se puede llamar desde cualquier lenguaje, de la misma manera uniforme: envíe por POST un sobre SOAP al punto de conexión indicado en 4.1 (o haga que un cliente SOAP lo genere automáticamente a partir de ?WSDL), pase los parámetros de 4.2 y luego lea los tres campos de 4.3 en la respuesta. Bibliotecas de cliente SOAP comunes por lenguaje:

El siguiente ejemplo utiliza SoapClient de PHP para demostrar la llamada completa. Guarde el código como get_params.php en su servidor y ejecútelo (PHP 7.4+ con la extensión soap habilitada) — imprime los tres valores de los argumentos de la línea de comandos:

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

5Paso dos: Ejecutar el comando de cifrado

5.1 Primer uso (Linux / macOS)

En una terminal, cambie al directorio del programa y conceda primero el permiso de ejecución:

# 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 Plantillas de comando de cifrado de un solo archivo

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 Referencia de argumentos

5.4 Ejemplos completos

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

Aquí RDpcSmFzb25c... se decodifica a 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=

Esto cifra ./input/01-linux-encrypt-video.mp4 → ./output/01-linux-encrypt-video2_P.mp4.

5.5 Verificar el resultado

• Cuando el programa termine, compruebe que se haya creado un archivo cifrado en el directorio de salida (se recomienda un sufijo _P para distinguirlo, por ejemplo course01_P.mp4);
• El cifrado requiere acceso de red al servidor DRM-X. Asegúrese de que su cortafuegos / grupo de seguridad permita el acceso saliente a 5.drm-x.com o 5.drm-x.cn;
• Se recomienda verificar el flujo de trabajo completo con un vídeo de prueba pequeño antes de cifrar contenido de producción en lote.

6Codificación Base64 de las rutas de entrada / salida (se recomienda la codificación local)

Práctica recomendada: genere los valores de -input_file_utf8_base64_encoded / -output_file_utf8_base64_encoded codificándolos en su propio programa — no es necesario llamar al servicio web una vez por archivo. La regla de codificación: convierta primero la cadena de ruta a bytes UTF-8 y luego aplique la codificación Base64 estándar. Nota: sus archivos de origen deben guardarse como UTF-8 (esto es importante especialmente para rutas no ASCII; en Windows, no use codificación ANSI / GBK). Ejemplos por lenguaje:

Para reiterar: no hay forma de generar el argumento -profile localmente. Es una cadena cifrada vinculada a su cuenta y solo se puede obtener a través del servicio web GetPackagerEncryptedParams.

7Ejemplos de automatización del lado del servidor

Encadenar "obtener parámetros + invocar el programa de cifrado" permite el cifrado con un solo clic desde el back office de su sitio web, o el cifrado por lotes programado. El siguiente ejemplo PHP invoca el programa de cifrado de Linux (continuando desde el código de la sección 4.4; en tiempo de ejecución, $profile debe leerse primero de la caché, y el servicio web de 4.4 debe llamarse solo cuando no exista un valor en caché):

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

Ejemplo de script de shell de cifrado por lotes (Linux — codifica las rutas localmente y luego cifra cada archivo):

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

Práctica recomendada: obtenga el ProfileEncryptedParam para un ProfileID dado una vez a través del servicio web y guárdelo en caché para reutilizarlo — no llame al servicio web una vez por cada archivo cifrado. Genere los equivalentes de enc_Input / enc_Output directamente codificando en Base64 (UTF-8) las rutas en su servidor (en PHP: base64_encode($path), véase la sección 6) — no se necesita llamada al servicio web. Al cifrar por lotes, limite la concurrencia (por ejemplo, 2-4 procesos de cifrado por servidor) para evitar saturar el ancho de banda y la CPU.

8Preguntas frecuentes (FAQ)

Q1: El servicio web devuelve "Your XML web service login info is not correct..."

AdminEmail o WebServiceAuthStr son incorrectos. Verifique ambos en la consola de administración de DRM-X; asegúrese de que los valores no tengan espacios iniciales ni finales. Tenga en cuenta también que, incluso para este error, el código de estado HTTP sigue siendo 200 — su programa debe determinar el éxito inspeccionando los campos de respuesta, no el código de estado HTTP.

Q2: Pasar el ID numérico (por ejemplo, 1001) directamente a -profile provoca un error

-profile debe ser la cadena cifrada completa de ProfileEncryptedParam devuelta por el servicio web — no el ID numérico del perfil. El ID numérico solo se utiliza al llamar al servicio web.

Q3: ¿La ruta contiene caracteres no ASCII o espacios y el cifrado falla?

Las rutas se transportan como Base64, y los caracteres no ASCII y los espacios son totalmente compatibles. La clave es que la codificación debe usar UTF-8: en Windows, el Bloc de notas / cmd pueden usar por defecto la codificación ANSI (GBK), que corrompe la ruta tras la decodificación Base64. Codifique las rutas como UTF-8 en su programa como se describe en la sección 6 (con un archivo de origen PHP guardado como UTF-8, base64_encode() simple funciona directamente; las cadenas heredadas codificadas en GBK se pueden convertir primero con iconv('GBK', 'UTF-8', $path) o mb_convert_encoding() antes de codificarlas).

Q4: El programa informa de un fallo de salida / no encuentra el directorio de salida

El directorio padre del archivo de salida debe crearse con antelación (por ejemplo, mkdir -p ./output). Verifique también que el usuario que ejecuta el programa tenga permiso de escritura en ese directorio.

Q5: macOS dice que el programa "cannot be opened because the developer cannot be verified"

El programa no está notarizado por Apple, por lo que Gatekeeper bloquea el primer inicio. Elija cualquiera de las dos soluciones: ① Ejecute xattr -d com.apple.quarantine ./drm-x5-encrypt-sdk-macos-arm64 en una terminal para eliminar la marca de cuarentena; ② O haga clic en "Abrir de todos modos" en Ajustes del Sistema → Privacidad y seguridad.

Q6: En Linux el programa no se puede ejecutar (Permission denied o error de formato)

Ejecute primero chmod +x drm-x5-encrypt-sdk-linux-x86_64. Si obtiene "cannot execute binary file", confirme que el servidor es x86_64 (uname -m). El paquete actual solo incluye compilaciones x86_64; para servidores ARM, póngase en contacto con Haihaisoft.

Q7: ¿Debo usar com o cn? ¿Qué ocurre si elijo el incorrecto?

Debe coincidir con la plataforma de su cuenta DRM-X: las cuentas internacionales usan com (y llaman a 5.drm-x.com), las cuentas de China usan cn (y llaman a 5.drm-x.cn). Una falta de coincidencia provoca un fallo de autenticación, o parámetros de cifrado que no coinciden con la plataforma.

Q8: ¿Cómo verifico los archivos cifrados?

Abra los archivos de salida en el reproductor de demostración DRM-X 5.0 / su reproductor integrado y confirme: la reproducción se bloquea sin licencia y se reproduce con normalidad tras autorizar a un usuario de prueba en la consola de administración. Verifique a pequeña escala antes del cifrado de producción en masa.

9Notas y mejores prácticas

• Conserve los archivos originales: escriba la salida en una nueva ubicación o con un nuevo nombre de archivo (por ejemplo, con un sufijo _P) para que los vídeos originales nunca se sobrescriban.
• Pequeño antes que grande: cuando utilice un nuevo perfil o un nuevo servidor por primera vez, ejecute un vídeo de prueba corto por todo el flujo "obtener parámetros → cifrar → reproducción con licencia" antes del procesamiento por lotes.
• Nunca edite los argumentos a mano: -profile es una cadena cifrada en Base64 — cópiela en su totalidad (sin espacios iniciales/finales adicionales, sin truncamiento por salto de línea).
• Mantenga en secreto la cadena de autenticación: WebServiceAuthStr pertenece únicamente a la configuración del lado del servidor; no despliegue herramientas web de demostración como GetPackagerEncryptedParams.php en internet público.
• Requisito de red: durante el cifrado, el servidor debe poder alcanzar los servidores DRM-X (Internacional 5.drm-x.com / China 5.drm-x.cn); permita el puerto de salida 443 si hay un cortafuegos.