Guia do Usuário do SDK de Criptografia DRM-X 5.0

1Conteúdo do Pacote SDK

Após extrair o arquivo DRM-X5.0_Encryption_SDK, o diretório contém os seguintes arquivos:

Os argumentos da linha de comando são idênticos nas três plataformas — apenas o nome do arquivo do programa difere.

2Visão Geral do Fluxo de Trabalho de Criptografia

Por que chamar primeiro o Serviço Web DRM-X 5.0?O argumento -profile do programa de criptografia não é o ID numérico do perfil de licença — é uma string criptografada vinculada à sua conta (ProfileEncryptedParam). Essa string não pode ser gerada localmente; só pode ser obtida através do Serviço Web. Ela mapeia um para um para um ProfileID, e uma vez obtida, pode ser armazenada em cache e reutilizada — você não precisa chamar o Serviço Web para cada arquivo. Os valores Base64 dos caminhos de entrada / saída, por outro lado, devem ser codificados localmente no seu programa (ver Seção 6) — nenhuma chamada ao Serviço Web é necessária para eles.

3Pré-requisitos

3.1 Informações da Conta DRM-X 5.0 (obtidas no console de administração DRM-X)

3.2 Requisitos do Ambiente do Servidor

Lembrete de segurança: WebServiceAuthStr equivale a uma chave de conta. Deve ser armazenado apenas no lado do servidor — nunca o coloque em páginas web de front-end, software cliente ou repositórios públicos.

4Etapa Um: Chamar o Serviço Web DRM-X 5.0 para Obter os Parâmetros de Criptografia

4.1 Informações do Serviço Web

O endpoint deve corresponder à edição da sua conta: contas internacionais usam 5.drm-x.com (linha de comando: -server_domain com); contas da China usam 5.drm-x.cn (linha de comando: -server_domain cn). Usar a edição errada fará com que a autenticação falhe, ou os arquivos criptografados não possam ser reproduzidos.

4.2 Parâmetros da Solicitação

4.3 Mapeamento entre os Campos de Resposta e os Argumentos da Linha de Comando (Núcleo)

4.4 Exemplo de Invocação (PHP / SoapClient)

Este Serviço Web é um serviço padrão SOAP 1.1 que pode ser chamado de qualquer linguagem, da mesma forma uniforme: envie um envelope SOAP por POST para o endpoint listado em 4.1 (ou faça um cliente SOAP gerá-lo automaticamente a partir de ?WSDL), passe os parâmetros de 4.2 e depois leia os três campos de 4.3 na resposta. Bibliotecas de cliente SOAP comuns por linguagem:

O exemplo a seguir usa o SoapClient do PHP para demonstrar a chamada completa. Salve o código como get_params.php no seu servidor e execute-o (PHP 7.4+ com a extensão soap habilitada) — ele imprime os três valores dos argumentos da linha de comando:

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

5Etapa Dois: Executar o Comando de Criptografia

5.1 Primeiro Uso (Linux / macOS)

Em um terminal, entre no diretório do programa e conceda primeiro a permissão de execução:

# 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 Modelos de Comando de Criptografia de Arquivo Único

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 Referência de Argumentos

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

Aqui RDpcSmFzb25c... é decodificado para 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=

Isso criptografa ./input/01-linux-encrypt-video.mp4 → ./output/01-linux-encrypt-video2_P.mp4.

5.5 Verificando o Resultado

• Quando o programa terminar, verifique se um arquivo criptografado foi criado no diretório de saída (recomenda-se um sufixo _P para distingui-lo, por exemplo course01_P.mp4);
• A criptografia requer acesso de rede ao servidor DRM-X. Certifique-se de que seu firewall / grupo de segurança permita acesso de saída para 5.drm-x.com ou 5.drm-x.cn;
• Recomenda-se verificar o fluxo de trabalho completo com um vídeo de teste pequeno antes de criptografar conteúdo de produção em lote.

6Codificação Base64 dos Caminhos de Entrada / Saída (Codificação Local Recomendada)

Prática recomendada: gere os valores de -input_file_utf8_base64_encoded / -output_file_utf8_base64_encoded codificando-os em seu próprio programa — não é necessário chamar o Serviço Web uma vez por arquivo. A regra de codificação: primeiro converta a string do caminho em bytes UTF-8, depois aplique a codificação Base64 padrão. Observação: seus arquivos de origem devem ser salvos como UTF-8 (isso é especialmente importante para caminhos não ASCII; no Windows, não use codificação ANSI / GBK). Exemplos por linguagem:

Para reenfatizar: não há como gerar o argumento -profile localmente. É uma string criptografada vinculada à sua conta e só pode ser obtida através do Serviço Web GetPackagerEncryptedParams.

7Exemplos de Automação no Lado do Servidor

Encadear "obter parâmetros + invocar o programa de criptografia" permite criptografia com um clique a partir do back office do seu site, ou criptografia em lote agendada. O exemplo PHP a seguir invoca o programa de criptografia do Linux (continuando a partir do código na Seção 4.4; em tempo de execução, $profile deve ser lido primeiro do cache, e o Serviço Web em 4.4 chamado apenas quando não existir um valor em cache):

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

