applican

マイページに戻る

whitelist.xml

アプリケーションから、アクセスを許可するURL・ファイルを設定出来るwhitelist.xmlの詳細は以下の通りです。

セキュリティ向上のため、whiltelist.xml必ず配置するようにして下さい。

サンプル XML

ホワイトリスト定義 XML のサンプルは次の通り。

<!-- whitelist.xml -->
			<applican-whitelist>
			  <!-- default: all scopes are passed. -->

			  <!-- all scopes (backward compatibility) -->
			  <allowed>http://www.applican.com/</allowed>

			  <!-- RegExp rules -->
			  <allowed format="regexp">https://www[1-9]\.example\.com/.*</allowed>

			  <!-- matching rules -->

			  <!-- all scopes -->
			  <rules scope="default">
			    <allowed>http://www.applican.com/</allowed>
			  </rules>

			  <!-- URL Scheme 'url' query parameter -->
			  <rules scope="launch_url">
			    <allowed>http://www.newphoria.co.jp/</allowed>
			  </rules>

			  <!-- href="http://www.example.com/?launch_browser=yes" -->
			  <rules scope="launch_browser">
			    <allowed>http://www.newphoria.co.jp/</allowed>
			    <allowed>http://www.newphoria.com/</allowed>
			  </rules>

			  <!-- href="http://www.example.com/?launch_webview=yes" -->
			  <rules scope="launch_webview">
			    <allowed>http://www.newphoria.co.jp/</allowed>
			  </rules>

			  <!-- href="http://www.example.com/?launch_tab=1" -->
			  <rules scope="launch_tab">
			    <allowed>http://www.newphoria.co.jp/</allowed>
			  </rules>

			  <!-- URL Scheme links -->
			  <rules scope="urlscheme">
			    <allowed>twitter://*</allowed>
			    <allowed>facebook://*</allowed>
			    <allowed>market://*</allowed>
			  </rules>

			  <!-- Applican API -->
			  <rules scope="api" api="applican.utilities.download" param="url">
			    <allowed>http://www.newphoria.co.jp/*</allowed>
			  </rules>

			  <rules scope="api" api="applican.utilities.download" param="destination">
			    <allowed>app-file://*</allowed>
			    <allowed>app-ext-cache://*</allowed>
			  </rules>

			  <rule scope="api" api="applican.media">
			    <allowed>app-ext-cache:///downloaded/music/*</allowed>
			  </rule>

			</applican-whitelist>

<rules>

このタグ内に <allowed> タグを複数配置できる。

scope 属性にルール適用の範囲を指定することで、細かい制御が可能になる。 また、scope に api が指定された場合は api 属性を指定して、使用する API を明確にする必要がある。

scope="default"

ルールが存在しない場合、ここに記載されたルールが適用される。scope 属性の指定が無い場合はこのスコープが使用される。

<!-- index.html -->
			<a href="http://www.applican.com">applican</a>

			<!-- whitelist.xml -->
			<rules scope="default">
			  <allowed>http://www.applican.com/</allowed>
			</rules>

scope="launch_url"

アプリが起動されたときの URL スキームに含まれる url クエリーパラメーターに対してルールを適用する。

<!-- other apps or pages -->
			<a href="jp.co.newphoria.exampleapp://?url=http%3A%2F%2Fwww.applican.com%2F">Click</a>

			<!-- whitelist.xml -->
			<rules scope="launch_url">
			  <allowed>http://www.applican.com/</allowed>
			</rules>

scope="launch_browser"

launch_browser クエリーパラメーターに対してルールを適用する。

<!-- index.html -->
			<a href="http://www.applican.com/?launch_browser=yes">applican</a>

			<!-- whitelist.xml -->
			<rules scope="launch_browser">
			  <allowed>http://www.newphoria.co.jp/</allowed>
			</rules>

scope="launch_webview"

launch_webview クエリーパラメーターに対してルールを適用する。

<!-- index.html -->
			<a href="local://index2.html?launch_webview=yes">index2</a>
			<a href="local://index3.html?launch_webview=yes_without_toolbar">index3</a>

			<!-- whitelist.xml -->
			<rules scope="launch_webview">
			  <allowed>local://*</allowed>
			</rules>

