• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

WordPress Nonce

提供: WordPress Codex 日本語版
移動先: 案内検索

ページ名検討中: このページ名「WordPress Nonce」について改名が提案されています。ご意見をお寄せください。

この項目「WordPress Nonce」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

nonce(ノンス)は、ある種の誤使用や悪意のある操作から URL やフォームを守るための「一度だけ使われる数値」です。WordPress の nonce は実際には数値ではなく、数字と英字で作られたハッシュです。また、本当に一度だけ使われるのではなく、無効になるまでの「有効期間」を持っています。その期間では、同じユーザーの同じコンテキストに対して、同じ nonce が生成されます。つまり、ある操作に対する nonce は、nonce の有効期間が切れるまで同じユーザーについて同じ値を保ちます。

上記のように本来の nonce と違いはありますが、WordPress のセキュリティトークンもほとんど同じ用途を満たすので "nonce" と呼ばれます。(WordPress の nonce は)CSRF を含む何種類かの攻撃から保護する助けになりますが、完全に一度しか使えない訳ではないので反射攻撃(replay attack)から守ることはできません。

nonce の使用例として、ID=123 の投稿をゴミ箱へ入れるとき、管理画面は次のような URL を生成します。URL の末尾に nonce が見えるでしょう:

http://example.com/wp-admin/post.php?post=123&action=trash&_wpnonce=b192fc4204

もし誰かが URL を書き換えて ID=456 の投稿をゴミ箱へ入れようとすると、nonce が無効になるので、その企みは失敗します:

http://example.com/wp-admin/post.php?post=456&action=trash&_wpnonce=b192fc4204

nonce が無効だと WordPress はブラウザーへ "403 Forbidden" を返し、エラーメッセージ「本当に実行していいですか?」を表示します。

自分で nonce を作って URL のクエリ文字列へ追加したり、フォームの hidden フィールドへ入れたり、もっと他の方法で使うこともできます。

AJAX リクエストで nonce を使う場合、JavaScript コードが nonce を取得できるように hidden フィールドへ入れるのが一般的です。

注意: nonce は現在のユーザーのセッションにユニークです。そのため、ユーザーが非同期にログインやログアウト(例えばページを表示中に別のウィンドウを開いてログアウト)すると、ページの nonce は有効ではなくなります。

URL へ nonce を追加

URL へ nonce を追加するには、裸の URL とアクションを表す文字列を指定して wp_nonce_url() を呼び出します。例えば:

$complete_url = wp_nonce_url( $bare_url, 'trash-post_'.$post->ID );

保護を最大化するため、アクションを表す文字列を可能な限り具体的(類似のものと重複しない)にしてください。

デフォルトでは、wp_nonce_url() は _wpnonce という名前のフィールドを追加します。関数を呼び出すときに違う名前を指定できます。例えば:

$complete_url = wp_nonce_url( $bare_url, 'trash-post_'.$post->ID, 'my_nonce' );

フォームへ nonce を追加

フォームへ nonce を追加するには、アクションを表す文字列を指定して wp_nonce_field() を呼び出します。デフォルトでは、wp_nonce_field() は 2 つの hidden フィールドを追加します。1 つは nonce の値、もう一つは現在の URL(リファラー)で、追加した結果を表示します。例えばこのように呼び出すと:

wp_nonce_field( 'delete-comment_'.$comment_id );

次のように表示されます:

<input type="hidden" id="_wpnonce" name="_wpnonce" value="796c7766b1" />
<input type="hidden" name="_wp_http_referer" value="/wp-admin/edit-comments.php" />

保護を最大化するため、アクションを表す文字列を可能な限り具体的(類似のものと重複しない)にしてください。

nonce フィールドに違う名前を指定できます。また、リファラーのフィールドを追加しないようにできます。さらに、結果を表示せず値として返すこともできます。使い方について詳しくは wp_nonce_field() を見てください。

他の用途向けに nonce を作成する

他の用途向けに nonce を作成するには、アクションを表す文字列を指定して wp_create_nonce() /en を呼び出します。例えば:

$nonce = wp_create_nonce( 'my-action_'.$post->ID );

すると nonce の値だけを返します。例えば: 295a686963

保護を最大化するため、アクションを表す文字列を可能な限り具体的(類似のものと重複しない)にしてください。

nonce の検証

URL、管理画面のフォーム、AJAX リクエスト、または他のコンテキストに含まれた nonce を検証できます。

管理画面からの nonce を検証する

URL または管理画面のフォームからの nonce を検証するには、アクションを表す文字列を指定して check_admin_referer() を呼び出します。例えば:

check_admin_referer( 'delete-comment_'.$comment_id );

このように呼び出すと nonce とリファラーをチェックし、失敗した場合は普通のアクションが行われます("403 Forbidden" とエラーメッセージを返してスクリプト実行を終了)。

nonce の作成時にデフォルトのフィールド名(_wpnonce)を使わなかった場合、フィールド名を指定します。例えば:

