概要
기既存の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 모듈에 대한 의존성을 줄이고 좀 더 유연하게 스펙 변경에 대응할 수 있도록 합니다.
注意事項
- JSON Webtoken(以下JWT)につきましてはhttp://jwt.io ページを参考
- JWTのPayload部分に以下の内容に記述されている、先に登録されたClaimを使用しては行けません。 (https://tools.ietf.org/html/rfc7519#section-4) 意図通り動作しない可能性があります。
- 暗号化アルゴリズムは 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.kr.kollus.com/s?jwt=生成したJWT&custom_key=ユーザーキー
JWT Payload Spec
JWT Payload形式は以下のようなJSON文字列となります。
{
"cuid": "CLIENT_USER_ID",
"awtc": “AUDIO_WATERMARKING_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_CONTENT_KEY”,
"mcpf": “MEDIA_CONTENT_PROFILE_KEY”,
"tilte": “TITLE”,
"intr": IS_INTRO,
“scroll_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" : "..."
}
}]
}
Payload 項目
名称 | Datatype | 必須有無 | 内容 | Mediatype |
cuid | String | 必須 | コンテンツにアクセスする顧客のユーザーID: | VOD/LIVE |
awtc | String | 選択 (基本値: null) | Kollus オーディオウォーターマーキング機能を実装するとき使用すウォーターマーキングコードで、APIを呼び出して獲得します。 | VOD |
expt | Integer | 必須 | JWTの有効時間となり、Unix timestamp 形式で入力します。顧客側のサーバーとの時刻が一致しない場合があるため、有効時間が過ぎても最長1分以内まではアクセスができます。 | VOD/LIVE |
pc_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 | String | 必須 | 再生するコンテンツの識別キー。拡張Media content key形式も同一に使用可能 | VOD/LIVE |
mcpf | String | 選択 (基本値: null) | コンテンツの複数のプロファイルの中で一つのプロファイルを強制に指定して再生する場合に使用します。強制に指定するプロファイルキーを入力します。 | VOD |
title | String | 選択 (基本値: null) | コンテンツのタイトルを代替する文字列 | VOD/LIVE |
intr | Boolean | 選択 (基本値: false) | Introの有無を入力します。詳しくは下段の例示を参照してください。 | VOD |
scroll_event | Boolean | (基本値: false) | 画面の scroll event 適用有無 true: 画面の縦を基準でvideo領域を合わせて、見えない領域はscroll可能とする false: 既存の通りに横を基準で画面を合わせる | VOD |
seek | Boolean | 選択 (基本値: true) | コンテンツのseek可能の有無を入力します。一般的にintroコンテンツの場合にはseek不可とします。 | VOD |
seekable_end | Integer | 選択 (基本値: -1) | Seek不可にした場合でも再生開始時点から入力した値の時点の間ではSeek可能になります。 | VOD |
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) 方式で挿入 "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使用有無 | |
| live.url (LIVE_URL) | String | 選択 (基本値: null) | Live Streamingの再生URLを入力 | LIVE |
| live.poster_url (LIVE_POSTER) | String | 選択 (基本値: null) | Live Streamingを再生する前に表示されるポスターイメージのURLを入力 | LIVE |
| live.cdn | Object | 選択 | CDNを使用しない場合JSONブロックを省略 | LIVE |
| live.cdn.password | Object | 選択 (基本値: 空の文字列) | CDNアクセスのパスワード: short, long 両方必要 | LIVE |
| live.auth_type | String | 選択 (基本値: user) | Edge 認証タイプ | LIVE |
| live.use_ip_validation | Boolean | 選択 (基本値: false) | EdgeからMedia URLを生成する際にP認証を使用するかを設定 | LIVE |
| live.use_kollus_token | Boolean | 選択 (基本値: false) | EdgeからMedia URLを生成する際にKollus Token (ktn パラメータ)を使用するかを設定 | LIVE |
例示
コンテンツの再生に使用する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": “vnCVPVyV“,
"play_section": {
"start_time": 0,
"end_time": 60,
}]
}