ایجاد کردن keystore و truststore بااستفاده از Edge management API

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

این سند نحوه ایجاد، اصلاح، و حذف کردن keystore و truststore برای Edge برای Cloud و برای Edge برای نسخه‌های Private Cloud 4.18.01 و جدیدتر را شرح می‌دهد.

مقدمه

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

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

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

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

برای ایجاد کردن انبار کلید در محیط:

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

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

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

تأیید کنید که انبار کلیدتان به‌درستی بارگذاری شده است:

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"
}

ایجاد فروشگاه مطمئن

میاناهای برنامه‌سازی کاربردی که برای ایجاد truststore استفاده می‌کنید همان‌هایی هستند که برای ایجاد keystore استفاده می‌شوند. تنها تفاوت این است که شما فقط یک فایل گواهی را به‌عنوان یک فایل PEM در مخزن اعتماد بارگذاری می‌کنید.

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

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

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

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

یا گواهی دوم، client_cert_2، را دارید که با همان گواهی، ca_cert، امضا شده است. بااین‌حال، client_cert_2 را در truststore بارگذاری نمی‌کنید. «انبار مطمئن» همچنان حاوی client_cert_1 و ca_cert است.

وقتی سرور client_cert_2 را به‌عنوان بخشی از دست‌دهی TLS ارسال می‌کند، درخواست موفقیت‌آمیز است. این امر به این دلیل است که Edge اجازه می‌دهد درستی‌سنجی «امنیت لایه انتقال» زمانی موفقیت‌آمیز باشد که client_cert_2 در truststore وجود نداشته باشد اما با گواهینامه‌ای که در truststore وجود دارد امضا شده باشد. اگر گواهینامه CA ، ca_cert، را از truststore بردارید، درستی‌سنجی TLS ناموفق خواهد بود.

بااستفاده از ایجاد «انبار کلید» یا «انبار اطمینان»، همان میانای برنامه‌سازی کاربردی که برای ایجاد انبار کلید استفاده می‌کنید، انبار اطمینان خالی در محیط ایجاد کنید:

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 بااستفاده از میانای برنامه‌سازی کاربردی ایجاد نام مستعار از فایل گواهینامه PEM در truststore بارگذاری کنید:

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 فهرست کردن keystores و truststores، محیط خود را برای یافتن keystores موجود بررسی کنید:

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

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

[ "freetrial" ]

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

برای مشتریان «ابر خصوصی»، آرایه برگشتی تا زمانی که اولین انبار کلید را ایجاد کنید خالی است.

محتوای keystore را بااستفاده از API دریافت 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",
]

برای دریافت همه اطلاعات درباره نام مستعار، مثل تاریخ انقضا و صادرکننده، از Get alias (دریافت نام مستعار) 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}"

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

{
  "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"
}

برای بارگیری گواهینامه برای نام مستعار، از Export a certificate for an alias 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 برای نام مستعار، از میانای برنامه‌سازی کاربردی تولید کردن CSR برای نام مستعار استفاده کنید:

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 دوطرفه

هنگام استفاده از «امنیت لایه انتقال» دوطرفه برای اتصالات ورودی، یعنی درخواست API به Edge، ذخیره اعتماد حاوی گواهینامه یا زنجیره CA برای هر کارخواهی است که اجازه دارد به Edge درخواست ارسال کند.

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

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

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

  3. مرجع مخزن مطمئن را به‌روزرسانی کنید تا آن را روی مقدار یکسان تنظیم کنید. این به‌روزرسانی باعث می‌شود Edge فروشگاه مطمئن و گواهینامه جدید را مجدد بار کند.

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

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

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

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

  1. همان‌طور که در بالا توضیح داده شد، keystore/truststore یا نام مستعار جدیدی ایجاد کنید.
  2. برای اتصال‌های ورودی، یعنی درخواست API به Edge، پیکربندی میزبان مجازی را به‌روز کنید تا به انبار کلید و نام مستعار کلید جدید ارجاع دهد.
  3. برای اتصال‌های خروجی، یعنی از Apigee به سرور زیرینه:
    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

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

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

بااستفاده از API حذف نام مستعار می‌توانید نام مستعار را در keystore یا truststore حذف کنید:

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