מדיניות 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 לא חלה עליהם.

משתני זרימה

המדיניות יכולה להגדיר את המשתנים האלה במהלך הביצוע.

הפניה לשגיאות

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

שגיאות בזמן ריצה

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.

משתני כשל

המשתנים האלה מוגדרים כשמתרחשת שגיאה בסביבת זמן הריצה. לקבלת מידע נוסף, קראו את המאמר מה צריך לדעת? על שגיאות שקשורות למדיניות.

דוגמה לתגובת שגיאה

לטיפול בשגיאות, השיטה המומלצת היא להעתיק את החלק errorcode של השגיאה תשובה. אין להסתמך על הטקסט שבfaultstring, כי הוא עשוי להשתנות.

דוגמה לכלל שגוי

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