Zasada HMAC

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Oblicza i weryfikuje kod HMAC (Hash-based Message Authentication Code). System HMAC, czasem nazywany kluczem uwierzytelniania wiadomości lub haszem, wykorzystuje kryptograficzną funkcję skrótu, taką jak SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 lub MD-5, stosowanej do wiadomości wraz z tajnym kluczem, by utworzyć podpis lub kod uwierzytelniania wiadomości. Termin „wiadomość” odnosi się do dowolnego strumienia bajtów. Nadawca wiadomości może też wysłać kod HMAC do odbiorcy, a odbiorca może użyć HMAC do uwierzytelnienia wiadomości.

Więcej informacji o HMAC znajdziesz w dokumencie HMAC: Keyed-Hashing for Message Authentication (rfc2104).

Sample

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

Odniesienie do elementu na potrzeby HMAC

Dokumentacja zasad zawiera opis elementów i atrybutów zasad HMAC.

Atrybuty stosowane do elementu najwyższego poziomu

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

Poniższe atrybuty są wspólne dla wszystkich elementów nadrzędnych zasad.

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

Określa algorytm szyfrowania do obliczania HMAC.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Użyj oprócz atrybutu name, aby oznaczyć zasadę w edytorze serwera proxy interfejsu Apigee inną nazwą w języku naturalnym.

<Message>

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

Określa ładunek wiadomości do podpisania. Dane wejściowe tego elementu obsługują szablony wiadomości (zastępowanie zmiennych), aby umożliwić uwzględnianie w czasie działania dodatkowych elementów, takich jak sygnatury czasowe, liczby jednorazowe, listy nagłówków i inne informacje. Na przykład:

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

Szablon wiadomości może zawierać stałe i zmienne części, w tym znaki nowego wiersza i funkcje statyczne. Odstępy są istotne.

<Dane wyjściowe>

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

Określa nazwę zmiennej, którą zasada powinna ustawić za pomocą obliczonej wartości HMAC. Określa też kodowanie danych wyjściowych.

<SecretKey>

<SecretKey encoding='encoding_name' ref='private.secretkey'/>

Określa tajny klucz używany do obliczania HMAC. Klucz jest odczytywany z wskazanej zmiennej i dekodowany zgodnie z określonym kodowaniem.

 <SecretKey encoding='hex' ref='private.encodedsecretkey'/>

<VerificationValue>

<VerificationValue encoding='encoding_name' ref='variable_name'/>
or
<VerificationValue encoding='encoding_name'>string_value</VerificationValue>

(Opcjonalnie) Określa wartość weryfikacji, a także algorytm kodowania, który został użyty do zakodowania wartości weryfikacyjnej. Zasada będzie używać tego algorytmu do dekodowania wartości.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Ustaw jako false, jeśli chcesz, aby zasada zgłaszała błąd, gdy jakakolwiek przywołana zmienna określona w zasadzie jest nierozwiązana. Ustaw jako true, aby traktować każdą nierozwiązaną zmienną jako pusty ciąg znaków (wartość null).

Wartość logiczna ignoreUnresolvedVariables ma wpływ tylko na zmienne, do których odwołuje się szablon wiadomości. Zmienne SecretKey i VerificationValue mogą odwoływać się do zmiennej, ale oba te elementy muszą być możliwe do rozpoznania, więc ustawienie ignore ich nie dotyczy.

Zmienne przepływu

Zasada może ustawiać te zmienne podczas wykonywania.

Informacje o błędach

W tej sekcji opisujemy kody błędów i komunikaty o błędach, które są zwracane, a także zmienne błędów ustawiane przez Apigee, gdy ta zasada wywołuje błąd. Te informacje są ważne, jeśli opracowujesz reguły dotyczące błędów do obsługi takich błędów. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego te zasady.

Zmienne błędów

Te zmienne są ustawiane, gdy wystąpi błąd środowiska wykonawczego. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami.

Przykładowa odpowiedź na błąd

W przypadku obsługi błędów najlepiej jest zablokować część errorcode odpowiedzi błędu. Nie polegaj na tekście w polu faultstring, ponieważ może się on zmienić.

Przykładowa reguła błędu

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