HMAC-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Diese Richtlinie berechnet und verifiziert optional einen Hash-basierten Nachrichtenauthentifizierungscode (Hash-based Message Authentication Code, HMAC). HMAC wird manchmal auch als Keyed Message Authentication Code oder Keyed Hash bezeichnet und verwendet eine kryptografische Hash-Funktion wie SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 oder MD-5, die zusammen mit einem geheimen Schlüssel auf eine "Nachricht" angewendet wird, um eine Signatur oder Nachrichtenauthentifizierungscode für diese Nachricht zu erstellen. Der Begriff "Nachricht" bezieht sich hier auf beliebige Byte-Streams. Bei der typischen Verwendung von HMAC sendet der Absender einer Nachricht eine Nachricht und den zugehörigen HMAC an einen Empfänger. Der Empfänger kann den HMAC zusammen mit dem gemeinsamen geheimen Schlüssel zur Authentifizierung der Nachricht verwenden.

Diese Richtlinie ist eine Standardrichtlinie, die in jeder Umgebung bereitgestellt werden kann. Informationen zu Richtlinientypen und zur Verfügbarkeit bei jedem Umgebungstyp finden Sie unter Richtlinientypen.

Weitere Informationen zu HMAC finden Sie unter HMAC: Keyed-Hashing for Message Authentication (rfc2104).

Beispiele

<HMAC name='HMAC-1'>

  <Algorithm>SHA256</Algorithm>

  <!-- the default encoding of the SecretKey is UTF-8 -->
  <SecretKey encoding='base64' ref='private.secretkey'/>

  <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <!-- optional -->

  <!--
    The Message element accepts a template, which means the "message" the policy operates
    on can include fixed and multiple variable parts, including newlines and static functions.
    Whitespace, such as newlines and space characters, 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>

  <!-- the default encoding of the SecretKey is UTF-8 -->
  <SecretKey encoding='base16' ref='private.secretkey'/>

  <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <!-- optional -->

  <!--
     The Message element accepts a template. This policy verifies an HMAC on the request content.
   -->
  <Message>{request.content}</Message>

  <!--
    VerificationValue is optional.
    Include it to perform an HMAC check.
  -->
  <VerificationValue encoding='base16' ref='expected_hmac_value'/>

  <!-- default encoding of the output is base64 -->
  <Output encoding='base16'>name_of_variable</Output>

</HMAC>

Elementreferenz für HMAC

In der Richtlinienreferenz werden die Elemente und Attribute der HMAC-Richtlinie beschrieben.

Attribute, die auf das oberste Element angewendet werden

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

Die folgenden Attribute gelten für alle übergeordneten Richtlinienelemente.

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

Gibt den Hash-Algorithmus an, der bei der Berechnung des HMAC verwendet werden soll.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Wird zusätzlich zum Namensattribut verwendet, um die Richtlinie im Proxy-Editor der Apigee-Benutzeroberfläche mit einem anderen Namen in einer natürlichen Sprache zu versehen.

<Message>

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

Gibt die zu signierende Nachrichtennutzlast an. Die Eingabe dieses Elements unterstützt Nachrichtenvorlagen (Variablensubstitution), damit zusätzliche Elemente zur Laufzeit einbezogen werden können, z. B. Zeitstempel, Nonces, Listen von Headern oder andere Informationen. Beispiel:

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

Die Nachrichtenvorlage kann feste und variable Teile enthalten, einschließlich Zeilenumbrüchen und statischer Funktionen. Leerstellen wie Zeilenumbrüche und Leerzeichen sind wichtig.

<Output>

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

Gibt den Namen der Variable an, die die Richtlinie mit dem berechneten HMAC-Wert festlegen soll. Außerdem wird die für die Ausgabe zu verwendende Codierung angegeben.

<SecretKey>

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

Gibt den geheimen Schlüssel an, der zur Berechnung des HMAC verwendet wird. Der Schlüssel wird gemäß der spezifischen Codierung aus der referenzierten Variable abgerufen.

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

<VerificationValue>

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

(Optional) Gibt den Überprüfungswert sowie die Codierung an, die zum Codieren des Überprüfungswerts verwendet wurde. Die Richtlinie verwendet diese Codierung, um den Wert zu decodieren.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Setzen Sie diesen Wert auf false, wenn die Richtlinie einen Fehler ausgibt, falls eine in der Richtlinie angegebene Variable, auf die verwiesen wird, nicht auflösbar ist. Setzen Sie diesen Wert auf true, um alle nicht aufgelösten Variablen als leeren String zu behandeln (null).

Der boolesche Wert "IgnoreUnresolvedVariables betrifft nur Variablen, auf die in der Nachrichtenvorlage verwiesen wird. Obwohl SecretKey und VerificationValue auf eine Variable verweisen können, müssen beide aufgelöst werden können. Daher gilt die Einstellung ignore nicht für diese.

Ablaufvariablen

Die Richtlinie kann diese Variablen während der Ausführung festlegen.

Allgemeine Probleme

Auf einer Ebene scheint die HMAC-Richtlinie unkompliziert zu sein: Geben Sie einen Schlüssel und eine Nachricht an und Sie erhalten einen berechneten HMAC als Antwort. Es kann frustrierend sein, wenn Sie bei Verwendung der Richtlinie einen unerwarteten HMAC-Wert für eine bekannte Kombination aus Nachricht und Schlüssel erhalten. In diesem Abschnitt werden einige Nutzungshinweise zur Behebung solcher Probleme erläutert.