Exemplo de script shell de criptografia em lote (Linux — codifica os caminhos localmente e depois criptografa cada arquivo):

#!/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ática recomendada: obtenha o ProfileEncryptedParam para um determinado ProfileID uma vez através do Serviço Web e armazene-o em cache para reutilização — não chame o Serviço Web uma vez por arquivo criptografado. Gere os equivalentes de enc_Input / enc_Output diretamente codificando em Base64 (UTF-8) os caminhos no seu servidor (em PHP: base64_encode($path), ver Seção 6) — nenhuma chamada ao Serviço Web é necessária. Ao criptografar em lote, limite a concorrência (por exemplo, 2-4 processos de criptografia por servidor) para evitar saturar a largura de banda e a CPU.

8Perguntas Frequentes (FAQ)

Q1: O Serviço Web retorna "Your XML web service login info is not correct..."

AdminEmail ou WebServiceAuthStr está incorreto. Verifique ambos no console de administração DRM-X; certifique-se de que os valores não tenham espaços no início ou no fim. Observe também que, mesmo para esse erro, o código de status HTTP ainda é 200 — seu programa deve determinar o sucesso inspecionando os campos de resposta, e não o código de status HTTP.

Q2: Passar o ID numérico (por exemplo, 1001) diretamente para -profile causa um erro

-profile deve ser a string criptografada completa de ProfileEncryptedParam retornada pelo Serviço Web — não o ID numérico do Perfil. O ID numérico é usado apenas ao chamar o Serviço Web.

Q3: O caminho contém caracteres não ASCII ou espaços e a criptografia falha?

Os caminhos são transportados como Base64, e caracteres não ASCII e espaços são totalmente suportados. O ponto-chave é que a codificação deve usar UTF-8: no Windows, o Bloco de Notas / cmd podem usar por padrão a codificação ANSI (GBK), o que corrompe o caminho após a decodificação Base64. Codifique os caminhos como UTF-8 no seu programa conforme descrito na Seção 6 (com um arquivo de origem PHP salvo como UTF-8, o base64_encode() simples funciona diretamente; strings legadas codificadas em GBK podem ser convertidas primeiro com iconv('GBK', 'UTF-8', $path) ou mb_convert_encoding() antes da codificação).

Q4: O programa relata uma falha de saída / não consegue encontrar o diretório de saída

O diretório pai do arquivo de saída deve ser criado com antecedência (por exemplo, mkdir -p ./output). Verifique também se o usuário que executa o programa tem permissão de escrita nesse diretório.

Q5: O macOS diz que o programa "cannot be opened because the developer cannot be verified"

O programa não é notarizado pela Apple, então o Gatekeeper bloqueia a primeira inicialização. Escolha qualquer uma das soluções: ① Execute xattr -d com.apple.quarantine ./drm-x5-encrypt-sdk-macos-arm64 em um terminal para remover o sinalizador de quarentena; ② Ou clique em "Abrir Mesmo Assim" em Ajustes do Sistema → Privacidade e Segurança.

Q6: No Linux o programa não pode ser executado (Permission denied ou erro de formato)

Execute primeiro chmod +x drm-x5-encrypt-sdk-linux-x86_64. Se você receber "cannot execute binary file", confirme que o servidor é x86_64 (uname -m). O pacote atual fornece apenas builds x86_64; para servidores ARM, entre em contato com a Haihaisoft.

Q7: Devo usar com ou cn? O que acontece se eu escolher o errado?

Deve corresponder à plataforma da sua conta DRM-X: contas internacionais usam com (e chamam 5.drm-x.com), contas da China usam cn (e chamam 5.drm-x.cn). Uma incompatibilidade causa falha de autenticação, ou parâmetros de criptografia que não correspondem à plataforma.

Q8: Como verifico os arquivos criptografados?

Abra os arquivos de saída no player de demonstração DRM-X 5.0 / no seu player integrado e confirme: a reprodução é bloqueada sem uma licença e funciona normalmente após autorizar um usuário de teste no console de administração. Verifique em pequena escala antes da criptografia de produção em massa.

9Notas e Melhores Práticas

• Mantenha os arquivos originais: escreva a saída em um novo local ou com um novo nome de arquivo (por exemplo, com um sufixo _P) para que os vídeos originais nunca sejam sobrescritos.
• Pequeno antes de grande: ao usar um novo perfil ou um novo servidor pela primeira vez, execute um vídeo de teste curto por todo o fluxo "obter parâmetros → criptografar → reprodução licenciada" antes do processamento em lote.
• Nunca edite os argumentos manualmente: -profile é uma string criptografada em Base64 — copie-a na íntegra (sem espaços extras no início/fim, sem truncamento por quebra de linha).
• Mantenha a string de autenticação em segredo: WebServiceAuthStr pertence apenas à configuração do lado do servidor; não implante ferramentas web de demonstração como GetPackagerEncryptedParams.php na internet pública.
• Requisito de rede: durante a criptografia, o servidor deve conseguir alcançar os servidores DRM-X (Internacional 5.drm-x.com / China 5.drm-x.cn); permita a porta de saída 443 se houver um firewall.