כרגע מוצג התיעוד של 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
<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
<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, ויש אפשרות לאמת את החתימה המחושבת לפי ערך צפוי. הרכיב האופציונלי verificationValue (אם קיים) מפנה את המדיניות לבדיקה של הערך המחושב מול ערך ידוע או נתון.
הפניה לרכיב עבור HMAC
בהפניה למדיניות מתוארים הרכיבים והתכונות של מדיניות HMAC.
מאפיינים שחלים על הרכיב ברמה העליונה
<HMAC name="HMAC" continueOnError="false" enabled="true" async="false">
המאפיינים הבאים משותפים לכל רכיבי ההורה של המדיניות.
מאפיין | תיאור | ברירת מחדל | נוכחות |
---|---|---|---|
name |
השם הפנימי של המדיניות. התווים שאפשר להשתמש בהם בשם מוגבלים ל:
A-Z0-9._\-$ % . עם זאת, ממשק המשתמש של Apigee אוכף הגבלות נוספות, כמו הסרה אוטומטית של תווים שאינם אלפאנומריים.
אפשר להשתמש באלמנט |
לא רלוונטי | נדרש |
continueOnError |
צריך להגדיר את הערך false כדי להחזיר שגיאה במקרה של כישלון במדיניות. זו התנהגות צפויה
ברוב כללי המדיניות.
צריך להגדיר את הערך |
false | אופציונלי |
פעיל |
צריך להגדיר את הערך true כדי לאכוף את המדיניות.
צריך להגדיר את הערך |
true | אופציונלי |
async | המאפיין הזה הוצא משימוש. | false | הוצא משימוש |
<Algorithm>
<Algorithm>algorithm-name</Algorithm>
ההגדרה קובעת את אלגוריתם הגיבוב לצורך חישוב ה-HMAC.
ברירת מחדל | לא רלוונטי |
נוכחות | נדרש |
סוג | מחרוזת |
ערכים חוקיים | SHA-1 , SHA-224 , SHA-256 , SHA-384 ,
SHA-512 וגם MD-5
בהגדרות המדיניות נעשה שימוש בשמות אלגוריתמים ללא הבחנה בין אותיות רישיות לקטנות, עם או בלי המקף בין האותיות למספרים . לדוגמה, |
<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>
תבנית ההודעה יכולה לכלול חלקים קבועים ומשתנים, כולל שורות חדשות ופונקציות סטטיות. יש משמעות לרווח לבן.
ברירת מחדל | לא רלוונטי |
נוכחות | נדרש |
סוג | מחרוזת |
ערכים חוקיים | כל מחרוזת תקפה לערך הטקסט. אם מספקים את המאפיין ref ,
הוא מקבל עדיפות על ערך הטקסט. המדיניות מבצעת הערכה של ערך
הטקסט או של המשתנה שאליו מתבצעת ההפניה כתבנית הודעה. |
<פלט>
<Output encoding='encoding_name'>variable_name</Output>
מציינת את שם המשתנה שהמדיניות צריכה להגדיר עם ערך ה-HMAC המחושב. מציין גם את הקידוד שבו יש להשתמש עבור הפלט.
ברירת מחדל |
משתנה הפלט שמוגדר כברירת מחדל הוא ערך ברירת המחדל של המאפיין |
נוכחות | אפשרות. אם הרכיב הזה לא קיים, המדיניות מגדירה את משתנה הזרימה
hmac.POLICYNAME.output עם ערך בקידוד base64. |
סוג | מחרוזת |
ערכים חוקיים | לקידוד, הערכים לא תלויי-רישיות. ערך הטקסט של הרכיב |
<SecretKey>
<SecretKey encoding='encoding_name' ref='private.secretkey'/>
מציינת את המפתח הסודי שמשמש לחישוב ה-HMAC. המפתח מתקבל מהמשתנה שאליו יש הפניה, ומפוענח בהתאם לקידוד הספציפי.
ברירת מחדל |
אין ערך ברירת מחדל למשתנה שאליו יש הפניה;
חובה להשתמש במאפיין אם המאפיין |
נוכחות | נדרש |
סוג | מחרוזת |
ערכים חוקיים | עבור שימוש במאפיין הקידוד מאפשר לציין מפתח שכולל בייטים מחוץ לטווח התווים שניתנים להדפסה בקידוד UTF-8. לדוגמה, נניח שתצורת המדיניות כוללת את הפרטים הבאים: <SecretKey encoding='hex' ref='private.encodedsecretkey'/>
ונניח שהערך של
במקרה כזה, הבייטים של המפתח יפענחו באופן הבא: [53 65 63 72 65 74 31 32 33]
(כל בייט מיוצג בהקסדצימלי). דוגמה נוספת: אם התגים |
<VerificationValue>
<VerificationValue encoding='encoding_name' ref='variable_name'/> or <VerificationValue encoding='encoding_name'>string_value</VerificationValue>
(אופציונלי) קובעת את ערך האימות וגם את אלגוריתם הקידוד ששימש לקידוד של ערך האימות. המדיניות תשתמש באלגוריתם הזה כדי לפענח את הערך.
ברירת מחדל | אין ערך ברירת מחדל לאימות. אם הרכיב קיים אבל
המאפיין encoding חסר, המדיניות משתמשת בקידוד ברירת המחדל של base64 |
נוכחות | אופציונלי |
סוג | מחרוזת |
ערכים חוקיים |
הערכים החוקיים במאפיין הקידוד הם: הקידוד של |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
צריך להגדיר את הערך false
אם רוצים שהמדיניות תגרום לשגיאה כאשר אי אפשר לפענח משתנה שצוין
במדיניות. צריך להגדיר את הערך true
כדי להתייחס לכל משתנה שלא ניתן לפתרון כמחרוזת ריקה (null).
הערך הבוליאני IgnoreUnresolvedVariables משפיע רק על משתנים שתבנית ההודעה
מפנה אליהם. הערכים SecretKey
ו-VerificationValue
יכולים להפנות למשתנה, אבל
צריך ליצור פתרון לשניהם, ולכן ההגדרה ignore
לא חלה עליהם.
ברירת מחדל | לא נכון |
נוכחות | אופציונלי |
סוג | בוליאני |
ערכים חוקיים | נכון או לא נכון |
משתני זרימה
המדיניות יכולה להגדיר את המשתנים האלה במהלך הביצוע.
משתנה | התיאור | דוגמה |
---|---|---|
hmac.policy_name.message |
המדיניות מגדירה את המשתנה הזה עם ההודעה בפועל, שהיא התוצאה של הערכה של תבנית ההודעה שצוינה ברכיב Message . |
hmac.HMAC-Policy.message = "Hello, World" |
hmac.policy_name.output |
הפונקציה מקבלת את התוצאה של
חישוב ה-HMAC, כשהרכיב Output
לא מציין שם משתנה. |
hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4= |
hmac.policy_name.outputencoding |
מקבל את השם של קידוד הפלט. | hmac.HMAC-Policy.outputencoding = base64 |
הפניה לשגיאות
בקטע הזה מתוארים קודי השגיאות והודעות השגיאה שמוחזרים, ומשתני השגיאה שמוגדרים על ידי Apigee כשהמדיניות הזו גורמת לשגיאה. חשוב לדעת אם אתם מפתחים כללים לתיקון תקלות. מידע נוסף זמין במאמר מה צריך לדעת על שגיאות מדיניות ועל טיפול בפגמים.
שגיאות בזמן ריצה
השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.
קוד שגיאה | סטטוס HTTP | מופיע כאשר |
---|---|---|
steps.hmac.UnresolvedVariable |
401 | השגיאה הזו מתרחשת אם משתנה שצוין במדיניות HMAC הוא:
|
steps.hmac.HmacVerificationFailed |
401 | אימות ה-HMAC נכשל. ערך האימות שצוין לא תואם לערך המחושב. |
steps.hmac.HmacCalculationFailed |
401 | לא ניתן היה לחשב את קוד ה-HMAC במדיניות. |
steps.hmac.EmptySecretKey |
401 | הערך של משתנה המפתח הסודי ריק. |
steps.hmac.EmptyVerificationValue |
401 | המשתנה שמכיל את ערך האימות ריק. |
שגיאות בפריסה
השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.
שם השגיאה | סטטוס HTTP | מופיע כאשר |
---|---|---|
steps.hmac.MissingConfigurationElement |
401 | השגיאה הזו מתרחשת כשחסרים רכיב או מאפיין נדרשים. |
steps.hmac.InvalidValueForElement |
401 | השגיאה הזו מופיעה אם הערך שצוין ברכיב האלגוריתם אינו אחד מהערכים הבאים: SHA-1 , SHA-224 , SHA-256 , SHA-512 או MD-5 . |
steps.hmac.InvalidSecretInConfig |
401 | השגיאה הזו מתרחשת אם צוין ערך טקסט באופן מפורש בשדה SecretKey . |
steps.hmac.InvalidVariableName |
401 | השגיאה הזו מתקבלת אם המשתנה SecretKey לא מכיל את
הקידומת private (private. ). |
משתני שבר
המשתנים האלה מוגדרים כשמתרחשת שגיאה בזמן הריצה. אפשר לקרוא מידע נוסף במאמר מה צריך לדעת על שגיאות מדיניות.
משתנים | מיקום | דוגמה |
---|---|---|
fault.name="fault_name" |
fault_name הוא שם התקלה, כפי שמפורט בטבלה שגיאות זמן ריצה שלמעלה. שם הכשל הוא החלק האחרון של קוד השגיאה. | fault.name Matches "UnresolvedVariable" |
hmac.policy_name.failed |
המדיניות מגדירה את המשתנה הזה במקרה של כשל. | hmac.HMAC-Policy.failed = true |
דוגמה לשגיאה
לטיפול בשגיאות, השיטה המומלצת היא להעתיק את החלק 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>