PallyCon 멀티 DRM 라이선스 토큰 API

개요

PallyCon 클라우드 서버에서 멀티 DRM(FPS, Widevine, PlayReady, NCG) 라이선스를 발급하는 방식은 게이트웨이 방식과 토큰 방식이 있습니다.

  1. 게이트웨이 방식

    • PallyCon 클라우드 서버는 멀티 DRM 클라이언트로부터 라이선스 요청을 받으면 먼저 해당 사용자가 유효한 권한이 있는지 해당 서비스 사이트의 콜백 페이지를 통해 확인합니다.
    • 권한이 있는 사용자로부터의 요청인 경우, 서비스 사이트는 콜백 게이트웨이 웹 페이지를 통해 인증 여부, 사용 권한(무제한, 기간제), 각종 보안 옵션 등의 정보를 PallyCon 클라우드 서버에게 리턴합니다.
    • PallyCon 클라우드 서버는 콜백 페이지의 응답을 받아 클라이언트에 해당 라이선스를 발급합니다.
  2. 토큰 방식

    • 멀티 DRM 클라이언트에서 콘텐츠 재생 시, 라이선스 발급을 위해 우선 서비스 사이트에 토큰을 요청합니다. 서비스 사이트는 토큰을 요청한 사용자가 콘텐츠에 대한 권한이 있는지 확인한 후, PallyCon 클라우드 서버로부터 토큰을 발급받아 클라이언트에 전달합니다.
    • 서비스 사이트는 토큰 REST API를 통해 사용 권한(무제한, 기간제)과 각종 보안 옵션 등을 설정할 수 있습니다.
    • 클라이언트가 토큰과 함께 라이선스를 요청하면, PallyCon 클라우드 서버는 해당 토큰의 유효성을 확인한 후 라이선스를 발급합니다.

본 문서는 두 번째 방식인 토큰 방식 라이선스 발급에 사용되는 REST API 규격에 대해 설명합니다. 게이트웨이 방식 규격에 대해서는 콜백 게이트웨이 API 문서를 참고하시기 바랍니다.

토큰 방식 라이선스 발급 과정

license workflow

(1) 토큰 요청

  • 클라이언트는 재생하려는 콘텐츠의 DRM 라이선스 발급에 필요한 토큰을 서비스 사이트에 요청합니다.

(1-1) 토큰 발급 요청 (아래 규격 참조)

  • 서비스 사이트는 클라이언트에서 받은 요청을 확인하고, 해당 사용자가 콘텐츠 사용 권한이 있는 경우 PallyCon 클라우드 서버에 토큰 발급을 요청합니다.
  • 요청 시에 Content ID, 토큰 유효기간, 라이선스 룰 정보를 전달합니다.

(1-2) 라이선스 토큰 발급

  • PallyCon 클라우드 서버는 토큰 정보를 생성하여 DB에 저장 후 회신합니다.

(2) 토큰 전달

  • 서비스 사이트는 PallyCon 클라우드 서버로부터 받은 토큰을 클라이언트에 전달합니다.

(3) 라이선스 요청

(4) 라이선스 발급

  • PallyCon 클라우드 서버는 해당 토큰의 유효성을 확인하고 설정된 룰에 따라 라이선스를 발급합니다.

라이선스 토큰 API (JSON 방식)

요청 데이터 규격

Key Value
Authorization HTTP Basic Auth (Site ID : Access Key)
  • Site ID : PallyCon 서비스에서 발급된 서비스 사이트 ID (4byte)
  • Access Key : PallyCon 서비스에서 발급된 해당 서비스 사이트의 액세스 키 (PallyCon Admin 사이트의 설정 페이지에서 확인 가능)

Body

Key Value
data base64 Encoding ( aes256 Encrypt ( JSON Data string ) )

* AES256 암호화 항목 참조

JSON 데이터 형식

{
    "drm_type": "<drm type string>",
    "cid":"<content id string>", 
    "token_expiry_date":"<token expiry GMT yyyy-mm-ddThh:mm:ssZ>", 
    "nonce":"<random string>", 
    "playback_policy": {
        "limit": "<true|false>",
        "persistent": "<true|false>",
        "duration" : "<duration(seconds)>",
        "expire_date": "<playback expiry GMT yyyy-mm-ddThh:mm:ssZ>"
    },
    "security_policy": {
        "hardware_drm": "<true|false>",
        "output_protect": {
            "allow_external_display" : "<true|false>",
            "control_hdcp": "<0|1|2>"
        },
        "allow_mobile_abnormal_device" : "<true|false>",
        "playready_security_level": "<150|2000|3000>"
    },
    "external_key": {
        "mpeg_cenc": {
        "key_id" : "<hex-string>",
            "key" : "<hex-string>",
            "iv" : "<hex-string>" ,
        },
        "hls_aes" : {
            "key" : "<hex-string>”,
            "iv" : "<hex-string>”
        },
        "ncg":{
            "cek":"<hex-string>"
        }
    }
}
Name Value Required Description
drm_type string No DRM 종류 ("NCG", "Widevine", "PlayReady", "FairPlay"), 기본값 : PlayReady
cid string Yes 재생하려는 콘텐츠의 ID. DRM 패키징 시에 사용된 값
token_expiry_date string Yes 토큰 유효기간 (GMT 기준) 'yyyy-mm-ddThh:mm:ssZ'
nonce string Yes One time Random String. 중복 요청을 방지하기 위한 Unique 값 (최대 32바이트)
playback_policy json No 재생 관련 룰 설정 (상세 규격 참조)
security_policy json No 보안 관련 룰 설정 (상세 규격 참조)
external_key json No 재생할 콘텐츠의 키 정보 (상세 규격 참조)
키 정보를 PallyCon 클라우드 서버에 저장하지 않고 별도로 관리하는 경우에 사용합니다.

