Security クラス

Security クラスは、あなたのアプリケーションを CSRF から守ります。

設定

Security クラスは、app/config/config.php 設定ファイルのセキュリティセクションで設定できます。

以下のセキュリティ設定が定義可能です。

パラメータ 型 デフォルト 説明
token_salt string 
'put your salt value here...'
 安全なトークンを生成するためにソルトを使用します。この文字列はランダムにし、容易に推測されないようにしてください。
csrf_token_key string 
'fuel_csrf_token'
 CSRF トークンクッキーの名前。トークンを含むフィールド名としても使用。
csrf_expiration integer 
0
 CRSF トークンクッキーの有効期限。デフォルトでは、ブラウザセッション終了時まで有効。
csrf_bad_request_on_fail boolean 
false
 true にすると、 CSRF トークンの検証が失敗したときに HttpBadRequestException が投げられます。 false にすると、一般的な SecurityException が投げられます。後方互換のためデフォルトは false です。
uri_filter array 
array('htmlentities')
 URI をフィルタするのに使用する呼び出し可能なアイテム(PHP 関数、オブジェクトメソッド、静的クラスメソッド)の配列。デフォルトでは、PHP のビルトイン関数 htmlentities を使用。
input_filter array 
array()
 $_GET、$_POST、$_COOKIE をフィルタするのに呼び出し可能なアイテム(PHP 関数、オブジェクトメソッド、静的クラスメソッド)の配列。デフォルトでは、未定義。
output_filter array 
array('Security::htmlentities')
 View または Presenter に送信する変数をフィルタするのに呼び出し可能なアイテム(PHP 関数、オブジェクトメソッド、静的クラスメソッド)の配列。 セキュリティ上、出力フィルタ(output filter)は必ず定義する必要がある。
htmlentities_flags integer 
null
 HTML エンティティをエンコーディングするときに使用するフラッグ。デフォルトは ENT_QUOTES。
htmlentities_double_encode boolean 
null
 エンコードされたものを再エンコードするかどうか。デフォルトは false。
auto_filter_output boolean 
true
 true にすると、ビューに渡すオブジェクトはすべて自動的にエンコードされる。
whitelisted_classes array 
array('stdClass', 'Fuel\\Core\\View',
 'Fuel\\Core\\Presenter', 'Closure')
 ビューに渡す変数の自動エンコーディングが有効なとき、オブジェクトを渡すときに問題が生じることがある。 この配列で定義したクラスは自動エンコードされない。
csrf_autoload boolean 
false
 true にすると、check_token() を使用して CSRF トークンを自動的にチェックする。チェックに失敗すると SecurityException 例外が投げられる。
csrf_autoload_methods array 
array('post', 'put', 'delete')
 csrf_autoload を true にすると、この配列にある http メソッドすべてで CSRF トークンが検証される。
csrf_auto_token boolean 
false
 When true, Form::open() adds CSRF token hidden field automatically.

"csrf_autoload" を有効にすると、指定したタイプの HTTP リクエストすべてで CSRF トークンを含める必要があります。さもないと、検証に失敗し、SecurityException 例外が投げられます。

オートロードが有効な場合で CSRF 検証失敗を自前で処理したい場合は、index.php で SecurityException 例外をキャッチすることができます。

check_token($value = null)

check_token メソッドは、CSRF トークンをチェックします。
check_token はトークンが存在することを保証します。また、チェックする値を受け取ったとき、(チェックの結果に関わらず) トークンを再生成します。

静的 はい
パラメータ
パラメータ デフォルト 説明
$value 
null
 チェックする CSRF トークン、未指定の場合は POST または JSON からの値をチェックする。
返り値 boolean
例 
Security::check_token();

fetch_token()

fetch_token メソッドはクッキーから CSRF トークンを取得します。

静的 はい
パラメータ なし
返り値 string
例 
$csrf_token = Security::fetch_token();

set_token($rotate = true)

The set_token method allows you to set the next CSRF token to be used, or to force a token rotation.

静的 はい
Parameters
Param Default Description
$rotate 
true
 If true, generation of a new CSRF token is forced. If false, an existing CSRF token is reused if available.
