Создание хранилищ ключей и хранилищ доверенных сертификатов с помощью API управления Edge

Вы просматриваете документацию Apigee Edge .
Перейдите к документации Apigee X. информация

В этом документе описывается, как создавать, изменять и удалять хранилища ключей и доверенные хранилища для Edge для облака и Edge для частного облака версий 4.18.01 и более поздних.

Введение

Чтобы настроить функциональные возможности, основанные на инфраструктуре открытых ключей, например TLS, необходимо создать хранилища ключей и хранилища доверенных сертификатов, которые предоставляют необходимые ключи и цифровые сертификаты.

Общие сведения о хранилищах ключей, хранилищах доверенных сертификатов и псевдонимах см. в разделе Хранилища ключей и хранилища доверенных сертификатов .

Создать хранилище ключей

Хранилище ключей зависит от среды вашей организации, например тестовой или рабочей среды. Поэтому, если вы хотите протестировать хранилище ключей в тестовой среде перед его развертыванием в производственной среде, вам необходимо создать его в обеих средах.

Чтобы создать хранилище ключей в среде:

  1. Используйте вызов API в этом разделе, чтобы создать хранилище ключей.
  2. Создайте псевдоним и загрузите в него пару сертификат/ключ. Способ загрузки сертификата и ключа зависит от формата пары сертификат/ключ. В следующих разделах описывается, как загрузить каждый тип пары сертификат/ключ:

Чтобы создать хранилище ключей, укажите имя хранилища ключей в 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, где последний сертификат должен быть подписан корневым центром сертификации. Сертификаты должны быть добавлены в файл 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 самозаверяющего сертификата , чтобы создать самозаверяющий сертификат и ключ и загрузить их в псевдоним. Следующий вызов указывает только необходимую информацию для создания самозаверяющего сертификата. Вы можете изменить этот вызов, чтобы добавить дополнительную информацию:

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-интерфейсы, которые вы используете для создания хранилища доверенных сертификатов, такие же, как и для создания хранилища ключей. Единственное отличие состоит в том, что в хранилище доверенных сертификатов вы загружаете только файл сертификата в виде PEM-файла.

Если сертификат является частью цепочки, вам необходимо либо загрузить все сертификаты в цепочке отдельно в хранилище доверенных сертификатов, либо создать один файл, содержащий все сертификаты. Вы должны вставить пустую строку между каждым сертификатом в файле.

Если вы хотите загрузить несколько самозаверяющих сертификатов, которые не являются частью цепочки, используйте тот же метод: если вы хотите доверять нескольким сертификатам, загрузите их в один файл.

Окончательный сертификат обычно подписывается эмитентом сертификата. Например, в хранилище доверенных сертификатов вы загружаете сертификат клиента client_cert_1 и сертификат издателя сертификата клиента ca_cert.

Во время двусторонней аутентификации TLS аутентификация клиента завершается успешно, когда сервер отправляет client_cert_1 клиенту в рамках процесса установления связи TLS.

Альтернативно у вас есть второй сертификат client_cert_2, подписанный тем же сертификатом ca_cert. Однако вы не загружаете client_cert_2 в хранилище доверенных сертификатов. Хранилище доверенных сертификатов по-прежнему содержит client_cert_1 и ca_cert.

Когда сервер передает client_cert_2 в рамках подтверждения TLS, запрос выполняется успешно. Это связано с тем, что Edge позволяет пройти проверку TLS успешно, если client_cert_2 не существует в хранилище доверенных сертификатов, но был подписан сертификатом, существующим в хранилище доверенных сертификатов. Если вы удалите сертификат CA ca_cert из хранилища доверенных сертификатов, проверка TLS завершится неудачно.

Создайте пустое хранилище доверенных сертификатов в среде с помощью 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

После создания хранилища доверенных сертификатов загрузите сертификат в виде файла PEM в хранилище доверенных сертификатов с помощью 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.

Получите подробную информацию о существующем хранилище ключей или хранилище доверенных сертификатов.

Проверьте свою среду на наличие существующих хранилищ ключей с помощью API List Keystores and Truststores :

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

