ایجاد keystores و truststores با استفاده از Edge management API

شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات

این سند نحوه ایجاد، اصلاح و حذف keystoreها و truststoreها را برای Edge for the Cloud و Edge for the Private Cloud نسخه‌های ۴.۱۸.۰۱ و بالاتر شرح می‌دهد.

مقدمه

برای پیکربندی قابلیت‌هایی که به زیرساخت کلید عمومی، مانند TLS، متکی هستند، باید keystoreها و truststoreهایی ایجاد کنید که کلیدهای لازم و گواهی‌های دیجیتال را ارائه دهند.

برای آشنایی با keystoreها، truststoreها و نام‌های مستعار، به Keystoreها و Truststoreها مراجعه کنید.

ایجاد یک فروشگاه کلید

یک keystore مختص یک محیط در سازمان شما است، برای مثال محیط تست یا تولید. بنابراین، اگر می‌خواهید keystore را قبل از استقرار در محیط تولید، در یک محیط تست آزمایش کنید، باید آن را در هر دو محیط ایجاد کنید.

برای ایجاد یک فروشگاه کلید در یک محیط:

  1. از فراخوانی API در این بخش برای ایجاد keystore استفاده کنید.
  2. یک نام مستعار ایجاد کنید و یک جفت گواهی/کلید را در آن آپلود کنید. نحوه آپلود گواهی و کلید بر اساس قالب جفت گواهی/کلید است. بخش‌های زیر نحوه آپلود هر نوع جفت گواهی/کلید را شرح می‌دهند:

برای ایجاد یک keystore، نام keystore را در API مربوط به Create a Keystore یا Truststore مشخص کنید. نام keystore فقط می‌تواند شامل کاراکترهای حرفی-عددی باشد:

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 مربوط به keystore می‌تواند فقط شامل این سه فایل باشد. اگر یک زنجیره گواهی دارید، تمام گواهی‌های موجود در زنجیره باید در یک فایل PEM واحد ضمیمه شوند، که در آن آخرین گواهی باید توسط یک CA ریشه امضا شود. گواهی‌ها باید به ترتیب صحیح به فایل 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 - رمز عبور کلید خصوصی. اگر کلید خصوصی رمز عبور ندارد، این پارامتر را حذف کنید.

تأیید کنید که keystore شما به درستی آپلود شده است:

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 مربوط به Create an alias from certificate and key PEM files آپلود کنید: 

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 - رمز عبور کلید خصوصی. اگر کلید خصوصی رمز عبور ندارد، این پارامتر را حذف کنید.

تأیید کنید که keystore شما به درستی آپلود شده است: 

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 آپلود کنید

با استفاده از API مربوط به ایجاد یک نام مستعار از فایل JAR یا PKCS، یک فایل PKCS12/PFX که حاوی گواهی و کلید خصوصی است را آپلود کنید: 

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 - رمز عبور کلید خصوصی. اگر کلید خصوصی رمز عبور ندارد، این پارامتر را حذف کنید.

تأیید کنید که keystore شما به درستی آپلود شده است: 

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 گواهی خودامضا» برای ایجاد یک گواهی و کلید خودامضا و آپلود آنها در یک نام مستعار استفاده کنید. فراخوانی زیر فقط اطلاعات مورد نیاز برای ایجاد گواهی خودامضا را مشخص می‌کند. می‌توانید این فراخوانی را برای افزودن اطلاعات اضافی تغییر دهید: 

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هایی که برای ایجاد یک truststore استفاده می‌کنید، همان‌هایی هستند که برای ایجاد keystore استفاده می‌شوند. تنها تفاوت این است که شما فقط یک فایل cert، به عنوان یک فایل PEM، را در truststore آپلود می‌کنید.

اگر گواهی بخشی از یک زنجیره است، باید تمام گواهی‌های موجود در زنجیره را جداگانه در truststore آپلود کنید، یا یک فایل واحد حاوی تمام گواهی‌ها ایجاد کنید. باید بین هر گواهی در فایل، یک خط خالی قرار دهید.

