HMAC-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation
weitere Informationen

Berechnet einen Hash-basierten 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 einen Signatur- oder Nachrichtenauthentifizierungscode für diese Nachricht zu erstellen. Der Begriff "Nachricht" bezieht sich hier auf beliebige Streams von Bytes. Ein Absender einer Nachricht kann auch einen HMAC an einen Empfänger senden und dieser kann den HMAC zur Authentifizierung der Nachricht verwenden.

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

Samples

HMAC generieren

<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 überprüfen

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

Die Berechnung einer Signatur und die Überprüfung dieser Signatur folgen genau dem gleichen Vorgang. Die HMAC-Richtlinie berechnet einen HMAC und kann optional die berechnete Signatur mit einem erwarteten Wert abgleichen. Das optionale "VerificationValue"-Element (falls vorhanden) leitet die Richtlinie an, einen berechneten Wert mit einem bekannten oder angegebenen Wert zu vergleichen.


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.

Attribut Beschreibung Standardeinstellung Präsenz
name Der interne Name der Richtlinie. Folgende Zeichen sind im Namen zulässig: A-Z0-9._\-$ %. Die Apigee-Benutzeroberfläche erzwingt jedoch zusätzliche Einschränkungen, z. B. das automatische Entfernen nicht alphanumerischer Zeichen.

Optional können Sie das Element <displayname></displayname> verwenden, um die Richtlinie im Proxy-Editor der Apigee-Benutzeroberfläche mit einem anderen Namen in der natürlichen Sprache zu versehen.

Erforderlich
continueOnError Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten.

Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird.

false Optional
aktiviert Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu "deaktivieren". Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

true Optional
async Dieses Attribut wurde verworfen. false Eingestellte Funktionen

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

Gibt den Hash-Algorithmus zur Berechnung des HMAC an.

Standardeinstellung
Präsenz Erforderlich
Typ String
Zulässige Werte SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 und MD-5

Die Richtlinienkonfiguration akzeptiert Algorithmusnamen, ohne zwischen Groß- und Kleinschreibung zu unterscheiden, und mit oder ohne den Bindestrich zwischen Buchstaben und Zahlen. Beispiel: SHA256 und SHA-256 und sha256 sind äquivalent.

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

Standard Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs der Richtlinie verwendet.
Präsenz Optional
Typ String

<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. Leerzeichen sind sehr wichtig.

Standard
Präsenz Erforderlich
Typ String
Zulässige Werte Jeder String ist für den Textwert gültig. Wenn Sie ein ref-Attribut angeben, hat es Vorrang vor dem Textwert. Die Richtlinie wertet entweder den Textwert oder die referenzierte Variable als Nachrichtenvorlage aus.

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

Standard

Die Standardausgabevariable ist hmac.POLICYNAME.output.

Der Standardwert für das Attribut encoding ist base64.

Präsenz Optional. Wenn dieses Element nicht vorhanden ist, legt die Richtlinie die Ablaufvariable hmac.POLICYNAME.output mit einem base64-codierten Wert fest.
Typ String
Zulässige Werte

Zum Codieren von hex, base16, base64, base64url.

Bei den Werten wird die Groß-/Kleinschreibung nicht berücksichtigt; hex und base16 sind Synonyme.

Der Textwert des Output-Elements kann ein beliebiger gültiger Name der Ablaufvariablen sein.

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

Standard

Für die referenzierte Variable gibt es keinen Standardwert. Das Attribut ref ist erforderlich.

Wenn kein encoding-Attribut vorhanden ist, decodiert die Richtlinie den geheimen Schlüsselstring standardmäßig mit UTF-8, um die Schlüsselbyte zu erhalten.

Präsenz Erforderlich
Typ String
Zulässige Werte

Gültige Werte für encoding sind hex, base16, base64 und utf8. Der Standard ist UTF-8. Bei den Werten wird die Groß-/Kleinschreibung nicht berücksichtigt. Bindestriche sind nicht wichtig. Base16 ist mit base-16 und bAse16 identisch. Base16 und Hex sind Synonyme.

Mit einem Codierungsattribut können Sie einen Schlüssel angeben, der Byte außerhalb des Bereichs der für UTF-8 druckbaren Zeichen enthält. Angenommen, die Richtlinienkonfiguration enthält Folgendes:

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

