כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
במסמך הזה מוסבר איך ליצור, לשנות ולמחוק מאגרי מפתחות ו-Truststores ב-Edge בגרסה 4.17.09 ומטה.
מידע על מאגרי מפתחות ו-Truststores
מאגרי מפתחות ומאגרים מגדירים מאגרים של אישורי אבטחה שמשמשים להצפנת TLS. ההבדל העיקרי בין השניים הוא איפה נעשה בהם שימוש בתהליך לחיצת היד של TLS:
- מאגר מפתחות מכיל אישור TLS ומפתח פרטי שמשמשים לזיהוי הישות במהלך לחיצת היד בפרוטוקול TLS.
ב-TLS חד-כיווני, כשלקוח מתחבר לנקודת הקצה של TLS בשרת, מאגר המפתחות של השרת מציג ללקוח את האישור של השרת. לאחר מכן הלקוח מאמת את האישור באמצעות רשות אישורים (CA), כמו Symantec או VeriSign.
ב-TLS דו-כיווני, גם הלקוח וגם השרת מחזיקים מאגר מפתחות עם האישור והמפתח הפרטי שלהם שמשמשים לאימות הדדי. - truststore מכילה אישורים שמשמשים לאימות האישורים שהתקבלו כחלק מלחיצת היד של TLS.
ב-TLS חד-כיווני, אין צורך ב-Truststore אם האישור חתום על ידי CA חוקי. אם האישור שמתקבל בלקוח TLS חתום על ידי CA חוקי, הלקוח מגיש בקשה לרשות האישורים כדי לאמת את האישור. בדרך כלל, לקוח TLS משתמש ב-Truststore כדי לאמת אישורים בחתימה עצמית שהתקבלו משרת ה-TLS, או אישורים שאינם חתומים על ידי רשות אישורים מהימנה. בתרחיש הזה, הלקוח יאכלס את מאגר האישורים שלו באישורים שהוא נותן בהם אמון. לאחר מכן, כשהלקוח יקבל אישור שרת, האישור הנכנס יאומת מול האישורים ב-Truststore שלו.
לדוגמה, לקוח TLS מתחבר לשרת TLS שבו השרת משתמש באישור בחתימה עצמית. זהו אישור בחתימה עצמית, ולכן הלקוח לא יכול לאמת אותו באמצעות CA. במקום זאת, הלקוח טוען מראש את האישור בחתימה עצמית של השרת ל-Truststore שלו. לאחר מכן, כשהלקוח ינסה להתחבר לשרת, הוא ישתמש ב-Truststore שלו כדי לאמת את האישור שהתקבל מהשרת.
ל-TLS דו-כיווני, גם לקוח ה-TLS וגם שרת ה-TLS יכולים להשתמש ב-Truststore. נדרש Truststore במהלך ביצוע TLS דו-כיווני כאשר Edge משמש כשרת TLS.
האישורים יכולים להונפק על ידי רשות אישורים (CA), או שהם יכולים להיות בחתימה עצמית באמצעות המפתח הפרטי שיוצרים. אם יש לך גישה ל-CA, צריך לפעול לפי ההוראות של רשות האישורים כדי ליצור מפתחות ולנפיק אישורים. אם אין לך גישה ל-CA, תוכל ליצור אישור בחתימה עצמית באמצעות אחד מהכלים הרבים שזמינים בחינם לציבור הרחב, כמו opensl.
הטמעה של מאגר מפתחות ו-Truststore ב-Edge
ב-Edge, מאגר מפתחות מכיל קובץ JAR אחד או יותר, שבו קובץ ה-JAR מכיל:
- אישור TLS כקובץ PEM – אישור שחתום על ידי רשות אישורים (CA), שרשרת אישורים שבה האישור האחרון חתום על ידי CA, או אישור בחתימה עצמית.
- מפתח פרטי כקובץ PEM. Edge תומך בגודלי מפתחות עד 2,048 ביט. ביטוי הסיסמה הוא אופציונלי.
מאגר אישורים דומה למאגר מפתחות, אבל הוא מכיל רק אישורים כקובץ PEM, אבל לא מפתחות פרטיים.
אם האישור הוא חלק מרשת, מאגר המפתחות או ה-Truststore צריך להכיל את כל האישורים ברשת, כקובצי PEM בודדים או כקובץ יחיד. אם משתמשים בקובץ יחיד, האישורים חייבים להופיע בסדר שבו האישור הראשון בקובץ הוא האישור שמשמש ל-TLS (אבטחת שכבת התעבורה) ואחריו שרשרת האישורים לאישור ה-CA. יש להוסיף שורה ריקה בין כל אישור בקובץ.
Edge מספק API שמשמש ליצירת מאגרי מפתחות ו-Truststores. ממשקי ה-API בפועל זהים. ההבדל הוא שכאשר יוצרים מאגר מפתחות, מעבירים קובץ JAR שמכיל את האישור ואת המפתח הפרטי. כשיוצרים Truststore, צריך להעביר רק את האישור כקובץ PEM.
מידע על הפורמט של קובצי האישור וקובצי המפתח
בדוגמאות במסמך הזה מופיעים אישור ה-TLS (אבטחת שכבת התעבורה) ומפתח שמוגדרים כקובצי PEM, שתואמים לפורמט X.509. אם האישור או המפתח הפרטי שלך לא מוגדרים על ידי קובץ PEM, אפשר להמיר אותו לקובץ PEM באמצעות כלים כמו opensl.
עם זאת, רבים מקובצי ה- .crt וקובצי ה- .key כבר קיימים בפורמט PEM. אם הקבצים האלה הם קובצי טקסט, והם מוקפים ב:
-----BEGIN CERTIFICATE----- -----END CERTIFICATE-----
או:
-----BEGIN ENCRYPTED PRIVATE KEY----- -----END ENCRYPTED PRIVATE KEY-----
הקבצים תואמים לפורמט PEM, וניתן להשתמש בהם ב-Keystore או ב-Truststore בלי להמיר אותם לקובץ PEM.
אם יש לך רשת אישורים וברצונך להשתמש בה ב-Keystore או ב-Truststore, אפשר לשלב את כל האישורים לקובץ PEM אחד עם שורה חדשה בין כל אישור. האישורים צריכים להיות בסדר, והאישור האחרון חייב להיות אישור בסיס או אישור ביניים חתום על ידי אישור בסיס:
-----BEGIN CERTIFICATE----- (Your Primary TLS certificate) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (Intermediate certificate) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (Root certificate or intermediate certificate signed by a root certificate) -----END CERTIFICATE-----
איך מקבלים פרטים על מאגר מפתחות קיים
כדי לבדוק אם יש מאגרי מפתחות קיימים בסביבה, משתמשים ב-List Keystores וב-Truststores API:
curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
ללקוחות Cloud, יש מאגר מפתחות שמוגדר כברירת מחדל לארגונים שמשתמשים בתקופת ניסיון בחינם, גם בסביבת הבדיקה וגם בסביבת הייצור. אתם אמורים לראות את התוצאות הבאות עבור הקריאה הזו בשתי הסביבות:
[ "freetrial" ]
אפשר להשתמש במאגר המפתחות שמוגדר כברירת מחדל כדי לבדוק את ממשקי ה-API ולדחוף את ממשקי ה-API לייצור, אבל בדרך כלל יוצרים מאגר מפתחות משלכם, עם אישור ומפתח, לפני הפריסה בסביבת ייצור.
ללקוחות של Private Cloud, המערך שיוחזר יהיה ריק עד ליצירה של מאגר המפתחות הראשון.
בדיקת התוכן של מאגר המפתחות באמצעות API Get a Keystore או Truststore. עבור לקוחות בענן, אמור להופיע אישור TLS של שרת יחיד – אישור ברירת המחדל ש-Apigee Edge מספק לחשבונות של תקופת ניסיון בחינם.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password
התגובה אמורה להופיע כך:
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
אפשר לראות את המידע הזה גם בממשק המשתמש לניהול Edge:
- מתחברים לממשק המשתמש לניהול Edge בכתובת https://enterprise.apigee.com (ענן) או ב-
http://<ms-ip>:9000(מקומי), כאשר<ms-ip>היא כתובת ה-IP של הצומת של שרת הניהול. - בתפריט של ממשק המשתמש לניהול Edge, בוחרים באפשרות Admin > TLS Certificates (מנהל מערכת > אישורי TLS).
קבלת פרטים על אישור TLS
באמצעות ה-API של קבלת פרטי אישור מ-Keystore או Truststore אפשר להציג פרטים על אישורי TLS ב-Keystore, כמו תאריך תפוגה ומנפיק. תחילה, יש להשיג את שם האישור הרצוי. בדוגמה הזו מתקבל מידע ל-Keystore בשם "freetrial".
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password
דוגמה לתשובה:
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
לאחר מכן, משתמשים בערך של המאפיין certs כדי לקבל את פרטי האישור:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \
-u email:password
דוגמה לתשובה:
{
"certInfo" : [ {
"expiryDate" : "Wed, 23 Apr 2014 20:50:02 UTC",
"isValid" : "Yes",
"issuer" : "CN=Go Daddy Secure Certificate Authority - G2, OU=http://certs.godaddy.com/repository/, O="GoDaddy.com, Inc.", L=Scottsdale, ST=Arizona, C=US",
"subject" : CN=*.example.apigee.net, OU=Domain Control Validated",
"subjectAlternativeNames" : ["*.example.apigee.net","*.example.apigee.net" ],
"validFrom" : "Tue, 15 Apr 2014 09:17:03 UTC",
"version" : 3
} ],
"name" : "example.apigee.net.crt"
}
אפשר לראות את המידע הזה גם בממשק המשתמש לניהול Edge:
- מתחברים לממשק המשתמש לניהול Edge בכתובת https://enterprise.apigee.com (ענן) או ב-
http://<ms-ip>:9000(מקומי), כאשר<ms-ip>היא כתובת ה-IP של הצומת של שרת הניהול. - בתפריט של ממשק המשתמש לניהול Edge, בוחרים באפשרות Admin > TLS Certificates (מנהל מערכת > אישורי TLS).
בממשק המשתמש של Edge, אפשר לציין עד כמה זמן מראש יפוג התוקף של האישור. כברירת מחדל, בממשק המשתמש מודגשים אישורים שהתוקף שלהם יפוג ב-10 הימים הקרובים.
יצירת מאגר מפתחות
מאגר מפתחות הוא ספציפי לסביבה בארגון, למשל סביבת הבדיקה או הייצור. לכן, אם רוצים לבדוק את מאגר המפתחות בסביבת בדיקה לפני שפורסים אותו בסביבת הייצור, צריך ליצור אותו בשתי הסביבות.
יצירת מאגר מפתחות היא תהליך דו-שלבי:
- יוצרים קובץ JAR שמכיל את האישור ואת המפתח הפרטי.
- יוצרים את מאגר המפתחות ומעלים את קובץ ה-JAR.
יוצרים קובץ JAR שמכיל את האישור ואת המפתח הפרטי
יוצרים קובץ JAR עם המפתח הפרטי, האישור ומניפסט. קובץ ה-JAR חייב להכיל את הקבצים והספריות הבאים:
/META-INF/descriptor.properties myCert.pem myKey.pem
בספרייה שמכילה את זוג המפתחות והאישור, יוצרים ספרייה בשם /META-INF. לאחר מכן, יוצרים קובץ בשם descriptor.properties בקובץ /META-INF עם התוכן הבא:
certFile={myCertificate}.pem
keyFile={myKey}.pem
יוצרים את קובץ ה-JAR שמכיל את זוג המפתחות והאישור:
jar -cf myKeystore.jar myCert.pem myKey.pem
מוסיפים את descriptor.properties לקובץ ה-JAR:
jar -uf myKeystore.jar META-INF/descriptor.properties
יוצרים את מאגר המפתחות ומעלים את קובץ ה-JAR
כדי ליצור מאגר מפתחות בסביבה מסוימת, צריך לציין את שם מאגר המפתחות רק ב-API Create a Keystore או Truststore. השם יכול להכיל תווים אלפאנומריים בלבד:
curl -X POST -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>' -u email:password
דוגמה לתשובה:
{
"certs" : [ ],
"keys" : [ ],
"name" : "myKeystore"
}
אחרי שיוצרים מאגר מפתחות בעל שם בסביבה, אפשר להעלות קובצי JAR שמכילים אישור ומפתח פרטי באמצעות ממשק ה-API של העלאת קובץ JAR ל-Keystore:
curl -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.jar" -F password={key_pass} \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}" \
-u email:password
כאשר האפשרות -F מציינת את
הנתיב לקובץ ה-JAR.
בקריאה הזו עליכם לציין שני פרמטרים של שאילתה:
alias- מזהה את האישור ואת המפתח במאגר המפתחות. כשיוצרים מארח וירטואלי, צריך להתייחס לאישור ולמפתח לפי השם החלופי שלהם.password- הסיסמה של המפתח הפרטי. יש להשמיט את הפרמטר הזה אם למפתח הפרטי אין סיסמה.
מוודאים שמאגר המפתחות הועלה כמו שצריך:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password
דוגמה לתשובה:
{
"certs" : [ "myCertificate" ],
"keys" : [ "myKey" ],
"name" : "myKeystore"
}
יצירת מאגר מהימנות
ממשקי ה-API שבהם אתם משתמשים כדי ליצור מאגר מפתחות זהים לממשקי ה-API שמשמשים ליצירת מאגר מפתחות. ההבדל היחיד הוא שהעברה של קובץ האישור מתבצעת כקובץ PEM ולא כקובץ JAR.
אם האישור הוא חלק מרשת, צריך להעלות את כל האישורים ברשת בנפרד אל ה-Truststore, או ליצור קובץ אחד שמכיל את כל האישורים ולכלול שורה חדשה בין כל אישורים בקובץ. האישור הסופי חתום בדרך כלל על ידי מנפיק האישור. לדוגמה, ב-Truststore צריך להעלות אישור לקוח, client_cert_1, ואת האישור של מנפיק אישור הלקוח ca_cert,
במהלך אימות TLS דו-כיווני, אימות הלקוח מצליח כשהשרת שולח את client_cert_1 ללקוח כחלק מתהליך לחיצת היד של TLS.
לחלופין, יש לך אישור שני, client_cert_2, שחתום על ידי אותו אישור,
ca_cert. עם זאת, לא תתבצע העלאה של client_cert_2
ל-Truststore. ה-Truststore עדיין מכיל את client_cert_1 ואת ca_cert.
כשהשרת מעביר את client_cert_2 כחלק מלחיצת היד של TLS, הבקשה
מצליחה. הסיבה לכך היא ש-Edge מאפשר לאימות TLS להצליח כש-client_cert_2 לא קיים ב-Truststore, אבל נחתם על ידי האישור שקיים ב-Truststore. אם מסירים מ-Truststore את אישור ה-CA, ca_cert, אימות ה-TLS ייכשל.
יוצרים Truststore ריק בסביבה באמצעות Create a Keystore או Truststore, אותו API שבו משתמשים ליצירת מאגר מפתחות:
curl -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
מעלים את האישור כקובץ PEM ל-Truststore באמצעות ממשק ה-API של העלאת אישור ל-Truststore:
curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore \
-u email:password
כאשר האפשרות -F מציינת את הנתיב לקובץ ה-PEM.
מחיקה של מאגר מפתחות או Truststore
אפשר למחוק מאגר מפתחות או Truststore באמצעות ממשק ה-API של מחיקת Keystore או Truststore:
curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password
דוגמה לתשובה:
{
"certs" : [ ],
"keys" : [ ],
"name" : "myKeystoreName"
}
אם מוחקים מאגר מפתחות או Truststore שנמצאים בשימוש של מארח וירטואלי או של נקודת קצה (endpoint), יעד או שרת של יעד, כל הקריאות ל-API דרך המארח הווירטואלי או דרך שרת נקודת הקצה/היעד של היעד ייכשלו.