Page Comparison

概要

기既存のKollusではMedia tokenは顧客がVideo gatewayにコンテンツ再生を要請する時、その内容を暗号化してURLの有効期限を設定するために使用されていました。ここでMedia tokenを使用するためにKollusから提供するモジュールをのサーバーに設置する必要があり、サーバーがモジュールに対応してない場合にはKollus APIを呼び出してMedia tokenを遠隔生成して使用したり、かつMedia tokenの仕様が変わる度にサーバーにモジュールを再度設置するなど、難点がありました。従って暗号学的に安全で具現が簡単なJSON Webtokenを利用してKollus モジュールに対する依存性を減らし、更に仕様変更により柔軟に対応ができるようにします。존 Kollus 시스템에서 Media Token은 고객사가 Videogateway로 컨텐츠 재생 요청을 전달할 때 요청 내용을 은닉(암호화)하고, 직접 url에 대한 유효 기간을 설정하기 위해 사용했습니다. 하지만 Media Token을 사용하기 위해서는 Kollus에서 제공하는 모듈을 서버에 직접 설치해야 하고, 모듈이 서버를 지원하지 않는 경우엔 Kollus API를 호출하여 Media Token을 원격으로 생성해 사용해야 하거나, Media Token의 스펙이 변경될 때마다 서버에 모듈을 재 설치해야 하는 등 문제가 많았습니다. 이에 암호학적으로 안전하고 구현이 간단한 JSON Webtoken을 이용하여 Kollus 모듈에 대한 의존성을 줄이고 좀 더 유연하게 스펙 변경에 대응할 수 있도록 합니다.

注意事項

注意事項

