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 設定はそれらには適用されません。

フロー変数

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

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

障害変数

ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

エラー レスポンスの例

ベスト プラクティスとして、エラー処理でエラー レスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

障害ルールの例

<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>