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

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

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

Хранилища ключей и доверенных сертификатов, а также виртуальные хосты для Edge Cloud

При создании хранилищ ключей и доверенных хранилищ для Edge Cloud необходимо соблюдать все правила использования виртуальных хостов. Например, при использовании виртуальных хостов в облаке:

• Виртуальные хосты должны использовать TLS.
• Виртуальные хосты могут использовать только порт 443.
• Необходимо использовать подписанный сертификат TLS. В облаке нельзя использовать неподписанные сертификаты с виртуальными хостами.
• Доменное имя, указанное в сертификате TLS, должно совпадать с псевдонимом хоста виртуального хоста.

Подробнее…

• О TLS/SSL
• Использование TLS с Edge
• Часто задаваемые вопросы о настройке виртуальных хостов
• О виртуальных хостах

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

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

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

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

• Хранилище ключей – объект keystore, содержащий один или несколько псевдонимов, каждый из которых содержит пару сертификата и ключа.
• truststore – объект хранилища ключей, который содержит один или несколько псевдонимов, где каждый псевдоним содержит только сертификат.

При настройке TLS для виртуального хоста или целевой конечной точки хранилища ключей и хранилища доверенных сертификатов выполняют разные роли в процессе установления TLS-соединения. При настройке виртуального хоста или целевой конечной точки вы указываете хранилища ключей и доверенные хранилища отдельно в теге <SSLInfo>, как показано ниже для виртуального хоста:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

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

Если требуется хранилище доверия, например для двусторонней конфигурации TLS, используйте тег <TrustStore>, чтобы указать хранилище доверия:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://truststoreref</TrustStore>
    </SSLInfo>
</VirtualHost>

В этом примере тег <TrustStore> ссылается только на хранилище ключей, но не указывает определенный псевдоним. Каждый псевдоним в хранилище ключей содержит сертификат или цепочку сертификатов, которые используются в процессе установления TLS-соединения.

Поддерживаемые форматы сертификатов

* Мы рекомендуем использовать формат PEM, если это возможно.

Использование хранилищ ключей PKCS12 с Edge для частного облака версии 4.53.00 или более поздней

Если вы используете Edge для частного облака версии 4.53.00 или более поздней, для загрузки ключей и связанных сертификатов в Apigee следует использовать только хранилище ключей PKCS12. Информацию о том, как преобразовать существующие ключи и сертификаты в формат PKCS12/PFX, можно найти в разделе Преобразование сертификатов в поддерживаемый формат.

Как реализовать псевдоним

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

• Сертификат TLS в виде файла PEM или PKCS12/PFX – сертификат, подписанный центром сертификации, файл, содержащий цепочку сертификатов, последний из которых подписан центром сертификации, или сертификат с собственной подписью.
• Закрытый ключ в виде файла PEM или PKCS12/PFX. Edge поддерживает ключи размером до 2048 бит. Кодовую фразу указывать необязательно.

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

• Сертификат TLS в виде PEM-файла: сертификат, подписанный центром сертификации (ЦС), цепочка сертификатов, последний из которых подписан ЦС, или самоподписанный сертификат.

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

О формате файлов сертификата и ключа

Сертификаты и ключи можно представить в виде файлов PEM или PKCS12/PFX. 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-----

Если ваши сертификаты представлены в виде файлов PKCS12/PFX, вы можете использовать команду openssl, чтобы создать файл PKCS12/PFX из цепочки сертификатов, как показано ниже:

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt

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

Особенности использования FIPS

Если вы используете Edge для частного облака версии 4.53.00 или более поздней в ОС с поддержкой FIPS, для загрузки ключей и связанных сертификатов в Apigee следует использовать только хранилище ключей PKCS12.

Страница хранилищ ключей TLS

Откроется страница хранилищ ключей TLS:

Как показано на предыдущем рисунке, на странице хранилищ ключей TLS можно:

• Выберите тип серверной среды
• Как создать хранилище ключей и псевдоним
• Тестирование и удаление хранилищ ключей
• Просматривать и удалять псевдонимы.

Как посмотреть псевдоним

Чтобы посмотреть псевдоним:

1. Как перейти на страницу хранилищ ключей TLS
2. Выберите среду (обычно prod или test).
3. Нажмите на строку, связанную с нужным псевдонимом.

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

