From ed1e762584aee3b76f13dd1a3641dae31e50ba47 Mon Sep 17 00:00:00 2001 From: Akira Ajisaka Date: Fri, 24 Apr 2026 18:15:28 +0900 Subject: [PATCH 1/6] Make kyuubi.engine.security parameters public --- docs/configuration/settings.md | 8 ++++++++ .../main/scala/org/apache/kyuubi/config/KyuubiConf.scala | 8 -------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/configuration/settings.md b/docs/configuration/settings.md index 3e34882b28f..b7183a6e6a0 100644 --- a/docs/configuration/settings.md +++ b/docs/configuration/settings.md @@ -199,6 +199,14 @@ You can configure the Kyuubi properties in `$KYUUBI_HOME/conf/kyuubi-defaults.co | kyuubi.engine.pool.size | -1 | The size of the engine pool. Note that, if the size is less than 1, the engine pool will not be enabled; otherwise, the size of the engine pool will be min(this, kyuubi.engine.pool.size.threshold). | int | 1.4.0 | | kyuubi.engine.pool.size.threshold | 9 | This parameter is introduced as a server-side parameter controlling the upper limit of the engine pool. | int | 1.4.0 | | kyuubi.engine.principal | <undefined> | Kerberos principal for the kyuubi engine. | string | 1.10.0 | +| kyuubi.engine.security.crypto.cipher | AES/CBC/PKCS5PADDING | The cipher transformation to use for encrypting internal access token. | string | 1.5.0 | +| kyuubi.engine.security.crypto.ivLength | 16 | Initial vector length, in bytes. | int | 1.5.0 | +| kyuubi.engine.security.crypto.keyAlgorithm | AES | The algorithm for generated secret keys. | string | 1.5.0 | +| kyuubi.engine.security.crypto.keyLength | 128 | The length in bits of the encryption key to generate. Valid values are 128, 192 and 256 | int | 1.5.0 | +| kyuubi.engine.security.enabled | false | Whether to enable the internal secure access. Before 1.6.0, it is used for the secure access between kyuubi server and kyuubi engine. Since 1.6.0, kyuubi supports internal secure across kyuubi server instances. | boolean | 1.5.0 | +| kyuubi.engine.security.secret.provider | zookeeper | The class used to manage the internal security secret. This class must be a subclass of `EngineSecuritySecretProvider`. | string | 1.5.0 | +| kyuubi.engine.security.secret.provider.simple.secret | <undefined> | The secret key used for internal security access. Only take affects when kyuubi.engine.security.secret.provider is 'simple' | string | 1.7.0 | +| kyuubi.engine.security.token.max.lifetime | PT10M | The max lifetime of the token used for internal secure access. | duration | 1.5.0 | | kyuubi.engine.session.initialize.sql || SemiColon-separated list of SQL statements to be initialized in the newly created engine session before queries. This configuration can not be used in JDBC url due to the limitation of Beeline/JDBC driver. | seq | 1.3.0 | | kyuubi.engine.share.level | USER | Engines will be shared in different levels, available configs are: See also `kyuubi.engine.share.level.subdomain` and `kyuubi.engine.doAs.enabled`. | string | 1.2.0 | | kyuubi.engine.share.level.sub.domain | <undefined> | (deprecated) - Using kyuubi.engine.share.level.subdomain instead | string | 1.2.0 | diff --git a/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala b/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala index 215a76e26d4..27df720d47c 100644 --- a/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala +++ b/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala @@ -2749,7 +2749,6 @@ object KyuubiConf { val ENGINE_SECURITY_ENABLED: ConfigEntry[Boolean] = buildConf("kyuubi.engine.security.enabled") - .internal .doc("Whether to enable the internal secure access. Before 1.6.0, it is used for the secure" + " access between kyuubi server and kyuubi engine. Since 1.6.0, kyuubi supports internal" + " secure across kyuubi server instances.") @@ -2759,7 +2758,6 @@ object KyuubiConf { val ENGINE_SECURITY_TOKEN_MAX_LIFETIME: ConfigEntry[Long] = buildConf("kyuubi.engine.security.token.max.lifetime") - .internal .doc("The max lifetime of the token used for internal secure access.") .version("1.5.0") .timeConf @@ -2767,7 +2765,6 @@ object KyuubiConf { val ENGINE_SECURITY_SECRET_PROVIDER: ConfigEntry[String] = buildConf("kyuubi.engine.security.secret.provider") - .internal .doc("The class used to manage the internal security secret. This class must be a " + "subclass of `EngineSecuritySecretProvider`.") .version("1.5.0") @@ -2783,7 +2780,6 @@ object KyuubiConf { val SIMPLE_SECURITY_SECRET_PROVIDER_PROVIDER_SECRET: OptionalConfigEntry[String] = buildConf("kyuubi.engine.security.secret.provider.simple.secret") - .internal .doc("The secret key used for internal security access. Only take affects when " + s"${ENGINE_SECURITY_SECRET_PROVIDER.key} is 'simple'") .version("1.7.0") @@ -2792,7 +2788,6 @@ object KyuubiConf { val ENGINE_SECURITY_CRYPTO_KEY_LENGTH: ConfigEntry[Int] = buildConf("kyuubi.engine.security.crypto.keyLength") - .internal .doc("The length in bits of the encryption key to generate. " + "Valid values are 128, 192 and 256") .version("1.5.0") @@ -2802,7 +2797,6 @@ object KyuubiConf { val ENGINE_SECURITY_CRYPTO_IV_LENGTH: ConfigEntry[Int] = buildConf("kyuubi.engine.security.crypto.ivLength") - .internal .doc("Initial vector length, in bytes.") .version("1.5.0") .intConf @@ -2810,7 +2804,6 @@ object KyuubiConf { val ENGINE_SECURITY_CRYPTO_KEY_ALGORITHM: ConfigEntry[String] = buildConf("kyuubi.engine.security.crypto.keyAlgorithm") - .internal .doc("The algorithm for generated secret keys.") .version("1.5.0") .stringConf @@ -2818,7 +2811,6 @@ object KyuubiConf { val ENGINE_SECURITY_CRYPTO_CIPHER_TRANSFORMATION: ConfigEntry[String] = buildConf("kyuubi.engine.security.crypto.cipher") - .internal .doc("The cipher transformation to use for encrypting internal access token.") .version("1.5.0") .stringConf From 218d06ce7ac6da8064ff8229dcf974a541531852 Mon Sep 17 00:00:00 2001 From: Akira Ajisaka Date: Tue, 28 Apr 2026 11:11:12 +0900 Subject: [PATCH 2/6] Document the features are available only when kyuubi.engine.security.enabled is true --- docs/configuration/settings.md | 14 +++++----- .../org/apache/kyuubi/config/KyuubiConf.scala | 28 +++++++++++++------ 2 files changed, 26 insertions(+), 16 deletions(-) diff --git a/docs/configuration/settings.md b/docs/configuration/settings.md index b7183a6e6a0..3626e689e84 100644 --- a/docs/configuration/settings.md +++ b/docs/configuration/settings.md @@ -199,14 +199,14 @@ You can configure the Kyuubi properties in `$KYUUBI_HOME/conf/kyuubi-defaults.co | kyuubi.engine.pool.size | -1 | The size of the engine pool. Note that, if the size is less than 1, the engine pool will not be enabled; otherwise, the size of the engine pool will be min(this, kyuubi.engine.pool.size.threshold). | int | 1.4.0 | | kyuubi.engine.pool.size.threshold | 9 | This parameter is introduced as a server-side parameter controlling the upper limit of the engine pool. | int | 1.4.0 | | kyuubi.engine.principal | <undefined> | Kerberos principal for the kyuubi engine. | string | 1.10.0 | -| kyuubi.engine.security.crypto.cipher | AES/CBC/PKCS5PADDING | The cipher transformation to use for encrypting internal access token. | string | 1.5.0 | -| kyuubi.engine.security.crypto.ivLength | 16 | Initial vector length, in bytes. | int | 1.5.0 | -| kyuubi.engine.security.crypto.keyAlgorithm | AES | The algorithm for generated secret keys. | string | 1.5.0 | -| kyuubi.engine.security.crypto.keyLength | 128 | The length in bits of the encryption key to generate. Valid values are 128, 192 and 256 | int | 1.5.0 | +| kyuubi.engine.security.crypto.cipher | AES/CBC/PKCS5PADDING | The cipher transformation to use for encrypting internal access token. Only take affects when kyuubi.engine.security.enabled is set to true. | string | 1.5.0 | +| kyuubi.engine.security.crypto.ivLength | 16 | Initial vector length, in bytes. Only take affects when kyuubi.engine.security.enabled is set to true. | int | 1.5.0 | +| kyuubi.engine.security.crypto.keyAlgorithm | AES | The algorithm for generated secret keys. Only take affects when kyuubi.engine.security.enabled is set to true. | string | 1.5.0 | +| kyuubi.engine.security.crypto.keyLength | 128 | The length in bits of the encryption key to generate. Only take affects when kyuubi.engine.security.enabled is set to true. Valid values are 128, 192 and 256 | int | 1.5.0 | | kyuubi.engine.security.enabled | false | Whether to enable the internal secure access. Before 1.6.0, it is used for the secure access between kyuubi server and kyuubi engine. Since 1.6.0, kyuubi supports internal secure across kyuubi server instances. | boolean | 1.5.0 | -| kyuubi.engine.security.secret.provider | zookeeper | The class used to manage the internal security secret. This class must be a subclass of `EngineSecuritySecretProvider`. | string | 1.5.0 | -| kyuubi.engine.security.secret.provider.simple.secret | <undefined> | The secret key used for internal security access. Only take affects when kyuubi.engine.security.secret.provider is 'simple' | string | 1.7.0 | -| kyuubi.engine.security.token.max.lifetime | PT10M | The max lifetime of the token used for internal secure access. | duration | 1.5.0 | +| kyuubi.engine.security.secret.provider | zookeeper | The class used to manage the internal security secret. This class must be a subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following built-in implementations: Only take affects when kyuubi.engine.security.enabled is set to true. | string | 1.5.0 | +| kyuubi.engine.security.secret.provider.simple.secret | <undefined> | The secret key used for internal security access. Only take affects when kyuubi.engine.security.enabled is set to true and kyuubi.engine.security.secret.provider is 'simple' | string | 1.7.0 | +| kyuubi.engine.security.token.max.lifetime | PT10M | The max lifetime of the token used for internal secure access. Only take affects when kyuubi.engine.security.enabled is set to true. | duration | 1.5.0 | | kyuubi.engine.session.initialize.sql || SemiColon-separated list of SQL statements to be initialized in the newly created engine session before queries. This configuration can not be used in JDBC url due to the limitation of Beeline/JDBC driver. | seq | 1.3.0 | | kyuubi.engine.share.level | USER | Engines will be shared in different levels, available configs are: See also `kyuubi.engine.share.level.subdomain` and `kyuubi.engine.doAs.enabled`. | string | 1.2.0 | | kyuubi.engine.share.level.sub.domain | <undefined> | (deprecated) - Using kyuubi.engine.share.level.subdomain instead | string | 1.2.0 | diff --git a/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala b/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala index 27df720d47c..1aae270d266 100644 --- a/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala +++ b/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala @@ -2758,7 +2758,8 @@ object KyuubiConf { val ENGINE_SECURITY_TOKEN_MAX_LIFETIME: ConfigEntry[Long] = buildConf("kyuubi.engine.security.token.max.lifetime") - .doc("The max lifetime of the token used for internal secure access.") + .doc("The max lifetime of the token used for internal secure access. Only take affects" + + s" when ${ENGINE_SECURITY_ENABLED.key} is set to true.") .version("1.5.0") .timeConf .createWithDefault(Duration.ofMinutes(10).toMillis) @@ -2766,7 +2767,12 @@ object KyuubiConf { val ENGINE_SECURITY_SECRET_PROVIDER: ConfigEntry[String] = buildConf("kyuubi.engine.security.secret.provider") .doc("The class used to manage the internal security secret. This class must be a " + - "subclass of `EngineSecuritySecretProvider`.") + "subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following " + + "built-in implementations: " + + s"Only take affects when ${ENGINE_SECURITY_ENABLED.key} is set to true.") .version("1.5.0") .stringConf .transform { @@ -2780,16 +2786,17 @@ object KyuubiConf { val SIMPLE_SECURITY_SECRET_PROVIDER_PROVIDER_SECRET: OptionalConfigEntry[String] = buildConf("kyuubi.engine.security.secret.provider.simple.secret") - .doc("The secret key used for internal security access. Only take affects when " + - s"${ENGINE_SECURITY_SECRET_PROVIDER.key} is 'simple'") + .doc("The secret key used for internal security access. Only take affects when" + + s" ${ENGINE_SECURITY_ENABLED.key} is set to true and" + + s" ${ENGINE_SECURITY_SECRET_PROVIDER.key} is 'simple'") .version("1.7.0") .stringConf .createOptional val ENGINE_SECURITY_CRYPTO_KEY_LENGTH: ConfigEntry[Int] = buildConf("kyuubi.engine.security.crypto.keyLength") - .doc("The length in bits of the encryption key to generate. " + - "Valid values are 128, 192 and 256") + .doc("The length in bits of the encryption key to generate. Only take affects when" + + s" ${ENGINE_SECURITY_ENABLED.key} is set to true. Valid values are 128, 192 and 256") .version("1.5.0") .intConf .checkValues(Set(128, 192, 256)) @@ -2797,21 +2804,24 @@ object KyuubiConf { val ENGINE_SECURITY_CRYPTO_IV_LENGTH: ConfigEntry[Int] = buildConf("kyuubi.engine.security.crypto.ivLength") - .doc("Initial vector length, in bytes.") + .doc("Initial vector length, in bytes. Only take affects when" + + s" ${ENGINE_SECURITY_ENABLED.key} is set to true.") .version("1.5.0") .intConf .createWithDefault(16) val ENGINE_SECURITY_CRYPTO_KEY_ALGORITHM: ConfigEntry[String] = buildConf("kyuubi.engine.security.crypto.keyAlgorithm") - .doc("The algorithm for generated secret keys.") + .doc("The algorithm for generated secret keys. Only take affects when" + + s" ${ENGINE_SECURITY_ENABLED.key} is set to true.") .version("1.5.0") .stringConf .createWithDefault("AES") val ENGINE_SECURITY_CRYPTO_CIPHER_TRANSFORMATION: ConfigEntry[String] = buildConf("kyuubi.engine.security.crypto.cipher") - .doc("The cipher transformation to use for encrypting internal access token.") + .doc("The cipher transformation to use for encrypting internal access token." + + s" Only take affects when ${ENGINE_SECURITY_ENABLED.key} is set to true.") .version("1.5.0") .stringConf .createWithDefault("AES/CBC/PKCS5PADDING") From 7658c05dcf6e583a1d551b157d6ef57214cbb561 Mon Sep 17 00:00:00 2001 From: Akira Ajisaka Date: Fri, 1 May 2026 16:30:55 +0900 Subject: [PATCH 3/6] Rename the config to kyuubi.internal.security.* with a fallback --- docs/configuration/settings.md | 19 +-- .../org/apache/kyuubi/config/KyuubiConf.scala | 110 +++++++++++++++--- .../AuthenticationProviderFactory.scala | 2 +- .../EngineSecuritySecretProvider.scala | 8 +- .../InternalSecurityAccessor.scala | 10 +- .../KyuubiAuthenticationFactory.scala | 2 +- .../InternalSecurityAccessorSuite.scala | 6 +- 7 files changed, 116 insertions(+), 41 deletions(-) diff --git a/docs/configuration/settings.md b/docs/configuration/settings.md index 3626e689e84..c529c329813 100644 --- a/docs/configuration/settings.md +++ b/docs/configuration/settings.md @@ -199,14 +199,6 @@ You can configure the Kyuubi properties in `$KYUUBI_HOME/conf/kyuubi-defaults.co | kyuubi.engine.pool.size | -1 | The size of the engine pool. Note that, if the size is less than 1, the engine pool will not be enabled; otherwise, the size of the engine pool will be min(this, kyuubi.engine.pool.size.threshold). | int | 1.4.0 | | kyuubi.engine.pool.size.threshold | 9 | This parameter is introduced as a server-side parameter controlling the upper limit of the engine pool. | int | 1.4.0 | | kyuubi.engine.principal | <undefined> | Kerberos principal for the kyuubi engine. | string | 1.10.0 | -| kyuubi.engine.security.crypto.cipher | AES/CBC/PKCS5PADDING | The cipher transformation to use for encrypting internal access token. Only take affects when kyuubi.engine.security.enabled is set to true. | string | 1.5.0 | -| kyuubi.engine.security.crypto.ivLength | 16 | Initial vector length, in bytes. Only take affects when kyuubi.engine.security.enabled is set to true. | int | 1.5.0 | -| kyuubi.engine.security.crypto.keyAlgorithm | AES | The algorithm for generated secret keys. Only take affects when kyuubi.engine.security.enabled is set to true. | string | 1.5.0 | -| kyuubi.engine.security.crypto.keyLength | 128 | The length in bits of the encryption key to generate. Only take affects when kyuubi.engine.security.enabled is set to true. Valid values are 128, 192 and 256 | int | 1.5.0 | -| kyuubi.engine.security.enabled | false | Whether to enable the internal secure access. Before 1.6.0, it is used for the secure access between kyuubi server and kyuubi engine. Since 1.6.0, kyuubi supports internal secure across kyuubi server instances. | boolean | 1.5.0 | -| kyuubi.engine.security.secret.provider | zookeeper | The class used to manage the internal security secret. This class must be a subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following built-in implementations:
  • simple: Use the secret set by kyuubi.engine.security.secret.provider.simple.secret. Only for testing purpose.
  • zookeeper: Use the secret stored in ZooKeeper. kyuubi.ha.zookeeper.engine.secure.secret.node must be configured.
Only take affects when kyuubi.engine.security.enabled is set to true. | string | 1.5.0 | -| kyuubi.engine.security.secret.provider.simple.secret | <undefined> | The secret key used for internal security access. Only take affects when kyuubi.engine.security.enabled is set to true and kyuubi.engine.security.secret.provider is 'simple' | string | 1.7.0 | -| kyuubi.engine.security.token.max.lifetime | PT10M | The max lifetime of the token used for internal secure access. Only take affects when kyuubi.engine.security.enabled is set to true. | duration | 1.5.0 | | kyuubi.engine.session.initialize.sql || SemiColon-separated list of SQL statements to be initialized in the newly created engine session before queries. This configuration can not be used in JDBC url due to the limitation of Beeline/JDBC driver. | seq | 1.3.0 | | kyuubi.engine.share.level | USER | Engines will be shared in different levels, available configs are:
  • CONNECTION: the engine will not be shared but only used by the current client connection, and the engine will be launched by session user.
  • USER: the engine will be shared by all sessions created by a unique username, and the engine will be launched by session user.
  • GROUP: the engine will be shared by all sessions created by all users belong to the same primary group name. The engine will be launched by the primary group name as the effective username, so here the group name is in value of special user who is able to visit the computing resources/data of the team. It follows the [Hadoop GroupsMapping](https://reurl.cc/xE61Y5) to map user to a primary group. If the primary group is not found, it fallback to the USER level.
  • SERVER_LOCAL: the engine will be shared by the same Kyuubi server which launched this engine.
  • SERVER: the engine will be shared by Kyuubi servers, and the engine will be launched by Server's user.
See also `kyuubi.engine.share.level.subdomain` and `kyuubi.engine.doAs.enabled`. | string | 1.2.0 | | kyuubi.engine.share.level.sub.domain | <undefined> | (deprecated) - Using kyuubi.engine.share.level.subdomain instead | string | 1.2.0 | @@ -362,6 +354,17 @@ You can configure the Kyuubi properties in `$KYUUBI_HOME/conf/kyuubi-defaults.co | kyuubi.ha.zookeeper.quorum || (deprecated) The connection string for the ZooKeeper ensemble | string | 1.0.0 | | kyuubi.ha.zookeeper.session.timeout | 60000 | The timeout(ms) of a connected session to be idled | int | 1.0.0 | +### Internal + +| Key | Default | Meaning | Type | Since | +|--------------------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------| +| kyuubi.internal.security.crypto.ivLength | 16 | Initial vector length, in bytes. Only take affects when kyuubi.internal.security.enabled is set to true. | int | 1.12.0 | +| kyuubi.internal.security.crypto.keyLength | 128 | The length in bits of the encryption key to generate. Only take affects when kyuubi.internal.security.enabled is set to true. Valid values are 128, 192 and 256 | int | 1.12.0 | +| kyuubi.internal.security.enabled | false | Whether to enable secure access across all the internal communications, both
  • between kyuubi server and kyuubi engine
  • across kyuubi server instances
You need to also provide configure | boolean | 1.12.0 | +| kyuubi.internal.security.secret.provider | zookeeper | The class used to manage the internal security secret. This class must be a subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following built-in implementations:
  • simple: Use the secret set by kyuubi.internal.security.secret.provider.simple.secret.
  • zookeeper: Use the secret stored in ZooKeeper. kyuubi.ha.zookeeper.engine.secure.secret.node must be configured.
Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | +| kyuubi.internal.security.secret.provider.simple.secret | <undefined> | The secret key used for internal security access. Only take affects when kyuubi.internal.security.enabled is set to true and kyuubi.internal.security.secret.provider is 'simple' | string | 1.12.0 | +| kyuubi.internal.security.token.max.lifetime | PT10M | The max lifetime of the token used for internal secure access. Only take affects when kyuubi.internal.security.enabled is set to true. | duration | 1.12.0 | + ### Kinit | Key | Default | Meaning | Type | Since | diff --git a/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala b/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala index 1aae270d266..53fef965f34 100644 --- a/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala +++ b/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala @@ -2747,8 +2747,10 @@ object KyuubiConf { .stringConf .createWithDefault("engine_operation_logs") + @deprecated("using kyuubi.internal.security.enabled instead", "1.12.0") val ENGINE_SECURITY_ENABLED: ConfigEntry[Boolean] = buildConf("kyuubi.engine.security.enabled") + .internal .doc("Whether to enable the internal secure access. Before 1.6.0, it is used for the secure" + " access between kyuubi server and kyuubi engine. Since 1.6.0, kyuubi supports internal" + " secure across kyuubi server instances.") @@ -2756,23 +2758,21 @@ object KyuubiConf { .booleanConf .createWithDefault(false) + @deprecated("using kyuubi.internal.security.token.max.lifetime instead", "1.12.0") val ENGINE_SECURITY_TOKEN_MAX_LIFETIME: ConfigEntry[Long] = buildConf("kyuubi.engine.security.token.max.lifetime") - .doc("The max lifetime of the token used for internal secure access. Only take affects" + - s" when ${ENGINE_SECURITY_ENABLED.key} is set to true.") + .internal + .doc("The max lifetime of the token used for internal secure access.") .version("1.5.0") .timeConf .createWithDefault(Duration.ofMinutes(10).toMillis) + @deprecated("using kyuubi.internal.security.secret.provider instead", "1.12.0") val ENGINE_SECURITY_SECRET_PROVIDER: ConfigEntry[String] = buildConf("kyuubi.engine.security.secret.provider") + .internal .doc("The class used to manage the internal security secret. This class must be a " + - "subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following " + - "built-in implementations:
  • simple: Use the secret set by " + - s"kyuubi.engine.security.secret.provider.simple.secret. Only for testing purpose.
    • " + - "
  • zookeeper: Use the secret stored in ZooKeeper. " + - "kyuubi.ha.zookeeper.engine.secure.secret.node must be configured.
" + - s"Only take affects when ${ENGINE_SECURITY_ENABLED.key} is set to true.") + "subclass of `EngineSecuritySecretProvider`.") .version("1.5.0") .stringConf .transform { @@ -2784,48 +2784,120 @@ object KyuubiConf { } .createWithDefault("zookeeper") + @deprecated("using kyuubi.internal.security.secret.provider.simple.secret instead", "1.12.0") val SIMPLE_SECURITY_SECRET_PROVIDER_PROVIDER_SECRET: OptionalConfigEntry[String] = buildConf("kyuubi.engine.security.secret.provider.simple.secret") - .doc("The secret key used for internal security access. Only take affects when" + - s" ${ENGINE_SECURITY_ENABLED.key} is set to true and" + - s" ${ENGINE_SECURITY_SECRET_PROVIDER.key} is 'simple'") + .internal + .doc("The secret key used for internal security access. Only take affects when " + + s"${ENGINE_SECURITY_SECRET_PROVIDER.key} is 'simple'") .version("1.7.0") .stringConf .createOptional + @deprecated("using kyuubi.internal.security.crypto.keyLength instead", "1.12.0") val ENGINE_SECURITY_CRYPTO_KEY_LENGTH: ConfigEntry[Int] = buildConf("kyuubi.engine.security.crypto.keyLength") - .doc("The length in bits of the encryption key to generate. Only take affects when" + - s" ${ENGINE_SECURITY_ENABLED.key} is set to true. Valid values are 128, 192 and 256") + .internal + .doc("The length in bits of the encryption key to generate. " + + "Valid values are 128, 192 and 256") .version("1.5.0") .intConf .checkValues(Set(128, 192, 256)) .createWithDefault(128) + @deprecated("using kyuubi.internal.security.crypto.ivLength instead", "1.12.0") val ENGINE_SECURITY_CRYPTO_IV_LENGTH: ConfigEntry[Int] = buildConf("kyuubi.engine.security.crypto.ivLength") - .doc("Initial vector length, in bytes. Only take affects when" + - s" ${ENGINE_SECURITY_ENABLED.key} is set to true.") + .internal + .doc("Initial vector length, in bytes.") .version("1.5.0") .intConf .createWithDefault(16) + @deprecated("using kyuubi.internal.security.crypto.keyAlgorithm instead", "1.12.0") val ENGINE_SECURITY_CRYPTO_KEY_ALGORITHM: ConfigEntry[String] = buildConf("kyuubi.engine.security.crypto.keyAlgorithm") - .doc("The algorithm for generated secret keys. Only take affects when" + - s" ${ENGINE_SECURITY_ENABLED.key} is set to true.") + .internal + .doc("The algorithm for generated secret keys.") .version("1.5.0") .stringConf .createWithDefault("AES") + @deprecated("using kyuubi.internal.security.crypto.cipher instead", "1.12.0") val ENGINE_SECURITY_CRYPTO_CIPHER_TRANSFORMATION: ConfigEntry[String] = buildConf("kyuubi.engine.security.crypto.cipher") - .doc("The cipher transformation to use for encrypting internal access token." + - s" Only take affects when ${ENGINE_SECURITY_ENABLED.key} is set to true.") + .internal + .doc("The cipher transformation to use for encrypting internal access token.") .version("1.5.0") .stringConf .createWithDefault("AES/CBC/PKCS5PADDING") + val INTERNAL_SECURITY_ENABLED: ConfigEntry[Boolean] = + buildConf("kyuubi.internal.security.enabled") + .doc("Whether to enable secure access across all the internal communications, both
    " + + "
  • between kyuubi server and kyuubi engine
    • " + + "
  • across kyuubi server instances
" + + "You need to also provide configure ") + .version("1.12.0") + .fallbackConf(ENGINE_SECURITY_ENABLED) + + val INTERNAL_SECURITY_TOKEN_MAX_LIFETIME: ConfigEntry[Long] = + buildConf("kyuubi.internal.security.token.max.lifetime") + .doc("The max lifetime of the token used for internal secure access. Only take affects" + + s" when ${INTERNAL_SECURITY_ENABLED.key} is set to true.") + .version("1.12.0") + .fallbackConf(ENGINE_SECURITY_TOKEN_MAX_LIFETIME) + + val INTERNAL_SECURITY_SECRET_PROVIDER: ConfigEntry[String] = + buildConf("kyuubi.internal.security.secret.provider") + .doc("The class used to manage the internal security secret. This class must be a " + + "subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following " + + "built-in implementations:
  • simple: Use the secret set by " + + s"kyuubi.internal.security.secret.provider.simple.secret.
    • " + + "
  • zookeeper: Use the secret stored in ZooKeeper. " + + "kyuubi.ha.zookeeper.engine.secure.secret.node must be configured.
" + + s"Only take affects when ${INTERNAL_SECURITY_ENABLED.key} is set to true.") + .version("1.12.0") + .fallbackConf(ENGINE_SECURITY_SECRET_PROVIDER) + + val INTERNAL_SECURITY_SECRET_PROVIDER_SIMPLE_SECRET: ConfigEntry[Option[String]] = + buildConf("kyuubi.internal.security.secret.provider.simple.secret") + .doc("The secret key used for internal security access. Only take affects when" + + s" ${INTERNAL_SECURITY_ENABLED.key} is set to true and" + + s" ${INTERNAL_SECURITY_SECRET_PROVIDER.key} is 'simple'") + .version("1.12.0") + .fallbackConf(SIMPLE_SECURITY_SECRET_PROVIDER_PROVIDER_SECRET) + + val INTERNAL_SECURITY_CRYPTO_KEY_LENGTH: ConfigEntry[Int] = + buildConf("kyuubi.internal.security.crypto.keyLength") + .doc("The length in bits of the encryption key to generate. Only take affects when" + + s" ${INTERNAL_SECURITY_ENABLED.key} is set to true. Valid values are 128, 192 and 256") + .version("1.12.0") + .fallbackConf(ENGINE_SECURITY_CRYPTO_KEY_LENGTH) + + val INTERNAL_SECURITY_CRYPTO_IV_LENGTH: ConfigEntry[Int] = + buildConf("kyuubi.internal.security.crypto.ivLength") + .doc("Initial vector length, in bytes. Only take affects when" + + s" ${INTERNAL_SECURITY_ENABLED.key} is set to true.") + .version("1.12.0") + .fallbackConf(ENGINE_SECURITY_CRYPTO_IV_LENGTH) + + val INTERNAL_SECURITY_CRYPTO_KEY_ALGORITHM: ConfigEntry[String] = + buildConf("kyuubi.internal.security.crypto.keyAlgorithm") + .internal + .doc("The algorithm for generated secret keys. Only take affects when" + + s" ${INTERNAL_SECURITY_ENABLED.key} is set to true.") + .version("1.12.0") + .fallbackConf(ENGINE_SECURITY_CRYPTO_KEY_ALGORITHM) + + val INTERNAL_SECURITY_CRYPTO_CIPHER_TRANSFORMATION: ConfigEntry[String] = + buildConf("kyuubi.internal.security.crypto.cipher") + .internal + .doc("The cipher transformation to use for encrypting internal access token." + + s" Only take affects when ${INTERNAL_SECURITY_ENABLED.key} is set to true.") + .version("1.12.0") + .fallbackConf(ENGINE_SECURITY_CRYPTO_CIPHER_TRANSFORMATION) + val SESSION_NAME: OptionalConfigEntry[String] = buildConf("kyuubi.session.name") .doc("A human readable name of the session and we use empty string by default. " + diff --git a/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/AuthenticationProviderFactory.scala b/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/AuthenticationProviderFactory.scala index bbd43bcc74e..b1453985337 100644 --- a/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/AuthenticationProviderFactory.scala +++ b/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/AuthenticationProviderFactory.scala @@ -57,7 +57,7 @@ object AuthenticationProviderFactory { } private def getAuthenticationProviderForEngine(conf: KyuubiConf): PasswdAuthenticationProvider = { - if (conf.get(KyuubiConf.ENGINE_SECURITY_ENABLED)) { + if (conf.get(KyuubiConf.INTERNAL_SECURITY_ENABLED)) { new EngineSecureAuthenticationProviderImpl } else { new AnonymousAuthenticationProviderImpl diff --git a/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/EngineSecuritySecretProvider.scala b/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/EngineSecuritySecretProvider.scala index 3216a43be7f..5a4cde07509 100644 --- a/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/EngineSecuritySecretProvider.scala +++ b/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/EngineSecuritySecretProvider.scala @@ -41,10 +41,10 @@ class SimpleEngineSecuritySecretProviderImpl extends EngineSecuritySecretProvide override def initialize(conf: KyuubiConf): Unit = _conf = conf override def getSecret(): String = { - _conf.get(SIMPLE_SECURITY_SECRET_PROVIDER_PROVIDER_SECRET).getOrElse { + _conf.get(INTERNAL_SECURITY_SECRET_PROVIDER_SIMPLE_SECRET).getOrElse { throw new IllegalArgumentException( - s"${SIMPLE_SECURITY_SECRET_PROVIDER_PROVIDER_SECRET.key} must be configured " + - s"when ${ENGINE_SECURITY_SECRET_PROVIDER.key} is `simple`.") + s"${INTERNAL_SECURITY_SECRET_PROVIDER_SIMPLE_SECRET.key} must be configured " + + s"when ${INTERNAL_SECURITY_SECRET_PROVIDER.key} is `simple`.") } } } @@ -52,7 +52,7 @@ class SimpleEngineSecuritySecretProviderImpl extends EngineSecuritySecretProvide object EngineSecuritySecretProvider { def create(conf: KyuubiConf): EngineSecuritySecretProvider = { val provider = DynConstructors.builder() - .impl(conf.get(ENGINE_SECURITY_SECRET_PROVIDER)) + .impl(conf.get(INTERNAL_SECURITY_SECRET_PROVIDER)) .buildChecked[EngineSecuritySecretProvider]() .newInstance(conf) provider.initialize(conf) diff --git a/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/InternalSecurityAccessor.scala b/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/InternalSecurityAccessor.scala index c44f0bdacb7..add8c1ad0b7 100644 --- a/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/InternalSecurityAccessor.scala +++ b/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/InternalSecurityAccessor.scala @@ -29,12 +29,12 @@ import org.apache.kyuubi.config.KyuubiConf import org.apache.kyuubi.config.KyuubiConf._ class InternalSecurityAccessor(conf: KyuubiConf, val isServer: Boolean) { - val cryptoKeyLengthBytes = conf.get(ENGINE_SECURITY_CRYPTO_KEY_LENGTH) / java.lang.Byte.SIZE - val cryptoIvLength = conf.get(ENGINE_SECURITY_CRYPTO_IV_LENGTH) - val cryptoKeyAlgorithm = conf.get(ENGINE_SECURITY_CRYPTO_KEY_ALGORITHM) - val cryptoCipher = conf.get(ENGINE_SECURITY_CRYPTO_CIPHER_TRANSFORMATION) + val cryptoKeyLengthBytes = conf.get(INTERNAL_SECURITY_CRYPTO_KEY_LENGTH) / java.lang.Byte.SIZE + val cryptoIvLength = conf.get(INTERNAL_SECURITY_CRYPTO_IV_LENGTH) + val cryptoKeyAlgorithm = conf.get(INTERNAL_SECURITY_CRYPTO_KEY_ALGORITHM) + val cryptoCipher = conf.get(INTERNAL_SECURITY_CRYPTO_CIPHER_TRANSFORMATION) - private val tokenMaxLifeTime: Long = conf.get(ENGINE_SECURITY_TOKEN_MAX_LIFETIME) + private val tokenMaxLifeTime: Long = conf.get(INTERNAL_SECURITY_TOKEN_MAX_LIFETIME) private val provider: EngineSecuritySecretProvider = EngineSecuritySecretProvider.create(conf) private val (secretKeySpec, encryptor, decryptor) = initializeForAuth(cryptoCipher, normalizeSecret(provider.getSecret())) diff --git a/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/KyuubiAuthenticationFactory.scala b/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/KyuubiAuthenticationFactory.scala index 978527b8818..1ef839fe8a0 100644 --- a/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/KyuubiAuthenticationFactory.scala +++ b/kyuubi-common/src/main/scala/org/apache/kyuubi/service/authentication/KyuubiAuthenticationFactory.scala @@ -50,7 +50,7 @@ class KyuubiAuthenticationFactory(conf: KyuubiConf, isServer: Boolean = true) ex } } - if (conf.get(ENGINE_SECURITY_ENABLED)) { + if (conf.get(INTERNAL_SECURITY_ENABLED)) { InternalSecurityAccessor.initialize(conf, isServer) } diff --git a/kyuubi-common/src/test/scala/org/apache/kyuubi/service/authentication/InternalSecurityAccessorSuite.scala b/kyuubi-common/src/test/scala/org/apache/kyuubi/service/authentication/InternalSecurityAccessorSuite.scala index e92ac7e6185..17bdd51e0a1 100644 --- a/kyuubi-common/src/test/scala/org/apache/kyuubi/service/authentication/InternalSecurityAccessorSuite.scala +++ b/kyuubi-common/src/test/scala/org/apache/kyuubi/service/authentication/InternalSecurityAccessorSuite.scala @@ -22,13 +22,13 @@ import org.apache.kyuubi.config.KyuubiConf class InternalSecurityAccessorSuite extends KyuubiFunSuite { private val conf = KyuubiConf() - .set(KyuubiConf.ENGINE_SECURITY_SECRET_PROVIDER, "simple") - .set(KyuubiConf.SIMPLE_SECURITY_SECRET_PROVIDER_PROVIDER_SECRET, "ENGINE____SECRET") + .set(KyuubiConf.INTERNAL_SECURITY_SECRET_PROVIDER, "simple") + .set(KyuubiConf.INTERNAL_SECURITY_SECRET_PROVIDER_SIMPLE_SECRET.key, "ENGINE____SECRET") test("test encrypt/decrypt, issue token/auth token") { Seq("AES/CBC/PKCS5PADDING", "AES/CTR/NoPadding").foreach { cipher => val newConf = conf.clone - newConf.set(KyuubiConf.ENGINE_SECURITY_CRYPTO_CIPHER_TRANSFORMATION, cipher) + newConf.set(KyuubiConf.INTERNAL_SECURITY_CRYPTO_CIPHER_TRANSFORMATION, cipher) val secureAccessor = new InternalSecurityAccessor(newConf, true) val value = "tokenToEncrypt" From 8be695c3cae420a46c292fa11bc2be1c66783b28 Mon Sep 17 00:00:00 2001 From: Akira Ajisaka Date: Thu, 7 May 2026 12:56:19 +0900 Subject: [PATCH 4/6] Add internal secure access doc --- docs/configuration/settings.md | 18 +++--- docs/security/index.rst | 1 + docs/security/internal_secure_access.md | 57 +++++++++++++++++++ .../org/apache/kyuubi/config/KyuubiConf.scala | 7 +-- 4 files changed, 71 insertions(+), 12 deletions(-) create mode 100644 docs/security/internal_secure_access.md diff --git a/docs/configuration/settings.md b/docs/configuration/settings.md index c529c329813..9f85743896c 100644 --- a/docs/configuration/settings.md +++ b/docs/configuration/settings.md @@ -356,14 +356,16 @@ You can configure the Kyuubi properties in `$KYUUBI_HOME/conf/kyuubi-defaults.co ### Internal -| Key | Default | Meaning | Type | Since | -|--------------------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------| -| kyuubi.internal.security.crypto.ivLength | 16 | Initial vector length, in bytes. Only take affects when kyuubi.internal.security.enabled is set to true. | int | 1.12.0 | -| kyuubi.internal.security.crypto.keyLength | 128 | The length in bits of the encryption key to generate. Only take affects when kyuubi.internal.security.enabled is set to true. Valid values are 128, 192 and 256 | int | 1.12.0 | -| kyuubi.internal.security.enabled | false | Whether to enable secure access across all the internal communications, both
  • between kyuubi server and kyuubi engine
  • across kyuubi server instances
You need to also provide configure | boolean | 1.12.0 | -| kyuubi.internal.security.secret.provider | zookeeper | The class used to manage the internal security secret. This class must be a subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following built-in implementations:
  • simple: Use the secret set by kyuubi.internal.security.secret.provider.simple.secret.
  • zookeeper: Use the secret stored in ZooKeeper. kyuubi.ha.zookeeper.engine.secure.secret.node must be configured.
Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | -| kyuubi.internal.security.secret.provider.simple.secret | <undefined> | The secret key used for internal security access. Only take affects when kyuubi.internal.security.enabled is set to true and kyuubi.internal.security.secret.provider is 'simple' | string | 1.12.0 | -| kyuubi.internal.security.token.max.lifetime | PT10M | The max lifetime of the token used for internal secure access. Only take affects when kyuubi.internal.security.enabled is set to true. | duration | 1.12.0 | +| Key | Default | Meaning | Type | Since | +|--------------------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------| +| kyuubi.internal.security.crypto.cipher | AES/CBC/PKCS5PADDING | The cipher transformation to use for encrypting internal access token. Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | +| kyuubi.internal.security.crypto.ivLength | 16 | Initial vector length, in bytes. Only take affects when kyuubi.internal.security.enabled is set to true. | int | 1.12.0 | +| kyuubi.internal.security.crypto.keyAlgorithm | AES | The algorithm for generated secret keys. Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | +| kyuubi.internal.security.crypto.keyLength | 128 | The length in bits of the encryption key to generate. Only take affects when kyuubi.internal.security.enabled is set to true. Valid values are 128, 192 and 256 | int | 1.12.0 | +| kyuubi.internal.security.enabled | false | Whether to enable secure access across all the internal communications, both
  • between kyuubi server and kyuubi engine
  • between kyuubi server instances
You need to also provide configure kyuubi.internal.security.secret.provider to manage the encryption secret. | boolean | 1.12.0 | +| kyuubi.internal.security.secret.provider | zookeeper | The class used to manage the internal security secret. This class must be a subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following built-in implementations:
  • simple: Use the secret set by kyuubi.internal.security.secret.provider.simple.secret.
  • zookeeper: Use the secret stored in ZooKeeper. kyuubi.ha.zookeeper.engine.secure.secret.node must be configured.
Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | +| kyuubi.internal.security.secret.provider.simple.secret | <undefined> | The secret key used for internal security access. Only take affects when kyuubi.internal.security.enabled is set to true and kyuubi.internal.security.secret.provider is 'simple' | string | 1.12.0 | +| kyuubi.internal.security.token.max.lifetime | PT10M | The max lifetime of the token used for internal secure access. Only take affects when kyuubi.internal.security.enabled is set to true. | duration | 1.12.0 | ### Kinit diff --git a/docs/security/index.rst b/docs/security/index.rst index 93a9b7930b3..9cb0398111a 100644 --- a/docs/security/index.rst +++ b/docs/security/index.rst @@ -25,4 +25,5 @@ Securing Kyuubi involves enabling authentication(authn), authorization(authz) an Authorization kinit hadoop_credentials_manager + internal_secure_access diff --git a/docs/security/internal_secure_access.md b/docs/security/internal_secure_access.md new file mode 100644 index 00000000000..82217d0b7e7 --- /dev/null +++ b/docs/security/internal_secure_access.md @@ -0,0 +1,57 @@ + + +# Internal Secure Access + +Kyuubi supports secure communication channels for all internal interactions, both: + +* Between the Kyuubi server and Kyuubi engines. +* Between Kyuubi server instances (High availability mode). + +If `kyuubi.internal.security.enabled` is set to `true`, all internal communication are encrypted. + +## Managing encryption secrets + +Encryption secrets are managed by a subclass of `org.apache.kyuubi.service.authentication.EngineSecuritySecretProvider`, +which can be configured via `kyuubi.internal.security.secret.provider`. + +Kyuubi provides the following built-in implementations: + +* simple: Use the secret configured by `kyuubi.internal.security.secret.provider.simple.secret`. +* zookeeper: Use the secret stored in the ZooKeeper znode configured by `kyuubi.ha.zookeeper.engine.secure.secret.node`. + +We strongly recommend restricting access to these secrets. + +* If using the `simple` provider, you should also configure `kyuubi.server.redaction.regex` + (e.g., `(?i)secret|password|token|access[.]?key`) to redact the secret. +* If using the `zookeeper` provider, ensure that ACLs (Access Control Lists) are properly configured for the znode + where the secret is stored. + +Custom implementations of `EngineSecuritySecretProvider` are also supported for advanced secret management needs. + +## Configurations + +| Key | Default | Meaning | Type | Since | +|----------------------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------|----------|--------| +| `kyuubi.internal.security.enabled` | false | Whether to enable secure access across all the internal communications. | boolean | 1.12.0 | +| `kyuubi.internal.security.token.max.lifetime` | PT10M | The max lifetime of the token used for internal secure access. | duration | 1.12.0 | +| `kyuubi.internal.security.secret.provider` | zookeeper | The class used to manage the internal security secret. | string | 1.12.0 | +| `kyuubi.internal.security.secret.provider.simple.secret` | <undefined> | The secret key used for internal security access when `kyuubi.internal.security.secret.provider` is set to `simple`. | string | 1.12.0 | +| `kyuubi.internal.security.crypto.keyAlgorithm` | AES | The algorithm for generated secret key. | string | 1.12.0 | +| `kyuubi.internal.security.crypto.keyLength` | 128 | The length in bits of the encryption key to generate. Valid values are 128, 192, and 256. | int | 1.12.0 | +| `kyuubi.internal.security.crypto.cipher` | AES/CBC/PKCS5PADDING | The cipher transformation to use for encrypting internal access token. | string | 1.12.0 | +| `kyuubi.internal.security.crypto.ivLength` | 16 | Initial vector length, in bytes. | int | 1.12.0 | diff --git a/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala b/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala index 53fef965f34..c4225a939c3 100644 --- a/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala +++ b/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala @@ -2836,8 +2836,9 @@ object KyuubiConf { buildConf("kyuubi.internal.security.enabled") .doc("Whether to enable secure access across all the internal communications, both
    " + "
  • between kyuubi server and kyuubi engine
    • " + - "
  • across kyuubi server instances
" + - "You need to also provide configure ") + "
  • between kyuubi server instances
    • " + + s"You need to also provide configure kyuubi.internal.security.secret.provider to manage " + + s"the encryption secret.") .version("1.12.0") .fallbackConf(ENGINE_SECURITY_ENABLED) @@ -2884,7 +2885,6 @@ object KyuubiConf { val INTERNAL_SECURITY_CRYPTO_KEY_ALGORITHM: ConfigEntry[String] = buildConf("kyuubi.internal.security.crypto.keyAlgorithm") - .internal .doc("The algorithm for generated secret keys. Only take affects when" + s" ${INTERNAL_SECURITY_ENABLED.key} is set to true.") .version("1.12.0") @@ -2892,7 +2892,6 @@ object KyuubiConf { val INTERNAL_SECURITY_CRYPTO_CIPHER_TRANSFORMATION: ConfigEntry[String] = buildConf("kyuubi.internal.security.crypto.cipher") - .internal .doc("The cipher transformation to use for encrypting internal access token." + s" Only take affects when ${INTERNAL_SECURITY_ENABLED.key} is set to true.") .version("1.12.0") From c9f6203912dc48f0d60504b674efe867fa483d0c Mon Sep 17 00:00:00 2001 From: Akira Ajisaka Date: Thu, 7 May 2026 18:27:23 +0900 Subject: [PATCH 5/6] Fix doc formatting --- docs/security/internal_secure_access.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/security/internal_secure_access.md b/docs/security/internal_secure_access.md index 82217d0b7e7..7165f864b4c 100644 --- a/docs/security/internal_secure_access.md +++ b/docs/security/internal_secure_access.md @@ -45,7 +45,7 @@ Custom implementations of `EngineSecuritySecretProvider` are also supported for ## Configurations -| Key | Default | Meaning | Type | Since | +| Key | Default | Meaning | Type | Since | |----------------------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------|----------|--------| | `kyuubi.internal.security.enabled` | false | Whether to enable secure access across all the internal communications. | boolean | 1.12.0 | | `kyuubi.internal.security.token.max.lifetime` | PT10M | The max lifetime of the token used for internal secure access. | duration | 1.12.0 | @@ -55,3 +55,4 @@ Custom implementations of `EngineSecuritySecretProvider` are also supported for | `kyuubi.internal.security.crypto.keyLength` | 128 | The length in bits of the encryption key to generate. Valid values are 128, 192, and 256. | int | 1.12.0 | | `kyuubi.internal.security.crypto.cipher` | AES/CBC/PKCS5PADDING | The cipher transformation to use for encrypting internal access token. | string | 1.12.0 | | `kyuubi.internal.security.crypto.ivLength` | 16 | Initial vector length, in bytes. | int | 1.12.0 | + From 861cea95fba513c789068f13c87e9a7ccdf7be80 Mon Sep 17 00:00:00 2001 From: Akira Ajisaka Date: Wed, 13 May 2026 15:18:46 +0900 Subject: [PATCH 6/6] Improve the doc --- docs/configuration/settings.md | 20 +++++++++---------- docs/security/internal_secure_access.md | 6 ++++-- .../org/apache/kyuubi/config/KyuubiConf.scala | 2 +- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/configuration/settings.md b/docs/configuration/settings.md index 9f85743896c..21a626c6874 100644 --- a/docs/configuration/settings.md +++ b/docs/configuration/settings.md @@ -356,16 +356,16 @@ You can configure the Kyuubi properties in `$KYUUBI_HOME/conf/kyuubi-defaults.co ### Internal -| Key | Default | Meaning | Type | Since | -|--------------------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------| -| kyuubi.internal.security.crypto.cipher | AES/CBC/PKCS5PADDING | The cipher transformation to use for encrypting internal access token. Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | -| kyuubi.internal.security.crypto.ivLength | 16 | Initial vector length, in bytes. Only take affects when kyuubi.internal.security.enabled is set to true. | int | 1.12.0 | -| kyuubi.internal.security.crypto.keyAlgorithm | AES | The algorithm for generated secret keys. Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | -| kyuubi.internal.security.crypto.keyLength | 128 | The length in bits of the encryption key to generate. Only take affects when kyuubi.internal.security.enabled is set to true. Valid values are 128, 192 and 256 | int | 1.12.0 | -| kyuubi.internal.security.enabled | false | Whether to enable secure access across all the internal communications, both
    • between kyuubi server and kyuubi engine
    • between kyuubi server instances
    You need to also provide configure kyuubi.internal.security.secret.provider to manage the encryption secret. | boolean | 1.12.0 | -| kyuubi.internal.security.secret.provider | zookeeper | The class used to manage the internal security secret. This class must be a subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following built-in implementations:
    • simple: Use the secret set by kyuubi.internal.security.secret.provider.simple.secret.
    • zookeeper: Use the secret stored in ZooKeeper. kyuubi.ha.zookeeper.engine.secure.secret.node must be configured.
    Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | -| kyuubi.internal.security.secret.provider.simple.secret | <undefined> | The secret key used for internal security access. Only take affects when kyuubi.internal.security.enabled is set to true and kyuubi.internal.security.secret.provider is 'simple' | string | 1.12.0 | -| kyuubi.internal.security.token.max.lifetime | PT10M | The max lifetime of the token used for internal secure access. Only take affects when kyuubi.internal.security.enabled is set to true. | duration | 1.12.0 | +| Key | Default | Meaning | Type | Since | +|--------------------------------------------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------| +| kyuubi.internal.security.crypto.cipher | AES/CBC/PKCS5PADDING | The cipher transformation to use for encrypting internal access token. Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | +| kyuubi.internal.security.crypto.ivLength | 16 | Initial vector length, in bytes. Only take affects when kyuubi.internal.security.enabled is set to true. | int | 1.12.0 | +| kyuubi.internal.security.crypto.keyAlgorithm | AES | The algorithm for generated secret keys. Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | +| kyuubi.internal.security.crypto.keyLength | 128 | The length in bits of the encryption key to generate. Only take affects when kyuubi.internal.security.enabled is set to true. Valid values are 128, 192 and 256 | int | 1.12.0 | +| kyuubi.internal.security.enabled | false | Whether to enable secure access across all the internal communications, both
    • between kyuubi server and kyuubi engine
    • between kyuubi server instances
    You need to also provide configure kyuubi.internal.security.secret.provider to manage the encryption secret. | boolean | 1.12.0 | +| kyuubi.internal.security.secret.provider | zookeeper | The class used to manage the internal security secret. This class must be a subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following built-in implementations:
    • simple: Use the pre-shared secret set by kyuubi.internal.security.secret.provider.simple.secret.
    • zookeeper: Use the secret stored in ZooKeeper. kyuubi.ha.zookeeper.engine.secure.secret.node must be configured.
    Only take affects when kyuubi.internal.security.enabled is set to true. | string | 1.12.0 | +| kyuubi.internal.security.secret.provider.simple.secret | <undefined> | The secret key used for internal security access. Only take affects when kyuubi.internal.security.enabled is set to true and kyuubi.internal.security.secret.provider is 'simple' | string | 1.12.0 | +| kyuubi.internal.security.token.max.lifetime | PT10M | The max lifetime of the token used for internal secure access. Only take affects when kyuubi.internal.security.enabled is set to true. | duration | 1.12.0 | ### Kinit diff --git a/docs/security/internal_secure_access.md b/docs/security/internal_secure_access.md index 7165f864b4c..980f1bd4d1d 100644 --- a/docs/security/internal_secure_access.md +++ b/docs/security/internal_secure_access.md @@ -20,9 +20,11 @@ Kyuubi supports secure communication channels for all internal interactions, both: * Between the Kyuubi server and Kyuubi engines. -* Between Kyuubi server instances (High availability mode). +* Between Kyuubi server instances (REST API high availability mode). If `kyuubi.internal.security.enabled` is set to `true`, all internal communication are encrypted. +Currently, it's enforced to set `kyuubi.internal.security.enabled` to `true` if you want to use +REST API high availability mode. ## Managing encryption secrets @@ -31,7 +33,7 @@ which can be configured via `kyuubi.internal.security.secret.provider`. Kyuubi provides the following built-in implementations: -* simple: Use the secret configured by `kyuubi.internal.security.secret.provider.simple.secret`. +* simple: Use the pre-shared secret configured by `kyuubi.internal.security.secret.provider.simple.secret`. * zookeeper: Use the secret stored in the ZooKeeper znode configured by `kyuubi.ha.zookeeper.engine.secure.secret.node`. We strongly recommend restricting access to these secrets. diff --git a/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala b/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala index c4225a939c3..e6b203fd295 100644 --- a/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala +++ b/kyuubi-common/src/main/scala/org/apache/kyuubi/config/KyuubiConf.scala @@ -2853,7 +2853,7 @@ object KyuubiConf { buildConf("kyuubi.internal.security.secret.provider") .doc("The class used to manage the internal security secret. This class must be a " + "subclass of `EngineSecuritySecretProvider`. Kyuubi provides the following " + - "built-in implementations:
    • simple: Use the secret set by " + + "built-in implementations:
      • simple: Use the pre-shared secret set by " + s"kyuubi.internal.security.secret.provider.simple.secret.
        • " + "
      • zookeeper: Use the secret stored in ZooKeeper. " + "kyuubi.ha.zookeeper.engine.secure.secret.node must be configured.
      " +