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

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

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

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

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

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

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

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

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

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

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

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

הטמעה של חנות מפתחות וחנות אישורים ב-Edge

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

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

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

  1. מתחברים לממשק ניהול Edge בכתובת https://enterprise.apigee.com (בענן) או בכתובת http://<ms-ip>:9000 (במקום), כאשר <ms-ip> היא כתובת ה-IP של צומת שרת הניהול.
  2. בתפריט של ממשק ניהול Edge, בוחרים באפשרות Admin > TLS Certificates (ניהול > אישורי 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"
}

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

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 (בענן) או בכתובת http://<ms-ip>:9000 (במקום), כאשר <ms-ip> היא כתובת ה-IP של צומת שרת הניהול.
  2. בתפריט של ממשק ניהול Edge, בוחרים באפשרות Admin > TLS Certificates (ניהול > אישורי 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 של יצירת מאגר מפתחות או מאגר אישורים. השם יכול להכיל רק תווים אלפאנומריים:

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 שבהם משתמשים כדי ליצור truststore זהים לאלה שבהם משתמשים כדי ליצור keystore. ההבדל היחיד הוא שמעבירים את קובץ האישור כקובץ PEM ולא כקובץ JAR.

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