Es gibt zwei übliche Stolperfallen, die während der Prüfung zu nicht übereinstimmenden HMACs führen: Unterschiede bei Leerstellen in der Nachricht und Unterschiede bei Codierung und Decodierung. Letzteres gilt sowohl für das SecretKey-Element als auch für das Output-Element.

Unterschiede bei Leerzeichen

Unterschiede, die für Menschen bedeutungslos wirken, wirken sich auf den HMAC-Ausgabewert aus. Angenommen, ein geheimer Schlüssel kann als "Secret123“ dargestellt werden. Bei der UTF-8-Decodierung lauten die Schlüsselbyte: [53 65 63 72 65 74 31 32 33]. Die Verwendung dieses Schlüssels zur Berechnung eines HMAC-SHA256-Werts für die Nachricht abc führt zu a7938720fe5749d31076e6961360364c0cd271443f1b580779932c244293bc94. Wenn Sie der Nachricht ein einzelnes Leerzeichen (abc<SPACE>) hinzufügen, wobei <SPACE> ein ASCII 32 impliziert, führt dies zu einem HMAC-SHA256 von 274669b2a85d2532da48e2ce3d8e52ee17346d1bcd1a606d87db1934b5ab294b.

Ist die Nachricht abc<NEWLINE>, wobei <NEWLINE> auf ASCII 10 verweist, ist der HMAC ebenfalls 0780370844ca07f896066837e8230d3b6a775f678a4ae03e6b5e864c674831f5. Geringfügige Änderungen an der Nachricht führen zu sehr unterschiedlichen HMAC-Werten. Dies geschieht absichtlich. Dies ist ein beabsichtigtes und erwünschtes Verhalten von HMAC.

Fazit: Es muss unbedingt dafür gesorgt werden, dass der Nachrichtentext, der zur Berechnung des ursprünglichen HMAC verwendet wird, und der Nachrichtentext, der zur Überprüfung des HMAC verwendet wird, identisch sind. Wenn der Verifizierer eines HMAC die Nachrichtennutzlast in irgendeiner Weise ändert, beispielsweise durch Hinzufügen eines Leerzeichens oder Neuformatieren von Text, ändert sich der berechnete HMAC.

Seien Sie besonders vorsichtig, wenn Sie in der Richtlinienkonfiguration eine Nachrichtenvorlage verwenden. Dieses Richtlinienkonfigurationsfragment zeigt beispielsweise ein potenzielles Problem:

<HMAC name='HMAC-1'>
    ...
    <!-- the result of this message template will include surrounding whitespace -->
    <Message>
        {request.content}
    </Message>
    ...
       
</HMAC>

Bei einer Auswertung der Nachrichtenvorlage innerhalb des <Message>-Elements wird der Nachrichteninhalt in Zeilenumbrüche und Leerzeichen eingeschlossen. Dies ist wahrscheinlich nicht beabsichtigt. Eine bessere Konfiguration würde so aussehen:

<HMAC name='HMAC-1'>
    ...
    <Message>{request.content}</Message>
    ...
         
</HMAC>

Unterschiede bei der Codierung

Unterschiedliche Decodierungen desselben Schlüsselmaterials führen zu unterschiedlichen Schlüsseln. Angenommen, Sie haben einen geheimen Schlüssel, der als "U2VjcmV0S2V5MTIz" dargestellt werden kann. Bei der UTF-8-Decodierung lauten die Schlüsselbyte, wie in base16 dargestellt: [55 32 56 6a 63 6d 56 30 53 32 56 35 4d 54 49 7a]. Bei der Base64-Decodierung lauten die Schlüsselbyte [53 65 63 72 65 74 4b 65 79 31 32 33]. Wenn das Quellmaterial unterschiedlich decodiert wird, erhalten Sie verschiedene Schlüssel, was wiederum zu unterschiedlichen HMAC-Werten führt.

Hierbei gilt: Es muss unbedingt sichergestellt werden, dass das Schlüsselmaterial, das zur Berechnung des ursprünglichen HMAC verwendet wird, und der Schlüssel, der zum Prüfen des HMAC verwendet wird, genau identisch sind. Das bedeutet wahrscheinlich, dass an beiden Enden dieselbe Schlüsselcodierung verwendet wird. In der HMAC-Richtlinie können Sie das encoding-Attribut für das SecretKey-Element verwenden, um die Schlüsselcodierung anzugeben.

Berücksichtigen Sie auch Codierungen für die Ausgabe. Ein HMAC-SHA256-Ausdruck in der base16- oder Hex-Codierung in Form von 27f17e11c8ece93844c5eb5e55161d993368628a214f9a51c25d0185e8ea06e2 ist mit einem HMAC-SHA256 identisch, in base64-Codierung als J/F+Ecjs6ThExeteVRYdmTNoYoohT5pRwl0BhejqBuI= ausgedrückt. Sie sehen unterschiedlich aus, aber diese beiden Strings stellen denselben Wert dar. Achten Sie darauf, dass dieselbe Codierung verwendet wird, um den ursprünglich berechneten HMAC sowie den Verifizierungs-HMAC zu codieren. In der HMAC-Richtlinie können Sie das Attribut encoding für das Output-Element verwenden, um die gewünschte Ausgabecodierung und das gleiche Attribut für das VerificationValue-Element anzugeben, um anzugeben, wie der Verifizierer decodiert werden soll.

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Beispiel für eine Fehlerantwort

Bei der Fehlerbehandlung besteht die Best Practice darin, den errorcode-Teil der Fehlerantwort zu beachten. Verlassen Sie sich nicht auf den Text in faultstring. Er kann sich ändern.

Beispiel für eine Fehlerregel

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