4. Используйте кнопки в верхней части страницы, чтобы:
   • Скачайте сертификат в виде PEM-файла.
   • Создайте запрос на подпись сертификата. Если срок действия сертификата истек и вы хотите его продлить, вы можете скачать запрос на подпись сертификата (CSR). Затем отправьте CSR в центр сертификации, чтобы получить новый сертификат.
   • Обновить сертификат. Внимание! Если вы обновите сертификат, который в данный момент используется виртуальным хостом или целевым сервером/конечной точкой, вам нужно будет обратиться в службу поддержки Apigee Edge, чтобы перезапустить маршрутизаторы и процессоры сообщений. Рекомендуемый способ обновить сертификат:
     1. Создайте новое хранилище ключей или доверенное хранилище.
     2. Добавьте новый сертификат в новое хранилище ключей или доверенное хранилище.
     3. Обновите ссылку в виртуальном хосте или целевом сервере/конечной точке на хранилище ключей или доверенное хранилище. Подробнее о том, как обновить сертификат TLS для облака…
     4. Удалите псевдоним. Примечание. Если вы удалите псевдоним, который в настоящее время используется виртуальным хостом или целевой конечной точкой, то виртуальный хост или целевая конечная точка перестанут работать.

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

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

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

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

1. Как перейти на страницу хранилищ ключей TLS
2. Выберите среду (обычно prod или test).
3. Нажмите + Хранилище ключей.
4. Укажите название хранилища ключей. Название может содержать только буквы и цифры.
5. Нажмите Добавить хранилище ключей. Новое хранилище ключей появится в списке.
6. Чтобы добавить псевдоним, выполните одно из следующих действий. Также ознакомьтесь с информацией о поддерживаемых форматах файлов сертификатов.
   • Как создать псевдоним на основе сертификата (только для хранилища доверенных сертификатов)
   • Как создать псевдоним из JAR-файла (только для хранилища ключей)
   • Создание псевдонима на основе сертификата и ключа (только для хранилища ключей)
   • Как создать псевдоним из файла PKCS12/PFX (только для хранилища ключей)
   • Создание псевдонима на основе самоподписанного сертификата (только для хранилища ключей)

Создание псевдонима на основе сертификата (только для хранилища доверенных сертификатов)

Чтобы создать псевдоним на основе сертификата:

1. Как перейти на страницу хранилищ ключей TLS
2. Наведите указатель на хранилище ключей, чтобы открыть меню действий, и нажмите +.
3. Укажите название псевдонима.
4. В разделе "Сведения о сертификате" выберите Только сертификат в раскрывающемся списке "Тип".
5. Нажмите Выбрать файл рядом с полем Файл сертификата, перейдите к PEM-файлу с сертификатом и нажмите Открыть.
6. По умолчанию API проверяет, не истек ли срок действия сертификата. При необходимости выберите Разрешить использование сертификата с истекшим сроком действия, чтобы пропустить проверку.
7. Нажмите Сохранить, чтобы загрузить сертификат и создать псевдоним.

Создание псевдонима из JAR-файла (только для хранилища ключей)

Чтобы создать псевдоним из JAR-файла:

1. Как перейти на страницу хранилищ ключей TLS
2. Наведите указатель на хранилище ключей, чтобы открыть меню действий, и нажмите +.
3. Укажите название псевдонима.
4. В разделе "Сведения о сертификате" выберите JAR-файл в раскрывающемся списке "Тип".
5. Нажмите Выбрать файл рядом с пунктом JAR-файл, перейдите к JAR-файлу, содержащему сертификат и ключ, и нажмите Открыть.
6. Если у ключа есть пароль, укажите его в поле Пароль. Если пароля нет, оставьте поле пустым.
7. По умолчанию API проверяет, не истек ли срок действия сертификата. При необходимости выберите Разрешить использование сертификата с истекшим сроком действия, чтобы пропустить проверку.
8. Нажмите Сохранить, чтобы загрузить ключ и сертификат и создать псевдоним.

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

Чтобы создать псевдоним на основе сертификата и ключа:

