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

<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

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

簽名的運算和驗證的準則完全相同 上傳資料集之後，您可以運用 AutoML 自動完成部分資料準備工作HMAC 政策會計算 HMAC，並視需要驗證已計算出的 HMAC 並套用預期值選擇性的 VerificationValue 元素 (如有) 指示政策根據已知或指定值核對計算值 值。

HMAC 的元素參照

政策參考資料說明瞭 HMAC 政策的元素和屬性。

具備的屬性 套用至頂層元素

<HMAC name="HMAC" continueOnError="false" enabled="true" async="false">

下列屬性適用於所有政策父項元素。

屬性 說明 預設 外觀狀態
名稱 政策的內部名稱。名稱中可使用的字元僅限於： A-Z0-9._\-$ %。不過，Apigee UI 會強制執行 限制 (例如自動移除非英數字元的字元)。

視需要使用 <displayname></displayname> 元素 在 Apigee UI Proxy 編輯器中，以不同的自然語言為政策加上標籤 名稱。

 不適用 必填
continueOnError 如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
已啟用 如要強制執行政策，請設為 true。

將 false 設為「關閉」政策。不會強制執行這項政策 即使服務仍附加於資料流

 true 選用
非同步 此屬性已淘汰。 false 已淘汰

&lt;Algorithm&gt;

<Algorithm>algorithm-name</Algorithm>

指定用於計算 HMAC 的雜湊演算法。

預設 不適用
外觀狀態 必填
類型 字串
有效值 SHA-1、SHA-224、SHA-256、SHA-384、 SHA-512及MD-5

政策設定接受演算法名稱 (不區分大小寫)，且 字母和數字之間是否加上破折號。例如 SHA256、SHA-256 和 sha256 等於

&lt;DisplayName&gt;

<DisplayName>Policy Display Name</DisplayName>

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

預設 如果省略這個元素，則會使用政策的名稱屬性值。
外觀狀態 選用
類型 字串

&lt;Message&gt;

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

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

<Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
</Message>

訊息範本可以包含固定和不變數的部分，包括換行符號和靜態函式。 空白字元相當有意義。

預設 不適用
外觀狀態 必填
類型 字串
有效值 任何字串對文字值有效。如果提供 ref 屬性， 且優先度高於文字值這項政策會評估 值或參照的變數做為訊息範本。

&lt;Output&gt;

<Output encoding='encoding_name'>variable_name</Output>

指定政策應使用計算出的 HMAC 值來設定變數名稱。 此外也會指定輸出要使用的編碼方式。

預設

預設輸出變數為 hmac.POLICYNAME.output。

encoding 屬性的預設值為 base64。
外觀狀態 選用設定。如果沒有這個元素，這項政策會設定流量變數 hmac.POLICYNAME.output (採用 Base64 編碼的值)。
類型 字串
有效值

在編碼方面，hex： base16，base64，base64url。

這些值不區分大小寫；hex 和 base16 是同義詞。

Output 元素的文字值 可以是任何有效的流程變數名稱。

&lt;SecretKey&gt;

<SecretKey encoding='encoding_name' ref='private.secretkey'/>

指定用來計算 HMAC 的密鑰。金鑰是從參照的 變數，根據特定編碼進行解碼。

預設

參照的變數沒有預設值； ref 為必要屬性，

如果缺少 encoding 屬性，系統會預設使用這項政策 以 UTF-8 解碼密鑰字串，以取得金鑰位元組。
外觀狀態 必填
類型 字串
有效值

encoding 的有效值為 hex、base16、base64、 utf8。預設值為 UTF8。這些值不區分大小寫，破折號則是 不具意義。Base16 與 base-16 相同，且 bAse16。Base16 和 Hex 是同義詞。

使用編碼屬性可指定鍵能 包含 UTF-8 可列印字元範圍外的位元組。 舉例來說，假設政策設定包含以下內容： 

 <SecretKey encoding='hex' ref='private.encodedsecretkey'/>

假設 private.encodedsecretkey 包含 536563726574313233 字串。

在本範例中，索引鍵位元組會解碼為：[53 65 63 72 65 74 31 32 33] (以十六進位表示的每個位元組)。再舉一個例子，如果 encoding='base64' private.encodedsecretkey 包含字串 U2VjcmV0MTIz， 這樣就會產生一組同樣的鍵位元組。沒有編碼屬性的話 或編碼屬性為 UTF8 的情況下，字串值 Secret123 會產生 也就是相同的位元組組合

&lt;VerificationValue&gt;

<VerificationValue encoding='encoding_name' ref='variable_name'/>
or
<VerificationValue encoding='encoding_name'>string_value</VerificationValue>

(選用) 指定驗證值，以及 用於將驗證值編碼政策會使用這個演算法將值解碼。

預設 沒有預設的驗證值。如果有元素，但 缺少 encoding 屬性，這項政策會使用 base64 的預設編碼
外觀狀態 選用
類型 字串
有效值

編碼屬性的有效值如下：hex、base16、 base64、base64url。設定值 不區分大小寫；hex 和 base16 是同義詞。

VerificationValue 的編碼不需要與編碼方式相同 用於 Output 元素

&lt;IgnoreUnresolvedVariables&gt;

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

如果您希望政策在指定的參照變數時擲回錯誤，請設為 false 無法解析政策設為 true，即可將任何無法解析的變數視為空白字串 (空值)。

IgnoreUnresolvedVariables 布林值只會影響 訊息範本雖然 SecretKey 和 VerificationValue 可以參照變數， 但不需要解析這些資源，因此 ignore 設定不適用於這些項目。

預設 否
外觀狀態 選用
類型 布林值
有效值 true 或 false

流程變數

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

變數 說明 範例
hmac.policy_name.message 政策會根據有效的訊息設定這個變數。 評估 Message 中指定的訊息範本後的結果 元素。 hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output 取得 Output 元素執行時，HMAC 運算作業 請務必指定變數名稱 hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4=
hmac.policy_name.outputencoding 取得輸出編碼的名稱。 hmac.HMAC-Policy.outputencoding = base64

錯誤參考資料

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

執行階段錯誤

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

錯誤代碼 HTTP 狀態 發生時機
steps.hmac.UnresolvedVariable 401

如果 HMAC 政策中指定的變數符合下列任一條件，就會發生這個錯誤：

  • 超出範圍 (不適用於執行政策的特定流程)

    或

  • 無法解析 (未定義)
steps.hmac.HmacVerificationFailed 401 HMAC 驗證失敗；提供的驗證值與計算值不符。
steps.hmac.HmacCalculationFailed 401 這項政策無法計算 HMAC。
steps.hmac.EmptySecretKey 401 密鑰變數的值為空白。
steps.hmac.EmptyVerificationValue 401 保留驗證值的變數空白。

部署錯誤

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

錯誤名稱 HTTP 狀態 發生時機
steps.hmac.MissingConfigurationElement 401 缺少必要元素或屬性時，就會發生這個錯誤。
steps.hmac.InvalidValueForElement 401 如果演算法元素中指定的值不是下列任一值，就會發生這個錯誤：SHA-1、SHA-224、SHA-256、SHA-512 或 MD-5。
steps.hmac.InvalidSecretInConfig 401 如果已明確為 SecretKey 提供文字值，就會發生這個錯誤。
steps.hmac.InvalidVariableName 401 如果 SecretKey 變數不含 private 前置字元 (private.)，就會發生這個錯誤。

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "UnresolvedVariable"
hmac.policy_name.failed The policy sets this variable in the case of a failure. hmac.HMAC-Policy.failed = true

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>