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

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

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

Введение

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

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

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

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

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

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

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

cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root

В каталоге, содержащем пару ключей и сертификат, создайте каталог с названием /META-INF. Затем создайте в каталоге /META-INF файл descriptor.properties со следующим содержимым:

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_cert из хранилища доверенных сертификатов, проверка TLS завершится неудачно.

Создайте в среде пустое хранилище доверенных сертификатов, используя Create a Keystore or 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 и их публикации, но обычно перед публикацией создается собственное хранилище ключей с собственным сертификатом и ключом.

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

Проверьте содержимое хранилища ключей с помощью API Get a Keystore or 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 List aliases (Список псевдонимов):

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