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

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

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

مقدمه

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

برای آشنایی با keystores، truststore، و مستعار، Keystores و Truststores را ببینید.

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

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

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

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

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

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

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

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

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 استفاده می شود. تنها تفاوت این است که شما فقط یک فایل گواهی را به عنوان یک فایل 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 امضا شده باشد. اگر گواهی CA، ca_cert را از فروشگاه اعتماد حذف کنید، تأیید TLS ناموفق است.

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

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، با استفاده از Create an alias from a Certificate file PEM API گواهی را به عنوان فایل 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 را مشخص می کند.

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

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

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

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

[ "freetrial" ]

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

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

با استفاده از 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"
}

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

با استفاده از List aliases 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 برای 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 برای نام مستعار، از Generate a CSR for a 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}/csr"

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

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

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

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

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

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

  1. اطمینان حاصل کنید که از یک مرجع به Truststore در میزبان مجازی استفاده می کنید.
  2. همانطور که در بالا در Create a truststore توضیح داده شد، یک گواهی جدید را در Truststore آپلود کنید.

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

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

ذخیره کلید/truststore یا نام مستعار را حذف کنید

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

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

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

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

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

با استفاده از Delete a Keystore یا Truststore API می‌توانید یک فروشگاه کلید یا Truststore را حذف کنید:

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

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

یک نام مستعار را حذف کنید

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

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