scope="launch_tab"

launch_tab クエリーパラメーターに対してルールを適用する。

<!-- index.html -->
			<a href="local://index.html?launch_tab=2">tab2</a>

			<!-- whitelist.xml -->
			<rules scope="launch_tab">
			    <allowed>local://*</allowed>
			</rules>

scope="urlscheme"

コンテンツ内のリンクから URL スキームで外部アプリを起動しようとした場合にルールを適用する。

<rules scope="urlscheme">
			  <allowed>twitter://*</allowed>
			  <allowed>facebook://*</allowed>
			  <allowed>market://*</allowed>
			</rules>

scope="api"

Applican API にルールを適用する。api 属性に適用する API 名を指定する。

<rules scope="api" api="applican.launcher.webview">
			  <allowed>http://www.newphoria.co.jp/</allowed>
			</rules>

この例では Launcher API に対してルールを適用する。

API によってはパラメーターごとにルールを適用する必要があるため、param 属性にパラメーター名も合わせて指定する。

<rules scope="api" api="applican.utilities.download" param="url">
			  <allowed>http://www.newphoria.co.jp/*</allowed>
			</rules>

			<rules scope="api" api="applican.utilities.download" param="destination">
			  <allowed>app-cache://downloads/*</allowed>
			</rules>

この例では http://www.newphoria.co.jp/ というサーバーからファイルをダウンロードでき、ダウンロードしたファイルはアプリケーションキャッシュディレクトリーにのみ保存可能である。

<allowed>

format 属性に regexp を指定することで正規表現によるルールの記述が可能。

評価される順番

アプリ起動 URL スキームの場合

  1. <rules> 内に scope="launch_url" が存在していればそのルールを適用。
  2. 存在していなければ scope="default" を適用。
  3. <applican-whitelist> 内の <allowed> を適用。 (従来通り)

scope が launch_browser、launch_webview、launch_tab、urlscheme の場合も同様の順番で評価される。

API の場合 (パラメーターなし)

  1. <rules> 内に scope="urlscheme" api="applican.XXX.XXX" が存在していればそのルールを適用。
  2. <rules> 内に scope="api" が存在していればそのルールを適用。
  3. 存在していなければ scope="default" を適用。
  4. <applican-whitelist> 内の <allowed> を適用。 (従来通り)

API の場合 (パラメーターあり)

  1. <rules> 内に scope="urlscheme" api="applican.XXX.XXX" param="param" が存在していればそのルールを適用。
  2. <rules> 内に scope="urlscheme" api="applican.XXX.XXX" が存在していればそのルールを適用。
  3. <rules> 内に scope="api" が存在していればそのルールを適用。
  4. 存在していなければ scope="default" を適用。
  5. <applican-whitelist> 内の <allowed> を適用。 (従来通り)

<allowed> が指定されていない場合の挙動

<allowed> が指定されていない場合は * が指定されていると見なされるため、適切に記述する必要がある。

アプリ起動 URL スキームのみにルールを適用し、それ以外は全て通す場合の例。

<applican-whitelist>
			  <!-- 全て解放 -->
			  <allowed>*</allowed>
			  <!-- URL スキームのみ評価 -->
			  <rules scope="launch_url">
			    <allowed>http://www.applican.com/*</allowed>
			  </rules>
			</applican-whitelist>

この定義は以下と等価。

<applican-whitelist>
			  <!-- <allowed> が存在しないため、全て解放 -->
			  <!-- URL スキームのみ評価 -->
			  <rules scope="launch_url">
			    <allowed>http://www.applican.com/*</allowed>
			  </rules>
			</applican-whitelist>

特定の API を使用する場合の例。

<applican-whitelist>
			  <!-- 全て閉じる -->
			  <allowed></allowed>
			  <!-- Download API のみ通す -->
			  <rules scope="api" api="applican.utilities.download">
			    <allowed>http://www.applican.com/*</allowed>
			  </rules>
			</applican-whitelist>

<rules> が指定されていない場合の挙動

