HMAC 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

計算及驗證雜湊式訊息驗證碼 (HMAC)。偶爾 通稱為金鑰訊息驗證碼或金鑰雜湊雜湊，HMAC 使用加密編譯雜湊 將 SHA-1、SHA-224、SHA-256、SHA-384、SHA-512 或 MD-5 等函式套用至「訊息」以及密鑰 產生簽名或訊息驗證碼。「訊息」一詞這裡 指的是任何位元組串流訊息寄件者也可以傳送 HMAC 給接收者。 ，接收者可以使用 HMAC 來驗證訊息。

如要進一步瞭解 HMAC， 請參閱 HMAC：金鑰雜湊 (Keyed-Hashing) 針對郵件驗證 (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>

除了名稱屬性以外，還能在 Apigee UI Proxy 編輯器中為政策加上標籤 使用不同的自然語言名稱

<Message>

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

指定要簽署的訊息酬載。此元素的輸入內容支援 訊息範本 (替代變數) 允許在執行階段納入其他項目，例如時間戳記、 Nonce 清單、 標題或其他資訊例如：

<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，即可將任何無法解析的變數視為空白字串 (空值)。

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>