HMAC 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

計算及驗證雜湊式訊息驗證碼 (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

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

簽章的計算和驗證程序完全相同。HMAC 政策會計算 HMAC，並可選擇性地根據預期值驗證計算出的簽章。選用的 VerificationValue 元素 (如有) 會指示政策根據已知或指定的值檢查計算值。

HMAC 的元素參照

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

適用於頂層元素的屬性

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

所有政策父項元素都有下列屬性。

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

視需要使用 <displayname></displayname> 元素，在 Apigee UI 代理程式編輯器中，以其他自然語言名稱標示政策。

 N/A 必填
continueOnError 設為 false，在政策失敗時傳回錯誤。這是大多數政策的預期行為。

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

 false 選用
已啟用 設為 true 即可強制執行政策。

設為 false 即可「關閉」這項政策。即使政策仍附加至流程，系統也不會強制執行。

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

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

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

預設 N/A
外觀狀態 必填
類型 字串
有效值 SHA-1、SHA-224、SHA-256、SHA-384、SHA-512和 MD-5

政策設定接受演算法名稱，不區分大小寫，且字母和數字之間可有連字號，也可沒有。舉例來說，SHA256、SHA-256 和 sha256 相當於同一種語言。

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

除了名稱屬性外，您還可以使用這個屬性，在 Apigee UI 代理程式編輯器中，以其他自然語言名稱標示政策。

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

<Message>

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

指定要簽署的訊息酬載。這個元素的輸入內容支援 訊息範本 (變數替換)，可在執行階段加入其他項目，例如時間戳記、隨機數、標頭清單或其他資訊。例如：

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

訊息範本可包含固定和可變動的部分，包括換行符號和靜態函式。 空白字元很重要。

預設 N/A
外觀狀態 必填
類型 字串
有效值 文字值可使用任意字串。如提供 ref 屬性，系統會優先採用該屬性，而非文字值。政策會將文字值或參照變數評估為訊息範本。

<Output>

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

指定政策應使用計算出的 HMAC 值設定的變數名稱。 並指定輸出內容要使用的編碼。

預設

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

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

如要編碼，請使用 hex、base16、base64、base64url。

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

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

<SecretKey>

<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 會產生相同的位元組集。

<VerificationValue>

<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 元素使用的編碼相同。

<IgnoreUnresolvedVariables>

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