<applican-whitelist> タグ直下に指定されている <allowed> タグは <rules scope="default"> に含まれているものとして処理される。

<applican-whitelist>
			    <allowed>http://www.applican.com/*</allowed>
			</applican-whitelist>

これは次の定義と等価。

<applican-whitelist>
			    <rules scope="default">
			        <allowed>http://www.applican.com/*</allowed>
			    </rules>
			</applican-whitelist>

Applican 固有のスキーム名

特別な URL スキーム名も使用することができる。

local://

web.zip を展開したディレクトリー。

app-cache://

アプリケーションキャッシュディレクトリー。

app-ext-cache://

外部アプリケーションキャッシュディレクトリー。iOS は app-cache:// と同じ。

<rule scope="api" api="applican.media">
			  <allowed>app-ext-cache://downloaded/music/*</allowed>
			</rule>

app-file://

アプリケーションファイルディレクトリー。

app-ext-file://

外部アプリケーションファイルディレクトリー。iOS は app-file:// と同じ。

アプリカン API へのホワイトリスト適用について

ホワイトリストブロックイベント

それぞれの API においてエラーコールバックが存在する場合は、ホワイトリストによりブロックされた際にエラーコールバックが呼び出されるが、通常のリンクなどでは検出できないため、ブロックされると whitelistblocked というイベントを発生する。

次のようなコードでホワイトリストによりブロックされたことが分かるようになる。

document.addEventListener("whitelistblocked", function (evt) {
			    console.log("Whitelist Blocked.");
			    alert("Whitelist Blocked.\n[url=" + evt.applican_whitelist_url + ", scope=" + evt.applican_whitelist_scope + ", api=" + evt.applican_whitelist_api);
			});

applican_whitelist_url

ブロック対象となった URL。

applican_whitelist_scope

ブロックされたスコープ。

applican_whitelist_api

スコープが API の場合、ブロックされた API。

Camera

saveToPhotoAlbum()

<rules scope="api" api="applican.camera.savetophotoalbum">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.camera.savetophotoalbum">
  2. <rules scope="api">
  3. <rules scope="default">

FileSystem

applican.requestFileSystem()

ホワイトリストの記述必要なし。

DirectoryEntry

全てのメソッドに共通してルールを適用できるが、それぞれのメソッドで指定できる場合はそちらを指定する方が望ましい。

<rules scope="api" api="applican.directoryentry">
			</rules>

createReader()

ホワイトリストの記述必要なし。

getDirectory()

options に create を指定した場合は param に create を指定することでディレクトリ生成について制限をかけることができる。

<rules scope="api" api="applican.directoryentry.getdirectory" param="create">
			</rules>

ディレクトリの読み取りのみを行う場合は必要ない。

<rules scope="api" api="applican.directoryentry.getdirectory">
			</rules>
ルール参照順

options に create を指定した場合

  1. <rules scope="api" api="applican.directoryentry.getdirectory" param="create">
  2. <rules scope="api" api="applican.directoryentry.getdirectory">
  3. <rules scope="api" api="applican.directoryentry">
  4. <rules scope="api">
  5. <rules scope="default">

options に create を指定しない場合

  1. <rules scope="api" api="applican.directoryentry.getdirectory">
  2. <rules scope="api" api="applican.directoryentry">
  3. <rules scope="api">
  4. <rules scope="default">

getFile()

options に create を指定した場合は param に create を指定することでファイル生成について制限をかけることができる。

<rules scope="api" api="applican.directoryentry.getfile" param="create">
			</rules>

ファイルの読み取りのみを行う場合は必要ない。

<rules scope="api" api="applican.directoryentry.getfile">
			</rules>
ルール参照順

options に create を指定した場合

  1. <rules scope="api" api="applican.directoryentry.getfile" param="create">
  2. <rules scope="api" api="applican.directoryentry.getfile">
  3. <rules scope="api" api="applican.directoryentry">
  4. <rules scope="api">
  5. <rules scope="default">

options に create を指定しない場合

  1. <rules scope="api" api="applican.directoryentry.getfile">
  2. <rules scope="api" api="applican.directoryentry">
  3. <rules scope="api">
  4. <rules scope="default">

