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