Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация
В этом документе рассказывается, как создавать, изменять и удалять хранилища ключей и доверенные хранилища для Edge версии 4.17.09 и более ранних версий для частного облака.
Хранилища ключей и доверенных сертификатов
Хранилища ключей и доверия определяют репозитории сертификатов безопасности, используемых для шифрования TLS. Основное различие между ними заключается в том, на каком этапе процесса рукопожатия TLS они используются:
- Хранилище ключей содержит сертификат TLS и закрытый ключ, используемые для идентификации объекта во время рукопожатия TLS.
При одностороннем TLS, когда клиент подключается к конечной точке TLS на сервере, хранилище ключей сервера предоставляет клиенту сертификат сервера (открытый сертификат). Затем клиент проверяет сертификат в центре сертификации (ЦС), например Symantec или VeriSign.
При двустороннем TLS и клиент, и сервер поддерживают хранилище ключей с собственным сертификатом и закрытым ключом, используемым для взаимной аутентификации. - truststore содержит сертификаты, используемые для проверки сертификатов, полученных в рамках рукопожатия TLS.
При одностороннем TLS хранилище доверия не требуется, если сертификат подписан действительным центром сертификации. Если сертификат, полученный клиентом TLS, подписан действительным центром сертификации, клиент отправляет запрос в этот центр, чтобы аутентифицировать сертификат. Клиент TLS обычно использует хранилище доверия для проверки самозаверяющих сертификатов, полученных от сервера TLS, или сертификатов, не подписанных доверенным центром сертификации. В этом случае клиент заполняет хранилище доверенных сертификатов теми сертификатами, которым он доверяет. Когда клиент получает сертификат сервера, он проверяет его на соответствие сертификатам в хранилище доверенных сертификатов.
Например, клиент TLS подключается к серверу TLS, на котором используется самоподписанный сертификат. Поскольку это самозаверяющий сертификат, клиент не может проверить его в ЦС. Вместо этого клиент предварительно загружает самоподписанный сертификат сервера в хранилище доверенных сертификатов. Затем, когда клиент пытается подключиться к серверу, он использует хранилище доверенных сертификатов, чтобы проверить сертификат, полученный от сервера.
При двустороннем TLS хранилище доверия могут использовать как клиент TLS, так и сервер TLS. Хранилище доверенных сертификатов необходимо при двустороннем TLS, когда Edge выступает в качестве сервера TLS.
Сертификаты могут быть выпущены центром сертификации или подписаны самостоятельно с помощью созданного вами закрытого ключа. Если у вас есть доступ к центру сертификации, следуйте инструкциям, предоставленным этим центром, чтобы сгенерировать ключи и выпустить сертификаты. Если у вас нет доступа к центру сертификации, вы можете создать самозаверяющий сертификат с помощью одного из множества общедоступных бесплатных инструментов, например OpenSSL.
Как реализовать хранилище ключей и хранилище доверенных сертификатов в Edge
В Edge хранилище ключей содержит один или несколько JAR-файлов, в которых есть:
- Сертификат TLS в виде PEM-файла: сертификат, подписанный центром сертификации (ЦС), цепочка сертификатов, последний из которых подписан ЦС, или самоподписанный сертификат.
- Закрытый ключ в виде PEM-файла. Edge поддерживает ключи размером до 2048 бит. Кодовую фразу указывать необязательно.
Хранилище доверенных сертификатов похоже на хранилище ключей, но содержит только сертификаты в виде PEM-файлов, а не закрытые ключи.
Если сертификат входит в цепочку, хранилище ключей/доверенных сертификатов должно содержать все сертификаты из цепочки в виде отдельных PEM-файлов или одного файла. Если вы используете один файл, сертификаты должны быть расположены в следующем порядке: сначала сертификат, используемый для TLS, а затем цепочка сертификатов до сертификата ЦС. Между сертификатами в файле должна быть пустая строка.
Edge предоставляет API, который можно использовать для создания хранилищ ключей и хранилищ доверенных сертификатов. Фактические API не изменились. Разница в том, что при создании хранилища ключей вы передаете JAR-файл, содержащий сертификат и закрытый ключ. При создании хранилища доверенных сертификатов передается только сертификат в виде PEM-файла.
О формате файлов сертификата и ключа
В примерах в этом документе сертификат TLS и ключ определены как файлы PEM, которые соответствуют формату X.509. Если сертификат или секретный ключ не определен в файле PEM, его можно преобразовать в файл PEM с помощью утилит, таких как openssl.
Однако многие файлы с расширениями .crt и .key уже имеют формат PEM. Если эти файлы являются текстовыми и заключены в:
-----BEGIN CERTIFICATE----- -----END CERTIFICATE-----
Или:
-----BEGIN ENCRYPTED PRIVATE KEY----- -----END ENCRYPTED PRIVATE KEY-----
После этого файлы будут совместимы с форматом PEM, и вы сможете использовать их в хранилище ключей или доверенном хранилище, не преобразуя в файл PEM.
Если у вас есть цепочка сертификатов и вы хотите использовать ее в хранилище ключей или доверенном хранилище, вы можете объединить все сертификаты в один 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 and Truststores:
curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
Для клиентов облачных сервисов хранилище ключей по умолчанию предоставляется бесплатно для организаций с пробным периодом как в тестовой, так и в рабочей среде. В обеих средах вы должны увидеть следующие результаты:
[ "freetrial" ]
Вы можете использовать хранилище ключей по умолчанию для тестирования API и их переноса в рабочую среду, но обычно перед этим создается собственное хранилище ключей с сертификатом и ключом.
Для клиентов Private Cloud возвращаемый массив будет пустым, пока вы не создадите первое хранилище ключей.
Проверьте содержимое хранилища ключей с помощью API Get a Keystore or Truststore (Получить хранилище ключей или доверенное хранилище). Для облачного клиента должен быть виден один сертификат 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:
- Войдите в интерфейс управления Edge на странице https://enterprise.apigee.com (облако) или
http://<ms-ip>:9000(локальная версия), где<ms-ip>– IP-адрес узла сервера управления. - В меню интерфейса управления Edge выберите Admin > TLS Certificates (Администратор > Сертификаты TLS).
Как получить сведения о сертификате TLS
Вы можете использовать API Get Cert Details from a Keystore or Truststore, чтобы посмотреть сведения о TLS-сертификатах в хранилище ключей, например дату окончания срока действия и издателя. Сначала узнайте название сертификата, который вас интересует. В этом примере извлекается информация о хранилище ключей с названием 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="GoDaddy.com, Inc.", 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:
- Войдите в интерфейс управления Edge на странице https://enterprise.apigee.com (облако) или
http://<ms-ip>:9000(локальная версия), где<ms-ip>– IP-адрес узла сервера управления. - В меню интерфейса управления Edge выберите Admin > TLS Certificates (Администратор > Сертификаты TLS).
В интерфейсе Edge можно указать, за какой период до истечения срока действия сертификата Edge должен сообщать об этом. По умолчанию в интерфейсе выделяются сертификаты, срок действия которых истекает в течение следующих 10 дней.
Как создать хранилище ключей
Хранилище ключей относится к определенной среде в вашей организации, например тестовой или производственной. Поэтому, если вы хотите протестировать хранилище ключей в тестовой среде, прежде чем развертывать его в рабочей среде, вам нужно создать его в обеих средах.
Создание хранилища ключей состоит из двух этапов:
- Создайте JAR-файл, содержащий сертификат и закрытый ключ.
- Создайте хранилище ключей и загрузите 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
Как создать хранилище ключей и загрузить JAR-файл
Чтобы создать хранилище ключей в среде, достаточно указать его название в API Create a Keystore or 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-файлы, содержащие сертификат и закрытый ключ, с помощью API Загрузка JAR-файла в хранилище ключей:
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– пароль для закрытого ключа. Если у закрытого ключа нет пароля, этот параметр можно не указывать.
Проверьте, правильно ли загружено хранилище ключей:
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, которые вы используете для создания хранилища доверенных сертификатов, те же, что и для создания хранилища ключей. Единственное отличие в том, что файл сертификата передается как PEM-файл, а не JAR-файл.
Если сертификат входит в цепочку, загрузите все сертификаты из цепочки в хранилище доверенных сертификатов по отдельности или создайте один файл, содержащий все сертификаты, и добавьте новую строку между каждым сертификатом в файле. Обычно последний сертификат подписывается эмитентом сертификата. Например, в хранилище доверенных сертификатов вы загружаете сертификат клиента 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_cert из хранилища доверия, проверка TLS завершится неудачно.
Создайте в среде пустое хранилище доверенных сертификатов, используя Create a Keystore or Truststore – тот же API, который вы используете для создания хранилища ключей:
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
Загрузите сертификат в хранилище доверенных сертификатов в виде PEM-файла, используя API Upload a Certificate to a 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 Удаление хранилища ключей или доверенного хранилища:
curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password
Пример ответа
{ "certs" : [ ], "keys" : [ ], "name" : "myKeystoreName" }
Если вы удалите хранилище ключей или доверенное хранилище, которое используется виртуальным хостом или целевой конечной точкой/целевым сервером, все вызовы API через виртуальный хост или целевую конечную точку/целевой сервер будут завершаться ошибкой.