HMAC 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

计算并验证基于哈希的消息身份验证代码 (HMAC)。HMAC 有时称为“密钥消息身份验证代码”或“密钥哈希”，它使用诸如 SHA-1、SHA-224、SHA-256、SHA-384、SHA-512 或 MD-5之类的加密哈希函数，与密钥一起应用于“消息”，以在该消息上生成签名或消息身份验证代码。此处的“消息”一词指任何字节流。消息的发送者也可以向接收者发送 HMAC，而接收者可以使用 HMAC 对该消息进行身份验证。

如需详细了解 HMAC，请参阅 HMAC：用于消息身份验证的键控哈希技术 (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 界面代理编辑器中给政策添加不同的自然语言名称标签。

<Message>

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

此元素指定要签名的消息载荷。此元素的输入支持消息模板（变量替换），允许在运行时添加其他项，例如时间戳、Nonce、标头列表或其他信息。例如：

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

消息模板可以包含固定和可变部分，包括换行符和静态函数。空格很重要。

<Output>

<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 可将任何无法解析的变量视为空字符串 (null)。

IgnoreUnresolvedVariables 布尔值仅会影响消息模板引用的变量。虽然 SecretKey 和 VerificationValue 可以引用变量，但这两者都需要可解析，因此 ignore 设置不适用于这些元素。

流变量

该政策可以在执行期间设置这些变量。

Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

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

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>