copyTo()

コピー先に制限をかけることができる。

<rules scope="api" api="applican.directoryentry.copyto">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.directoryentry.copyto">
  2. <rules scope="api" api="applican.directoryentry">
  3. <rules scope="api">
  4. <rules scope="default">

moveTo()

移動先に制限をかけることができる。

<rules scope="api" api="applican.directoryentry.moveto">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.directoryentry.moveto">
  2. <rules scope="api" api="applican.directoryentry">
  3. <rules scope="api">
  4. <rules scope="default">
remove() / removeRecursively()

remove() および removeRecursively() ともに以下のルールを適用できる。

<rules scope="api" api="applican.directoryentry.remove">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.directoryentry.remove">
  2. <rules scope="api" api="applican.directoryentry">
  3. <rules scope="api">
  4. <rules scope="default">

getParent()

api="applican.directoryentry" のルールが適用される。

<rules scope="api" api="applican.directoryentry">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.directoryentry">
  2. <rules scope="api">
  3. <rules scope="default">

FileEntry

全てのメソッドに共通してルールを適用できるが、それぞれのメソッドで指定できる場合はそちらを指定する方が望ましい。

<rules scope="api" api="applican.fileentry">
			</rules>

読み取りだけであれば api="applican.fileentry" の指定だけで良いが、ファイルに変更が加えられるメソッドについてはそれぞれのルールに従う。

createWriter()

このメソッド呼び出しの結果として FileWriter が生成されるため、api="applican.filewriter" のルールが適用される。

<rules scope="api" api="applican.filewriter">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.filewriter">
  2. <rules scope="api">
  3. <rules scope="default">

file()

api="applican.fileentry" のルールが適用される。

<rules scope="api" api="applican.fileentry">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.fileentry">
  2. <rules scope="api">
  3. <rules scope="default">

copyTo()

コピー先に制限をかけることができる。

<rules scope="api" api="applican.fileentry.copyto">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.fileentry.copyto">
  2. <rules scope="api" api="applican.fileentry">
  3. <rules scope="api">
  4. <rules scope="default">

moveTo()

移動先に制限をかけることができる。

<rules scope="api" api="applican.fileentry.moveto">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.fileentry.moveto">
  2. <rules scope="api" api="applican.fileentry">
  3. <rules scope="api">
  4. <rules scope="default">
remove()

ファイルの削除に対して制限をかけることができる

<rules scope="api" api="applican.fileentry.remove">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.fileentry.remove">
  2. <rules scope="api" api="applican.fileentry">
  3. <rules scope="api">
  4. <rules scope="default">

getParent()

api="applican.fileentry" のルールが適用される。

<rules scope="api" api="applican.fileentry">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.fileentry">
  2. <rules scope="api">
  3. <rules scope="default">

DirectoryReader

読み取り対象のディレクトリーに対してルールを適用する。

<rules scope="api" api="applican.directoryreader">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.directoryreader">
  2. <rules scope="api">
  3. <rules scope="default">

FileWriter

書き込み対象のファイルに対してルールを適用する。

<rules scope="api" api="applican.filewriter">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.filewriter">
  2. <rules scope="api">
  3. <rules scope="default">

FileTransfer

FileTransfer は転送元と転送先のパラメーターが必要であるため、それぞれのメソッドごとにルールを適用する。

upload()

アップロード対象のファイルにルールを適用する場合は param に fileurl を指定する。

<rules scope="api" api="applican.filetransfer.upload" param="fileurl">
			</rules>

アップロード先のサーバーにルールを適用する場合は param に encodeuri を指定する。

<rules scope="api" api="applican.filetransfer.upload" param="encodeuri">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.filetransfer.upload" param="fileurl"> および <rules scope="api" api="applican.filetransfer.upload" param="encodeuri">
  2. <rules scope="api" api="applican.filetransfer.upload">
  3. <rules scope="api">
  4. <rules scope="default">

download()

ダウンロード元のサーバーにルールを適用する場合は param に source を指定する。