Und angenommen, private.encodedsecretkey enthält den String 536563726574313233.

In diesem Fall werden die Schlüsselbyte folgendermaßen decodiert: [53 65 63 72 65 65 74 31 32 33] (jedes Byte wird als Hexadezimalwert dargestellt). Ein weiteres Beispiel: Wenn encoding='base64' und private.encodedsecretkey den String U2VjcmV0MTIz enthalten, wird der gleiche Bytesatz für den Schlüssel ausgegeben. Ohne Codierungsattribut oder mit einem Codierungsattribut UTF8 führt der Stringwert Secret123 zum selben Bytesatz.

<VerificationValue>

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

(Optional) Gibt den Verifizierungswert sowie den Codierungsalgorithmus an, der zum Codieren des Überprüfungswerts verwendet wurde. Die Richtlinie verwendet diesen Algorithmus, um den Wert zu decodieren.

Standard Es gibt keinen Standardwert für die Bestätigung. Wenn das Element vorhanden ist, das Attribut encoding jedoch fehlt, verwendet die Richtlinie die Standardcodierung base64.
Präsenz Optional
Typ String
Zulässige Werte

Gültige Werte für das Codierungsattribut sind hex, base16, base64, base64url. Bei den Werten wird die Groß-/Kleinschreibung nicht berücksichtigt; hex und base16 sind Synonyme.

Die Codierung von VerificationValue muss nicht der Codierung entsprechen, die für das Element Output verwendet wird.

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

Standard False
Präsenz Optional
Typ Boolesch
Zulässige Werte "true" oder "false"

Ablaufvariablen

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

Variable Beschreibung Beispiel
hmac.policy_name.message Die Richtlinie legt diese Variable mit der effektiven Nachricht fest, das Ergebnis der Auswertung der im Element Message angegebenen Nachrichtenvorlage. hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output Ruft das Ergebnis der HMAC-Berechnung ab, wenn das Output-Element keinen Variablennamen angibt. hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4=
hmac.policy_name.outputencoding Ruft den Namen der Ausgabecodierung ab. hmac.HMAC-Policy.outputencoding = base64

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.

Fehlercode HTTP-Status Tritt auf, wenn Folgendes eintritt
steps.hmac.UnresolvedVariable 401

Dieser Fehler tritt auf, wenn eine in der HMAC-Richtlinie angegebene Variable

  • Wert liegt außerhalb des Bereichs (nicht in dem spezifischen Ablauf verfügbar, in dem die Richtlinie ausgeführt wird)

    oder

  • kann nicht gelöst werden (ist nicht definiert)
steps.hmac.HmacVerificationFailed 401 Die HMAC-Verifizierung ist fehlgeschlagen. Der bereitgestellte Verifizierungswert stimmt nicht mit dem berechneten Wert überein.
steps.hmac.HmacCalculationFailed 401 Der HMAC-Wert konnte mit der Richtlinie nicht berechnet werden.
steps.hmac.EmptySecretKey 401 Der Wert der Variablen für den geheimen Schlüssel ist leer.
steps.hmac.EmptyVerificationValue 401 Die Variable mit dem Verifizierungswert ist leer.

Bereitstellungsfehler

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

Fehlername HTTP-Status Tritt auf, wenn Folgendes eintritt
steps.hmac.MissingConfigurationElement 401 Dieser Fehler tritt auf, wenn ein erforderliches Element oder Attribut fehlt.
steps.hmac.InvalidValueForElement 401 Dieser Fehler tritt auf, wenn der im Algorithmuselement angegebene Wert keiner der folgenden ist: SHA-1, SHA-224, SHA-256, SHA-512 oder MD-5.
steps.hmac.InvalidSecretInConfig 401 Dieser Fehler tritt auf, wenn für SecretKey explizit ein Textwert angegeben wurde.
steps.hmac.InvalidVariableName 401 Dieser Fehler tritt auf, wenn die Variable SecretKey nicht das Präfix private (private.) enthält.

Fehlervariablen

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

Variablen Wo Beispiel
fault.name="fault_name" fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "UnresolvedVariable"
hmac.policy_name.failed Bei einem Fehler legt die Richtlinie diese Variable fest. hmac.HMAC-Policy.failed = true

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>