Для облачных клиентов хранилище ключей по умолчанию предоставляется организациям с бесплатной пробной версией как в тестовой, так и в рабочей среде. Вы должны увидеть следующие результаты для этого вызова для обеих сред:

[ "freetrial" ]

Вы можете использовать это хранилище ключей по умолчанию для тестирования своих API и внедрения своих API в рабочую среду, но перед развертыванием в рабочей среде обычно вы создаете собственное хранилище ключей с собственным сертификатом и ключом.

Для клиентов частного облака возвращаемый массив пуст, пока вы не создадите свое первое хранилище ключей.

Проверьте содержимое хранилища ключей с помощью 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 в свой центр сертификации для получения нового сертификата. Чтобы создать CSR для псевдонима, используйте API создания 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.

При использовании двустороннего TLS для входящих соединений , то есть запроса API в Edge, хранилище доверенных сертификатов содержит цепочку сертификатов или ЦС для каждого клиента, которому разрешено отправлять запросы к Edge.

При первоначальной настройке хранилища доверенных сертификатов вы можете добавить все сертификаты для известных клиентов. Однако со временем вам может потребоваться добавить дополнительные сертификаты в хранилище доверенных сертификатов по мере добавления новых клиентов.

Чтобы добавить новые сертификаты в хранилище доверенных сертификатов, используемое для двустороннего TLS:

  1. Убедитесь, что вы используете ссылку на хранилище доверенных сертификатов на виртуальном хосте.
  2. Загрузите новый сертификат в хранилище доверенных сертификатов, как описано выше в разделе Создание хранилища доверенных сертификатов .

  3. Обновите ссылку на хранилище доверенных сертификатов, чтобы установить для нее то же значение. Это обновление заставляет Edge перезагрузить хранилище доверенных сертификатов и новый сертификат.

    Дополнительную информацию см. в разделе Изменение ссылки .

Удаление хранилища ключей/доверенного хранилища или псевдонима

Вы должны соблюдать осторожность при удалении хранилища ключей/доверенного хранилища или псевдонима. Если вы удалите хранилище ключей, хранилище доверенных сертификатов или псевдоним, который используется виртуальным хостом, целевой конечной точкой или целевым сервером, все вызовы API через виртуальный хост или целевую конечную точку/целевой сервер завершатся ошибкой.

Обычно для удаления хранилища ключей/доверенного хранилища или псевдонима используется следующий процесс:

  1. Создайте новое хранилище ключей/доверенное хранилище или псевдоним, как описано выше.
  2. Для входящих подключений , то есть запроса API в Edge, обновите конфигурацию виртуального хоста, чтобы она ссылалась на новое хранилище ключей и псевдоним ключа.
  3. Для исходящих подключений , то есть от Apigee к внутреннему серверу:
    1. Обновите конфигурацию TargetEndpoint для всех прокси-серверов API, которые ссылались на старое хранилище ключей и псевдоним ключа, чтобы они ссылались на новое хранилище ключей и псевдоним ключа. Если ваша TargetEndpoint ссылается на TargetServer, обновите определение TargetServer, чтобы оно ссылалось на новое хранилище ключей и псевдоним ключа.
    2. Если на хранилище ключей и хранилище доверенных сертификатов имеются ссылки непосредственно из определения TargetEndpoint, необходимо повторно развернуть прокси-сервер. Если TargetEndpoint ссылается на определение TargetServer, а определение TargetServer ссылается на хранилище ключей и хранилище доверенных сертификатов, то повторное развертывание прокси-сервера не требуется.
    3. Убедитесь, что ваши прокси API работают правильно.
    4. Удалите хранилище ключей/доверенное хранилище или псевдоним.

Дополнительные сведения см. в разделе Обновление сертификата в псевдониме .

Удаление хранилища ключей или хранилища доверенных сертификатов

Вы можете удалить хранилище ключей или хранилище доверенных сертификатов с помощью API удаления хранилища ключей или хранилища доверенных сертификатов :

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

Если вы удалите и заново создадите хранилище ключей или хранилище доверенных сертификатов, которое используется виртуальным хостом, вам необходимо повторно развернуть свои прокси-серверы 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}