برای نسخه 4.17.09 Private Cloud و پیش از آن، کلیدها و ذخیره‌های اعتماد ایجاد کنید.

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

این سند نحوه ایجاد، اصلاح و حذف keystoreها و truststoreها برای Edge برای Private Cloud نسخه ۴.۱۷.۰۹ و قبل از آن را شرح می‌دهد.

درباره فروشگاه‌های کلید و فروشگاه‌های امانی

Keystoreها و truststoreها مخازن گواهی‌های امنیتی مورد استفاده برای رمزگذاری TLS را تعریف می‌کنند. تفاوت اصلی بین این دو، محل استفاده آنها در فرآیند TLS handshaking است:

  • یک keystore شامل یک گواهی TLS و کلید خصوصی است که برای شناسایی موجودیت در طول TLS handshaking استفاده می‌شود.

    در TLS یک‌طرفه، وقتی یک کلاینت به نقطه پایانی TLS روی سرور متصل می‌شود، کلید سرور، گواهی سرور (گواهی عمومی) را به کلاینت ارائه می‌دهد. سپس کلاینت آن گواهی را با یک مرجع صدور گواهی (CA) مانند Symantec یا VeriSign اعتبارسنجی می‌کند.

    در TLS دوطرفه، هم کلاینت و هم سرور یک کلید عمومی (keystore) با گواهی و کلید خصوصی خود که برای احراز هویت متقابل استفاده می‌شود، نگهداری می‌کنند.
  • یک فروشگاه اعتماد شامل گواهی‌هایی است که برای تأیید گواهی‌های دریافتی به عنوان بخشی از TLS handshaking استفاده می‌شوند.

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

    برای مثال، یک کلاینت TLS به یک سرور TLS متصل می‌شود که در آن سرور از یک گواهی خودامضا استفاده می‌کند. از آنجایی که این یک گواهی خودامضا است، کلاینت نمی‌تواند آن را با یک CA اعتبارسنجی کند. در عوض، کلاینت گواهی خودامضای سرور را در truststore خود از قبل بارگذاری می‌کند. سپس، هنگامی که کلاینت سعی در اتصال به سرور دارد، کلاینت از truststore خود برای اعتبارسنجی گواهی دریافتی از سرور استفاده می‌کند.

    برای TLS دوطرفه، هم کلاینت TLS و هم سرور TLS می‌توانند از یک truststore استفاده کنند. هنگام اجرای TLS دوطرفه، زمانی که Edge به عنوان سرور TLS عمل می‌کند، truststore مورد نیاز است.

گواهینامه‌ها می‌توانند توسط یک مرجع صدور گواهینامه (CA) صادر شوند، یا می‌توانند توسط کلید خصوصی که شما تولید می‌کنید، خودامضا شوند. اگر به یک مرجع صدور گواهینامه (CA) دسترسی دارید، دستورالعمل‌های ارائه شده توسط مرجع صدور گواهینامه خود را برای تولید کلیدها و صدور گواهینامه‌ها دنبال کنید. اگر به مرجع صدور گواهینامه (CA) دسترسی ندارید، می‌توانید با استفاده از یکی از ابزارهای رایگان و در دسترس عموم، مانند openssl، یک گواهینامه خودامضا ایجاد کنید.

پیاده‌سازی یک keystore و truststore در Edge

در Edge، یک keystore شامل یک یا چند فایل JAR است که فایل JAR شامل موارد زیر است:

  • گواهی TLS به عنوان یک فایل PEM - یا گواهی امضا شده توسط یک مرجع صدور گواهی (CA)، زنجیره‌ای از گواهی‌ها که در آن آخرین گواهی توسط یک مرجع صدور گواهی امضا شده است، یا یک گواهی خودامضا.
  • کلید خصوصی به صورت یک فایل PEM. Edge از اندازه کلید تا ۲۰۴۸ بیت پشتیبانی می‌کند. عبارت عبور اختیاری است.

یک فروشگاه اعتماد شبیه به یک فروشگاه کلید است با این تفاوت که فقط شامل گواهی‌ها به صورت فایل PEM است، اما کلیدهای خصوصی ندارد.

اگر گواهی بخشی از یک زنجیره باشد، آنگاه keystore/truststore باید شامل تمام گواهی‌های موجود در زنجیره باشد، چه به صورت فایل‌های PEM مجزا و چه به صورت یک فایل واحد. اگر از یک فایل واحد استفاده می‌کنید، گواهی‌ها باید به ترتیب باشند، به طوری که اولین گواهی در فایل، گواهی مورد استفاده برای TLS باشد و به دنبال آن زنجیره گواهی‌ها، به ترتیب، تا گواهی CA قرار گیرد. شما باید بین هر گواهی در فایل یک خط خالی وارد کنید.

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

درباره قالب فایل‌های گواهی و کلید

مثال‌های این سند، گواهی و کلید TLS تعریف‌شده به عنوان فایل‌های PEM را نشان می‌دهند که با فرمت X.509 مطابقت دارند. اگر گواهی یا کلید خصوصی شما توسط یک فایل PEM تعریف نشده است، می‌توانید با استفاده از ابزارهایی مانند openssl آن را به یک فایل PEM تبدیل کنید.

با این حال، بسیاری از فایل‌های .crt و .key از قبل در قالب PEM هستند. اگر این فایل‌ها متنی باشند و در داخل ... قرار گیرند:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

یا:

-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----

سپس فایل‌ها با فرمت PEM سازگار می‌شوند و می‌توانید بدون تبدیل آنها به فایل PEM، از آنها در یک keystore یا truststore استفاده کنید.

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

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

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

[ "freetrial" ]

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

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

با استفاده از Get a Keystore یا Truststore API، محتویات keystore را بررسی کنید. برای یک مشتری ابری، باید یک گواهی 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 را دریافت کنید

شما می‌توانید از API مربوط به دریافت جزئیات گواهی از یک Keystore یا Truststore برای مشاهده جزئیات مربوط به گواهی‌های TLS در Keystore، مانند تاریخ انقضا و صادرکننده، استفاده کنید. ابتدا، نام گواهی مورد نظر خود را دریافت کنید. این مثال اطلاعات مربوط به Keystore با نام "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"
}

سپس، از مقدار ویژگی certs برای دریافت جزئیات گواهی استفاده کنید: 

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 را انتخاب کنید.

در رابط کاربری Edge، می‌توانید مشخص کنید که Edge چقدر قبل از انقضای یک گواهی، آن را نشان می‌دهد. به طور پیش‌فرض، رابط کاربری هر گواهی که قرار است در 10 روز آینده منقضی شود را برجسته می‌کند.

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

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

ایجاد یک فروشگاه کلید (keystore) یک فرآیند دو مرحله‌ای است:

  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

ایجاد keystore و آپلود فایل JAR

برای ایجاد یک keystore در یک محیط، فقط باید نام keystore را در API مربوط به Create a Keystore یا 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 در یک 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 - رمز عبور کلید خصوصی. اگر کلید خصوصی رمز عبور ندارد، این پارامتر را حذف کنید.

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

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 استفاده می‌شوند. تنها تفاوت این است که فایل cert را به جای یک فایل JAR، به صورت یک فایل 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 -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

با استفاده از API مربوط به آپلود گواهی در Truststore، گواهی را به عنوان یک فایل PEM در 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 مربوط به حذف یک Keystore یا Truststore، یک Keystore یا 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"
}

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