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 for Message Authentication (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 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>