1. JSON Webtoken(以下JWT)につきましてはhttp://jwt.io ページを参考
2. JWTのPayload部分に以下の内容に記述されている、先に登録されたClaimを使用しては行けません。 (https://tools.ietf.org/html/rfc7519#section-4) 意図通り動作しない可能性があります。
3. 暗号化アルゴリズムは HMAC SHA256 (HS256) のみに対応しています。

JWT Request

用語

• セキュリティキー (Security Key)
  • セキュリティキーは JWTをsigning するためにKollusと顧客だけが共有する秘密キーとなります。セキュリティキーは “設定 > サービスアカウント” ページから確認できます。この値は顧客の要望に応じて変更が可能であり、変更と同時に使用していたセキュリティキーは無効になります。従ってセキュリティキーは顧客のメンテナンス時間中などを利用して変更した方が好ましいです。
• ユーザーキー (Custom Key)
  • ユーザーキーは平文セキュリティキーを暗号化したものになります。JWTを使用して Videogatewayに要請する場合JWTと共に転送されなければなりません。

JWT生成方法

暗号化アルゴリズムはHMAC SHA256 (HS256)にして、Secret keyはセキュリティキー、Payloadには以下のPayload Specに合わせたJSON Stringを追加してJWTを生成します。

生成したJWTを使用してVideo gatewayに要請する方法

生成したJWTと使用者キーを以下のような形式のurlで生成して呼び出します。

http://v.krjp.kollus.com/s?jwt=生成したJWT&custom_key=ユーザーキー

JWT Payload Spec

JWT Payload形式は以下のようなJSON文字列となります。

{
	"cuid": "CLIENT_USER_ID",
	"awtc": “AUDIO"AUDIO_WATERMARKING_CODE”CODE",
            "video_watermarking_code_policy": {
                       "code_kind":"client_user_id",
                       "font_size":7,
                      "font_color":"FFFFFF",
                      "show_time":1,
                      "hide_time":500,
                     "alpha":50,
                     "enable_html5_player": false,
            },
	"expt": EXPIRE_TIME,
	"pc_skin": {
		"skin_path": "http://file.kr.dev.kollus.com/public/custom/skin2.zip",
		"skin_sha1sum": "B2B688123F68BFA7DB4B1F89EC292C0835086D9B"
	},
	"mc": [{
		"mckey": “MEDIA"MEDIA_CONTENT_KEY”KEY",
		"mcpf": “MEDIA_CONTENT_PROFILE_KEY”,
		"tilte": “TITLE”"TITLE",
		"intr": IS_INTRO,
                   “scroll"scroll_event”event": SCROLL_EVENT,
		"seek": IS_SEEKABLE,
		"seekable_end": SEEKABLE_END,
		"disable_playrate": DISABLE_PLAYRATE,
                   “disable_nscreen”: DISABLE_NSCREEN,
                   "play_section": {
                              "start_time": PLAY_SECTION_START_TIME,
                              "end_time": PLAY_SECTION_END_TIME
                         }
                         "thumbnail": {
                             "enable": IS_ENABLE,
                             "thread": IS_THREAD,
                             "type": "TYPE"
                         },
                         "subtitle_policy" : {
                             "filter": {
                                 "name": "SUBTITLE_NAME",
                                 "language_code": "SUBTITLE_LANGUAGE_CODE",
                             },
                            "show_by_filter" : false,
                            "is_showable": true,
                         },
                         "drm_policy" : {
                             "kind" : "DRM_KIND",
                             "streaming_type": "hls",
                             "data" : "..."
                         },
	}]
}

名称

Datatype

必須有無

内容

Mediatype

cuid
(CLIENT_USER_ID)

String

必須

コンテンツにアクセスする顧客のユーザーID: 
ブックマーク及びNScreenデータのKeyとして使用されます。

VOD/LIVE

awtc
(AUDIO_WATERMARKING_CODE)

String

選択 (基本値: null)

Kollus オーディオウォーターマーキング機能を実装するとき使用すウォーターマーキングコードで、APIを呼び出して獲得します。
詳しい内容は技術担当者にお問い合わせください。
使用しない場合にはEntryを削除するか、nullを入力します。

VOD

expt
(EXPIRE_TIME)

Integer

必須

JWTの有効時間となり、Unix timestamp 形式で入力します。顧客側のサーバーとの時刻が一致しない場合があるため、有効時間が過ぎても最長1分以内まではアクセスができます。

VOD/LIVE

pc_skin
(PC_EX_PLAYER_SKIN)

Array

選択

V2 PC PlayerのSkin(デザイン)を顧客が指定することができます。設定しない場合には省略できますが、このフィールドを追加した場合には必ず下位フィールドのskin_path, skin_sha1sumの正確な値を入力してください。

V2 Player

skin_path

String

選択

V2 PC PlayerのSkin情報が入っている圧縮ファイルのURL

V2 Player

skin_sha1sum

String

選択

V2 PC PlayerのSkin情報が入っている圧縮ファイルのsha1 checksum 値

V2 Player

mc

Array

必須

再生するコンテンツの再生情報が含まれたObjectタイプのEntryを配列として含まれている項目

VOD/LIVE

mckey
(MEDIA_CONTENT_KEY)

String

必須

再生するコンテンツの識別キー。拡張Media content key形式も同一に使用可能

VOD/LIVE

mcpf
(MEDIA_CONTENT_PROFILE_KEY)

String

選択 (基本値: null)

コンテンツの複数のプロファイルの中で一つのプロファイルを強制に指定して再生する場合に使用します。強制に指定するプロファイルキーを入力します。
自動検出にするにはEntryを削除するか、 nullを入力

VOD

title
(TITLE)

String

選択 (基本値: null)

コンテンツのタイトルを代替する文字列

VOD/LIVE

intr
(IS_INTRO)

Boolean

選択 (基本値: false)

Introの有無を入力します。詳しくは下段の例示を参照してください。
Introがないコンテンツの場合にはEntryを削除するかまたはfalseを入力してください。

VOD

scroll_event

Boolean

(基本値: false)

画面の scroll event 適用有無

true: 画面の縦を基準でvideo領域を合わせて、見えない領域はscroll可能とする

false: 既存の通りに横を基準で画面を合わせる

VOD

seek
(IS_SEEKABLE)

Boolean

選択 (基本値: true)

コンテンツのseek可能の有無を入力します。一般的にintroコンテンツの場合にはseek不可とします。
Seek可能とする場合にはEntryを削除するかまたはtrueを入力してください。

VOD

seekable_end
(SEEKABLE_END)

Integer

選択 (基本値: -1)

Seek不可にした場合でも再生開始時点から入力した値の時点の間ではSeek可能になります。

VOD

disable_playrate
(DISABLE_PLAYRATE)

Boolean

選択 (基本値: false)

倍速調整機能のOn/Offを設定

VOD

disable_nscreen

(DISABLE_NSCREEN)

Boolean

選択 (基本値: false)

nscreen使用有無を設定

VOD

play_section.start_time

Integer

選択 (基本値: null)

リピート開始時点を設定 (単位: 秒)

VOD

play_section.end_time

integer

選択 (基本値: null)

リピート終了時点を設定 (単位: 秒)

VOD

thumbnail.enable

Boolean

選択 (基本値: true)

サムネール有効化有無を設定: Androidのみ対応

Android Player App/SDK

thumbnail.thread

Boolean

選択 (基本値: false)

スレッド方式の有無を設定: Androidのみ対応

Android Player App/SDK

thumbnail.type

String

選択 (基本値: null)

サムネールサイズを設定 (big / small): Androidのみ対応

Android Player App/SDK

subtitle_policy.filter.name

String

選択 (基本値: null)

字幕フィルターに字幕名を使用show_by_filter: trueに設定することが前提

VOD

subtitle_policy.filter.language_code

String

選択 (基本値: null)

字幕フィルターに言語コードを使用show_by_filter: trueに設定することが前提

VOD

subtitle_policy.show_by_filter

Boolean

選択 (基本値: false)

字幕ポリシーフィルターとの合致有無を識別

VOD

subtitle_policy.is_showable

Boolean

選択 (基本値: true)

字幕表示有無を識別

VOD

drm_policy.kind

String

選択 (基本値: null)

drm タイプを指定: 現状指定可能なDRMは"inka" ("inka"を使用する場合 third_party_infoの"cid"を "skb_kollus"に設定)

VOD

drm_policy.streaming_type

String

選択 (基本値: null)

ストリーミング方式をhls, dashに制限: "inka"にした場合ストリーミング方式を指定

VOD

drm_policy.data

Object

選択 (基本値: null)

DRM 認証データをオブジェクト(json) 方式で挿入
ex)
{
  "license_url": "https://tokyo.pallycon.com/ri/licenseManager.do",

  "certificate_url": "https://license.pallycon.com/ri/fpsKeyManager.do?siteId=XXXX",

  "custom_header": {

    "key": "pallycon-customdata-v2",

    "value": "eyJ0aW1lc3RhbXAiOiI5OTk5LTEyLTMxVDIzOjU5....cl9pZCI6bnVsbCwiY2lkIjoidGVzdCJ9"

  }

}

