מדיניות HMAC

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

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

למידע נוסף על HMAC, אפשר לקרוא את המאמר HMAC: Keyed-Hashing for Message Authentication (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>

ההגדרה קובעת את אלגוריתם הגיבוב לצורך חישוב ה-HMAC.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Message>

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

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

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

תבנית ההודעה יכולה לכלול חלקים קבועים ומשתנים, כולל שורות חדשות ופונקציות סטטיות. יש משמעות לרווח לבן.

<פלט>

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