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.name="fault_name" fault_name 是錯誤的名稱，如 上方的「執行階段錯誤」表格。錯誤名稱是最後一個 部分錯誤 fault.name Matches "UnresolvedVariable"
hmac.policy_name.failed 這項政策會在發生錯誤時設定這個變數。 hmac.HMAC-Policy.failed = true

錯誤回應範例

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