اگر می‌خواهید چندین گواهی خودامضا را که بخشی از یک زنجیره نیستند، آپلود کنید، از همین تکنیک استفاده کنید: اگر چندین گواهی وجود دارد که می‌خواهید به آنها اعتماد کنید، آنها را در یک فایل واحد آپلود کنید.

گواهی نهایی معمولاً توسط صادرکننده گواهی امضا می‌شود. برای مثال، در فروشگاه اعتماد، شما یک گواهی مشتری، client_cert_1، و گواهی صادرکننده گواهی مشتری، ca_cert را آپلود می‌کنید.

در طول احراز هویت دوطرفه TLS، احراز هویت کلاینت زمانی با موفقیت انجام می‌شود که سرور، client_cert_1 را به عنوان بخشی از فرآیند TLS handshaking برای کلاینت ارسال کند.

روش دیگر این است که شما یک گواهی دوم، client_cert_2، دارید که توسط همان گواهی، ca_cert، امضا شده است. با این حال، شما client_cert_2 را در truststore آپلود نمی‌کنید. truststore هنوز شامل client_cert_1 و ca_cert است.

وقتی سرور client_cert_2 را به عنوان بخشی از TLS handshaking ارسال می‌کند، درخواست با موفقیت انجام می‌شود. دلیل این امر این است که Edge اجازه می‌دهد تأیید TLS زمانی که client_cert_2 در truststore وجود ندارد اما توسط گواهی موجود در truststore امضا شده است، با موفقیت انجام شود. اگر گواهی CA، ca_cert، را از truststore حذف کنید، تأیید TLS با شکست مواجه می‌شود.

با استفاده از Create a Keystore یا Truststore ، همان API که برای ایجاد یک keystore استفاده می‌کنید، یک truststore خالی در محیط ایجاد کنید: 

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

پس از ایجاد فروشگاه اعتماد، با استفاده از API مربوط به ایجاد یک نام مستعار از یک فایل PEM گواهی، گواهی را به عنوان یک فایل 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 را مشخص می‌کند.

جزئیات مربوط به یک فروشگاه کلید یا فروشگاه اعتماد موجود را دریافت کنید

با استفاده از API مربوط به List Keystores و Truststores، محیط خود را برای وجود هرگونه keystore موجود بررسی کنید: 

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

برای مشتریان ابری، یک keystore پیش‌فرض برای سازمان‌های آزمایشی رایگان در هر دو محیط آزمایشی و تولیدی ارائه می‌شود. شما باید نتایج زیر را برای این فراخوانی برای هر دو محیط مشاهده کنید: 

[ "freetrial" ]

شما می‌توانید از این keystore پیش‌فرض برای آزمایش APIهای خود و انتشار آنها در محیط عملیاتی استفاده کنید، اما معمولاً قبل از انتشار در محیط عملیاتی، keystore مخصوص به خود را با گواهی و کلید اختصاصی خود ایجاد می‌کنید.

برای مشتریان Private Cloud، آرایه‌ی برگردانده شده تا زمانی که اولین keystore خود را ایجاد نکنید، خالی است.

با استفاده از Get a Keystore یا Truststore API، محتویات keystore را بررسی کنید. برای یک مشتری ابری، باید یک گواهی 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 خود ارسال می‌کنید. برای تولید CSR برای یک نام مستعار، از API Generate a CSR for an 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}/csr"

پاسخ باید به صورت زیر ظاهر شود: 

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

برای TLS دو طرفه، یک گواهی به یک فروشگاه اعتماد اضافه کنید

هنگام استفاده از TLS دوطرفه برای اتصالات ورودی ، به معنای درخواست API به Edge، فروشگاه اعتماد شامل یک زنجیره گواهی یا CA برای هر کلاینت مجاز به ارسال درخواست به Edge است.

