יצירת מאגרי מפתחות ו-Truststores באמצעות Edge Management API

מוצג התיעוד של Apigee Edge.
נכנסים למסמכי התיעוד של Apigee X.
מידע

כאן מוסבר איך ליצור, לשנות ולמחוק מאגרי מפתחות ומאגרי אמינות עבור Edge עבור Cloud ועבור Edge בגרסה 4.18.01 ואילך של הענן הפרטי.

מבוא

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

לקריאת מבוא למאגרי מפתחות, Truststore וכינויים: Keystores ו-Truststores

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

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

כדי ליצור מאגר מפתחות בסביבה:

  1. בקטע הזה משתמשים בקריאה ל-API כדי ליצור את מאגר המפתחות.
  2. יוצרים כינוי ומעלים זוג אישורים/מפתחות אל הכינוי. הדרך להעלות את האישור והמפתח מבוססת על הפורמט של זוג האישור/המפתח. בקטעים הבאים מוסבר איך להעלות כל סוג של צמד אישור/מפתחות:

כדי ליצור מאגר מפתחות, צריך לציין את שם מאגר המפתחות ב-API של יצירת Keystore או Truststore. שם מאגר המפתחות יכול להכיל תווים אלפאנומריים בלבד:

curl -X POST -u orgAdminEmail:password -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>'

תשובה לדוגמה:

{
  "certs" : [ ],
  "keys" : [ ],
  "name" : "myKeystore"
}

העלאת אישור ומפתח כקובץ JAR

קודם כול צריך ליצור קובץ JAR עם המפתח הפרטי, האישור ומניפסט. קובץ ה-JAR צריך להכיל את הקבצים והספריות הבאים:

/META-INF/descriptor.properties
myCert.pem
myKey.pem

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

cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root

בספרייה שמכילה את זוג המפתחות והאישור, יוצרים ספרייה בשם /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 של יצירת כינוי מקובץ JAR או PKCS:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertjar"

כאשר האפשרות -F מציינת את הנתיב לקובץ ה-JAR.

בשיחה הזו, עליכם לציין:

  • alias_name – מזהה את האישור והמפתח שבמאגר המפתחות. כשיוצרים מארח וירטואלי, צריך להפנות לאישור ולמפתח לפי השם החלופי שלו.
  • key_pword - הסיסמה של המפתח הפרטי. יש להשמיט את הפרמטר הזה אם למפתח הפרטי אין סיסמה.

מוודאים שמאגר המפתחות הועלה כמו שצריך:

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

תשובה לדוגמה:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

העלאת אישור ומפתח כקובצי PEM

כדי להעלות קובצי PEM שמכילים אישור ומפתח פרטי, משתמשים ב-API של יצירת כינוי מקובצי אישור ומפתחות PEM:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F keyFile="@server.key" -F certFile="@signed.crt" \
-F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertfile"

כאשר האפשרות -F מציינת את הנתיבים לקובצי ה-PEM.

בשיחה הזו, עליכם לציין:

  • alias_name – מזהה את האישור והמפתח שבמאגר המפתחות. כשיוצרים מארח וירטואלי, צריך להפנות לאישור ולמפתח לפי השם החלופי שלו.
  • key_pword - הסיסמה של המפתח הפרטי. יש להשמיט את הפרמטר הזה אם למפתח הפרטי אין סיסמה.

מוודאים שמאגר המפתחות הועלה כמו שצריך:

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

תשובה לדוגמה:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

העלאת אישור ומפתח כקובץ PKCS12/PFX

מעלים קובץ PKCS12/PFX שמכיל אישור ומפתח פרטי באמצעות ה-API של יצירת כינוי מקובץ JAR או PKCS:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.p12" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=pkcs12"

כאשר האפשרות -F מציינת את הנתיב לקובץ P12.

בשיחה הזו, עליכם לציין:

  • alias_name – מזהה את האישור והמפתח שבמאגר המפתחות. כשיוצרים מארח וירטואלי, צריך להפנות לאישור ולמפתח לפי השם החלופי שלו.
  • key_pword - הסיסמה של המפתח הפרטי. יש להשמיט את הפרמטר הזה אם למפתח הפרטי אין סיסמה.

מוודאים שמאגר המפתחות הועלה כמו שצריך:

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

תשובה לדוגמה:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

יצירה והעלאה של אישור ומפתח בחתימה עצמית

