HMAC ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

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

このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。ポリシータイプと各環境タイプで使用可能かどうかは、ポリシータイプをご覧ください。

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

サンプル

<HMAC name='HMAC-1'>

  <Algorithm>SHA256</Algorithm>

  <!-- the default encoding of the SecretKey is UTF-8 -->
  <SecretKey encoding='base64' ref='private.secretkey'/>

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

  <!--
    The Message element accepts a template, which means the "message" the policy operates
    on can include fixed and multiple variable parts, including newlines and static functions.
    Whitespace, such as newlines and space characters, 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>

  <!-- the default encoding of the SecretKey is UTF-8 -->
  <SecretKey encoding='base16' ref='private.secretkey'/>

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

  <!--
     The Message element accepts a template. This policy verifies an HMAC on the request content.
   -->
  <Message>{request.content}</Message>

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

  <!-- default encoding of the output 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 設定はそれらには適用されません。

フロー変数

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

一般的な問題

あるレベルでは、HMAC ポリシーはとても単純に見えます。鍵とメッセージを指定し、計算された HMAC を取得するだけです。しかし、このポリシーで既知のメッセージと鍵の組み合わせを使って取得した HMAC が予期した値と異なる場合は、ストレスを感じるかもしれません。このセクションでは、このような問題に対処するための使用上の注意をいくつか説明します。

検証中に HMAC の不一致を生じさせる一般的な落とし穴は 2 つあります。それは、メッセージ内の空白文字の違いと、エンコードとデコードの違いです。後者は、SecretKey 要素と Output 要素の両方に当てはまります。

空白文字の違い

出力 HMAC 値は、人間が些細に感じるような違いの影響を受けます。たとえば、「Secret123」として表すことができる秘密鍵があるとします。UTF-8 デコードの場合、キーバイトは [53 65 63 72 65 74 31 32 33] になります。このキーを使用してメッセージ abc に対する HMAC-SHA256 を計算すると、a7938720fe5749d31076e6961360364c0cd271443f1b580779932c244293bc94 になります。メッセージにスペースを 1 つ追加して abc<SPACE> にする（<SPACE> は ASCII 32 を意味します）と、HMAC-SHA256 は 274669b2a85d2532da48e2ce3d8e52ee17346d1bcd1a606d87db1934b5ab294b になります。

同様に、メッセージを abc<NEWLINE> にする（<NEWLINE> は ASCII 10 を意味します）と、HMAC は 0780370844ca07f896066837e8230d3b6a775f678a4ae03e6b5e864c674831f5 になります。メッセージを少し変えただけで、HMAC 値は大きく変化します。これは意図的なものです。 これは HMAC に意図された望ましい動作です。

重要なポイント: 元の HMAC の計算に使用するメッセージ本文と、HMAC の検証に使用されたメッセージ本文が完全に同じになるようにすることが重要です。HMAC の検証ツールが空白文字を追加するかテキストを再フォーマットして、なんらかの方法でメッセージ ペイロードを変更すると、計算された HMAC が変更されます。

ポリシー構成でメッセージ テンプレートを使用する場合は特に注意してください。たとえば、次のポリシー構成フラグメントは問題となる可能性があります。

<HMAC name='HMAC-1'>
    ...
    <!-- the result of this message template will include surrounding whitespace -->
    <Message>
        {request.content}
    </Message>
    ...
       
</HMAC>

<Message> 要素内のこのメッセージ テンプレートの評価結果には、メッセージのコンテンツを囲む改行とスペースが含まれます。これはおそらく、意図されたものではありません。次のような構成の方が適切です。

<HMAC name='HMAC-1'>
    ...
    <Message>{request.content}</Message>
    ...
         
</HMAC>

エンコードの違い

鍵のマテリアルが同じ場合でも異なるデコードが行われると、異なる鍵が生成されます。「U2VjcmV0S2V5MTIz」として表すことができる秘密鍵があるとします。UTF-8 デコードの場合、base16 で表現されるキーバイトは [55 32 56 6a 63 6d 56 30 53 32 56 35 4d 54 49 7a] になります。base64 デコードでは、キーバイトは [53 65 63 72 65 74 4b 65 79 31 32 33] になります。ソース マテリアルのデコードが異なると、異なる鍵になり、異なる HMAC 値が生成されます。

重要なポイント: 元の HMAC の計算に使用する鍵のマテリアルと、HMAC の検証に使用する鍵が完全に同じであることを保証することが重要です。これはおそらく、両端で同じキーエンコードを確実に使用することを意味します。HMAC ポリシーでは、SecretKey 要素の encoding 属性を使用してキーエンコードを指定できます。

出力のエンコードについても考えましょう。base16 または hex エンコードで 27f17e11c8ece93844c5eb5e55161d993368628a214f9a51c25d0185e8ea06e2 と表現される HMAC-SHA256 と、base64 エンコード形式で J/F+Ecjs6ThExeteVRYdmTNoYoohT5pRwl0BhejqBuI= と表現される HMAC-SHA256 は同じです。この 2 つの文字列は異なっているように見えますが、同じ値を表します。最初に計算された HMAC と検証対象の HMAC で、同じエンコードを確実に使用してください。HMAC ポリシーでは、Output 要素の encoding 属性を使用して目的の出力エンコードを指定したり、VerificationValue 要素にある同じ属性を使用して検証ツールのデコード方法を指定したりできます。

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードおよびエラー メッセージと、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>