check_admin_referer( 'delete-comment_'.$comment_id, 'my_nonce' );

AJAX リクエストからの nonce を検証する

AJAX リクエストからの nonce を検証するには、アクションを表す文字列を指定して check_ajax_referer() /en を呼び出します。例えば:

check_ajax_referer( 'process-comment' );

このように呼び出すと nonce をチェックし(リファラーは対象外)、失敗するとデフォルトではスクリプトの実行を終了します。

nonce の作成時にデフォルトのフィールド名(_wpnonce または _ajax_nonce)を使わなかった場合、またはチェックが失敗したときの動作を変えたい場合は、追加のパラメーターを指定します。詳しくは check_ajax_referer() /en を見てください。

他のコンテキストからの nonce を検証する

他のコンテキストからの nonce を検証するには、nonce の値とアクションを表す文字列を指定して wp_verify_nonce() を呼び出します。例えば:

wp_verify_nonce( $_REQUEST['my_nonce'], 'process-comment'.$comment_id );

結果が false であれば、リクエストの処理を続けないでください。代わりに適切なアクションを行います。一般的には wp_nonce_ays() /en を呼び出して、ブラウザーへ "403 Forbidden" を返し、エラーメッセージ「本当に実行していいですか?」を表示します。

nonce システムの変更

いろいろな アクションフィルター を使って nonce システムを変更できます。

nonce の有効期間の変更

デフォルトでは、nonce の有効期間は 1 日です。これを過ぎると、アクション文字列が一致しても nonce は無効です。有効期間を変更するには、nonce_life フィルターに関数をフックして有効期間を秒数で指定します。例えば、有効期間を 4 時間とするには:

add_filter( 'nonce_life', function () { return 4 * HOUR_IN_SECONDS; } );

注意: WordPress の nonce が一度だけ使われる数値ではないという意味で、nonce の有効期間は本当の有効期間とは異なります。WordPress は 2 期(有効期間の半分が 1 期)のシステムを用いて、nonce を前期と後期の両方で検証します。デフォルト設定(有効期間が 24 時間)では、nonce に含まれる時刻データは、いくつの 12 時間区切りを過ぎたかチェックされます。ただし期の区切りは UNIX エポック を起点として計算されます。つまり、昼 12 時〜夜 12 時に作られた nonce は翌日の昼 12 時までの有効期間を持ちます。従って本当の有効期間は一定ではなく 12〜24 時間の間です。上の例では 2〜4 時間の有効期間を持つ nonce が得られます。

検証を追加する

check_admin_referrer() が nonce を見つけてリファラーも正しい場合に、追加の検証を実行させるには、check_admin_referer アクションを使います。例えば:

function my_additional_check ( $action, $result ) { ... }
add_action( 'check_admin_referrer', 'my_additional_check', 10, 2 );

check_ajax_referer() では、check_ajax_referer アクションを同じ方法で使います。

エラーメッセージを変更する

nonce が無効なときに送るエラーメッセージを、翻訳システムを使って変更できます。例えば:

function my_nonce_message ($translation) {
  if ($translation == 'Are you sure you want to do this?')
    return 'No! No! No!';
  else
    return $translation;
  }

add_filter('gettext', 'my_nonce_message');

追加情報

このセクションには WordPress の nonce システムについて、たまに役立ちそうな情報があります。

nonce の有効期間

nonce の有効期間は 2 つのに分けられます。nonce が有効なとき、nonce を検証する関数は期の番号である 1 または 2 を返します。この情報は、例えば、後半の期に nonce があったら期限切れする前に nonce を更新するなどの使い道があるでしょう。

nonce のセキュリティ

nonce は key(認証用キー)と salt(シークレットキー)を使って生成されます。その key と salt は WordPress を正しくインストールすると、あなたのサイトにユニークな値です。NONCE_KEY と NONCE_SALT は wp-config.php ファイル内に定義されており、もっと詳しいコメントも含まれています。

nonce システムを入れ替える

nonce システムを構成する関数の一部は プラガブル なので、自分で関数を用意して入れ替えることができます。

管理画面および AJAX からのリクエストを検証する方法を変えるには、check_admin_referrer() と check_ajax_referrer() の片方または両方を入れ替えます。

nonce システム全体を別の nonce システムで置き換えるには、wp_create_nonce(), wp_verify_nonce() および wp_nonce_tick() を入れ替えます。

Nonce関数: wp_explain_nonce() /en, wp_nonce_ays() /en, wp_nonce_field(), wp_nonce_url(), wp_verify_nonce(), wp_create_nonce() /en, check_admin_referer() /en, check_ajax_referer() /en, wp_referer_field() /en


Nonceフック: nonce_life, nonce_user_logged_out, explain_nonce_(verb)-(noun), check_admin_referer

リソース

日本語リソース

最新英語版: WordPress Codex » WordPress Nonces最新版との差分