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

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

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

Введение

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

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

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

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

Для создания хранилища ключей в среде:

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

Для создания хранилища ключей укажите его имя в 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 . Затем создайте в каталоге /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) ca_cert из хранилища доверенных сертификатов, проверка TLS завершится неудачей.

Создайте пустое хранилище доверенных сертификатов в среде, используя функцию «Создать хранилище ключей» или «Хранилище доверенных сертификатов» — тот же 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 «Список хранилищ ключей и доверенных сертификатов» :

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

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

[ "freetrial" ]

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

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

Проверьте содержимое хранилища ключей, используя API «Получить хранилище ключей» или «Хранилище доверенных сертификатов» . Для облачных клиентов вы должны увидеть сертификат 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 в свой центр сертификации (CA) для получения нового сертификата. Чтобы сгенерировать 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. Убедитесь, что вы используете ссылку на хранилище доверенных сертификатов (truststore) на виртуальном хосте.
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}