DRM-X 5.0 암호화 SDK 사용자 가이드

1SDK 패키지 내용

DRM-X5.0_Encryption_SDK 아카이브의 압축을 풀면 디렉터리에 다음 파일이 포함되어 있습니다:

명령줄 인수는 세 플랫폼 모두에서 동일합니다 — 프로그램 파일 이름만 다릅니다.

2암호화 워크플로 개요

왜 먼저 DRM-X 5.0 웹 서비스를 호출해야 합니까?암호화 프로그램의 -profile 인수는 라이선스 프로필의 숫자 ID가 아닙니다 — 사용자의 계정에 바인딩된 암호화 문자열(ProfileEncryptedParam)입니다. 이 문자열은 로컬에서 생성할 수 없으며 웹 서비스를 통해서만 얻을 수 있습니다. 이는 ProfileID에 일대일로 매핑되며, 한 번 얻으면 캐시하여 재사용할 수 있습니다 — 파일마다 웹 서비스를 호출할 필요가 없습니다. 반면 입력 / 출력 경로의 Base64 값은 프로그램에서 로컬로 인코딩해야 합니다(섹션 6 참조) — 이를 위해 웹 서비스 호출이 필요하지 않습니다.

3사전 요구 사항

3.1 DRM-X 5.0 계정 정보 (DRM-X 관리 콘솔에서 획득)

3.2 서버 환경 요구 사항

보안 알림: WebServiceAuthStr는 계정 키와 동일합니다. 서버 측에만 저장해야 합니다 — 프런트엔드 웹 페이지, 클라이언트 소프트웨어 또는 공개 리포지토리에 절대 두지 마십시오.

41단계: 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 서비스로, 모든 언어에서 동일하고 균일한 방식으로 호출할 수 있습니다: 4.1에 나열된 엔드포인트로 SOAP 엔벨로프를 POST하거나(?WSDL에서 SOAP 클라이언트가 자동으로 생성하도록 함), 4.2의 매개변수를 전달한 다음, 응답의 4.3에서 세 필드를 읽습니다. 언어별 일반적인 SOAP 클라이언트 라이브러리:

다음 예제는 PHP의 SoapClient를 사용하여 전체 호출을 보여줍니다. 코드를 서버에 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";

52단계: 암호화 명령 실행

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