وقتی در ابتدا truststore را پیکربندی می‌کنید، می‌توانید تمام گواهینامه‌های مربوط به کلاینت‌های شناخته‌شده را اضافه کنید. با این حال، با گذشت زمان، ممکن است بخواهید با اضافه کردن کلاینت‌های جدید، گواهینامه‌های اضافی را به truststore اضافه کنید.

برای افزودن گواهی‌های جدید به یک فروشگاه اعتماد که برای TLS دوطرفه استفاده می‌شود:

  1. مطمئن شوید که از ارجاع به truststore در میزبان مجازی استفاده می‌کنید.
  2. همانطور که در بالا در بخش «ایجاد یک فروشگاه اعتماد» توضیح داده شد، یک گواهی جدید در فروشگاه اعتماد آپلود کنید.

  3. مرجع truststore را به‌روزرسانی کنید تا روی همان مقدار تنظیم شود. این به‌روزرسانی باعث می‌شود Edge، truststore و گواهی جدید را مجدداً بارگذاری کند.

    برای اطلاعات بیشتر به بخش اصلاح مرجع مراجعه کنید.

حذف یک keystore/truststore یا نام مستعار

هنگام حذف یک keystore/truststore یا نام مستعار باید احتیاط کنید. اگر یک keystore، truststore یا نام مستعار را که توسط یک میزبان مجازی، نقطه پایانی هدف یا سرور هدف استفاده می‌شود حذف کنید، تمام فراخوانی‌های API از طریق میزبان مجازی یا نقطه پایانی هدف/سرور هدف با شکست مواجه می‌شوند.

معمولاً فرآیندی که برای حذف یک keystore/truststore یا نام مستعار استفاده می‌کنید به شرح زیر است:

  1. همانطور که در بالا توضیح داده شد، یک keystore/truststore یا نام مستعار جدید ایجاد کنید.
  2. برای اتصالات ورودی ، یعنی درخواست API به Edge، پیکربندی میزبان مجازی را به‌روزرسانی کنید تا به کلید اصلی و نام مستعار کلید جدید ارجاع داده شود.
  3. برای اتصالات خروجی ، یعنی از Apigee به یک سرور backend:
    1. پیکربندی TargetEndpoint را برای هر پروکسی API که به کلید اصلی و نام مستعار کلید قدیمی ارجاع داده است، به‌روزرسانی کنید تا به کلید اصلی و نام مستعار کلید جدید ارجاع داده شود. اگر TargetEndpoint شما به یک TargetServer ارجاع می‌دهد، تعریف TargetServer را به‌روزرسانی کنید تا به کلید اصلی و نام مستعار کلید جدید ارجاع دهد.
    2. اگر keystore و truststore مستقیماً از تعریف TargetEndpoint ارجاع داده شوند، باید پروکسی را مجدداً مستقر کنید. اگر TargetEndpoint به تعریف TargetServer ارجاع دهد و تعریف TargetServer به keystore و truststore ارجاع دهد، نیازی به استقرار مجدد پروکسی نیست.
    3. تأیید کنید که پروکسی‌های API شما به درستی کار می‌کنند.
    4. keystore/truststore یا نام مستعار را حذف کنید.

برای اطلاعات بیشتر به بخش «به‌روزرسانی گواهی با نام مستعار» مراجعه کنید.

حذف یک فروشگاه کلید یا فروشگاه اعتماد

شما می‌توانید با استفاده از API مربوط به حذف یک Keystore یا Truststore، یک Keystore یا Truststore را حذف کنید: 

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

اگر یک keystore یا truststore که توسط یک میزبان مجازی استفاده می‌شود را حذف و دوباره ایجاد کنید، باید پروکسی‌های API خود را مجدداً مستقر کنید.

حذف نام مستعار

شما می‌توانید با استفاده از API مربوط به حذف نام مستعار، یک نام مستعار را در یک فروشگاه کلید یا فروشگاه اعتماد حذف کنید: 

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