אפשר להשתמש ב-API של יצירת כינוי על ידי יצירת אישור בחתימה עצמית API כדי ליצור אישור בחתימה עצמית ומפתח ולהעלות אותם לכתובת אימייל חלופית. הקריאה הבאה מציינת רק את הפרטים הנדרשים ליצירת האישור בחתימה עצמית. אפשר לשנות את השיחה כדי להוסיף מידע:

curl -u orgAdminEmail:password -X POST --header "Content-Type: application/json"  \
-d "{
    "alias": "selfsigned",
    "subject": {
        "commonName": "mycert"
    }
}" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?format=selfsignedcert"

התגובה אמורה להופיע כך:

{
  "alias": "selfsigned",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:FALSE",
        "expiryDate": 1491497204000,
        "isValid": "Yes",
        "issuer": "CN=mycert",
        "publicKey": "RSA Public Key, 2048 bits",
        "serialNumber": "00:d1:b4:78:e1",
        "sigAlgName": "SHA256withRSA",
        "subject": "CN=mycert",
        "subjectAlternativeNames": [],
        "validFrom": 1459961204000,
        "version": 3
      }
    ],
    "certName": "selfsigned-cert"
  },
  "keyName": "selfsigned"
}

יצירת מאגר אמינות

ממשקי ה-API שבהם אתם משתמשים כדי ליצור מאגר אישורים זהים לממשקי ה-API שמשמשים ליצירת מאגר מפתחות. ההבדל היחיד הוא שצריך להעלות רק קובץ אישור, כקובץ PEM, ל-Truststore.

אם האישור הוא חלק מרשת, צריך להעלות את כל האישורים ברשת בנפרד אל ה-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 -u orgAdminEmail:password -X POST -H "Content-Type: text/xml" \
-d '<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

לאחר יצירת ה-Truststore, צריך להעלות את האישור כקובץ PEM ל-Truststore באמצעות ממשק ה-API של יצירת כינוי מקובץ PEM של אישור:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F certFile="@cert.pem" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myTruststore/aliases?alias=myTruststore&format=keycertfile"

כאשר האפשרות -F מציינת את הנתיב לקובץ ה-PEM.

קבלת פרטים על מאגר מפתחות או Truststore קיימים

כדאי לבדוק בסביבה אם יש מאגרי מפתחות קיימים, באמצעות ה-API של List Keystores ו-Truststores:

curl -u orgAdminEmail:password -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

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

[ "freetrial" ]

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

ללקוחות Private Cloud, המערך שיוחזר יהיה ריק עד שתיצרו את מאגר המפתחות הראשון.

אפשר לבדוק את התוכן של מאגר המפתחות באמצעות ה-API של Get a Keystore או Truststore. ללקוחות בענן, אמור להופיע אישור TLS של שרת יחיד – אישור ברירת המחדל ש-Apigee Edge מספק לחשבונות לתקופת ניסיון בחינם.

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/freetrial

התגובה אמורה להופיע כך:

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

קבלת פרטים על כתובת אימייל חלופית

איך מקבלים רשימה של כל הכינויים של מאגרי מפתחות באמצעות ה-API של רשימת הכינויים:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases"

התגובה אמורה להופיע כך:

[
  "alias1",
  "alias2",
  "alias3",
]

כדי לקבל את כל המידע על כינוי, כמו תאריך תפוגה ומנפיק, יש להשתמש ב-API של Get alias ולציין את שם הכינוי:

curl  -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}"

התגובה אמורה להופיע כך:

{
  "alias": "alias1",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:TRUE",
        "expiryDate": 1459371335000,
        "isValid": "No",
        "issuer": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "publicKey": "RSA Public Key, 1024 bits",
        "serialNumber": "00:86:a0:9b:5b:91:a9:fe:92",
        "sigAlgName": "SHA256withRSA",
        "subject": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "subjectAlternativeNames": [],
        "validFrom": 1456779335000,
        "version": 3
      }
    ],
    "certName": "new\-cert"
  },
  "keyName": "newssl20"
}

כדי להוריד את האישור של כתובת אימייל חלופית, משתמשים ב-API של ייצוא אישור לכתובת אימייל חלופית:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/e/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/certificate"

התגובה אמורה להופיע כך:

-----BEGIN CERTIFICATE-----
MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD
...
RBUkaTe/570sLHY0tvkIm5tEX36ESw==
-----END CERTIFICATE-----

