Правила HMAC

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Вычисляет и проверяет код аутентификации сообщений на основе хеш-функции (HMAC). Иногда его называют кодом аутентификации сообщений с ключом или хешем с ключом. В HMAC используется криптографическая хеш-функция, например SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 или MD-5, которая применяется к сообщению вместе с секретным ключом, чтобы создать подпись или код аутентификации сообщения. Термин "сообщение" здесь относится к любому потоку байтов. Отправитель сообщения также может отправить получателю HMAC, чтобы тот мог аутентифицировать сообщение.

Подробнее об HMAC можно узнать из RFC 2104.

Примеры

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

Используйте этот атрибут вместе с атрибутом name, чтобы задать для правила в редакторе прокси-серверов Apigee UI другое, более понятное название.

<Message>

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

Указывает полезную нагрузку сообщения для подписи. Входные данные этого элемента поддерживают шаблоны сообщений (замену переменных), что позволяет добавлять во время выполнения дополнительные элементы, такие как временные метки, одноразовые коды, списки заголовков и другую информацию. Пример:

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