video_watermarking_code_policy.code_kind

String

選択

"client_user_id"以外のStringの場合、そのまま表示

video_watermarking_code_policy.alpha

Integer

選択 (基本値: 200)

ビデオウォーターマーキングコードのalpha値を定義 (16進数 0~255)

video_watermarking_code_policy.font_size

Integer

選択 (基本値: 7)

ビデオウォーターマーキングコードのfont-size値を定義 (単位: px)

video_watermarking_code_policy.font_color

String

選択 (基本値; 'FFFFFF')

ビデオウォーターマーキングコードのfont-color値を定義

video_watermarking_code_policy.show_time

Integer

選択 (基本値;1)

ビデオウォーターマーキングコードの表示時間 (単位: 秒)

video_watermarking_code_policy.hide_time

Integer

選択 (基本値;60)

ビデオウォーターマーキングコードが表示されてから非表示になるまでの時間 (単位: 秒)

video_watermarking_code_policy.enable_html5_player

Boolean

選択 (基本値: false)

ビデオウォーターマーキングコードのHTML5 Player使用有無

例示

コンテンツの再生に使用するJWT Payload

catenoid というIDを持つユーザーがMedia content key “vnCVPVyV”を再生する場合

{
	"cuid": “catenoid”,
	"expt": 1462931880,
	"mc": [{
		"mckey": “vnCVPVyV“
	}]
}

