אתם צופים במסמכי העזרה של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info
במסמך הזה מוסבר איך יוצרים, משנים ומוחקים מאגרי מפתחות ומאגרי אמון ל-Edge בענן הפרטי בגרסה 4.17.09 ואילך.
מידע על מאגרי מפתחות ומאגרי אמון
מאגרי מפתחות ומאגרי אישורים מוגדרים כמאגרים של אישורי אבטחה המשמשים להצפנת TLS. ההבדל העיקרי בין השניים הוא המיקום שבו הם משמשים בתהליך לחיצת היד ב-TLS:
- מאגר מפתחות מכיל אישור TLS ומפתח פרטי שמשמש לזיהוי הישות במהלך לחיצת היד ב-TLS.
ב-TLS חד-כיווני, כשלקוח מתחבר לנקודת הקצה של ה-TLS בשרת, מאגר המפתחות של השרת מציג ללקוח את האישור של השרת (אישור ציבורי). לאחר מכן הלקוח מאמת את האישור הזה באמצעות רשות אישורים (CA), כמו Symantec או VeriSign.
ב-TLS דו-כיווני, גם הלקוח וגם השרת שומרים מאגר מפתחות עם אישור ומפתח פרטי משלהם, המשמשים לאימות הדדי. - מאגר אישורים מכיל אישורים המשמשים לאימות אישורים שהתקבלו במסגרת לחיצת היד ב-TLS.
ב-TLS חד-כיווני, אין צורך במאגר אישורים אם האישור חתום על ידי רשות אישורים תקינה. אם האישור שהתקבל על ידי לקוח TLS נחתם על ידי רשות אישורים תקפה, הלקוח שולח בקשה לרשות האישורים כדי לאמת את האישור. לקוח TLS בדרך כלל משתמש במאגר אישורים כדי לאמת אישורים בחתימה עצמית שהתקבלו משרת ה-TLS, או אישורים שלא נחתמו על ידי רשות אישורים מהימנה. בתרחיש הזה, הלקוח מאכלס את מאגר האמון שלו באישורים שהוא סומך עליהם. לאחר מכן, כשהלקוח מקבל אישור שרת, האישור הנכנס מאומת מול האישורים שבמאגר האמון שלו.
לדוגמה, לקוח TLS מתחבר לשרת TLS שבו השרת משתמש באישור חתום-עצמי. מכיוון שמדובר באישור עם חתימה עצמית, הלקוח לא יכול לאמת אותו באמצעות רשות אישורים. במקום זאת, הלקוח טוען מראש את האישור החתום העצמאי של השרת למאגר האמון שלו. לאחר מכן, כשהלקוח מנסה להתחבר לשרת, הוא משתמש במאגר האמון שלו כדי לאמת את האישור שהתקבל מהשרת.
ב-TLS דו-כיווני, גם לקוח ה-TLS וגם שרת ה-TLS יכולים להשתמש במאגר אישורים. נדרש מאגר אמון כשמבצעים TLS דו-כיווני כש-Edge פועל בתור שרת TLS.
אישורים יכולים להינפק על ידי רשות אישורים (CA), או שהם יכולים להיות בחתימה עצמית באמצעות המפתח הפרטי שיצרתם. אם יש לכם גישה לרשות אישורים, פועלים לפי ההוראות של רשות האישורים ליצירת מפתחות ולהנפקת אישורים. אם אין לכם גישה לרשות אישורים, תוכלו ליצור אישור בחתימה עצמית באמצעות אחד מהכלים החינמיים הרבים שזמינים לציבור, כמו openssl.
הטמעת מאגר מפתחות ומאגר אמון ב-Edge
ב-Edge, מאגר מפתחות מכיל קובץ JAR אחד או יותר, שבו קובץ ה-JAR מכיל:
- אישור TLS כקובץ PEM – אישור שחתום על ידי רשות אישורים (CA), שרשרת של אישורים שבהם האישור האחרון חתום על ידי רשות אישורים או אישור בחתימה עצמית.
- מפתח פרטי כקובץ PEM. Edge תומך בגדלי מפתחות של עד 2048 ביט. השימוש בביטוי סיסמה הוא אופציונלי.
מאגר אמון דומה למאגר מפתחות, אלא שהוא מכיל רק אישורים כקובץ PEM, אבל לא מפתחות פרטיים.
אם האישור הוא חלק משרשור, מאגר המפתחות/מאגר האמון חייב להכיל את כל האישורים בשרשור, כקובצי PEM נפרדים או כקובץ אחד. אם משתמשים בקובץ יחיד, אישורי ה-CA חייבים להיות מסודרים לפי הסדר, כאשר האישור הראשון בקובץ הוא האישור שמשמש ל-TLS, ואחריו שרשרת האישורים, לפי הסדר, עד לאישור ה-CA. צריך להוסיף שורה ריקה בין כל אישור בקובץ.
ב-Edge יש ממשק API שמשמש ליצירת מאגרי מפתחות ומאגרי אמון. ממשקי ה-API בפועל זהים. ההבדל הוא שכשיוצרים מאגר מפתחות, מעבירים קובץ JAR שמכיל את האישור ואת המפתח הפרטי. כשיוצרים מאגר אמון, מעבירים רק את האישור כקובץ PEM.
מידע על הפורמט של קובצי האישור והמפתח
בדוגמאות במסמך הזה מוצגים האישור והמפתח של TLS שמוגדרים כקובצי PEM, שתואמים לפורמט X.509. אם האישור או המפתח הפרטי לא מוגדרים בקובץ PEM, אפשר להמיר אותו לקובץ PEM באמצעות כלי שירות כמו openssl.
עם זאת, הרבה קובצי .crt וקובצי .key כבר נמצאים בפורמט PEM. אם הקבצים האלה הם קבצי טקסט, והם מצורפים ל:
-----BEGIN CERTIFICATE----- -----END CERTIFICATE-----
או:
-----BEGIN ENCRYPTED PRIVATE KEY----- -----END ENCRYPTED PRIVATE KEY-----
לאחר מכן, הקבצים יהיו תואמים לפורמט PEM ותוכלו להשתמש בהם במאגר מפתחות או במאגר אמון בלי להמיר אותם לקובץ PEM.
אם יש לכם שרשרת אישורים ואתם רוצים להשתמש בשרשרת הזו במאגר מפתחות או במאגר אמון, תוכלו לשלב את כל האישורים בקובץ 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-----
הצגת פרטים על מאגר מפתחות קיים
כדי לבדוק אם יש בסביבה מאגרי מפתח קיימים, משתמשים ב-API List Keystores and Truststores:
curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
ללקוחות בענן, מערכת אחסון המפתחות שמוגדרת כברירת מחדל זמינה לארגונים עם תקופת ניסיון בחינם גם בסביבת הבדיקה וגם בסביבת הייצור. התוצאות הבאות אמורות להתקבל עבור הקריאה הזו בשתי הסביבות:
[ "freetrial" ]
אפשר להשתמש במאגר המפתחות שמוגדר כברירת מחדל כדי לבדוק את ממשקי ה-API ולשלוח אותם לסביבת הייצור, אבל בדרך כלל יוצרים מאגר מפתחות משלכם, עם האישור והמפתח שלכם, לפני הפריסה בסביבת הייצור.
אצל לקוחות Private Cloud, המערך המוחזר יהיה ריק עד שתיצרו את מאגר המפתחות הראשון.
בודקים את התוכן של מאגר המפתחות באמצעות ה-API Get a Keystore or Truststore. ללקוחות Cloud, אמור להופיע אישור 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, בוחרים באפשרות אדמין > אישורי TLS.
אחזור פרטי אישור TLS
אפשר להשתמש ב-API Get Cert Details from a Keystore or Truststore כדי להציג פרטים על אישורי TLS במאגר המפתחות, כמו תאריך התפוגה והמנפיק. קודם כל, צריך לקבל את שם ההסמכה שבה אתם מעוניינים. בדוגמה הזו מתבצע אחזור מידע של מאגר המפתחות שנקרא '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, בוחרים באפשרות אדמין > אישורי TLS.
בממשק המשתמש של Edge, אפשר לציין כמה זמן מראש 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 or 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 Upload a JAR file to a 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 שבהם משתמשים כדי ליצור מאגר אמון הם אותם ממשקים שבהם משתמשים כדי ליצור מאגר מפתחות. ההבדל היחיד הוא שצריך להעביר את קובץ האישור כקובץ PEM במקום כקובץ JAR.
אם האישור הוא חלק מרשת, צריך להעלות את כל האישורים ברשת בנפרד למאגר האמון, או ליצור קובץ אחד שמכיל את כל האישורים, תוך הוספת שורה חדשה בין כל אישור בקובץ. בדרך כלל, המנפיק של האישור חותם על האישור הסופי. לדוגמה, ב-truststore מעלים אישור לקוח, client_cert_1, ואת האישור של מנפיק אישור הלקוח, ca_cert.
במהלך אימות TLS דו-כיווני, אימות הלקוח מסתיים בהצלחה כשהשרת שולח את הערך client_cert_1 ללקוח כחלק מתהליך לחיצת היד של TLS.
לחלופין, יש לכם אישור שני, client_cert_2, שנחתם על ידי אותו אישור,
ca_cert. עם זאת, לא מעלים את client_cert_2 למאגר האמון. מאגר האמון עדיין מכיל את client_cert_1 ואת ca_cert.
כשהשרת מעביר את client_cert_2 כחלק מלחיצת היד של TLS, הבקשה מסתיימת בהצלחה. הסיבה לכך היא ש-Edge מאפשר לאימות TLS להצליח גם אם client_cert_2 לא קיים במאגר האישורים, אבל נחתם על ידי אישור שנמצא במאגר האישורים. אם מסירים את אישור ה-CA, ca_cert, ממאגר האישורים, האימות של TLS נכשל.
יוצרים מאגר אמון ריק בסביבה באמצעות Create a Keystore or 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 למאגר האישורים באמצעות ה-API Upload a Certificate to a 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.
מחיקה של מאגר מפתחות או מאגר אמון
אפשר למחוק מאגר מפתחות או מאגר אמון באמצעות ה-API Delete a Keystore or 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"
}
אם מוחקים מאגר מפתחות או מאגר אמון שמשמשים מארח וירטואלי או יעד/נקודת קצה/שרת יעד, כל הקריאות ל-API דרך המארח הווירטואלי או יעד/נקודת קצה/שרת היעד ייכשל.