אם יש לך אישור שפג תוקפו וברצונך לחדש אותו, אפשר להוריד בקשה לחתימה על אישור (CSR). לאחר מכן, תשלח את ה-CSR ל-CA שלך כדי לקבל אישור חדש. כדי ליצור נציג שירות לקוחות עבור כתובת אימייל חלופית, השתמשו ב-API של יצירת נציג שירות לקוחות עבור כינוי:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/csr"

התגובה אמורה להופיע כך:

-----BEGIN CERTIFICATE REQUEST-----
MIIB1DCCAT0CAQAwgZMxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRl
...
RF5RMytbkxkvPxIE17mDKJH0d8aekv/iEOItZ+BtQg+EibMUkkjTzQ==
-----END CERTIFICATE REQUEST-----

הוספת אישור ל-Truststore ל-TLS דו-כיווני

כשמשתמשים ב-TLS דו-כיווני לחיבורים נכנסים, כלומר בקשת API ל-Edge, ה-Truststore מכיל אישור או שרשרת CA לכל לקוח שמותר לשלוח בקשות ל-Edge.

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

כדי להוסיף אישורים חדשים ל-Truststore שמשמש ל-TLS דו-כיווני:

  1. מוודאים שאתם משתמשים בהפניה ל-Truststore במארח הווירטואלי.
  2. מעלים אישור חדש ל-Truststore, כמו שמתואר למעלה, בקטע יצירת מאגר אמינות.
  3. מעדכנים את ההפניה ל-Truststore כדי להגדיר אותה לערך אותו. העדכון הזה גורם ל-Edge לטעון מחדש את ה-Truststore ואת האישור החדש.

    מידע נוסף זמין בשינוי קובץ עזר.

מחיקה של מאגר מפתחות/מאגר מהימנות או כינוי

צריך להפעיל שיקול דעת כשמוחקים מאגר מפתחות/מאגר מהימנות או כינוי. אם מוחקים מאגר מפתחות, Truststore או כינוי שמשמשים מארח וירטואלי, נקודת קצה (endpoint) של יעד או שרת יעד, כל הקריאות ל-API דרך המארח הווירטואלי או דרך שרת היעד או נקודת הקצה ייכשלו.

בדרך כלל, התהליך שבו משתמשים כדי למחוק מאגר מפתחות/מאגר מהימנות או כינוי הוא:

  1. יוצרים מאגר מפתחות, מאגר מהימנות או כינוי חדש, כמו שמתואר למעלה.
  2. במקרה של חיבורים נכנסים, כלומר בקשת API ל-Edge, צריך לעדכן את ההגדרה של המארח הווירטואלי כך שיפנה למאגר המפתחות החדש ולכינוי המפתח.
  3. לחיבורים יוצאים, כלומר מ-Apigee לשרת עורפי:
    1. מעדכנים את ההגדרה של TargetEndpoint עבור כל שרת proxy של API שמפנה למאגר המפתחות הישן ולכינוי המפתח הקודם, כדי להפנות למאגר המפתחות החדש ולכינוי המפתח. אם TargetEndpoint מפנה ל-TargetServer, צריך לעדכן את ההגדרה של TargetServer כך שתתייחס למאגר המפתחות החדש ולכינוי המפתח.
    2. אם מתבצעת הפניה ישירות ל-Keystore ול-Truststore מההגדרה של TargetEndpoint, צריך לפרוס מחדש את שרת ה-proxy. אם TargetEndpoint מפנה להגדרה של TargetServer, וההגדרה של TargetServer מפנה ל-Keystore ול-Truststore, אז לא נדרשת פריסה מחדש של שרת ה-proxy.
    3. חשוב לוודא ששרתי ה-proxy של ה-API פועלים באופן תקין.
    4. מוחקים את מאגר המפתחות/מאגר המהימנות או הכינוי.

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

מחיקת מאגר מפתחות או מאגר אישורים

אפשר למחוק מאגר מפתחות או Truststore באמצעות ה-API של מחיקת מפתחות או Truststore:

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName

אם מחקתם ויצרתם מחדש מאגר מפתחות או Truststore שנמצאים בשימוש של מארח וירטואלי, תצטרכו לפרוס מחדש את שרתי ה-proxy ל-API.

מחיקת כינוי

אפשר למחוק כתובת אימייל חלופית ב-Keystore או ב-Truststore באמצעות ה-API של מחיקת החשבון החלופי:

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}