יצירת מאגרי מפתחות ומאגרים (Truststores) לגרסה 4.17.09 וגרסאות קודמות של הענן

מוצג המסמך של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info

במסמך הזה מוסבר איך ליצור, לשנות ולמחוק מאגרי מפתחות ומאגרי אמון ב-Edge ל-Private Cloud בגרסה 4.17.09 ובגרסאות קודמות.

מידע על מאגרי מפתחות ועל מאגרי אמון

מאגרי מפתחות ומאגרי אישורים מוגדרים כמאגרים של אישורי אבטחה המשמשים להצפנת TLS. ההבדל העיקרי בין שתי הפלטפורמות הוא המקום שבו משתמשים בהן ללחיצת יד בפרוטוקול TLS תהליך:

  • מאגר מפתחות מכיל אישור TLS ומפתח פרטי שמשמש לזיהוי הישות במהלך לחיצת היד ב-TLS.

    ב-TLS חד-כיווני, כשלקוח מתחבר לנקודת הקצה של ה-TLS בשרת, מאגר המפתחות של השרת מציג ללקוח את האישור של השרת (אישור ציבורי). לאחר מכן הלקוח מאמת את האישור הזה באמצעות רשות אישורים (CA), כמו Symantec או VeriSign.

    ב-TLS דו-כיווני, גם הלקוח וגם השרת שומרים מאגר מפתחות עם אישור ומפתח פרטי משלהם, המשמשים לאימות הדדי.
  • truststore מכילה אישורים שמשמשים לאימות אישורים שהתקבלו בתור חלק מלחיצת היד בפרוטוקול TLS.

    ב-TLS חד-כיווני, אין צורך במאגר אישורים אם האישור חתום על ידי רשות אישורים תקינה. אם האישור שהתקבל על ידי לקוח TLS נחתם על ידי רשות אישורים תקפה, הלקוח שולח בקשה לרשות האישורים כדי לאמת את האישור. לקוח TLS בדרך כלל משתמש במאגר אישורים כדי לאמת אישורים בחתימה עצמית שהתקבלו משרת ה-TLS, או אישורים שלא נחתמו על ידי רשות אישורים מהימנה. בתרחיש הזה, הלקוח מאכלס את מאגר האמון שלו באישורים שהוא סומך עליהם. לאחר מכן, כשהלקוח מקבל אישור שרת, האישור הנכנס מאומת מול האישורים במאגר האמון שלו.

    לדוגמה, לקוח TLS מתחבר לשרת TLS שבו השרת משתמש באישור חתום-עצמי. מאחר שזהו אישור בחתימה עצמית, הלקוח לא יכול לאמת אותו באמצעות CA. במקום זאת, הלקוח טוען מראש את האישור החתום העצמאי של השרת למאגר האמון שלו. לאחר מכן: כשהלקוח מנסה להתחבר לשרת, הוא משתמש במאגר האמון שלו כדי לאמת את האישור שהתקבל מהשרת.

    ב-TLS דו-כיווני, גם לקוח ה-TLS וגם שרת ה-TLS יכולים להשתמש במאגר אישורים. נדרש מאגר אמון כשמבצעים TLS דו-כיווני כש-Edge פועל בתור שרת TLS.

אישורים יכולים להיות מונפקים על ידי רשות אישורים (CA), או שניתן לחתום עליהם בחתימה עצמית המפתח הפרטי שיוצרים, אם יש לכם גישה לרשות אישורים, פועלים לפי ההוראות של רשות האישורים ליצירת מפתחות ולהנפקת אישורים. אם אין לכם גישה לרשות אישורים, תוכלו ליצור אישור בחתימה עצמית באמצעות אחד מהכלים החינמיים הרבים שזמינים לציבור, כמו openssl.

ההטמעה של Keystore ו-Truststore ב-Edge

ב-Edge, מאגר מפתחות מכיל קובץ JAR אחד או יותר, שבו קובץ ה-JAR מכיל:

  • אישור TLS כקובץ PEM – אישור שחתום על ידי רשות אישורים (CA), שרשרת של אישורים שבהם האישור האחרון חתום על ידי רשות אישורים או אישור בחתימה עצמית.
  • מפתח פרטי כקובץ PEM. Edge תומך בגדלי מפתחות של עד 2048 ביט. השימוש בביטוי סיסמה הוא אופציונלי.