catenoid というIDを持つユーザーがintroでMedia content key “gDV2B1ZG”をseek 不可の状態で、本コンテンツは “vnCVPVyV”を再生する場合

{
	"cuid": “catenoid”,
	"expt": 1462931880,
	"mc": [{
		"mckey": “gDV2B1ZG“,
		"intr": true,
		"seek": false,
	},{
		"mckey": “vnCVPVyV“
	}]
}

Skip無効のコンテンツを再生するとき指定した時点まではSkipを許可するためのJWT Payload

catenoid というIDの使用者がintroでMedia contents key 「gDV2B1ZG」をseek 無効になっている状態で、開始から30秒まではSkipを許可する場合

{
	"cuid": “catenoid”,
	"expt": 1462931880,
	"mc": [{
		"mckey": “gDV2B1ZG“,
		"intr": true,
		"seek": false,
		"seekable_end": 30,
	}]
}

コンテンツの一部だけを再生させるためのJWT Payload

catenoid というIDの使用者がMedia contents key「vnCVPVyV」を60秒間再生をさせる場合

{
	"cuid": “catenoid”,
	"expt": 1462931880,
	"mc": [{
		"mckey": “vnCVPVyV“,
		"play_section": {
			"start_time": 0,
			"end_time": 60,
	}]
}						  "live": {
                       "url" : "LIVE_URL",
                       "poster_url" : "LIVE_POSTER",
                       "cdn": {
                           "type": "akamai",
                           "password": {
                               "short": "901490a9",
                               "long": "B2E2B80BCC848FB302EC55215C95E826"
                           }
                       },
                       "auth_type": "user",
                       "use_ip_validation": true,
                       "use_kollus_token": false
                   }
	}]
}

Payload 項目

{
	"license_url": "https://tokyo.pallycon.com/ri/licenseManager.do",
	"certificate_url": "https://license.pallycon.com/ri/fpsKeyManager.do?siteId=XXXX",
	"custom_header": {
		"key": "pallycon-customdata-v2",
		"value": "eyJ0aW1lc3RhbXAiOiI5OTk5LTEyLTMxVDIzOjU5....cl9pZCI6bnVsbCwiY2lkIjoidGVzdCJ9"
	}
}

例示

コンテンツの再生に使用するJWT Payload

catenoid というIDを持つユーザーがMedia content key “vnCVPVyV”を再生する場合

{
	"cuid": "catenoid",
	"expt": 1462931880,
	"mc": [{
		"mckey": "vnCVPVyV"
	}]
}

introありのコンテンツの再生に使用するJWT Payload

catenoid というIDを持つユーザーがintroでMedia content key “gDV2B1ZG”をseek 不可の状態で、本コンテンツは “vnCVPVyV”を再生する場合

{
	"cuid": "catenoid",
	"expt": 1462931880,
	"mc": [{
		"mckey": "gDV2B1ZG",
		"intr": true,
		"seek": false,
	},{
		"mckey": "vnCVPVyV"
	}]
}

Skip無効のコンテンツを再生するとき指定した時点まではSkipを許可するためのJWT Payload

catenoid というIDの使用者がintroでMedia contents key 「gDV2B1ZG」をseek 無効になっている状態で、開始から30秒まではSkipを許可する場合

