Ssl-context-builder#

Плагин позволяет получать сертификаты из HashiCorp Vault или из хранилищ на файловой системе и формировать SSL-контекст. Также поддерживается расширение Kafka-клиента для интеграции с HashiCorp Vault.

Предусловия#

Не требуются.

Последовательность выполнения#

Подключение#

1. Добавить актуальную версию плагина в зависимости проекта.

2. Использовать необходимые классы для построения SSLContext.

Построение контекста из хранилищ из файлов#

Используется класс ru.sbt.ss.ssl.context.builder.SSLContextBuilder:

SSLContext context = SSLContextBuilder.builder()
        .withProtocol("TLSv1.2")
        .withConscrypt()
        .withKeyPassword("123".toCharArray())
        .withKeyStorePassword("456".toCharArray())
        .withTrustStorePassword("456".toCharArray())
        .withStoreType("JKS")
        .withKeyStoreLocation(storeLocation)
        .withTrustStoreLocation(storeLocation)
        .withDnList("CN=test,OU=FPSS,O=SBT,ST=Moscow,C=RU")
        .withEndpointVerificationAlgorithm("dn")
        .build();

Параметры SSLContextBuilder#

Построение контекста из HashiCorp Vault#

Используется класс ru.sbt.ss.ssl.context.builder.VaultContextBuilder:

// SSLContext для подключения к Vault
SSLContextBuilder builder = SSLContextBuilder.builder()
        .withTrustStoreLocation("/Users/sbt-navalikhin-an/workspace/apps/vault/vaultclient.jks")
        .withTrustStorePassword("qwe123".toCharArray())
        .withProtocol("TLSv1.2");

        SSLContext context = VaultContextBuilder.builder()
        .withVaultSSLContextBuilder(builder)
        .withAuth(new PasswordAuth("test", "qwe123".toCharArray(), "userpass"))
        .withKeyStoreLocation("client.jks")
        .withKeyAlias("test-1")
        .withTrustStoreLocation("client.jks")
        .withVaultAddress("https://vault:8200/")
        .withCommonName("TestCert")
        .withAltNames(Collections.singletonList("localhost"))
        .withIpSans(Collections.singletonList("127.0.0.1"))
        .withSecretPath("kv1/certstore")
        .withKeySecret("key")
        .withKeyStoreSecret("keystore")
        .withTrustStoreSecret("truststore")
        .withIssueRoleName("test1")
        .withEngineVersion(1)
        .withProtocol("TLSv1.2").build();

Получение сертификатов из консоли#

1. Скачать ssl-context-builder-*.jar.

2. Создать файл vault.properties с параметрами подключения к HashiCorp Vault.

3. Выполнить команду:

java -jar ssl-context-builder-*.jar vault.properties

4. Сертификаты будут расположены в хранилищах из параметров ssl.keystore.location и ssl.truststore.location.

Параметры VaultContextBuilder#

Параметры подключения и авторизации в Hashicorp Vault#

Общие параметры, применимые при использовании любого типа хранилищ сертификатов и режима получения клиентского сертификата#

Параметры хранения сертификатов в JKS хранилищах#

Параметры хранения сертификатов в формате PEM#

Параметры выпуска сертификата через PKI Engine HashiCorp Vault#

Параметры получения клиентского сертификата из секрета KV Engine HashiCorp Vault#

Пример конфигурации с загрузкой параметров из файла#

Любые настройки можно загрузить из файла (в данном примере config/vault.properties):

# 1) Путь до файла с параметрами
ssl.vault.properties.file = config/vault.properties

# 2) ОПЦИОНАЛЬНО Переопределить любые настройки, загруженные из файла конфигурации
# Common name сертификата (CN)
ssl.vault.pki.common.name = OVERRIDE-TEST

# Пути до хранилищ сертификатов, сгенерированных vault
ssl.keystore.location = override-vault-keystore.jks
ssl.truststore.location = override-vault-truststore.jks

Настройка функций обратного вызова (callback) метода verify() класса ru.sbt.ss.ssl.conscrypt.DnConscryptHostnameVerifier проверки DN сертификатов#

Для настройки сallback’ов необходимо:

1. Реализовать интерфейс ru.sbt.ss.ssl.conscrypt.VerifyCallback

2. При помощи библиотеки "ssl-context-builder" (версии 1.9.4+) получения контекста передать реализацию как параметр метода withDnVerifyCallback() при создании SSLContext с помощью класса ru.sbt.ss.ssl.context.builder.SSLContextBuilder:

SSLContext context = SSLContextBuilder.builder().withProperties(properties.asJava).withDnVerifyCallback(new CustomVerifyCallback()).build()

public class CustomVerifyCallback implements VerifyCallback {
    @Override
    public void onSuccess(X509Certificate cert, String address) {
        System.out.println("Call \"onSuccess\" method");
    }

    @Override
    public void onError(X509Certificate cert, String address, Throwable cause) {
        System.out.println("Call \"onError\" method");
    }
}

По умолчанию используется дефолтная реализация интерфейса ru.sbt.ss.ssl.conscrypt.VerifyCallback с пустым телом методов onSuccess/onError:

VerifyCallback defaultCallback = new VerifyCallback() {
    @Override
    public void onSuccess(X509Certificate cert, String address) {
        // nothing by default
    }

    @Override
    public void onError(X509Certificate cert, String address, Throwable cause) {
        // nothing by default
    }
};

Загрузка ключей из Vault#

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

encryption.service.key.store.type = vault
ssl.vault.address = { IP_ADDRESS }
ssl.vault.auth.role.id = role_id
ssl.vault.auth.secret.id = secret_key
ssl.vault.secret.path = test/encryptions/keys
ssl.vault.tls.enable = true
ssl.vault.tls.truststore.location = /vault.jks
ssl.vault.tls.truststore.password = password

, где ssl.vault.secret.path – путь, откуда будет выполнена загрузка всех ключей.

Пример загрузки ключей:

Map<String, String> keys = VaultContextBuilder.builder().withProperties(proprties).buildSecretLoader();

Использование движка SberCA#

Движок SberCA аналогичен стандартному движку pki, но в дополнение к стандартному запросу issue предоставляет запрос fetch.

Разница между методами в том, что issue всегда выпускает новый сертификат, а fetch выпускает новый сертификат только если сертификат не существует или истек. Во всем остальном запросы и настройки идентичны.

Для использования метода fetch используется настройка ssl.vault.pki.method=fetch.

При использовании метода fetch:

• при каждом запуске приложения сертификат запрашивается из vault запросом SberCA/fetch;

• при наличии локального кеша полученный сертификат сравнивается сертификатом в локальном кеше, используя fingerprint – по умолчанию SHA-256 хеш от сертификата;

• если fingerprint полученного сертификата отличается от сертификата в локальном кеше – сертификат перезаписывается.

Результат#

Выполнено подключение плагина Ssl-context-builder.