diff --git a/.gitignore b/.gitignore index 5c0d927a..6e64eb74 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ package-lock.json fio qemu +node_modules diff --git a/README-ru.md b/README-ru.md index 95e581cc..3fa2712e 100644 --- a/README-ru.md +++ b/README-ru.md @@ -62,6 +62,7 @@ Vitastor поддерживает QEMU-драйвер, протоколы UBLK, - [Дисковые параметры OSD](docs/config/layout-osd.ru.md) - [Прочие параметры OSD](docs/config/osd.ru.md) - [Параметры мониторов](docs/config/monitor.ru.md) + - [Безопасность](docs/config/security.ru.md) - [Настройки пулов](docs/config/pool.ru.md) - [Метаданные образов в etcd](docs/config/inode.ru.md) - Использование diff --git a/README.md b/README.md index 63b12bf8..61c07584 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,7 @@ Read more details in the documentation. You can start from here: [Quick Start](d - [OSD Disk Layout](docs/config/layout-osd.en.md) - [OSD Runtime Parameters](docs/config/osd.en.md) - [Monitor](docs/config/monitor.en.md) + - [Security](docs/config/security.en.md) - [Pool configuration](docs/config/pool.en.md) - [Image metadata in etcd](docs/config/inode.en.md) - Usage diff --git a/docs/config.en.md b/docs/config.en.md index aff93ea4..5a7a1570 100644 --- a/docs/config.en.md +++ b/docs/config.en.md @@ -38,3 +38,4 @@ In the future, additional configuration methods may be added: - [OSD Disk Layout](config/layout-osd.en.md) - [OSD Runtime Parameters](config/osd.en.md) - [Monitor](config/monitor.en.md) +- [Security Parameters](config/security.en.md) diff --git a/docs/config.ru.md b/docs/config.ru.md index a67316cf..2628465d 100644 --- a/docs/config.ru.md +++ b/docs/config.ru.md @@ -41,3 +41,4 @@ - [Дисковые параметры OSD](config/layout-osd.ru.md) - [Прочие параметры OSD](config/osd.ru.md) - [Параметры мониторов](config/monitor.ru.md) +- [Параметры безопасности](config/security.ru.md) diff --git a/docs/config/layout-osd.en.md b/docs/config/layout-osd.en.md index 524b21d1..cad393ab 100644 --- a/docs/config/layout-osd.en.md +++ b/docs/config/layout-osd.en.md @@ -198,8 +198,14 @@ put a modified value into etcd key /vitastor/config/global. - Type: string - Default: none -Data checksum type to use. May be "crc32c" or "none". Set to "crc32c" to -enable data checksums. +Data and metadata checksum type to use. May be "crc32c", "xxh3_32" or "none". +Select crc32c or xxh3_32 and set csum_block_size to enable data checksums. + +Both crc32c and xxh3_32 are almost equally fast, xxh3_32 is safer. xxh3_32 is +the xxhash3 algorithm truncated from 64 to 32 bits (which is still a good hash). + +Note that enabled data checksums either increase memory usage or reduce +performance. Check details in [csum_block_size](#csum_block_size) description. ## csum_block_size diff --git a/docs/config/layout-osd.ru.md b/docs/config/layout-osd.ru.md index 1b40768f..44ddfdee 100644 --- a/docs/config/layout-osd.ru.md +++ b/docs/config/layout-osd.ru.md @@ -209,8 +209,12 @@ journal_block_size и meta_block_size. Однако на данный момен - Тип: строка - Значение по умолчанию: none -Тип используемых OSD контрольных сумм данных. Может быть "crc32c" или "none". -Установите в "crc32c", чтобы включить расчёт и проверку контрольных сумм данных. +Тип используемых OSD контрольных сумм данных и метаданных. Может быть "crc32c", +"xxh3_32" или "none". Выберите crc32c или xxh3_32 и установите csum_block_size, +чтобы включить контрольные суммы данных. + +И crc32c, и xxh3_32 примерно одинаково быстры, xxh3_32 надёжней. xxh3_32 - это +алгоритм xxhash3, обрезанный с 64 до 32 бит (это всё равно хороший хеш). Следует понимать, что контрольные суммы в зависимости от размера блока их расчёта либо увеличивают потребление памяти, либо снижают производительность. diff --git a/docs/config/monitor.en.md b/docs/config/monitor.en.md index a7b072ab..6be7b18c 100644 --- a/docs/config/monitor.en.md +++ b/docs/config/monitor.en.md @@ -50,6 +50,9 @@ or antietcd_data_dir options). All other antietcd parameters cluster, cluster_key, persist_filter, stale_read can also be set in Vitastor configuration with `antietcd_` prefix. +See also: [antietcd_cert](security.en.md#antietcd_cert), +[antietcd_key](security.en.md#antietcd_key) and [etcd_proxy](security.en.md#etcd_proxyurls). + You can dump/load data to or from antietcd using Antietcd `anticli` tool: ``` diff --git a/docs/config/monitor.ru.md b/docs/config/monitor.ru.md index 81c8d438..e40b0316 100644 --- a/docs/config/monitor.ru.md +++ b/docs/config/monitor.ru.md @@ -50,6 +50,9 @@ antietcd_data_file или antietcd_data_dir). Все остальные пара node_id, cluster, cluster_key, persist_filter, stale_read также можно задавать в конфигурации Vitastor с префиксом `antietcd_`. +Смотрите также настройки [antietcd_cert](security.ru.md#antietcd_cert), +[antietcd_key](security.ru.md#antietcd_key) и [etcd_proxy](security.ru.md#etcd_proxyurls). + Вы можете выгружать/загружать данные в или из antietcd с помощью его инструмента `anticli`: diff --git a/docs/config/security.en.md b/docs/config/security.en.md new file mode 100644 index 00000000..903933e4 --- /dev/null +++ b/docs/config/security.en.md @@ -0,0 +1,306 @@ +[Documentation](../../README.md#documentation) → [Configuration](../config.en.md) → Security Parameters + +----- + +[Читать на русском](security.ru.md) + +# Security Parameters + +These parameters affect your Vitastor installation security and apply to OSDs, monitors and clients. + +Most of them can be set in /etc/vitastor/vitastor.conf and in etcd, but don't support online modification. + +All certificate and private key parameters mentioned may contain a path to a PEM file or just +a PEM string with certificate or a private key. In the latter case, the string must begin with +"-----BEGIN CERTIFICATE-----" or "-----BEGIN PRIVATE KEY-----". + +- [use_perms](#use_perms) +- [cert](#cert) +- [pkey](#pkey) +- [etcd_ca](#etcd_ca) +- [client_ca](#client_ca) +- [osd_ca](#osd_ca) +- [mon_ca](#mon_ca) +- [antietcd_cert](#antietcd_cert) +- [antietcd_key](#antietcd_key) +- [etcd_proxy.urls](#etcd_proxyurls) +- [etcd_proxy.cert](#etcd_proxycert) +- [etcd_proxy.key](#etcd_proxykey) +- [etcd_proxy.ca](#etcd_proxyca) +- [osd_cert](#osd_cert) +- [osd_pkey](#osd_pkey) +- [api_cert](#api_cert) +- [api_pkey](#api_pkey) +- [etcd_client_cert](#etcd_client_cert) +- [etcd_client_key](#etcd_client_key) +- [osd_etcd_client_cert](#osd_etcd_client_cert) +- [osd_etcd_client_key](#osd_etcd_client_key) +- [mon_etcd_client_cert](#mon_etcd_client_cert) +- [mon_etcd_client_key](#mon_etcd_client_key) +- [proto_checksums](#proto_checksums) +- [force_proto_checksums](#force_proto_checksums) +- [max_cipher_pool_size](#max_cipher_pool_size) +- [vault_url](#vault_url) +- [vault_secret_api_path](#vault_secret_api_path) +- [vault_client_cert](#vault_client_cert) +- [vault_client_key](#vault_client_key) +- [vault_ca](#vault_ca) +- [vault_timeout_ms](#vault_timeout_ms) +- [vault_error_timeout_sec](#vault_error_timeout_sec) +- [vault_refresh_leeway_sec](#vault_refresh_leeway_sec) + +## use_perms + +- Type: boolean +- Default: false + +Enable client permissions in a Vitastor cluster, including Antietcd built into the Monitor. +Requires configured encryption. Also note that separate Antietcd requires separate configuration +to use permissions (see [security documentation](../intro/security.en.md) for details). + +## cert + +- Type: string + +Client certificate of the current Vitastor user. Required for Vitastor protocol encryption. +Must be signed with [client_ca](#client_ca). Also used as the client certificate for etcd/Antietcd +connections by default. + +## pkey + +- Type: string + +Private key of the current Vitastor user. + +## etcd_ca + +- Type: string + +Trusted TLS CA to verify etcd server certificate. Or just the etcd server's +certificate itself - it's fine to use it for etcd_ca. + +## client_ca + +- Type: string + +Trusted TLS CA to verify Vitastor client certificates. +Mandatory for Vitastor protocol encryption. + +## osd_ca + +- Type: string + +Trusted TLS CA to verify Vitastor OSD certificates. Also mandatory for Vitastor protocol +encryption. Must be different from client_ca. May be equal to osd_cert - different OSDs +don't require separate certificates at the moment because their permissions don't differ. + +## mon_ca + +- Type: string + +Trusted TLS CA to verify Vitastor Monitor certificates. Used only for separate Antietcd, +not required when a monitor built-in Antietcd is used. May be equal to mon_client_etcd_cert. + +## antietcd_cert + +- Type: string + +Server TLS certificate for Antietcd built into the Monitor. + +## antietcd_key + +- Type: string + +Private key for antietcd_cert. + +## etcd_proxy.urls + +- Type: string or array of strings + +etcd URLs for Antietcd etcd proxy mode. +See [Mon as Etcd proxy](../intro/security.en.md#mon-as-etcd-proxy) for details. + +## etcd_proxy.cert + +- Type: string + +Client certificate for Antietcd connections to etcd in proxy mode. + +## etcd_proxy.key + +- Type: string + +Private key for etcd_proxy.cert. + +## etcd_proxy.ca + +- Type: string + +Trusted TLS CA to verify etcd server certificate when connecting to it from Antietcd. + +## osd_cert + +- Type: string + +Vitastor OSD server certificate. Required for Vitastor protocol encryption. May be equal +to [osd_ca](#osd_ca) - all OSDs share the same permission set for now. Also used as the client +certificate for connections from OSD to etcd/Antietcd by default. + +## osd_pkey + +- Type: string + +Private key for osd_cert. + +## api_cert + +- Type: string + +Server TLS certificate for [vitastor-cli serve](../usage/cli.en.md#serve) API server. + +## api_pkey + +- Type: string + +Private key for api_cert. + +## etcd_client_cert + +- Type: string + +Client TLS certificate to use for connections from Vitastor clients to etcd/Antietcd if you don't want +to use the common client certificate [cert](#cert). + +## etcd_client_key + +- Type: string + +Private key for etcd_client_cert. + +## osd_etcd_client_cert + +- Type: string + +Client TLS certificate to use for connections from Vitastor OSDs to etcd/Antietcd if you don't want +to use the common OSD certificate [osd_cert](#osd_cert). + +## osd_etcd_client_key + +- Type: string + +Private key for osd_etcd_client_cert. + +## mon_etcd_client_cert + +- Type: string + +Client TLS certificate to use for connections from Vitastor Monitors to etcd/Antietcd - required +if you don't use the built-in Antietcd. In case you use it Monitor has direct access to Antietcd data +and doesn't require any connection. + +## mon_etcd_client_key + +- Type: string + +Private key for mon_etcd_client_cert. + +## proto_checksums + +- Type: string +- Default: payload + +One of "full", "payload", "gcm", "none": +- "full" means calculate and verify transport level checksums from the full message data + including the header - recommended for unencrypted setups. +- "payload" enables checksums only for the actual read/write data, but skips them for message + headers - recommended for encrypted setups because headers are already protected by AES-GCM. +- "gcm" disables checksums and enables AES-GCM encryption of the whole messages including headers + and data - AES-GCM already includes MAC which is actually a stronger checksum. This option is + slower and is only recommended for untrusted networks. +- "none" disables transport level checksums at all. + +## force_proto_checksums + +- Type: string + +To allow older clients to connect to a Vitastor cluster with enabled checksums, Vitastor OSDs +allow clients to downgrade their proto_checksums by default. force_proto_checksums sets the +minimum security level allowed for connecting clients. When encryption is disabled, default +force_proto_checksums is none and clients without checksums are allowed. With enabled +encryption, force_proto_checksums becomes "payload" by default to block unauthenticated data +on the transport level. + +## max_cipher_pool_size + +- Type: integer +- Default: 256 + +Maximum number of OpenSSL cipher contexts cached in OSD memory, counted separately +for each cipher and for encryption/decryption. Probably doesn't require modification. + +## vault_url + +- Type: string + +Vault base URL. + +Vitastor clients support AES-256-XTS image data encryption with different per-image keys. +Encryption is performed by the client, OSDs don't have access to decrypted data. + +Encryption keys may be stored in etcd or, for the increased security level, in an external +[HashiCorp Vault](https://developer.hashicorp.com/vault/) or [OpenBao](https://openbao.org/) +instance. + +Vitastor clients use [v1 k/v secrets engine](https://openbao.org/api-docs/secret/kv/kv-v1/) +and [TLS authentication engine](https://openbao.org/api-docs/auth/cert/) in Vault. + +In that case, only key IDs are stored in etcd. + +## vault_secret_api_path + +- Type: string +- Default: /v1/secret/ + +Vault v1 secret API mount path to use. + +## vault_client_cert + +- Type: string + +Client TLS certificate to use for Vault connections if you don't want to use the common Vitastor +client certificate [cert](#cert) which is also used for Vault connections by default. + +## vault_client_key + +- Type: string + +Private key for the vault_client_cert certificate. + +## vault_ca + +- Type: string + +Trusted TLS CA to verify Vault server certificate. May be path to a file, +directory or just a PEM string with certificate. + +## vault_timeout_ms + +- Type: integer +- Default: 5000 + +Timeout for Vault requests in milliseconds. + +## vault_error_timeout_sec + +- Type: integer +- Default: 60 + +Time (in seconds) to wait before retrying after receiving an error from Vault. + +## vault_refresh_leeway_sec + +- Type: integer +- Default: 60 + +Extra time (in seconds) before real Vault token lease_timeout to refresh it, just +in case of system clock drift. diff --git a/docs/config/security.ru.md b/docs/config/security.ru.md new file mode 100644 index 00000000..111df91e --- /dev/null +++ b/docs/config/security.ru.md @@ -0,0 +1,312 @@ +[Документация](../../README-ru.md#документация) → [Конфигурация](../config.ru.md) → Параметры безопасности + +----- + +[Read in English](security.en.md) + +# Параметры безопасности + +Данные параметры затрагивают безопасность инсталляций Vitastor и используются +OSD, мониторами и клиентами. + +Большая их часть может задаваться в /etc/vitastor/vitastor.conf и в etcd, но не +поддерживает онлайн-изменение. + +Все параметры сертификатов и закрытых ключей могут быть путём к файлу или просто +строкой с сертификатом в формате PEM. В последнем случае строка должна начинаться с +"-----BEGIN CERTIFICATE-----" или "-----BEGIN PRIVATE KEY-----". + +- [use_perms](#use_perms) +- [cert](#cert) +- [pkey](#pkey) +- [etcd_ca](#etcd_ca) +- [client_ca](#client_ca) +- [osd_ca](#osd_ca) +- [mon_ca](#mon_ca) +- [antietcd_cert](#antietcd_cert) +- [antietcd_key](#antietcd_key) +- [etcd_proxy.urls](#etcd_proxyurls) +- [etcd_proxy.cert](#etcd_proxycert) +- [etcd_proxy.key](#etcd_proxykey) +- [etcd_proxy.ca](#etcd_proxyca) +- [osd_cert](#osd_cert) +- [osd_pkey](#osd_pkey) +- [api_cert](#api_cert) +- [api_pkey](#api_pkey) +- [etcd_client_cert](#etcd_client_cert) +- [etcd_client_key](#etcd_client_key) +- [osd_etcd_client_cert](#osd_etcd_client_cert) +- [osd_etcd_client_key](#osd_etcd_client_key) +- [mon_etcd_client_cert](#mon_etcd_client_cert) +- [mon_etcd_client_key](#mon_etcd_client_key) +- [proto_checksums](#proto_checksums) +- [force_proto_checksums](#force_proto_checksums) +- [max_cipher_pool_size](#max_cipher_pool_size) +- [vault_url](#vault_url) +- [vault_secret_api_path](#vault_secret_api_path) +- [vault_client_cert](#vault_client_cert) +- [vault_client_key](#vault_client_key) +- [vault_ca](#vault_ca) +- [vault_timeout_ms](#vault_timeout_ms) +- [vault_error_timeout_sec](#vault_error_timeout_sec) +- [vault_refresh_leeway_sec](#vault_refresh_leeway_sec) + +## use_perms + +- Тип: булево (да/нет) +- Значение по умолчанию: false + +Включает клиентские привилегии в кластере Vitastor, в том числе во встроенном в мониторе Antietcd. +Требует настроенного шифрования протокола. Также обратите внимание, что отдельно установленный Antietcd +требует отдельной настройки привилегий (подробности смотрите в [документации безопасности](../intro/security.ru.md)). + +## cert + +- Тип: строка + +Клиентский сертификат текущего пользователя Vitastor. Требуется для шифрования протокола Vitastor. +Должен быть подписан [client_ca](#client_ca). Также по умолчанию используется как клиентский +сертификат для подключения к etcd/Antietcd и Vault. + +## pkey + +- Тип: строка + +Закрытый ключ текущего пользователя Vitastor. + +## etcd_ca + +- Тип: строка + +Доверенный корневой TLS-сертификат для проверки сертификата сервера etcd. +Либо же просто сам сертификат сервера etcd - его можно использовать как etcd_ca. + +## client_ca + +- Тип: строка + +Доверенный TLS-сертификат для проверки сертификатов клиентов Vitastor. +Требуется для шифрования протокола Vitastor. + +## osd_ca + +- Тип: строка + +Доверенный TLS-сертификат для проверки сертификатов OSD Vitastor. Также обязателен +для шифрования протокола Vitastor. Должен отличаться от client_ca. Может быть равен +osd_cert - разные OSD не требуют разных сертификатов, потому что на данный момент +привилегии разных OSD никак не отличаются. + +## mon_ca + +- Тип: строка + +Доверенный TLS-сертификат для проверки сертификатов мониторов Vitastor. Используется +только отдельно установленным Antietcd, не требуется при использовании встроенного в монитор +Antietcd. Может быть равен mon_client_etcd_cert. + +## antietcd_cert + +- Тип: строка + +Серверный TLS-сертификат для Antietcd, встроенного в монитор. + +## antietcd_key + +- Тип: строка + +Закрытый ключ для сертификата antietcd_cert. + +## etcd_proxy.urls + +- Тип: строка или массив строк + +Адреса etcd для режима Antietcd etcd-прокси. +Смотрите подробности в разделе [Mon в роли Etcd proxy](../intro/security.ru.md#mon-в-роли-etcd-proxy). + +## etcd_proxy.cert + +- Тип: строка + +Клиентский сертификат для подключений от Antietcd к etcd в режиме прокси. + +## etcd_proxy.key + +- Тип: строка + +Закрытый ключ для сертификата etcd_proxy.cert. + +## etcd_proxy.ca + +- Тип: строка + +Доверенный TLS-сертификат для проверки сертификата сервера etcd при подключениях от Antietcd. + +## osd_cert + +- Тип: строка + +Сертификат сервера Vitastor OSD. Требуется для шифрования протокола Vitastor. Может быть равен +[osd_ca](#osd_ca) - все OSD на данный момент имеют одинаковые привилегии. Также по умолчанию +используется как клиентский сертификат для подключения от OSD к etcd/Antietcd. + +## osd_pkey + +- Тип: строка + +Закрытый ключ для сертификата osd_cert. + +## api_cert + +- Тип: строка + +Серверный TLS-сертификат для API-сервера [vitastor-cli serve](../usage/cli.ru.md#serve). + +## api_pkey + +- Тип: строка + +Закрытый ключ для сертификата api_cert. + +## etcd_client_cert + +- Тип: строка + +Клиентский TLS сертификат для подключений от клиентов Vitastor к etcd/Antietcd, если вы не хотите +использовать общий клиентский сертификат [cert](#cert). + +## etcd_client_key + +- Тип: строка + +Закрытый ключ для сертификата etcd_client_cert. + +## osd_etcd_client_cert + +- Тип: строка + +Клиентский TLS сертификат для подключений от Vitastor OSD к etcd/Antietcd, если вы не хотите +использовать общий сертификат OSD [osd_cert](#osd_cert). + +## osd_etcd_client_key + +- Тип: строка + +Закрытый ключ для сертификата osd_etcd_client_cert. + +## mon_etcd_client_cert + +- Тип: строка + +Клиентский TLS сертификат для подключений от мониторов Vitastor к etcd/Antietcd - требуется, если +вы не используете встроенный в монитор Antietcd. Если вы используете его, то монитор и так имеет +прямой доступ к данным Antietcd и не требует никаких соединений. + +## mon_etcd_client_key + +- Тип: строка + +Закрытый ключ для сертификата mon_etcd_client_cert. + +## proto_checksums + +- Тип: строка +- Значение по умолчанию: payload + +Одно из значений "full", "payload", "gcm" и "none": +- "full" означает расчёт и проверку контрольных сумм на транспортном уровне от полных сообщений, + включая их заголовки и данные - рекомендуется для кластеров без шифрования. +- "payload" включает контрольные суммы только для данных сообщений, но пропускает заголовки - + такая настройка рекомендуется для кластеров с включённым шифрованием, потому что в них заголовки + и так защищены шифрованием AES-GCM. +- "gcm" отключает контрольные суммы и включает шифрование полных сообщений включая заголовки и + данные - AES-GCM уже включает в себя MAC, который по сути является криптостойкой контрольной + суммой. Такая настройка медленнее и рекомендуется только для недоверенных сетей. +- "none" полностью отключает контрольные суммы на транспортном уровне. + +## force_proto_checksums + +- Тип: строка + +Чтобы старые клиенты Vitastor могли подключаться к кластеру с включёнными контрольными +суммами, Vitastor OSD по умолчанию разрешают клиентам отключать контрольные суммы +данных (proto_checksums). Настройка force_proto_checksums задаёт минимальный уровень +безопасности, разрешённый для подключающихся клиентов. Когда шифрование отключено, +force_proto_checksums по умолчанию равно none и подключения клиентов без контрольных +сумм разрешаются. При включённом шифровании значение по умолчанию force_proto_checksums +становится "payload", чтобы блокировать подключения с неаутентифицированными данными. + +## max_cipher_pool_size + +- Тип: целое число +- Значение по умолчанию: 256 + +Максимальное количество кэшируемых в памяти OSD контекстов шифра OpenSSL, учитываемое +отдельно для каждого шифра и для шифрования и расшифровки. Вряд ли требует изменения. + +## vault_url + +- Тип: строка + +Базовый адрес Vault. + +Клиенты Vitastor поддерживают AES-256-XTS шифрование данных образов с отдельными ключами на +каждый образ. Данные шифруются клиентами, OSD не имеют доступа к незашифрованным данным. + +Ключи шифрования могут храниться в etcd или, для повышенного уровня безопасности, во внешнем +[HashiCorp Vault](https://developer.hashicorp.com/vault/) или [OpenBao](https://openbao.org/). + +Клиенты Vitastor используют [движок секретов v1](https://openbao.org/api-docs/secret/kv/kv-v1/) +и [TLS-аутентификацию](https://openbao.org/api-docs/auth/cert/) в Vault. + +В этом случае, только ID ключей хранятся в etcd. + +## vault_secret_api_path + +- Тип: строка +- Значение по умолчанию: /v1/secret/ + +Путь к API секретов v1 для использования клиентами. + +## vault_client_cert + +- Тип: строка + +Клиентский TLS сертификат для подключений к Vault на тот случай, если вы не хотите использовать +общий сертификат клиента Vitastor [cert](#cert), используемый для подключений к Vault по умолчанию. + +## vault_client_key + +- Тип: строка + +Закрытый ключ для сертификата vault_client_cert. + +## vault_ca + +- Тип: строка + +Доверенный корневой TLS-сертификат для проверки сертификата сервера Vault. +Может быть путём к файлу, директории или просто строкой с сертификатом в +формате PEM. + +## vault_timeout_ms + +- Тип: целое число +- Значение по умолчанию: 5000 + +Максимально время выполнения Vault-запросов в миллисекундах. + +## vault_error_timeout_sec + +- Тип: целое число +- Значение по умолчанию: 60 + +Время (в секундах) для ожидания перед повторной попыткой при получении ошибки от Vault. + +## vault_refresh_leeway_sec + +- Тип: целое число +- Значение по умолчанию: 60 + +Зазор времени (в секундах), чтобы обновлять токены Vault чуть раньше их реального +lease_timeout, на случай "ухода" системных часов. diff --git a/docs/config/src/included.en.md b/docs/config/src/included.en.md index f8d8aa40..fb6b99e0 100644 --- a/docs/config/src/included.en.md +++ b/docs/config/src/included.en.md @@ -44,6 +44,8 @@ {{../../config/monitor.en.md|indent=2}} +{{../../config/security.en.md|indent=2}} + {{../../config/pool.en.md|indent=2}} {{../../config/inode.en.md|indent=2}} diff --git a/docs/config/src/included.ru.md b/docs/config/src/included.ru.md index 89e06171..0ff08490 100644 --- a/docs/config/src/included.ru.md +++ b/docs/config/src/included.ru.md @@ -44,6 +44,8 @@ {{../../config/monitor.ru.md|indent=2}} +{{../../config/security.ru.md|indent=2}} + {{../../config/pool.ru.md|indent=2}} {{../../config/inode.ru.md|indent=2}} diff --git a/docs/config/src/layout-osd.yml b/docs/config/src/layout-osd.yml index 4a5d28bb..e43edf19 100644 --- a/docs/config/src/layout-osd.yml +++ b/docs/config/src/layout-osd.yml @@ -233,11 +233,21 @@ type: string default: none info: | - Data checksum type to use. May be "crc32c" or "none". Set to "crc32c" to - enable data checksums. + Data and metadata checksum type to use. May be "crc32c", "xxh3_32" or "none". + Select crc32c or xxh3_32 and set csum_block_size to enable data checksums. + + Both crc32c and xxh3_32 are almost equally fast, xxh3_32 is safer. xxh3_32 is + the xxhash3 algorithm truncated from 64 to 32 bits (which is still a good hash). + + Note that enabled data checksums either increase memory usage or reduce + performance. Check details in [csum_block_size](#csum_block_size) description. info_ru: | - Тип используемых OSD контрольных сумм данных. Может быть "crc32c" или "none". - Установите в "crc32c", чтобы включить расчёт и проверку контрольных сумм данных. + Тип используемых OSD контрольных сумм данных и метаданных. Может быть "crc32c", + "xxh3_32" или "none". Выберите crc32c или xxh3_32 и установите csum_block_size, + чтобы включить контрольные суммы данных. + + И crc32c, и xxh3_32 примерно одинаково быстры, xxh3_32 надёжней. xxh3_32 - это + алгоритм xxhash3, обрезанный с 64 до 32 бит (это всё равно хороший хеш). Следует понимать, что контрольные суммы в зависимости от размера блока их расчёта либо увеличивают потребление памяти, либо снижают производительность. diff --git a/docs/config/src/make.js b/docs/config/src/make.js index 4ae5eea9..8e8e36f7 100755 --- a/docs/config/src/make.js +++ b/docs/config/src/make.js @@ -64,7 +64,7 @@ for (const file of params_files) let out = '\n'; for (const c of cfg) { - out += `\n- [${c.name}](#${c.name})`; + out += `\n- [${c.name}](#${c.name.replace(/\./g, '')})`; } for (const c of cfg) { diff --git a/docs/config/src/monitor.yml b/docs/config/src/monitor.yml index 6e9b12aa..0f586a4e 100644 --- a/docs/config/src/monitor.yml +++ b/docs/config/src/monitor.yml @@ -21,6 +21,9 @@ cluster, cluster_key, persist_filter, stale_read can also be set in Vitastor configuration with `antietcd_` prefix. + See also: [antietcd_cert](security.en.md#antietcd_cert), + [antietcd_key](security.en.md#antietcd_key) and [etcd_proxy](security.en.md#etcd_proxyurls). + You can dump/load data to or from antietcd using Antietcd `anticli` tool: ``` @@ -47,6 +50,9 @@ node_id, cluster, cluster_key, persist_filter, stale_read также можно задавать в конфигурации Vitastor с префиксом `antietcd_`. + Смотрите также настройки [antietcd_cert](security.ru.md#antietcd_cert), + [antietcd_key](security.ru.md#antietcd_key) и [etcd_proxy](security.ru.md#etcd_proxyurls). + Вы можете выгружать/загружать данные в или из antietcd с помощью его инструмента `anticli`: diff --git a/docs/config/src/package.json b/docs/config/src/package.json new file mode 100644 index 00000000..88def59c --- /dev/null +++ b/docs/config/src/package.json @@ -0,0 +1,5 @@ +{ + "dependencies": { + "yaml": "^2.8.2" + } +} diff --git a/docs/config/src/security.en.md b/docs/config/src/security.en.md new file mode 100644 index 00000000..73ae9c6c --- /dev/null +++ b/docs/config/src/security.en.md @@ -0,0 +1,9 @@ +# Security Parameters + +These parameters affect your Vitastor installation security and apply to OSDs, monitors and clients. + +Most of them can be set in /etc/vitastor/vitastor.conf and in etcd, but don't support online modification. + +All certificate and private key parameters mentioned may contain a path to a PEM file or just +a PEM string with certificate or a private key. In the latter case, the string must begin with +"-----BEGIN CERTIFICATE-----" or "-----BEGIN PRIVATE KEY-----". diff --git a/docs/config/src/security.ru.md b/docs/config/src/security.ru.md new file mode 100644 index 00000000..027a3b45 --- /dev/null +++ b/docs/config/src/security.ru.md @@ -0,0 +1,11 @@ +# Параметры безопасности + +Данные параметры затрагивают безопасность инсталляций Vitastor и используются +OSD, мониторами и клиентами. + +Большая их часть может задаваться в /etc/vitastor/vitastor.conf и в etcd, но не +поддерживает онлайн-изменение. + +Все параметры сертификатов и закрытых ключей могут быть путём к файлу или просто +строкой с сертификатом в формате PEM. В последнем случае строка должна начинаться с +"-----BEGIN CERTIFICATE-----" или "-----BEGIN PRIVATE KEY-----". diff --git a/docs/config/src/security.yml b/docs/config/src/security.yml new file mode 100644 index 00000000..562977b3 --- /dev/null +++ b/docs/config/src/security.yml @@ -0,0 +1,276 @@ +- name: use_perms + type: bool + default: false + info: | + Enable client permissions in a Vitastor cluster, including Antietcd built into the Monitor. + Requires configured encryption. Also note that separate Antietcd requires separate configuration + to use permissions (see [security documentation](../intro/security.en.md) for details). + info_ru: | + Включает клиентские привилегии в кластере Vitastor, в том числе во встроенном в мониторе Antietcd. + Требует настроенного шифрования протокола. Также обратите внимание, что отдельно установленный Antietcd + требует отдельной настройки привилегий (подробности смотрите в [документации безопасности](../intro/security.ru.md)). +- name: cert + type: string + info: | + Client certificate of the current Vitastor user. Required for Vitastor protocol encryption. + Must be signed with [client_ca](#client_ca). Also used as the client certificate for etcd/Antietcd + connections by default. + info_ru: | + Клиентский сертификат текущего пользователя Vitastor. Требуется для шифрования протокола Vitastor. + Должен быть подписан [client_ca](#client_ca). Также по умолчанию используется как клиентский + сертификат для подключения к etcd/Antietcd и Vault. +- name: pkey + type: string + info: Private key of the current Vitastor user. + info_ru: Закрытый ключ текущего пользователя Vitastor. +- name: etcd_ca + type: string + info: | + Trusted TLS CA to verify etcd server certificate. Or just the etcd server's + certificate itself - it's fine to use it for etcd_ca. + info_ru: | + Доверенный корневой TLS-сертификат для проверки сертификата сервера etcd. + Либо же просто сам сертификат сервера etcd - его можно использовать как etcd_ca. +- name: client_ca + type: string + info: | + Trusted TLS CA to verify Vitastor client certificates. + Mandatory for Vitastor protocol encryption. + info_ru: | + Доверенный TLS-сертификат для проверки сертификатов клиентов Vitastor. + Требуется для шифрования протокола Vitastor. +- name: osd_ca + type: string + info: | + Trusted TLS CA to verify Vitastor OSD certificates. Also mandatory for Vitastor protocol + encryption. Must be different from client_ca. May be equal to osd_cert - different OSDs + don't require separate certificates at the moment because their permissions don't differ. + info_ru: | + Доверенный TLS-сертификат для проверки сертификатов OSD Vitastor. Также обязателен + для шифрования протокола Vitastor. Должен отличаться от client_ca. Может быть равен + osd_cert - разные OSD не требуют разных сертификатов, потому что на данный момент + привилегии разных OSD никак не отличаются. +- name: mon_ca + type: string + info: | + Trusted TLS CA to verify Vitastor Monitor certificates. Used only for separate Antietcd, + not required when a monitor built-in Antietcd is used. May be equal to mon_client_etcd_cert. + info_ru: | + Доверенный TLS-сертификат для проверки сертификатов мониторов Vitastor. Используется + только отдельно установленным Antietcd, не требуется при использовании встроенного в монитор + Antietcd. Может быть равен mon_client_etcd_cert. +- name: antietcd_cert + type: string + info: Server TLS certificate for Antietcd built into the Monitor. + info_ru: Серверный TLS-сертификат для Antietcd, встроенного в монитор. +- name: antietcd_key + type: string + info: Private key for antietcd_cert. + info_ru: Закрытый ключ для сертификата antietcd_cert. +- name: etcd_proxy.urls + type: string or array of strings + type_ru: строка или массив строк + info: | + etcd URLs for Antietcd etcd proxy mode. + See [Mon as Etcd proxy](../intro/security.en.md#mon-as-etcd-proxy) for details. + info_ru: | + Адреса etcd для режима Antietcd etcd-прокси. + Смотрите подробности в разделе [Mon в роли Etcd proxy](../intro/security.ru.md#mon-в-роли-etcd-proxy). +- name: etcd_proxy.cert + type: string + info: Client certificate for Antietcd connections to etcd in proxy mode. + info_ru: Клиентский сертификат для подключений от Antietcd к etcd в режиме прокси. +- name: etcd_proxy.key + type: string + info: Private key for etcd_proxy.cert. + info_ru: Закрытый ключ для сертификата etcd_proxy.cert. +- name: etcd_proxy.ca + type: string + info: Trusted TLS CA to verify etcd server certificate when connecting to it from Antietcd. + info_ru: Доверенный TLS-сертификат для проверки сертификата сервера etcd при подключениях от Antietcd. +- name: osd_cert + type: string + info: | + Vitastor OSD server certificate. Required for Vitastor protocol encryption. May be equal + to [osd_ca](#osd_ca) - all OSDs share the same permission set for now. Also used as the client + certificate for connections from OSD to etcd/Antietcd by default. + info_ru: | + Сертификат сервера Vitastor OSD. Требуется для шифрования протокола Vitastor. Может быть равен + [osd_ca](#osd_ca) - все OSD на данный момент имеют одинаковые привилегии. Также по умолчанию + используется как клиентский сертификат для подключения от OSD к etcd/Antietcd. +- name: osd_pkey + type: string + info: Private key for osd_cert. + info_ru: Закрытый ключ для сертификата osd_cert. +- name: api_cert + type: string + info: Server TLS certificate for [vitastor-cli serve](../usage/cli.en.md#serve) API server. + info_ru: Серверный TLS-сертификат для API-сервера [vitastor-cli serve](../usage/cli.ru.md#serve). +- name: api_pkey + type: string + info: Private key for api_cert. + info_ru: Закрытый ключ для сертификата api_cert. +- name: etcd_client_cert + type: string + info: | + Client TLS certificate to use for connections from Vitastor clients to etcd/Antietcd if you don't want + to use the common client certificate [cert](#cert). + info_ru: | + Клиентский TLS сертификат для подключений от клиентов Vitastor к etcd/Antietcd, если вы не хотите + использовать общий клиентский сертификат [cert](#cert). +- name: etcd_client_key + type: string + info: Private key for etcd_client_cert. + info_ru: Закрытый ключ для сертификата etcd_client_cert. +- name: osd_etcd_client_cert + type: string + info: | + Client TLS certificate to use for connections from Vitastor OSDs to etcd/Antietcd if you don't want + to use the common OSD certificate [osd_cert](#osd_cert). + info_ru: | + Клиентский TLS сертификат для подключений от Vitastor OSD к etcd/Antietcd, если вы не хотите + использовать общий сертификат OSD [osd_cert](#osd_cert). +- name: osd_etcd_client_key + type: string + info: Private key for osd_etcd_client_cert. + info_ru: Закрытый ключ для сертификата osd_etcd_client_cert. +- name: mon_etcd_client_cert + type: string + info: | + Client TLS certificate to use for connections from Vitastor Monitors to etcd/Antietcd - required + if you don't use the built-in Antietcd. In case you use it Monitor has direct access to Antietcd data + and doesn't require any connection. + info_ru: | + Клиентский TLS сертификат для подключений от мониторов Vitastor к etcd/Antietcd - требуется, если + вы не используете встроенный в монитор Antietcd. Если вы используете его, то монитор и так имеет + прямой доступ к данным Antietcd и не требует никаких соединений. +- name: mon_etcd_client_key + type: string + info: Private key for mon_etcd_client_cert. + info_ru: Закрытый ключ для сертификата mon_etcd_client_cert. +- name: proto_checksums + type: string + default: payload + info: | + One of "full", "payload", "gcm", "none": + - "full" means calculate and verify transport level checksums from the full message data + including the header - recommended for unencrypted setups. + - "payload" enables checksums only for the actual read/write data, but skips them for message + headers - recommended for encrypted setups because headers are already protected by AES-GCM. + - "gcm" disables checksums and enables AES-GCM encryption of the whole messages including headers + and data - AES-GCM already includes MAC which is actually a stronger checksum. This option is + slower and is only recommended for untrusted networks. + - "none" disables transport level checksums at all. + info_ru: | + Одно из значений "full", "payload", "gcm" и "none": + - "full" означает расчёт и проверку контрольных сумм на транспортном уровне от полных сообщений, + включая их заголовки и данные - рекомендуется для кластеров без шифрования. + - "payload" включает контрольные суммы только для данных сообщений, но пропускает заголовки - + такая настройка рекомендуется для кластеров с включённым шифрованием, потому что в них заголовки + и так защищены шифрованием AES-GCM. + - "gcm" отключает контрольные суммы и включает шифрование полных сообщений включая заголовки и + данные - AES-GCM уже включает в себя MAC, который по сути является криптостойкой контрольной + суммой. Такая настройка медленнее и рекомендуется только для недоверенных сетей. + - "none" полностью отключает контрольные суммы на транспортном уровне. +- name: force_proto_checksums + type: string + info: | + To allow older clients to connect to a Vitastor cluster with enabled checksums, Vitastor OSDs + allow clients to downgrade their proto_checksums by default. force_proto_checksums sets the + minimum security level allowed for connecting clients. When encryption is disabled, default + force_proto_checksums is none and clients without checksums are allowed. With enabled + encryption, force_proto_checksums becomes "payload" by default to block unauthenticated data + on the transport level. + info_ru: | + Чтобы старые клиенты Vitastor могли подключаться к кластеру с включёнными контрольными + суммами, Vitastor OSD по умолчанию разрешают клиентам отключать контрольные суммы + данных (proto_checksums). Настройка force_proto_checksums задаёт минимальный уровень + безопасности, разрешённый для подключающихся клиентов. Когда шифрование отключено, + force_proto_checksums по умолчанию равно none и подключения клиентов без контрольных + сумм разрешаются. При включённом шифровании значение по умолчанию force_proto_checksums + становится "payload", чтобы блокировать подключения с неаутентифицированными данными. +- name: max_cipher_pool_size + type: int + default: 256 + info: | + Maximum number of OpenSSL cipher contexts cached in OSD memory, counted separately + for each cipher and for encryption/decryption. Probably doesn't require modification. + info_ru: | + Максимальное количество кэшируемых в памяти OSD контекстов шифра OpenSSL, учитываемое + отдельно для каждого шифра и для шифрования и расшифровки. Вряд ли требует изменения. +- name: vault_url + type: string + info: | + Vault base URL. + + Vitastor clients support AES-256-XTS image data encryption with different per-image keys. + Encryption is performed by the client, OSDs don't have access to decrypted data. + + Encryption keys may be stored in etcd or, for the increased security level, in an external + [HashiCorp Vault](https://developer.hashicorp.com/vault/) or [OpenBao](https://openbao.org/) + instance. + + Vitastor clients use [v1 k/v secrets engine](https://openbao.org/api-docs/secret/kv/kv-v1/) + and [TLS authentication engine](https://openbao.org/api-docs/auth/cert/) in Vault. + + In that case, only key IDs are stored in etcd. + info_ru: | + Базовый адрес Vault. + + Клиенты Vitastor поддерживают AES-256-XTS шифрование данных образов с отдельными ключами на + каждый образ. Данные шифруются клиентами, OSD не имеют доступа к незашифрованным данным. + + Ключи шифрования могут храниться в etcd или, для повышенного уровня безопасности, во внешнем + [HashiCorp Vault](https://developer.hashicorp.com/vault/) или [OpenBao](https://openbao.org/). + + Клиенты Vitastor используют [движок секретов v1](https://openbao.org/api-docs/secret/kv/kv-v1/) + и [TLS-аутентификацию](https://openbao.org/api-docs/auth/cert/) в Vault. + + В этом случае, только ID ключей хранятся в etcd. +- name: vault_secret_api_path + type: string + default: /v1/secret/ + info: Vault v1 secret API mount path to use. + info_ru: Путь к API секретов v1 для использования клиентами. +- name: vault_client_cert + type: string + info: | + Client TLS certificate to use for Vault connections if you don't want to use the common Vitastor + client certificate [cert](#cert) which is also used for Vault connections by default. + info_ru: | + Клиентский TLS сертификат для подключений к Vault на тот случай, если вы не хотите использовать + общий сертификат клиента Vitastor [cert](#cert), используемый для подключений к Vault по умолчанию. +- name: vault_client_key + type: string + info: Private key for the vault_client_cert certificate. + info_ru: Закрытый ключ для сертификата vault_client_cert. +- name: vault_ca + type: string + info: | + Trusted TLS CA to verify Vault server certificate. May be path to a file, + directory or just a PEM string with certificate. + info_ru: | + Доверенный корневой TLS-сертификат для проверки сертификата сервера Vault. + Может быть путём к файлу, директории или просто строкой с сертификатом в + формате PEM. +- name: vault_timeout_ms + type: int + default: 5000 + info: Timeout for Vault requests in milliseconds. + info_ru: Максимально время выполнения Vault-запросов в миллисекундах. +- name: vault_error_timeout_sec + type: int + default: 60 + info: | + Time (in seconds) to wait before retrying after receiving an error from Vault. + info_ru: | + Время (в секундах) для ожидания перед повторной попыткой при получении ошибки от Vault. +- name: vault_refresh_leeway_sec + type: int + default: 60 + info: | + Extra time (in seconds) before real Vault token lease_timeout to refresh it, just + in case of system clock drift. + info_ru: | + Зазор времени (в секундах), чтобы обновлять токены Vault чуть раньше их реального + lease_timeout, на случай "ухода" системных часов. diff --git a/docs/intro/features.en.md b/docs/intro/features.en.md index 9503120c..bf137b1b 100644 --- a/docs/intro/features.en.md +++ b/docs/intro/features.en.md @@ -41,6 +41,8 @@ - [Built-in Prometheus metric exporter](../config/monitor.en.md#enable_prometheus) - [NFS RDMA support](../usage/nfs.en.md#rdma) (probably also usable for GPUDirect) - [S3](../installation/s3.en.md) +- [TLS support for etcd connections](../config/security.en.md) +- [AES-256-XTS image encryption](../usage/cli.en.md#create) and [Vault support](../config/security.en.md#vault_url) for key storage ## Plugins and tools diff --git a/docs/intro/features.ru.md b/docs/intro/features.ru.md index 4fa755b1..514c4a8a 100644 --- a/docs/intro/features.ru.md +++ b/docs/intro/features.ru.md @@ -43,6 +43,8 @@ - [Встроенный Prometheus-экспортер метрик](../config/monitor.ru.md#enable_prometheus) - [Поддержка NFS RDMA](../usage/nfs.ru.md#rdma) (вероятно, также подходящая для GPUDirect) - [S3](../installation/s3.ru.md) +- [Поддержка TLS-соединений с etcd](../config/security.ru.md) +- [AES-256-XTS шифрование данных](../usage/cli.ru.md#create) и [поддержка Vault](../config/security.ru.md#vault_url) для хранения ключей ## Драйверы и инструменты