{
	"cuid": "catenoid",
	"expt": 1462931880,
	"mc": [{
		"mckey": "gDV2B1ZG",
		"intr": true,
		"seek": false,
		"seekable_end": 30,
	}]
}

コンテンツの一部だけを再生させるためのJWT Payload

catenoid というIDの使用者がMedia contents key「vnCVPVyV」を60秒間再生をさせる場合

{
	"cuid": "catenoid",
	"expt": 1462931880,
	"mc": [{
		"mckey": "vnCVPVy",
		"play_section": {
			"start_time": 0,
			"end_time": 60,
	}]
}

Live(in VOD) JWT Payload Spec

Payload 項目

例示

Live Streaming JWT Payload

ライブストリーミングの場合、intro / seek / playbackRate機能が無効になるため、該当JWTオプションは無意味

{
	"cuid": “catenoid”,
	"expt": 1462931880,
	"mc": [{
		"mckey": “gDV2B1ZG“,
		"title": “Live Sample“,
                         "live" : {
                                  "url": "http://XXXXX/XXX.m3u8",
                                  "poster_url": "http://XXXXX/XXX.jpg"
                         },
	}]
}

Live Streaming JWT Payload + Akamai CDN 認証

ライブストリーミングの場合、intro / seek / playbackRate機能が無効になるため、該当JWTオプションは無意味

{
  "mc": [
    {
      "mckey": "gDV2B1ZG",
      "live": {
        "url": "http://XXXXX/XXX.m3u8",
        "poster_url": "http://XXXXX/XXX.jpg",
        "cdn": {
           "type": "akamai",
           "password": {
              "short": "000000a0",
              "long": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
           },
           "auth_type": "user",
           "use_ip_validation": true,
           "use_kollus_token": false
        }
      },
      "title": "Live Sample"
    }
  ],
  "cuid": "test",
  "expt": 1462931880
}

Live Streaming JWT Payload + Kollus 認証

ライブストリーミングの場合、intro / seek / playbackRate機能が無効になるため、該当JWTオプションは無意味

{
  "mc": [
    {
      "mckey": "gDV2B1ZG",
      "live": {
        "url": "http://XXXXX/XXX.m3u8",
        "poster_url": "http://XXXXX/XXX.jpg",
        "cdn": {
           "type": "kollus",
           "use_ip_validation": true,
           "use_duplication_block": false
        }
      },
      "title": "Kollus Live"
    }
  ],
  "cuid": "test",
  "expt": 1462931880
}

※ exptフィールドの値は onetime URLの expire timeとなり、同時にライブストリームのexpire timeとして使用されます。例えば1時間のライブ配信をする場合にはexptの値を1時間以降の値に設定しなければなりません。

Live Streaming JWT Payload + Kollus 認証

Kollus Live 用のJWT SPECとなります。JWT Payload形式は以下のようなJSON文字列となります。

{
    "client_user_id": "CLIENT_USER_ID",
    "client_user_name": "CLIENT_USER_NAME",
    "video_watermarking_code_policy": {
                "code_kind":"client_user_id",
                "font_size":7,
                "font_color":"FFFFFF",
                "show_time":1,
                "hide_time":500,
                "alpha":50,
                "enable_html5_player": false
      },
    "client_user_image": "CLIENT_USER_IMAGE",
    "expire_time": EXPIRE_TIME,
    "play_expt": PLAY_EXPT_TIME,
    "live_media_channel_key": "LIVE_MEDIA_CHANNEL_KEY",
    "live_media_profile_key": "LIVE_MEDIA_PROFILE_KEY",
    "title": "TITLE",
    "chatting_policy": {
        "is_visible": true,
        "is_admin": false,
        "position": "right"
    }
}

Payload 項目

サンプルコード

 Json Web Tokens – Java

 Json Web Tokens – ruby

 Json Web Tokens – php

Download

サンプルコード

 Download – jsp

 Download – php

 Download – dotnet