במדריך הזה מוסבר איך ליצור טוקן, ומוצגים השדות הנדרשים והאופציונליים לטוקנים.
כדי ליצור טוקן, צריך ליצור מחרוזת לחתימה, שאנחנו קוראים לה במדריך הזה ערך חתום. הערך החתום כולל פרמטרים שמתארים את התוכן שאתם מגנים עליו, את זמן התפוגה של הערך החתום וכו'.
משתמשים בערך החתום כשיוצרים מחרוזת של טוקן. יוצרים מחרוזת של טוקן על ידי הרכבת הפרמטרים של הטוקן, כמו קוד אימות הודעות (HMAC) מבוסס-גיבוב (hash) של ערך חתום עם מפתח סימטרי.
Media CDN משתמש באסימון הסופי המורכב כדי להגן על התוכן שלכם.
יצירת טוקן
כדי ליצור ערך חתום, צריך לשרשר מחרוזת שמכילה את שדות הטוקן הנדרשים ואת שדות הטוקן האופציונליים הרצויים. מפרידים בין כל שדה וכל פרמטר באמצעות התו
~(טילדה).חתימה על הערך החתום באמצעות חתימת Ed25519 או מפתח סימטרי HMAC.
יוצרים את האסימון על ידי שרשור של מחרוזת שמכילה את שדות החובה של האסימון ואת השדות האופציונליים של האסימון. מפרידים בין כל שדה ובין כל פרמטר באמצעות התו 'טילדה' (
~).כשיוצרים את האסימון, הערכים של כל אחד מהפרמטרים זהים בין הערך החתום לבין מחרוזת האסימון, למעט המקרים הבאים:
FullPathHeaders
בדוגמת הקוד הבאה אפשר לראות איך ליצור טוקן באופן פרוגרמטי:
Python
כדי לבצע אימות ב-Media CDN, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.
Java
כדי לבצע אימות ב-Media CDN, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.
בקטעים הבאים מתוארים השדות שבהם נעשה שימוש באסימונים.
שדות חובה בטוקן
חובה למלא את השדות הבאים לכל אסימון:
Expires- אחד מהפרטים הבאים:
PathGlobsURLPrefixFullPath
- אחד מהפרטים הבאים:
Signaturehmac
אלא אם צוין אחרת, השמות של הפרמטרים והערכים שלהם הם תלויי אותיות רישיות.
בטבלה הבאה מוסבר על כל פרמטר:
| שם השדה / כינויים | פרמטרים של טוקנים | ערך חתום |
|---|---|---|
|
מספר שלם של שניות שחלפו מאז ראשית זמן יוניקס (Unix epoch) (1970-01-01T00:00:00Z) | Expires=EXPIRATION_TIME, ואחריו הטוקן כבר לא בתוקף. |
|
רשימה של עד חמישה פלחים בנתיב שאליהם רוצים להעניק גישה. אפשר להשתמש בפסיקים ( אסור להשתמש בפרמטרים של נתיבים, שמסומנים באמצעות נקודה ופסיק ( לכן, חשוב לוודא שכתובת ה-URL לא מכילה את התווים המיוחדים הבאים: |
PathGlobs=PATHS |
URLPrefix |
כתובת URL מקודדת ב-base64 שמתאימה לאינטרנט, כולל הפרוטוקול
לדוגמה, חלק מהערכים התקינים של URLPrefix עבור `https://example.com/foo/bar.ts` הם `https://example.com`, `https://example.com/foo` ו-`https://example.com/foo/bar`. |
URLPrefix=BASE_64_URL_PREFIX |
FullPath |
אין. כשמציינים FullPath בטוקן, לא משכפלים את הנתיב שציינתם בערך החתום. בטוקן, כוללים את שם השדה בלי =. |
FullPath=FULL_PATH_TO_OBJECT |
Signature |
גרסה של החתימה בקידוד Base64 שמתאים לשימוש באינטרנט. | לא רלוונטי |
hmac |
גרסה בקידוד Base64 שמותאמת לאינטרנט של ערך ה-HMAC. | לא רלוונטי |
PathGlobs תחביר של תו כללי
בטבלה הבאה מוסבר התחביר של PathGlobsתווים כלליים.
| אופרטור | התאמות | דוגמאות |
|---|---|---|
* (כוכבית) |
התאמה לאפס תווים או יותר בנתיב של כתובת ה-URL, כולל
תווים של לוכסן קדימה (/).
|
|
? (סימן שאלה) |
התאמה לתו יחיד בנתיב של כתובת ה-URL, לא כולל תווים של קו נטוי קדימה (/).
|
/videos/s?main.m3u8 matches
/videos/s1main.m3u8. הוא לא תואם ל-/videos/s01main.m3u8 או ל-/videos/s/main.m3u8.
|
כתובות Globs חייבות להתחיל בכוכבית (*) או בקו נטוי קדימה (/) עבור נתיבים של כתובות URL.
מכיוון ש-* ו-/* תואמים לכל נתיבי כתובות ה-URL, לא מומלץ להשתמש באף אחד מהם באסימונים החתומים. כדי להבטיח הגנה מקסימלית, חשוב לוודא שהתבניות תואמות לתוכן שאליו אתם רוצים להעניק גישה.
שדות אופציונליים של טוקן
אלא אם צוין אחרת, השמות של הפרמטרים והערכים שלהם הם תלויי אותיות רישיות.
בטבלה הבאה מוסבר על שמות הפרמטרים, הכינויים שלהם ופרטים על פרמטרים אופציונליים:
| שם השדה / כינויים | פרמטרים | ערך חתום |
|---|---|---|
|
מספר שלם של שניות מאז ראשית זמן יוניקס (1970-01-01T00:00:00Z) | Starts=START_TIME |
IPRanges |
רשימה של עד חמש כתובות IPv4 ו-IPv6 בפורמט CIDR, שכתובת ה-URL הזו תקפה לגביהן בפורמט base64 בטוח לשימוש באינטרנט. לדוגמה,
כדי לציין את טווחי כתובות ה-IP 192.6.13.13/32,193.5.64.135/32, מציינים את
הערך יכול להיות שטווח כתובות ה-IP לא יעזור לכם אם אתם רוצים לכלול אותו בטוקנים כשלקוחות נמצאים בסיכון למיגרציות WAN או במקרים שבהם נתיב הרשת לקצה הקדמי של האפליקציה שונה מנתיב המסירה.
Media CDN דוחה לקוחות עם קוד אלה מקרים שבהם יכול להיות ש-Media CDN ידחה לקוחות עם קוד
כל הגורמים האלה יכולים לגרום לכך שללקוח מסוים תהיה כתובת IP לא דטרמיניסטית במהלך הפעלת סרטון. אם כתובת ה-IP של הלקוח משתנה אחרי שניתנה גישה, והלקוח מנסה להוריד קטע וידאו למאגר הזמני להפעלה, הוא מקבל קוד שגיאה |
IPRanges=BASE_64_IP_RANGES |
|
מחרוזת שרירותית, שימושית לניתוח יומנים או למעקב אחר הפעלה. כדי להימנע מיצירת טוקן לא תקין, צריך להשתמש במחרוזות עם קידוד % או במחרוזות עם קידוד Base64 שמתאים לשימוש באינטרנט. אסור להשתמש בתווים הבאים בשם |
SessionID=SESSION_ID_VALUE |
|
מחרוזת שרירותית, שימושית לניתוח יומנים. כדי להימנע מיצירת טוקן לא תקין, צריך להשתמש במחרוזות עם קידוד % או במחרוזות עם קידוד Base64 שמתאים לשימוש באינטרנט. אסור להשתמש בתווים הבאים בשם |
data=DATA_VALUE |
Headers |
רשימה של שמות שדות בכותרת, שמופרדים בפסיקים. שמות הכותרות הם לא תלויי-רישיות בחיפושים בבקשה. שמות הכותרות בערכים החתומים הם תלויי אותיות רישיות. אם חסרה כותרת, הערך הוא מחרוזת ריקה. אם יש כמה עותקים של כותרת, הם מחוברים באמצעות פסיק. | Headers=HEADER_1_NAME=HEADER_1_EXPECTED_VALUE,
HEADER_2_NAME=HEADER_2_EXPECTED_VALUE |
דוגמאות
בקטעים הבאים מוצגות דוגמאות ליצירת אסימונים.
דוגמה לשימוש ב-FullPath
דוגמה לשימוש בשדה FullPath:
- הפריט המבוקש:
http://example.com/tv/my-show/s01/e01/playlist.m3u8 - מועד התפוגה: 160000000
הערך החתום הוא:
Expires=160000000~FullPath=/tv/my-show/s01/e01/playlist.m3u8
כדי ליצור אסימון, חותמים על הערך החתום באמצעות חתימת Ed25519 או HMAC עם מפתח סימטרי.
אלה דוגמאות לאסימונים שנוצרו מערך חתום:
חתימת Ed25519
Expires=160000000~FullPath~Signature=SIGNATURE_OF_SIGNED_VALUE
כאשר SIGNATURE_OF_SIGNED_VALUE היא חתימת ED25519 של הערך החתום שנוצר קודם.
מפתח סימטרי HMAC
Expires=160000000~FullPath~hmac=HMAC_OF_SIGNED_VALUE
כאשר HMAC_OF_SIGNED_VALUE הוא HMAC של מפתח סימטרי של הערך החתום שנוצר קודם.
בדוגמאות הקודמות, הערך FullPath מופיע בטוקן, אבל הערך לא חוזר על עצמו מהנתיב שצוין בערך החתום. כך אפשר לחתום על הנתיב המלא של הבקשה בלי לשכפל את הבקשה בטוקן.
דוגמה לשימוש ב-URLPrefix
דוגמה לשימוש בשדה URLPrefix:
- הפריט המבוקש:
http://example.com/tv/my-show/s01/e01/playlist.m3u8 - מועד התפוגה: 160000000
הערך החתום הוא:
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4
בדוגמה הקודמת, החלפנו את הנתיב לפריט המבוקש, http://example.com/tv/my-show/s01/e01/playlist.m3u8, בנתיב לפריט בפורמט Base64 שמותאם לאינטרנט, aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4.
כדי ליצור אסימון, חותמים על הערך החתום באמצעות חתימת Ed25519 או HMAC עם מפתח סימטרי.
אלה דוגמאות לאסימונים שנוצרו מערך חתום:
חתימת Ed25519
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4~Signature=SIGNATURE_OF_SIGNED_VALUE
כאשר SIGNATURE_OF_SIGNED_VALUE היא חתימת ED25519 של הערך החתום שנוצר קודם.
מפתח סימטרי HMAC
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4~hmac=HMAC_OF_SIGNED_VALUE
כאשר HMAC_OF_SIGNED_VALUE הוא HMAC של מפתח סימטרי של הערך החתום שנוצר קודם.
דוגמה לשימוש ב-Headers
דוגמה לשימוש בשדה Headers:
- הפריט המבוקש:
http://example.com/tv/my-show/s01/e01/playlist.m3u8 - מועד התפוגה: 160000000
- הערך של PathGlobs:
* - כותרות הבקשה הצפויות:
user-agent: browseraccept: text/html
הערך החתום הוא:
Expires=160000000~PathGlobs=*~Headers=user-agent=browser,accept=text/html
כדי ליצור אסימון, חותמים על הערך החתום באמצעות חתימת Ed25519 או HMAC עם מפתח סימטרי.
אלה דוגמאות לאסימונים שנוצרו מערך חתום:
חתימת Ed25519
Expires=160000000~PathGlobs=*~Headers=user-agent,accept~Signature=SIGNATURE_OF_SIGNED_VALUE
כאשר SIGNATURE_OF_SIGNED_VALUE היא חתימת ED25519 של הערך החתום שנוצר קודם.
מפתח סימטרי HMAC
Expires=160000000~PathGlobs=*~Headers=user-agent,accept~hmac=HMAC_OF_SIGNED_VALUE
כאשר HMAC_OF_SIGNED_VALUE הוא HMAC של מפתח סימטרי של הערך החתום שנוצר קודם.
בדוגמאות הקודמות, הערך Headers=user-agent,accept מופיע בטוקן,
אבל ערכי הכותרת הצפויים לא חוזרים על עצמם מהערך החתום. כך אפשר לחתום על צמדי מפתח/ערך ספציפיים בכותרת הבקשה בלי לשכפל את הערכים בטוקן.