셸 일괄 암호화 스크립트 예제 (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

권장 사례: 특정 ProfileID의 ProfileEncryptedParam을 웹 서비스를 통해 한 번 가져와 재사용을 위해 캐시하십시오 — 암호화된 파일마다 웹 서비스를 호출하지 마십시오. 서버에서 경로를 Base64(UTF-8)로 인코딩하여 enc_Input / enc_Output에 해당하는 값을 직접 생성하십시오 (PHP에서는 base64_encode($path), 섹션 6 참조) — 웹 서비스 호출이 필요하지 않습니다. 일괄 암호화 시 대역폭과 CPU 포화를 피하기 위해 동시 실행을 제한하십시오 (예: 서버당 2-4개의 암호화 프로세스).

8자주 묻는 질문(FAQ)

Q1: 웹 서비스가 "Your XML web service login info is not correct..."를 반환합니다

AdminEmail 또는 WebServiceAuthStr이 올바르지 않습니다. DRM-X 관리 콘솔에서 둘 다 다시 확인하십시오. 값에 앞뒤 공백이 없는지 확인하십시오. 또한 이 오류의 경우에도 HTTP 상태 코드는 여전히 200입니다 — 프로그램은 HTTP 상태 코드가 아니라 응답 필드를 검사하여 성공 여부를 판단해야 합니다.

Q2: 숫자 ID(예: 1001)를 -profile에 직접 전달하면 오류가 발생합니다

-profile은 웹 서비스에서 반환된 전체 ProfileEncryptedParam 암호화 문자열이어야 합니다 — 숫자 Profile ID가 아닙니다. 숫자 ID는 웹 서비스를 호출할 때만 사용됩니다.

Q3: 경로에 비 ASCII 문자나 공백이 포함되어 암호화가 실패합니까?

경로는 Base64로 전송되며, 비 ASCII 문자와 공백은 완전히 지원됩니다. 핵심은 인코딩이 UTF-8을 사용해야 한다는 것입니다: Windows에서는 메모장 / cmd가 기본적으로 ANSI(GBK) 인코딩을 사용할 수 있으며, 이는 Base64 디코딩 후 경로를 손상시킵니다. 섹션 6에 설명된 대로 프로그램에서 경로를 UTF-8로 인코딩하십시오 (PHP 소스 파일이 UTF-8로 저장된 경우 일반 base64_encode()가 바로 작동합니다. 레거시 GBK 인코딩 문자열은 인코딩 전에 iconv('GBK', 'UTF-8', $path) 또는 mb_convert_encoding()으로 변환할 수 있습니다).

Q4: 프로그램이 출력 실패를 보고하거나 출력 디렉터리를 찾을 수 없습니다

출력 파일의 상위 디렉터리를 미리 생성해야 합니다 (예: mkdir -p ./output). 또한 프로그램을 실행하는 사용자가 해당 디렉터리에 대한 쓰기 권한이 있는지 확인하십시오.

Q5: macOS가 프로그램을 "cannot be opened because the developer cannot be verified"라고 표시합니다

프로그램이 Apple의 공증을 받지 않았으므로 Gatekeeper가 첫 실행을 차단합니다. 다음 중 하나를 선택하십시오: ① 터미널에서 xattr -d com.apple.quarantine ./drm-x5-encrypt-sdk-macos-arm64를 실행하여 격리 플래그를 제거합니다; ② 또는 시스템 설정 → 개인 정보 보호 및 보안에서 "확인 없이 열기"를 클릭합니다.

Q6: Linux에서 프로그램을 실행할 수 없습니다 (Permission denied 또는 형식 오류)

먼저 chmod +x drm-x5-encrypt-sdk-linux-x86_64를 실행하십시오. "cannot execute binary file"이 표시되면 서버가 x86_64인지 확인하십시오 (uname -m). 현재 패키지는 x86_64 빌드만 제공합니다. ARM 서버의 경우 Haihaisoft에 문의하십시오.

Q7: com과 cn 중 어느 것을 사용해야 합니까? 잘못 선택하면 어떻게 됩니까?

DRM-X 계정의 플랫폼과 일치해야 합니다: 국제 계정은 com을 사용하고(5.drm-x.com 호출), 중국 계정은 cn을 사용합니다(5.drm-x.cn 호출). 불일치하면 인증 실패 또는 플랫폼과 일치하지 않는 암호화 매개변수가 발생합니다.

Q8: 암호화된 파일을 어떻게 확인합니까?

DRM-X 5.0 데모 플레이어 / 통합 플레이어에서 출력 파일을 열고 확인하십시오: 라이선스 없이는 재생이 차단되고, 관리 콘솔에서 테스트 사용자를 승인한 후 정상적으로 재생됩니다. 대량 프로덕션 암호화 전에 소규모로 검증하십시오.

9참고 사항 및 모범 사례

• 원본 파일을 보관하십시오: 출력을 새 위치 또는 새 파일 이름(예: _P 접미사 포함)으로 작성하여 원본 동영상이 절대 덮어쓰이지 않도록 하십시오.
• 작게 먼저, 크게 나중에: 새 프로필이나 새 서버를 처음 사용할 때는 일괄 처리 전에 짧은 테스트 동영상으로 "매개변수 가져오기 → 암호화 → 라이선스 재생" 전체 흐름을 실행하십시오.
• 인수를 직접 편집하지 마십시오: -profile은 Base64 암호화 문자열입니다 — 전체를 복사하십시오 (앞뒤에 추가 공백 없이, 줄 바꿈 잘림 없이).
• 인증 문자열을 비밀로 유지하십시오: WebServiceAuthStr는 서버 측 구성에만 있어야 합니다. GetPackagerEncryptedParams.php와 같은 데모 웹 도구를 공개 인터넷에 배포하지 마십시오.
• 네트워크 요구 사항: 암호화 중에 서버가 DRM-X 서버(국제 5.drm-x.com / 중국 5.drm-x.cn)에 도달할 수 있어야 합니다. 방화벽이 있는 경우 아웃바운드 포트 443을 허용하십시오.