מדיניות HMAC

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

מחשב ומאמת קוד אימות הודעות (HMAC) מבוסס גיבוב. לפעמים שנקרא 'קוד אימות הודעות עם מפְתח' (Keyed Message Authentication Code), או גיבוב (hash) עם קידוד, HMAC משתמש בגיבוב קריפטוגרפי פונקציה כמו SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 או MD-5, שהוחלו על 'הודעה', וגם מפתח סודי, כדי להפיק חתימה או קוד אימות הודעה בהודעה הזו. המונח 'הודעה' לדף הזה מתייחס לכל זרם של בייטים. מי ששולח הודעה יכול גם לשלוח HMAC למקלט, והמקבל יכול להשתמש ב-HMAC כדי לאמת את ההודעה.

למידע נוסף על HMAC: צפייה ב-HMAC: Keyed-Hashing עבור אימות הודעות (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>

מציינת את אלגוריתם הגיבוב (hash) שיחשב את ה-HMAC.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

שימוש בנוסף למאפיין השם כדי להוסיף תווית למדיניות בעורך ה-Proxy של ממשק המשתמש של Apigee בשם אחר בשפה טבעית.

<Message>

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

מציינת את המטען הייעודי (Payload) של ההודעה לחתימה. הקלט של הרכיב הזה תומך תבניות של הודעות (החלפת משתנה) כדי לאפשר הכללה של פריטים נוספים בזמן הריצה, כמו חותמות זמן, צפנים חד-פעמיים, רשימות של כותרות או מידע אחר. לדוגמה:

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