מאגר אמון דומה למאגר מפתחות, אבל הוא מכיל רק אישורים כקובץ PEM, למפתחות פרטיים.

אם האישור הוא חלק משרשרת, מאגר המפתחות/חנות המפתחות צריכים להכיל את כל האישורים כקובצי PEM בודדים או כקובץ יחיד. אם משתמשים בקובץ יחיד, האישורים צריכים להיות בסדר שבו האישור הראשון בקובץ הוא האישור שמשמש ל-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 ואפשר להשתמש בהם במאגר מפתחות או ל-Truststore בלי להמיר אותם לקובץ 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-----

הצגת פרטים על מאגר מפתחות קיים

כדי לבדוק אם יש מאגרי מפתחות קיימים בסביבה, משתמשים ב-List Keystores ו-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 של Keystore או 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:

  1. מתחברים לממשק המשתמש לניהול של Edge בכתובת https://enterprise.apigee.com (ענן) או בכתובת http://<ms-ip>:9000 (ארגוני), כאשר <ms-ip> היא כתובת ה-IP של הצומת של שרת הניהול.
  2. בתפריט של ממשק המשתמש לניהול Edge, בוחרים באפשרות אדמין > אישורי TLS.

אחזור פרטי אישור TLS

אפשר להשתמש ב קבלת פרטי אישור מ-Keystore או Truststore API כדי לצפות בפרטים על אישורי 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"
}

אחר כך משתמשים בערך של מאפיין האישורים כדי לקבל את פרטי האישור:

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=&quot;GoDaddy.com, Inc.&quot;, 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:

  1. מתחברים לממשק המשתמש של ניהול Edge בכתובת https://enterprise.apigee.com (Cloud) או ב-http://<ms-ip>:9000 (בארגון), כאשר <ms-ip> היא כתובת ה-IP של הצומת של שרת הניהול.
  2. בתפריט של ממשק המשתמש לניהול Edge, בוחרים באפשרות אדמין > אישורי TLS.

בממשק המשתמש של Edge, אפשר לציין כמה זמן מראש יופיע האישור ב-Edge עד תאריך התפוגה. כברירת מחדל, בממשק המשתמש מודגשים אישורים שתוקפם יפוג ב-10 הימים הקרובים.

יצירת מאגר מפתחות

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

יצירת מאגר מפתחות היא תהליך דו-שלבי:

  1. יצירת קובץ JAR שמכיל את האישור והמפתח הפרטי שלך.
  2. יוצרים את מאגר המפתחות ומעלים את קובץ ה-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 מכילים אישור ומפתח פרטי באמצעות הפקודה העלאת קובץ JAR ל-Keystore API:

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 או ליצור קובץ יחיד שמכיל את כל האישורים, לכלול שורה חדשה בין לכל אישור בקובץ. בדרך כלל, המנפיק של האישור חותם על האישור הסופי. עבור לדוגמה: ב-Truststore מעלים אישור לקוח, client_cert_1 ואת אישור הלקוח. אישור של המנפיק, ca_cert.

במהלך אימות TLS דו-כיווני, אימות הלקוח מסתיים בהצלחה כשהשרת שולח את הערך client_cert_1 ללקוח כחלק מתהליך לחיצת היד של TLS.

לחלופין, יש לכם אישור שני, client_cert_2, שנחתם על ידי אותו אישור, ca_cert. עם זאת, לא להעלות את client_cert_2 אל ב-Truststore. מאגר האמון עדיין מכיל את client_cert_1 ואת ca_cert.

כשהשרת מעביר את client_cert_2 כחלק מלחיצת היד של TLS, הבקשה מסתיימת בהצלחה. הסיבה לכך היא ש-Edge מאפשר אימות TLS להצליח כאשר client_cert_2 לא קיים האמון, אבל נחתם על ידי האישור שקיים ב-Truststore. אם מסירים את ה-CA אישור, ca_cert, מ- truststore ואז אימות TLS נכשל.

כדי ליצור מאגר אמון ריק בסביבה באמצעות 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 באמצעות העלאת אישור ל-Truststore API:

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 דרך המארח הווירטואלי או יעד/נקודת קצה/שרת היעד ייכשל.