<rules scope="api" api="applican.filetransfer.download" param="source">
			</rules>

ダウンロードしたファイルの保存場所にルールを適用する場合は param に target を指定する。

<rules scope="api" api="applican.filetransfer.download" param="target">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.filetransfer.download" param="source"> および <rules scope="api" api="applican.filetransfer.download" param="target">
  2. <rules scope="api" api="applican.filetransfer.download">
  3. <rules scope="api">
  4. <rules scope="default">

GameSound

applican.gamesound.loadBGM()

<rules scope="api" api="applican.gamesound.loadbgm">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.gamesound.loadbgm">
  2. <rules scope="api">
  3. <rules scope="default">

applican.gamesound.loadSE()

<rules scope="api" api="applican.gamesound.loadse">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.gamesound.loadse">
  2. <rules scope="api">
  3. <rules scope="default">

HTTP

applican.http.get()

<rules scope="api" api="applican.http.get">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.http.get">
  2. <rules scope="api">
  3. <rules scope="default">

applican.http.post()

<rules scope="api" api="applican.http.post">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.http.post">
  2. <rules scope="api">
  3. <rules scope="default">

Launcher

applican.launcher.urlScheme()

<rules scope="api" api="applican.launcher.urlscheme">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.launcher.urlscheme">
  2. <rules scope="api">
  3. <rules scope="default">

applican.launcher.webview()

<rules scope="api" api="applican.launcher.webview">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.launcher.webview">
  2. <rules scope="api">
  3. <rules scope="default">

LocalNotification

applican.localNotification.schedule()

options の url に対してルールを適用する。

<rules scope="api" api="applican.localnotification.schedule">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.localnotification.schedule">
  2. <rules scope="api">
  3. <rules scope="default">

Media

それぞれのメソッドに対して個別にルールを適用しない場合は以下のようなルールだけで良いが、録音機能を使用しない場合はそのように振る舞うようにルールを適用するのが望ましい。

<rules scope="api" api="applican.media">
			</rules>

録音機能に制限をかける場合の例。

<rules scope="api" api="applican.media">
			</rules>
			<rules scope="api" api="applican.media.startrecord">
			    <allowed></allowed>
			</rules>

applican.media.play()

ルール参照順
  1. <rules scope="api" api="applican.media.play">
  2. <rules scope="api" api="applican.media">
  3. <rules scope="api">
  4. <rules scope="default">

applican.media.startrecord()

<rules scope="api" api="applican.media.startrecord">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.media.startrecord">
  2. <rules scope="api" api="applican.media">
  3. <rules scope="api">
  4. <rules scope="default">

Utilities

applican.utilities.download()

ダウンロード元と保存先のパラメーターが必要であるため、それぞれのパラメーターごとにルールを適用する。

<rules scope="api" api="applican.utilities.download" param="url">
			</rules>

			<rules scope="api" api="applican.utilities.download" param="destination">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.utilities.download" param="url"> および <rules scope="api" api="applican.utilities.download" param="destination">
  2. <rules scope="api" api="applican.utilities.download">
  3. <rules scope="api">
  4. <rules scope="default">

applican.utilities.unzip()

展開元のファイルと保存先のパラメーターが必要であるため、それぞれのパラメーターごとにルールを適用する。

<rules scope="api" api="applican.utilities.unzip" param="source">
			</rules>

			<rules scope="api" api="applican.utilities.unzip" param="target">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.utilities.unzip" param="source"> および <rules scope="api" api="applican.utilities.unzip" param="target">
  2. <rules scope="api" api="applican.utilities.unzip">
  3. <rules scope="api">
  4. <rules scope="default">

Video

applican.video.play()

<rules scope="api" api="applican.video.play">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.video.play">
  2. <rules scope="api">
  3. <rules scope="default">

WebSocket

applican.webSocket.open()

アプリカン API のみで HTML5 の WebSocket には適用されない。

<rules scope="api" api="applican.websocket.open">
			</rules>
ルール参照順
  1. <rules scope="api" api="applican.websocket.open">
  2. <rules scope="api">
  3. <rules scope="default">