HMAC ポリシー

<ph type="x-smartling-placeholder"></ph> 現在、Apigee Edge のドキュメントが表示されています。
Apigee X のドキュメント。 詳細

ハッシュベースのメッセージ認証コード（HMAC）を計算して検証します。HMAC（鍵付きのメッセージ認証コード、鍵付きハッシュとも呼ばれる）は、SHA-1、SHA-224、SHA-256、SHA-384、SHA-512、MD-5 などの暗号ハッシュ関数を秘密鍵ともに「メッセージ」に適用して、そのメッセージに署名またはメッセージ認証コードを生成します。ここでの「メッセージ」という用語は、任意のバイト ストリームを指します。メッセージの送信者は HMAC を受信者に送信することもでき、その受信者は HMAC を使用してメッセージを認証できます。

HMAC の詳細については、HMAC: 鍵付きハッシュ用のメッセージ認証（rfc2104）をご覧ください。

サンプル

<HMAC name='HMAC-1'>

  <Algorithm>SHA256</Algorithm>

  <SecretKey ref='private.secretkey'/>

  <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <!-- optional -->

  <!--
    The "message" can include fixed and multiple variable parts,
    including newlines and static functions.
    Whitespace is significant.
   -->
  <Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
  </Message>

  <!-- default encoding is base64 -->
  <Output encoding='base16'>name_of_variable</Output>

</HMAC>

<HMAC name='HMAC-1'>

  <Algorithm>SHA256</Algorithm>

  <SecretKey ref='private.secretkey'/>

  <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <!-- optional -->

  <!--
    The "message" can include fixed and multiple variable parts,
    including newlines and static functions.
    Whitespace is significant.
   -->
  <Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
  </Message>

  <!--
    VerificationValue is optional.
    Include it to perform an HMAC check.
  -->
  <VerificationValue encoding='base16' ref='expected_hmac_value'/>

  <!-- default encoding is base64 -->
  <Output encoding='base16'>name_of_variable</Output>

</HMAC>

HMAC の要素リファレンス

このポリシー リファレンスでは、HMAC ポリシーの要素と属性について説明します。

最上位の要素に適用される属性

<HMAC name="HMAC" continueOnError="false" enabled="true" async="false">

次の属性は、すべてのポリシーの親要素に共通です。

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

HMAC を計算するハッシュ アルゴリズムを指定します。

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

name 属性に加えて、Apigee UI プロキシ エディタでポリシーを別の自然言語名でラベル付けするために使用します。

<Message>

<Message>message_template_here</Message>
or
<Message ref='variable_here'/>

署名するメッセージ ペイロードを指定します。この要素の入力では、メッセージ テンプレート（変数置換）がサポートされているため、タイムスタンプ、ノンス、ヘッダーのリストなど、追加の項目を実行時に含めることができます。次に例を示します。

<Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
</Message>

メッセージ テンプレートには、改行や静的関数など、固定部と変数部を含めることができます。空白文字は、有意です。

<Output>

<Output encoding='encoding_name'>variable_name</Output>

ポリシーが計算済みの HMAC 値を使用して設定する必要がある変数の名前を指定します。また、出力に使用するエンコードを指定します。

<SecretKey>

<SecretKey encoding='encoding_name' ref='private.secretkey'/>

HMAC の計算に使用する秘密鍵を指定します。この鍵は参照先の変数から取得され、特定のエンコードに従ってデコードされます。

 <SecretKey encoding='hex' ref='private.encodedsecretkey'/>

<VerificationValue>

<VerificationValue encoding='encoding_name' ref='variable_name'/>
or
<VerificationValue encoding='encoding_name'>string_value</VerificationValue>

（省略可）検証値と、検証値のエンコードに使用されたエンコード アルゴリズムを指定します。ポリシーはこのアルゴリズムを使用して値をデコードします。

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

false に設定すると、ポリシーで指定された参照先の変数を解決できない場合にエラーを返します。true に設定すると、解決できない変数を空の文字列（null）として扱います。

IgnoreUnresolvedVariables ブール値は、メッセージ テンプレートで参照される変数にのみ影響します。SecretKey と VerificationValue は変数を参照できますが、両方とも解決可能である必要があるため、ignore 設定はそれらには適用されません。

フロー変数

ポリシーは実行時にこれらの変数を設定できます。

Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

<FaultRules>
    <FaultRule name="HMAC Policy Errors">
        <Step>
            <Name>AM-Unauthorized</Name>
            <Condition>(fault.name Matches "HmacVerificationFailed")</Condition>
        </Step>
        <Condition>hmac.HMAC-1.failed = true</Condition>
    </FaultRule>
</FaultRules>