HMAC 政策

您正在查看的是 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 设置不适用于这些元素。

流变量

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

错误参考信息

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

故障变量

发生运行时错误时，系统会设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

错误响应示例

处理错误时，最佳做法是捕获错误响应的 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>