Пользовательский SSL-сертификат для АктивногоШлюза

Материал из Документация Ключ-АСТРОМ

Не применимо к АктивномуШлюзу Кластера Прямая загрузка SSL-сертификата в АктивныйШлюз неприменима для АктивногоШлюза Кластера. Не пытайтесь настроить SSL-сертификаты непосредственно на АктивныйШлюз Кластера. Если вы сделаете это, сертификат будет перезаписан автоматическим управлением Ключ-АСТРОМ. Для АктивныхШлюзов Кластера вы должны загрузить свои сертификаты с помощью Cluster Management Console или Cluster REST API v1.

Подключение к АктивномуШлюзу из ЕдиныхАгентов или REST API происходит по зашифрованному каналу HTTPS. АктивныйШлюз предоставляет самозаверяющий сертификат аутентификации всем подключающимся клиентам. В то время как экземпляры ЕдиногоАгента могут игнорировать действительность сертификатов АктивныхШлюзов (в зависимости от конфигурации), подключения от клиентов браузера (например, RUM JavaScript) перед отправкой данных проверяют правильность имени хоста, указанного в сертификате.

АктивныйШлюз может обслуживать пользовательский сертификат вместо сертификата по умолчанию. Чтобы настроить это, вам нужен файл в формате PKCS#12, который содержит закрытый ключ и соответствующую цепочку сертификатов.

Настройка во время установки

Эту конфигурацию также можно применить во время установки АктивногоШлюза, указав параметры установки для установок Linux или Windows.

Настройка пользовательского сертификата

Чтобы настроить АктивныйШлюз для использования пользовательского сертификата

  1. Скопируйте файл сертификата в каталог ssl и установите правильные разрешения. В Linux убедитесь, что разрешения скопированного файла сертификата включают пользователя АктивногоШлюза, которого вы назначили для запуска службы АктивногоШлюза. Если вы не указали пользовательского пользователя во время установки, пользователем по умолчанию будет dtuserag. В Windows убедитесь, что учетная запись LocalService имеет разрешения на доступ к скопированному файлу сертификата.
  2. Добавьте следующие записи в файл custom.properties в каталоге конфигурации АктивногоШлюза.
[com.compuware.apm.webserver]
certificate-file = certificate-file.p12
certificate-password = password
certificate-alias = friendly-name

Вам необходимо добавить указанные выше записи в раздел [com.compuware.apm.webserver]. Если в вашем файле custom.properties уже есть такой раздел, просто добавьте свойства в раздел. Если раздела нет, то создайте и заголовок раздела.

Пароль сертификата, который вы указываете в свойстве certificate-password, будет запутан после перезапуска основной службы АктивногоШлюза. Запутанный пароль хранится в свойстве certificate-password-encr, а исходное свойство удаляется.

Примечание:

Значение certificate-alias должно быть указано в нижнем регистре.

Если у сертификата нет понятного имени, вы можете опустить свойство certificate-alias.

Управление сертификатами через REST API

Сертификатами можно управлять удаленно через REST API. Подготовьте файл сертификата PKCS#12, и вы можете загрузить его в АктивныйШлюз с помощью REST.

Токен авторизации

Токен API необходим для авторизации. Токены API могут предоставляться через заголовки HTTP или другими способами.

Токен API, используемый для следующих действий, должен иметь разрешение ActiveGate Certificate Management.

Загрузить и активировать сертификат

Следующая точка REST загружает и активирует выбранный файл сертификата. Пароль для файла должен совпадать с паролем для ключей, содержащихся в файле, и они должны быть указаны в пользовательском HTTP-заголовке X-Password.

curl https://{address of ActiveGate}:{port}/e/{environment ID}/api/v1/certificate/{certificate file name} -H"Authorization: Api-Token {token}" -H"X-Password: {password}" -T {path to certificate file}

  • Порт настраивается, по умолчанию 9999.
  • Путь к файлу сертификата может быть просто именем локального файла или полным путем.
  • Имя сертификата, указанное в URL-адресе, не обязательно должно совпадать с именем файла.
curl https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12 -H"Authorization: Api-Token 123abc" -H"X-Password: myPassword" -T cert.p12

Если вызов API выполнен успешно, ответ HTTP будет 200 с описанием содержимого файла активированного сертификата в формате JSON.

Если вызов API завершится неудачно, ответом HTTP будет код ошибки 4xx или 5xx с обычным текстовым сообщением.

Замена активного сертификата

Вы не можете заменить активный сертификат с помощью этой конечной точки. Операция вернет HTTP 403 Forbidden. Чтобы заменить активный сертификат, загрузите новый сертификат под другим именем, а затем удалите старый сертификат.ld certificate.

Удаление сертификата

curl -XDELETE https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12 -H"Authorization: Api-Token 123abc"

Если сертификат удален успешно, вызов API ответит кодом HTTP 200 без содержимого.