1. Как перейти на страницу хранилищ ключей TLS
2. Наведите указатель на хранилище ключей, чтобы открыть меню действий, и нажмите +.
3. Укажите название псевдонима.
4. В разделе "Сведения о сертификате" в раскрывающемся списке "Тип" выберите Сертификат и ключ.
5. Нажмите Выбрать файл рядом с полем Файл сертификата, перейдите к PEM-файлу с сертификатом и нажмите Открыть.
6. Если у ключа есть пароль, укажите его в поле Пароль ключа. Если пароля нет, оставьте поле пустым.
7. Нажмите Выбрать файл рядом с пунктом Файл ключа, перейдите к PEM-файлу с ключом и нажмите Открыть.
8. По умолчанию API проверяет, не истек ли срок действия сертификата. При необходимости выберите Разрешить использование сертификата с истекшим сроком действия, чтобы пропустить проверку.
9. Нажмите Сохранить, чтобы загрузить ключ и сертификат и создать псевдоним.

Как создать псевдоним из файла PKCS12/PFX (только для хранилища ключей)

Чтобы создать псевдоним из файла PKCS12, содержащего сертификат и ключ:

1. Как перейти на страницу хранилищ ключей TLS
2. Наведите указатель на хранилище ключей, чтобы открыть меню действий, и нажмите +.
3. Укажите название псевдонима.
4. В разделе "Сведения о сертификате" выберите PKCS12/PFX в раскрывающемся списке "Тип".
5. Нажмите Выбрать файл рядом с пунктом PKCS12/PFX, перейдите к файлу, содержащему ключ и сертификат, и нажмите Открыть.
6. Если у ключа есть пароль, укажите пароль для файла PKCS12/PFX. Если у ключа нет пароля, оставьте поле пустым.
7. По умолчанию API проверяет, не истек ли срок действия сертификата. При необходимости выберите Разрешить использование сертификата с истекшим сроком действия, чтобы пропустить проверку.
8. Нажмите Сохранить, чтобы загрузить файл и создать псевдоним.

Как создать псевдоним на основе сертификата с собственной подписью (только для хранилища ключей)

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

Чтобы создать псевдоним на основе самоподписанного сертификата:

1. Как перейти на страницу хранилищ ключей TLS
2. Наведите указатель на хранилище ключей, чтобы открыть меню действий, и нажмите +.
3. Укажите название псевдонима.
4. В разделе "Сведения о сертификате" выберите Самоподписанный сертификат в раскрывающемся списке "Тип".
5. Заполните форму, используя таблицу ниже.
6. Нажмите Сохранить, чтобы создать пару сертификата и закрытого ключа и загрузить их в псевдоним.

В созданном сертификате будут следующие дополнительные поля:

• Издатель
  Организация, которая подписала и выпустила сертификат. Для сертификата с собственной подписью это значение CN, которое вы указали при создании сертификата.
• Срок действия
  Срок действия сертификата, представленный двумя датами: датой начала и датой окончания срока действия сертификата. Оба значения могут быть закодированы как UTCTime или GeneralizedTime.

В таблице ниже описаны поля формы.

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

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

Чтобы проверить одностороннее шифрование TLS:

1. Как перейти на страницу хранилищ ключей TLS
2. Выберите среду (обычно prod или test).
3. Наведите указатель на хранилище ключей TLS, которое нужно протестировать, чтобы открыть меню действий, и нажмите Тест. Появится диалоговое окно с названием хранилища доверенных сертификатов:
   
4. Введите имя хоста бэкенд-службы.
5. Введите номер порта TLS (обычно 443).
6. При необходимости укажите протоколы или шифры.
7. Нажмите Проверить.

Чтобы проверить двустороннее шифрование TLS:

1. Нажмите кнопку Проверить рядом с нужным хранилищем доверенных сертификатов.
2. В диалоговом окне выберите Двусторонняя в качестве типа проверки SSL. Появится следующее диалоговое окно:
   
3. Укажите название хранилища ключей, используемого в двустороннем протоколе TLS.
4. Укажите псевдоним в хранилище ключей, содержащем сертификат и ключ.
5. Введите имя хоста бэкенд-службы.
6. Введите номер порта TLS (обычно 443).
7. При необходимости укажите протоколы или шифры.
8. Нажмите Проверить.

Как добавить сертификат в хранилище доверия для двустороннего 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, а оно, в свою очередь, – на хранилище ключей и доверенное хранилище, повторное развертывание прокси-сервера не требуется.
4. Убедитесь, что прокси API работают правильно.
5. Удалите хранилище ключей/доверенных сертификатов или псевдоним.

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

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

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

Как удалить псевдоним

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

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