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 設定不適用於這些項目。

流程變數

政策可以在執行期間設定這些變數。

錯誤參考資料

本節說明政策觸發錯誤時，系統傳回的錯誤代碼和錯誤訊息，以及 Apigee 所設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

執行政策時，可能會發生這些錯誤。

部署錯誤

若您部署包含這項政策的 Proxy，就可能會發生這些錯誤。

錯誤變數

系統會在發生執行階段錯誤時設定這些變數。如需更多資訊 請參閱注意事項 政策錯誤。

錯誤回應範例

針對錯誤處理，最佳做法是將錯誤的 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>