playback_policy

Name Value Required Description
limit boolean No 기간제 적용 여부 (기본값: false)
true : 기간제, false : 무제한
persistent boolean No 오프라인용 라이선스 저장 여부. (기본값: false)
true : 라이선스 유지, false : 재생 후 라이선스 제거(스트리밍)
duration number Select 라이선스 유효 기간 (단위 : 초). duration, expire_date 동시 설정 시, duration 값을 우선시합니다.
'limit'값이 true인 경우에만 적용됩니다. (false일 경우 이 항목은 무시됨)
expire_date time Select 라이선스 만료 날짜, GMT Time 표기'yyyy-mm-ddThh:mm:ssZ' 'limit'값이 true인 경우에만 적용됩니다. (false일 경우 이 항목은 무시) duration 항목과 함께 사용된 경우, 이 항목은 무시됩니다.

security_policy (optional)

Name Value Required Description
hardware_drm boolean No 하드웨어 DRM 적용 여부.(기본값 false)
- 각 DRM 종류에 따라 security level 설정됨
- cenc 컨텐츠에만 적용
output_protect json No 외부 출력 룰 설정 (상세 규격 참조)
allow_mobile_abnormal_device boolean No 탈옥 기기 재생 허용 여부 (기본값 false)
playready_security_level number No PlayReady 보안 레벨 설정, 150,2000,3000 (기본값 150)
hardware_drm 속성이 true인 경우, playready_security_level은 3000이 적용됩니다.

security_policy.output_protect

Name Value Required Description
allow_external_display boolean No 모바일 외부 출력 허용 여부. (기본값 false) NCG DRM에만 해당
control_hdcp string No HDCP 적용 여부. (기본값 0)
0 : HDCP 제어 안함, 1 : HDCP 1.4 필요, 2 : HDCP 2.2 필요 (widevine)

external_key (optional)

Name Value Required Description
mpeg_cenc json No CENC 외부 키 정보 설정 - PlayReady/Widevine (상세 규격 참조)
hls_aes json No HLS AES 외부 키 정보 설정 - FairPlay Streaming (상세 규격 참조)
ncg json No NCG 외부 키 정보 설정 (상세 규격 참조)

external_key.mpeg_cenc

Name Value Required Description
key_id hex-string No DASH CENC 패키징(PlayReady/Widevine) 시 사용한 key ID 16byte hex string 값
key hex-string No DASH CENC 패키징 시 사용한 key 16byte hex string 값
iv hex-string No DASH CENC 패키징 시 사용한 iv 16byte hex string 값

external_key.hls_aes

Name Value Required Description
key hex-string No HLS Sample AES 패키징(FairPlay Streaming) 시 사용한 key 16byte hex string 값
iv hex-string No HLS Sample AES 패키징 시 사용한 iv 16byte hex string 값

external_key.ncg

Name Value Required Description
cek hex-string No NCG 패키징 시 사용한 cek 32byte hex string 값

응답 데이터 규격

  • body : base64 Encoding ( JSON Data string )
HTTP Status Code Description Body
200 OK 성공 base64enc(JSON Data String)
400 파라미터가 없거나 잘못됨
401 인증 실패
404 잘못된 URL
406 토큰 인증 방식을 사용할 수 없는 사이트
5xx 서버 에러 .

JSON 데이터 형식

{
    "drm_type": "<multi-drm type>", 
    "site_id": "<site id>",
    "cid": "<contents id>",
    "token": “<base64 encode(aes256 encrypt(token json string))>”
}
Name Value Required Description
drm_type string Yes DRM 종류 ("NCG", "Widevine", "PlayReady", "FairPlay")
site_id string Yes PallyCon에서 발급받은 서비스 사이트 ID (4바이트)
cid string No 토큰 발급 요청 시 입력된 콘텐츠 ID
token string Yes base64 encoding( aes256 encrypt( token json string ) )

token json string

Name Value Required Description
token_serial string Yes 토큰 시리얼 문자열

AES256 암호화

AES256 암호화/복호화 처리는 PallyCon Admin 사이트에서 서비스 사이트 생성 시 발급 되는 사이트 키 값을 이용하여 아래와 같이 처리합니다. ( PallyCon Admin 사이트의 셋팅 페이지에서 확인 )

- mode : CBC
- key : 32 byte (PallyCon 서비스 사이트에서 발급된 사이트 키)
- iv : 16 byte ( **0123456789abcdef** )
- padding : pkcs7

예제

요청 데이터

{  
    "drm_type":"Widevine", 
    "cid":"contents id", 
    "token_expiry_date":"2017-04-10T23:59:59Z", 
    “playback_policy”: {
        “limit”: “true”,
        “persistent”: “true”,
        “duration" : “3600”
    },    
    "security_policy": {
        "output_protect": {
            "control_hdcp": “1”,
            “playready_security_level”: “150”
        }
    },
    "external_key": {
        "mpeg_cenc": {
        "key_id" : "30313233343536373839616263646566",
            "key" : "30313233343536373839616263646566",
            "iv" : "30313233343536373839616263646566"
        },
        "hls_aes" : {
            "key" : "30313233343536373839616263646566”,
            "iv" : "30313233343536373839616263646566"
        },
        “ncg”:{                                      
            “cek”:”3031323334353637383961626364656630313233343536373839616263646566”
        }
    }
}

results matching ""

    No results matching ""