例 
Security::set_token();

generate_token()

generate_token メソッドは、セキュリティトークンを生成します。 このメソッドは、CSRF トークンを生成するのに使用します。セキュアでランダムなトークンが必要な場合、このメソッドを アプリケーションの任意の場所で使用できます。

静的 はい
パラメータ なし
返り値 string
例 
$token = Security::generate_token();

clean($value, $filters = null)

clean メソッドは、提供されるフィルタを用いてデータを綺麗にします。

静的 はい
パラメータ
パラメータ デフォルト 説明
$value 必須 綺麗にされる値。文字列または文字列からなる配列。
$filters 
null
 文字列を綺麗にするのに使用するフィルタ。フィルタは単一の値、または値からなる配列。それぞれの値は、妥当な PHP コールバック。 関数 ('htmlentities'), オブジェクト ($this), 静的メソッド ('Classname::method') を指定可能。
返り値 string
例 
// まず strip tags を適用し、残った html エンティティを変換し、さらに特別なメソッドを適用する
$filters = array('strip_tags', 'htmlentities', '\\cleaners\\soap::clean');
$text = Security::clean($text, $filters);

strip_tags($value)

strip_tags メソッドは、文字列から HTML および PHP タグを取り除きます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$value 必須 タグを取り除かれる文字列
返り値 string
例 
$text = '<p>Test paragraph.</p>';
$text = Security::strip_tags($text);

xss_clean($value, array $options = array())

xss_clean メソッドは、HTMLawed ライブラリを使用して、文字列から危険な HTML タグを取り除きます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$value 必須 タグを取り除かれる文字列
$options 
array()
 htmLawed の追加のオプション設定の配列。綺麗にする規則をカスタマイズする場合に使用する。
返り値 string
例 
$text = '<SCRIPT>alert("XSS attack!")</SCRIPT>';
$text = Security::xss_clean($text);

htmlentities($value, $flags = null, $encoding = null, $double_encode = null)

htmlentities メソッドは、HTML 文字を実体参照に変換します。 このメソッドは、PHP の htmlentities() 関数と同じ操作ですが、 配列やオブジェクトにも適用できます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$value 必須 変換される文字列。
$flags 
null
 htmlentities() に渡すフラグ。未指定の場合、デフォルト値は ENT_QUOTES。
$encoding 
null
 値の文字エンコーディング。未指定の場合、デフォルト値は FuelPHP のデフォルト文字エンコーディング。
$double_encoding 
null
 true の場合、エンコードされた文字列をさらにエンコードしない。未指定の場合、デフォルト値は false。
返り値 mixed
例外 文字列にキャストできないオブジェクトを渡すと、RuntimeException が投げられる。
例 
$text = '<p>Test paragraph.</p>';
$text = Security::htmlentities($text);

js_fetch_token()

The js_fetch_token method allows you to produce JavaScript fuel_csrf_token() function that will return the current CSRF token when called. Use to fill right field on form submit for AJAX operations.

Static Yes
Parameters None
Returns string
Example 
// output the javascript function
echo Security::js_fetch_token();

// you can now use the generated function in the javascript code on your page
<script type="text/javascript">
	var current_token = fuel_csrf_token();
</script>

js_set_token()

The js_set_token method allows you to produce JavaScript fuel_set_csrf_token() function that will set the current CSRF token field in the form when called. Use this on an onsubmit of a form, to update the hidden token field in the form with the current value of the csrf cookie. You have to use this when you want to allow multiple windows open, and use a strict rotation and expiry of the CSRF token.

Static Yes
Parameters None
Returns string
Example 
// output the javascript function
echo Security::js_set_token();

// you use the function generated as an onsubmit function, like so.
// do NOT forget the 'this' parameter, so the function knows which form to update!
<form onsubmit="fuel_set_csrf_token(this);">
	<!-- do your stuff here -->
</form>

Procedural helpers

e($string)

e 関数は、Security::htmlentities の別名。

パラメータ
パラメータ デフォルト 説明
$string 必須 タグを取り除かれる文字列。
返り値 string、Security::htmlentities の返り値
例 
$text = '<p>Test paragraph.</p>';
$text = e($text);