Если файл с указанным именем не существует, вызов API ответит кодом HTTP 404 Not found.

Если файл сертификата в настоящее время используется, вызов API ответит кодом HTTP 403 Forbidden.

Активация сертификата

curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/activate -H"Authorization: Api-Token 123abc" -d"{\"password\":\"pass\"}"

curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/activate -H"Authorization: Api-Token 123abc" -H"X-Password: pass"

Если сертификат успешно активирован, вызов API ответит кодом HTTP 200 с описанием содержимого файла активированного сертификата в формате JSON.

Если запрошенный файл сертификата не существует в АктивномШлюзе, вызов API ответит кодом HTTP 404.

Если предоставленный пароль не совпадает, вызов API отвечает кодом HTTP 400.

Список всех сертификатов

curl https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/list -H"Authorization: Api-Token 123abc"

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

Пример ответа: 

[
   {
      "name":"cert_demo.p12"

},
   {      "name":"cert.p12",
      "desc":[         {
            "alias":"local",
            "description":"Subject:CN=myActiveGate;Valid from:Fri Feb 15 13:16:58 CET 2019;Valid to:Sat Feb 15 13:16:58 CET 2020;Serial number:71d275dd3983c3cb9382437275dd3983c3cb93dbca"

},
         {
            "alias":"astromkey",
            "description":"Subject:CN=*.clients.astromkey.org;Valid from:Thu Feb 21 10:06:03 CET 2019;Valid to:Fri Feb 21 10:06:03 CET 2020;Serial number:6dc7008ab269ecebeed03652ce08ab269ecebeeeb33"

}

]

},
   {
      "name":"cert_key_1.p12"

}
]

Описание сертификата

Этот вызов API возвращает описание выбранного файла в формате JSON. 

curl https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token 123abc" -H"X-Password: pass"

curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token 123abc" -H"X-Password: pass"

curl -XPOST https://myActiveGate:9999/e/myEnvironmentId/api/v1/certificate/cert.p12/list -H"Authorization: Api-Token 123abc" -d"{\"password\":\"pass\"}"

Если запрошенный файл сертификата не существует в АктивномШлюзе, вызов API ответит кодом HTTP 404.

Если пароль не совпадает, вызов API отвечает кодом HTTP 400.

Пример ответа: 

{   "name":"cert.p12",
   "desc":[      {
         "alias":"local",
         "description":"Subject:CN=myActiveGate;Valid from:Fri Feb 15 13:16:58 CET 2019;Valid to:Sat Feb 15 13:16:58 CET 2020;Serial number:7137275dd398c4182437275dd3983c3cb93dbca"

},
      {
         "alias":"astromkey",
         "description":"Subject:CN=*.clients.astromkey.org;Valid from:Thu Feb 21 10:06:03 CET 2019;Valid to:Fri Feb 21 10:06:03 CET 2020;Serial number:6d2ce08ab269ecebeee7f1bd03652ce08ab269ecebeeeb33"

}

]
}

Исправление проблем

Когда файл сертификата и пароль указаны, АктивныйШлюз пытается использовать заданную конфигурацию.

  • Если файл или пароль отсутствуют, АктивныйШлюз молча вернется к конфигурации по умолчанию. Запись в журнале в обоих случаях одинакова.
  • Если АктивныйШлюз попытается использовать сконфигурированный сертификат и определит, что конфигурация непригодна для использования, он будет использовать SSL-сертификат по умолчанию и сделает следующую запись в журнале:
UTC WARNING [<1>] [CollectorImpl] Unusable custom SSL config, falling back to default.

АктивныйШлюз дополнительно регистрирует причину, по которой он не может использовать настроенный сертификат. Например, если псевдоним не соответствует содержимому файла, АктивныйШлюз запишет в лог-файл запись: 

UTC SEVERE [<1>] [SSLEnvironment] missing configured-alias entry in keystore:/var/lib/astromkey/gateway/config/../ssl/cert-file.p12, available aliases: available-alias,

Создание файла сертификата для тестирования

Чтобы создать файл самоподписанного сертификата PKCS#12 для тестирования,

  • Сгенерируйте ключ и самоподписанный сертификат:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -subj "/CN=localhost"

  • Преобразуйте сгенерированные файлы в формат PKCS#12, устанавовив понятное имя -name friendly-name в нижнем регистре:
openssl pkcs12 -export -inkey key.pem -in cert.pem -out cert_key.p12

Известные ограничения и поддержка нескольких сертификатов

  • Пароль для файла PKCS#12 должен совпадать с паролем для ключа, содержащегося в этом файле. Не используйте параметр -twopass в команде openssl pkcs12.
  • Невозможно использовать несколько файлов сертификатов: может быть только один файл сертификата АктивногоШлюза, хотя файл может содержать несколько сертификатов и ключей.
Источник — https://doc.ruscomtech.ru/index.php?title=Пользовательский_SSL-сертификат_для_АктивногоШлюза&oldid=3142