Hadoop 密钥管理服务器 (KMS) - 文档集

KMS 客户端配置
KMS

Hadoop KMS 是基于 Hadoop 的KeyProvider API 的加密密钥管理服务器。

它提供了一个客户端和一个服务器组件，它们使用 REST API 通过 HTTP 进行通信。

该客户端是一个 KeyProvider 实现，它使用 KMS HTTP REST API 与 KMS 交互。

KMS 及其客户端具有内置安全性，并且它们支持 HTTP SPNEGO Kerberos 身份验证和 HTTPS 安全传输。

KMS 是一个 Java Jetty Web 应用程序。

KMS 客户端配置

KMS 客户端 KeyProvider 使用 kms 方案，嵌入式 URL 必须是 KMS 的 URL。例如，对于在 http://localhost:9600/kms 上运行的 KMS，KeyProvider URI 为 kms://http@localhost:9600/kms。而对于在 https://localhost:9600/kms 上运行的 KMS，KeyProvider URI 为 kms://https@localhost:9600/kms

以下是在 core-site.xml 中将 HDFS NameNode 配置为 KMS 客户端的示例

<property>
  <name>hadoop.security.key.provider.path</name>
  <value>kms://http@localhost:9600/kms</value>
  <description>
    The KeyProvider to use when interacting with encryption keys used
    when reading and writing to an encryption zone.
  </description>
</property>

KMS

启动/停止 KMS

要启动/停止 KMS，请使用 hadoop --daemon start|stop kms。例如

hadoop-3.3.6 $ hadoop --daemon start kms

注意：脚本 kms.sh 已弃用。它现在只是 hadoop kms 的一个包装器。

KMS 配置

在 etc/hadoop/kms-site.xml 配置文件中配置 KMS 支持的 KeyProvider 属性

  <property>
     <name>hadoop.kms.key.provider.uri</name>
     <value>jceks://file@/${user.home}/kms.keystore</value>
  </property>

  <property>
    <name>hadoop.security.keystore.java-keystore-provider.password-file</name>
    <value>kms.keystore.password</value>
  </property>

密码文件通过类路径在 Hadoop 的配置目录中查找。

注意：您需要重新启动 KMS 才能使配置更改生效。

注意：KMS 服务器可以选择任何 KeyProvider 实现作为支持提供程序。此处的示例使用 JavaKeyStoreProvider，该提供程序仅应出于实验目的而使用，切勿在生产中使用。有关 JavaKeyStoreProvider 的详细用法和注意事项，请参阅凭据提供程序 API 的密钥库密码部分。

KMS HTTP 配置

KMS 将 HTTP 端口预配置为 9600。

KMS 支持在 etc/hadoop/kms-site.xml 中以下 HTTP 配置属性。

注意：您需要重新启动 KMS 才能使配置更改生效。

KMS 缓存

KMS 有两种缓存：用于缓存加密密钥的 CachingKeyProvider，以及用于缓存 EEK 的 KeyProvider。

CachingKeyProvider

KMS 在短时间内缓存加密密钥，以避免对底层 KeyProvider 过度命中。

此缓存默认启用（可以通过将 hadoop.kms.cache.enable 布尔属性设置为 false 来禁用）

此缓存仅与以下 3 个方法一起使用，getCurrentKey() 和 getKeyVersion() 和 getMetadata()。

对于 getCurrentKey() 方法，无论访问密钥的次数如何，缓存的条目最多保留 30000 毫秒（以避免将过时的密钥视为当前密钥）。

对于 getKeyVersion() 和 getMetadata() 方法，缓存的条目保留的默认非活动超时时间为 600000 毫秒（10 分钟）。

当密钥被 deleteKey() 删除，或调用 invalidateCache() 时，缓存将失效。

可以通过 etc/hadoop/kms-site.xml 配置文件中的以下属性更改这些配置

   <property>
     <name>hadoop.kms.cache.enable</name>
     <value>true</value>
   </property>

   <property>
     <name>hadoop.kms.cache.timeout.ms</name>
     <value>600000</value>
   </property>

   <property>
     <name>hadoop.kms.current.key.cache.timeout.ms</name>
     <value>30000</value>
   </property>

密钥提供程序

在架构上，服务器端（例如 KMS）和客户端（例如 NameNode）都为 EEK 缓存。可以在缓存中配置以下内容

缓存大小。这是每个密钥名称下可缓存的 EEK 的最大数量。
缓存上的低水位线。对于每个密钥名称，如果在 get 调用后，缓存的 EEK 数量少于（大小 * 低水位线），则此密钥名称下的缓存将异步填充。对于每个密钥名称，只有一个线程可以运行以进行异步填充。
允许填充缓存中队列的跨密钥名称的异步线程的最大数量。
缓存过期时间（以毫秒为单位）。内部使用 Guava 缓存作为缓存实现。过期方法是 expireAfterAccess。

请注意，由于异步填充机制，在 rollNewVersion() 之后，调用者仍可能获取旧 EEK。在最坏的情况下，调用者最多可能获取（服务器端缓存大小 + 客户端缓存大小）数量的旧 EEK，或者直到两个缓存都过期。此行为是为了避免锁定缓存而进行的权衡，并且是可以接受的，因为旧版本的 EEK 仍可用于解密。

以下是配置及其默认值

可以通过 etc/hadoop/kms-site.xml 配置文件中的以下属性更改服务器端

   <property>
     <name>hadoop.security.kms.encrypted.key.cache.size</name>
     <value>500</value>
   </property>

   <property>
     <name>hadoop.security.kms.encrypted.key.cache.low.watermark</name>
     <value>0.3</value>
   </property>

   <property>
     <name>hadoop.security.kms.encrypted.key.cache.num.fill.threads</name>
     <value>2</value>
   </property>

   <property>
     <name>hadoop.security.kms.encrypted.key.cache.expiry</name>
     <value>43200000</value>
   </property>

可以通过 etc/hadoop/core-site.xml 配置文件中的以下属性更改客户端

   <property>
     <name>hadoop.security.kms.client.encrypted.key.cache.size</name>
     <value>500</value>
   </property>

   <property>
     <name>hadoop.security.kms.client.encrypted.key.cache.low-watermark</name>
     <value>0.3</value>
   </property>

   <property>
     <name>hadoop.security.kms.client.encrypted.key.cache.num.refill.threads</name>
     <value>2</value>
   </property>

   <property>
     <name>hadoop.security.kms.client.encrypted.key.cache.expiry</name>
     <value>43200000</value>
   </property>

KMS 聚合审计日志

对 GET_KEY_VERSION、GET_CURRENT_KEY、DECRYPT_EEK、GENERATE_EEK、REENCRYPT_EEK 操作的 API 访问聚合审计日志。

条目按（用户、密钥、操作）组合键分组，在可配置的聚合间隔后，将用户对给定密钥执行的指定端点的访问次数刷新到审计日志。

通过属性配置聚合间隔

  <property>
    <name>hadoop.kms.aggregation.delay.ms</name>
    <value>10000</value>
  </property>

KMS 安全配置

启用 Kerberos HTTP SPNEGO 身份验证

使用 KDC 服务器的信息配置 Kerberos etc/krb5.conf 文件。

为 KMS 创建服务主体及其密钥表，它必须是 HTTP 服务主体。

使用正确的安全值配置 KMS etc/hadoop/kms-site.xml，例如

   <property>
     <name>hadoop.kms.authentication.type</name>
     <value>kerberos</value>
   </property>

   <property>
     <name>hadoop.kms.authentication.kerberos.keytab</name>
     <value>${user.home}/kms.keytab</value>
   </property>

   <property>
     <name>hadoop.kms.authentication.kerberos.principal</name>
     <value>HTTP/localhost</value>
   </property>

   <property>
     <name>hadoop.kms.authentication.kerberos.name.rules</name>
     <value>DEFAULT</value>
   </property>

注意：您需要重新启动 KMS 才能使配置更改生效。

KMS 代理用户配置

每个代理用户都必须在 etc/hadoop/kms-site.xml 中使用以下属性进行配置

  <property>
    <name>hadoop.kms.proxyuser.#USER#.users</name>
    <value>*</value>
  </property>

  <property>
    <name>hadoop.kms.proxyuser.#USER#.groups</name>
    <value>*</value>
  </property>

  <property>
    <name>hadoop.kms.proxyuser.#USER#.hosts</name>
    <value>*</value>
  </property>

#USER# 是要配置的代理用户的用户名。

users 属性表示可以模拟的用户。

groups 属性表示要模拟的用户必须属于的组。

必须至少定义 users 或 groups 属性之一。如果同时指定了这两个属性，则配置的代理用户将能够模拟 users 列表中的用户和属于 groups 列表中某个组的任何用户。

hosts 属性表示代理用户可以从中发出模拟请求的主机。

如果 users、groups 或 hosts 有 *，则表示代理用户在用户、组或主机方面没有限制。

通过 HTTPS（SSL）使用 KMS

在 etc/hadoop/kms-site.xml 中启用 SSL

  <property>
    <name>hadoop.kms.ssl.enabled</name>
    <value>true</value>
    <description>
      Whether SSL is enabled. Default is false, i.e. disabled.
    </description>
  </property>

使用适当的值配置 etc/hadoop/ssl-server.xml，例如

<property>
  <name>ssl.server.keystore.location</name>
  <value>${user.home}/.keystore</value>
  <description>Keystore to be used. Must be specified.</description>
</property>

<property>
  <name>ssl.server.keystore.password</name>
  <value></value>
  <description>Must be specified.</description>
</property>

<property>
  <name>ssl.server.keystore.keypassword</name>
  <value></value>
  <description>Must be specified.</description>
</property>

SSL 密码可以通过凭据提供程序进行保护。请参阅凭据提供程序 API。

您需要为 KMS 创建一个 SSL 证书。作为 kms Unix 用户，使用 Java keytool 命令创建 SSL 证书

$ keytool -genkey -alias jetty -keyalg RSA

系统将在交互式提示符中向您询问一系列问题。它将创建密钥库文件，该文件将被命名为 .keystore 并位于用户的 home 目录中。

您为“密钥库密码”输入的密码必须与配置目录中 ssl-server.xml 中设置的属性 ssl.server.keystore.password 的值匹配。

对“您的名字和姓氏是什么？”（即“CN”）的回答必须是 KMS 将要运行的机器的主机名。

注意：您需要重新启动 KMS 才能使配置更改生效。

注意：某些旧的 SSL 客户端可能使用 KMS 服务器不支持的弱密码。建议升级 SSL 客户端。

ACL（访问控制列表）

KMS 支持 ACL（访问控制列表）以实现细粒度的权限控制。

KMS 中存在两级 ACL：KMS ACL 和密钥 ACL。KMS ACL 控制 KMS 操作级别的访问，并优先于密钥 ACL。具体来说，只有在 KMS ACL 级别授予权限后，才会执行针对密钥 ACL 的权限检查。

以下部分介绍了 KMS ACL 和密钥 ACL 的配置和用法。

KMS ACL

KMS ACL 配置在 KMS etc/hadoop/kms-acls.xml 配置文件中定义。此文件在更改时会热重新加载。

KMS 支持精细访问控制以及通过一组 ACL 配置属性对 kms 操作进行黑名单处理。

访问 KMS 的用户首先会检查是否包含在请求操作的访问控制列表中，然后在授予访问权限之前检查是否包含在操作的黑名单中。

<configuration>
  <property>
    <name>hadoop.kms.acl.CREATE</name>
    <value>*</value>
    <description>
          ACL for create-key operations.
          If the user is not in the GET ACL, the key material is not returned
          as part of the response.
    </description>
  </property>

  <property>
    <name>hadoop.kms.blacklist.CREATE</name>
    <value>hdfs,foo</value>
    <description>
          Blacklist for create-key operations.
          If the user is in the Blacklist, the key material is not returned
          as part of the response.
    </description>
  </property>

  <property>
    <name>hadoop.kms.acl.DELETE</name>
    <value>*</value>
    <description>
          ACL for delete-key operations.
    </description>
  </property>

  <property>
    <name>hadoop.kms.blacklist.DELETE</name>
    <value>hdfs,foo</value>
    <description>
          Blacklist for delete-key operations.
    </description>
  </property>

  <property>
    <name>hadoop.kms.acl.ROLLOVER</name>
    <value>*</value>
    <description>
          ACL for rollover-key operations.
          If the user is not in the GET ACL, the key material is not returned
          as part of the response.
    </description>
  </property>

  <property>
    <name>hadoop.kms.blacklist.ROLLOVER</name>
    <value>hdfs,foo</value>
    <description>
          Blacklist for rollover-key operations.
    </description>
  </property>

  <property>
    <name>hadoop.kms.acl.GET</name>
    <value>*</value>
    <description>
          ACL for get-key-version and get-current-key operations.
    </description>
  </property>

  <property>
    <name>hadoop.kms.blacklist.GET</name>
    <value>hdfs,foo</value>
    <description>
          ACL for get-key-version and get-current-key operations.
    </description>
  </property>

  <property>
    <name>hadoop.kms.acl.GET_KEYS</name>
    <value>*</value>
    <description>
         ACL for get-keys operation.
    </description>
  </property>

  <property>
    <name>hadoop.kms.blacklist.GET_KEYS</name>
    <value>hdfs,foo</value>
    <description>
          Blacklist for get-keys operation.
    </description>
  </property>

  <property>
    <name>hadoop.kms.acl.GET_METADATA</name>
    <value>*</value>
    <description>
        ACL for get-key-metadata and get-keys-metadata operations.
    </description>
  </property>

  <property>
    <name>hadoop.kms.blacklist.GET_METADATA</name>
    <value>hdfs,foo</value>
    <description>
         Blacklist for get-key-metadata and get-keys-metadata operations.
    </description>
  </property>

  <property>
    <name>hadoop.kms.acl.SET_KEY_MATERIAL</name>
    <value>*</value>
    <description>
            Complimentary ACL for CREATE and ROLLOVER operation to allow the client
            to provide the key material when creating or rolling a key.
    </description>
  </property>

  <property>
    <name>hadoop.kms.blacklist.SET_KEY_MATERIAL</name>
    <value>hdfs,foo</value>
    <description>
            Complimentary Blacklist for CREATE and ROLLOVER operation to allow the client
            to provide the key material when creating or rolling a key.
    </description>
  </property>

  <property>
    <name>hadoop.kms.acl.GENERATE_EEK</name>
    <value>*</value>
    <description>
          ACL for generateEncryptedKey
          CryptoExtension operations
    </description>
  </property>

  <property>
    <name>hadoop.kms.blacklist.GENERATE_EEK</name>
    <value>hdfs,foo</value>
    <description>
          Blacklist for generateEncryptedKey
          CryptoExtension operations
    </description>
  </property>

  <property>
    <name>hadoop.kms.acl.DECRYPT_EEK</name>
    <value>*</value>
    <description>
          ACL for decrypt EncryptedKey
          CryptoExtension operations
    </description>
  </property>

  <property>
    <name>hadoop.kms.blacklist.DECRYPT_EEK</name>
    <value>hdfs,foo</value>
    <description>
          Blacklist for decrypt EncryptedKey
          CryptoExtension operations
    </description>
  </property>
</configuration>

密钥 ACL

KMS 支持在密钥级别对所有非读取操作进行访问控制。所有密钥访问操作都分类为

MANAGEMENT - createKey、deleteKey、rolloverNewVersion
GENERATE_EEK - generateEncryptedKey、reencryptEncryptedKey、reencryptEncryptedKeys、warmUpEncryptedKeys
DECRYPT_EEK - decryptEncryptedKey
READ - getKeyVersion、getKeyVersions、getMetadata、getKeysMetadata、getCurrentKey
ALL - 以上所有

这些可以在 KMS etc/hadoop/kms-acls.xml 中按如下方式定义

对于尚未明确配置密钥访问权限的所有密钥，可以为操作类型的子集配置默认密钥访问控制。

还可以为操作类型的子集配置“白名单”密钥 ACL。白名单密钥 ACL 授予对密钥的访问权限，此外还有明确或默认的每个密钥 ACL。也就是说，如果没有明确设置每个密钥 ACL，则当用户存在于默认每个密钥 ACL 或白名单密钥 ACL 中时，将授予其访问权限。如果明确设置了每个密钥 ACL，则当用户存在于每个密钥 ACL 或白名单密钥 ACL 中时，将授予其访问权限。

如果未针对特定密钥配置 ACL 且未配置默认 ACL 且未针对请求的操作配置白名单密钥 ACL，则将拒绝访问。

注意：默认和白名单密钥 ACL 不支持 ALL 操作限定符。

  <property>
    <name>key.acl.testKey1.MANAGEMENT</name>
    <value>*</value>
    <description>
      ACL for create-key, deleteKey and rolloverNewVersion operations.
    </description>
  </property>

  <property>
    <name>key.acl.testKey2.GENERATE_EEK</name>
    <value>*</value>
    <description>
      ACL for generateEncryptedKey operations.
    </description>
  </property>

  <property>
    <name>key.acl.testKey3.DECRYPT_EEK</name>
    <value>admink3</value>
    <description>
      ACL for decryptEncryptedKey operations.
    </description>
  </property>

  <property>
    <name>key.acl.testKey4.READ</name>
    <value>*</value>
    <description>
      ACL for getKeyVersion, getKeyVersions, getMetadata, getKeysMetadata,
      getCurrentKey operations
    </description>
  </property>

  <property>
    <name>key.acl.testKey5.ALL</name>
    <value>*</value>
    <description>
      ACL for ALL operations.
    </description>
  </property>

  <property>
    <name>whitelist.key.acl.MANAGEMENT</name>
    <value>admin1</value>
    <description>
      whitelist ACL for MANAGEMENT operations for all keys.
    </description>
  </property>

  <!--
  'testKey3' key ACL is defined. Since a 'whitelist'
  key is also defined for DECRYPT_EEK, in addition to
  admink3, admin1 can also perform DECRYPT_EEK operations
  on 'testKey3'
-->
  <property>
    <name>whitelist.key.acl.DECRYPT_EEK</name>
    <value>admin1</value>
    <description>
      whitelist ACL for DECRYPT_EEK operations for all keys.
    </description>
  </property>

  <property>
    <name>default.key.acl.MANAGEMENT</name>
    <value>user1,user2</value>
    <description>
      default ACL for MANAGEMENT operations for all keys that are not
      explicitly defined.
    </description>
  </property>

  <property>
    <name>default.key.acl.GENERATE_EEK</name>
    <value>user1,user2</value>
    <description>
      default ACL for GENERATE_EEK operations for all keys that are not
      explicitly defined.
    </description>
  </property>

  <property>
    <name>default.key.acl.DECRYPT_EEK</name>
    <value>user1,user2</value>
    <description>
      default ACL for DECRYPT_EEK operations for all keys that are not
      explicitly defined.
    </description>
  </property>

  <property>
    <name>default.key.acl.READ</name>
    <value>user1,user2</value>
    <description>
      default ACL for READ operations for all keys that are not
      explicitly defined.
    </description>
  </property>

KMS 委派令牌配置

KMS 支持委派令牌，以便从没有 Kerberos 凭据的进程对密钥提供程序进行身份验证。

KMS 委派令牌身份验证扩展了默认的 Hadoop 身份验证。与 Hadoop 身份验证相同，KMS 委派令牌不得使用委派令牌身份验证来获取或续订。有关更多详细信息，请参阅 Hadoop Auth 页面。

此外，KMS 委派令牌密钥管理器可以使用以下属性进行配置

  <property>
    <name>hadoop.kms.authentication.delegation-token.update-interval.sec</name>
    <value>86400</value>
    <description>
      How often the master key is rotated, in seconds. Default value 1 day.
    </description>
  </property>

  <property>
    <name>hadoop.kms.authentication.delegation-token.max-lifetime.sec</name>
    <value>604800</value>
    <description>
      Maximum lifetime of a delegation token, in seconds. Default value 7 days.
    </description>
  </property>

  <property>
    <name>hadoop.kms.authentication.delegation-token.renew-interval.sec</name>
    <value>86400</value>
    <description>
      Renewal interval of a delegation token, in seconds. Default value 1 day.
    </description>
  </property>

  <property>
    <name>hadoop.kms.authentication.delegation-token.removal-scan-interval.sec</name>
    <value>3600</value>
    <description>
      Scan interval to remove expired delegation tokens.
    </description>
  </property>

高可用性

可以使用多个 KMS 实例来提供高可用性和可伸缩性。目前有两种支持多个 KMS 实例的方法：在负载均衡器/VIP 后面运行 KMS 实例，或使用 LoadBalancingKMSClientProvider。

在这两种方法中，必须对 KMS 实例进行特殊配置，以使其能够作为单个逻辑服务正常工作，因为来自同一客户端的请求可能由不同的 KMS 实例处理。特别是，Kerberos 主体配置、HTTP 身份验证签名和委派令牌需要特别注意。

在负载均衡器或 VIP 后面

由于 KMS 客户端和服务器通过 HTTP 上的 REST API 进行通信，因此可以使用负载均衡器或 VIP 将传入流量分配到各个实例，以实现可伸缩性和高可用性。在此模式中，客户端不知道服务器端的多个 KMS 实例。

使用 LoadBalancingKMSClientProvider

在负载均衡器或 VIP 后面运行多个 KMS 实例的另一种方法是使用 LoadBalancingKMSClientProvider。使用此方法，KMS 客户端（例如，HDFS 名称节点）知道多个 KMS 实例，并以循环方式向它们发送请求。当在 hadoop.security.key.provider.path 中指定多个 URI 时，会隐式使用 LoadBalancingKMSClientProvider。

core-site.xml 中的以下示例配置了两个 KMS 实例，kms01.example.com 和 kms02.example.com。主机名用分号分隔，所有 KMS 实例都必须在同一端口上运行。

<property>
  <name>hadoop.security.key.provider.path</name>
  <value>kms://[email protected];kms02.example.com:9600/kms</value>
  <description>
    The KeyProvider to use when interacting with encryption keys used
    when reading and writing to an encryption zone.
  </description>
</property>

如果对 KMS 实例的请求失败，客户端会使用下一个实例重试。只有当所有实例都失败时，请求才会返回失败。

HTTP Kerberos 主体配置

当 KMS 实例位于负载均衡器或 VIP 后面时，客户端将使用 VIP 的主机名。对于 Kerberos SPNEGO 身份验证，URL 的主机名用于构造服务器的 Kerberos 服务名称，HTTP/#HOSTNAME#。这意味着所有 KMS 实例都必须具有带有负载均衡器或 VIP 主机名的 Kerberos 服务名称。

为了能够直接访问特定的 KMS 实例，KMS 实例还必须具有带有其自身主机名的 Kerberos 服务名称。这是出于监控和管理目的而必需的。

负载均衡器/VIP 主机名和实际 KMS 实例主机名的 Kerberos 服务主体凭据（必须）位于为身份验证配置的密钥表文件中。并且配置中指定的原则名称必须为“*”。例如

  <property>
    <name>hadoop.kms.authentication.kerberos.principal</name>
    <value>*</value>
  </property>

注意：如果使用 HTTPS，则 KMS 实例使用的 SSL 证书必须配置为支持多个主机名（有关如何执行此操作的详细信息，请参阅 Java 7 keytool SAN 扩展支持）。

HTTP 身份验证签名

KMS 使用 Hadoop 身份验证进行 HTTP 身份验证。一旦客户端成功进行身份验证，Hadoop 身份验证就会签发一个 HTTP Cookie。此 HTTP Cookie 具有一个过期时间，过期后将触发一个新的身份验证序列。这样做是为了避免在客户端的每个 HTTP 请求上触发身份验证。

KMS 实例必须验证由其他 KMS 实例签名的 HTTP Cookie 签名。为此，所有 KMS 实例都必须共享签名密钥。有关详细说明和配置示例，请参阅SignerSecretProvider 配置。请注意，KMS 配置需要以 hadoop.kms.authentication 为前缀，如下面的示例所示。

可以使用 Zookeeper 服务进行此密钥共享，该服务在 KMS 中配置了 kms-site.xml 中的以下属性

  <property>
    <name>hadoop.kms.authentication.signer.secret.provider</name>
    <value>zookeeper</value>
    <description>
      Indicates how the secret to sign the authentication cookies will be
      stored. Options are 'random' (default), 'file' and 'zookeeper'.
      If using a setup with multiple KMS instances, 'zookeeper' should be used.
      If using file, signature.secret.file should be configured and point to the secret file.
    </description>
  </property>
  <property>
    <name>hadoop.kms.authentication.signer.secret.provider.zookeeper.path</name>
    <value>/hadoop-kms/hadoop-auth-signature-secret</value>
    <description>
      The Zookeeper ZNode path where the KMS instances will store and retrieve
      the secret from. All KMS instances that need to coordinate should point to the same path.
    </description>
  </property>
  <property>
    <name>hadoop.kms.authentication.signer.secret.provider.zookeeper.connection.string</name>
    <value>#HOSTNAME#:#PORT#,...</value>
    <description>
      The Zookeeper connection string, a list of hostnames and port comma
      separated.
    </description>
  </property>
  <property>
    <name>hadoop.kms.authentication.signer.secret.provider.zookeeper.auth.type</name>
    <value>sasl</value>
    <description>
      The Zookeeper authentication type, 'none' (default) or 'sasl' (Kerberos).
    </description>
  </property>
  <property>
    <name>hadoop.kms.authentication.signer.secret.provider.zookeeper.kerberos.keytab</name>
    <value>/etc/hadoop/conf/kms.keytab</value>
    <description>
      The absolute path for the Kerberos keytab with the credentials to
      connect to Zookeeper.
    </description>
  </property>
  <property>
    <name>hadoop.kms.authentication.signer.secret.provider.zookeeper.kerberos.principal</name>
    <value>kms/#HOSTNAME#</value>
    <description>
      The Kerberos service principal used to connect to Zookeeper.
    </description>
  </property>

委派令牌

与 HTTP 身份验证类似，KMS 也将 Hadoop 身份验证用于委派令牌。在 HA 下，每个 KMS 实例都必须验证由另一个 KMS 实例给出的委派令牌。为此，所有 KMS 实例都必须使用 ZKDelegationTokenSecretManager 从 ZooKeeper 检索 TokenIdentifiers 和 DelegationKeys。

etc/hadoop/kms-site.xml 中的示例配置

  <property>
    <name>hadoop.kms.authentication.zk-dt-secret-manager.enable</name>
    <value>true</value>
    <description>
      If true, Hadoop KMS uses ZKDelegationTokenSecretManager to persist
      TokenIdentifiers and DelegationKeys in ZooKeeper.
    </description>
  </property>
  <property>
    <name>hadoop.kms.authentication.zk-dt-secret-manager.zkConnectionString</name>
    <value>#HOSTNAME#:#PORT#,...</value>
    <description>
      The ZooKeeper connection string, a comma-separated list of hostnames and port.
    </description>
  </property>
  <property>
    <name>hadoop.kms.authentication.zk-dt-secret-manager.znodeWorkingPath</name>
    <value>/hadoop-kms/zkdtsm</value>
    <description>
      The ZooKeeper znode path where the KMS instances will store and retrieve
      the secret from. All the KMS instances that need to coordinate should point to the same path.
    </description>
  </property>
  <property>
    <name>hadoop.kms.authentication.zk-dt-secret-manager.zkAuthType</name>
    <value>sasl</value>
    <description>
      The ZooKeeper authentication type, 'none' (default) or 'sasl' (Kerberos).
    </description>
  </property>
  <property>
    <name>hadoop.kms.authentication.zk-dt-secret-manager.kerberos.keytab</name>
    <value>/etc/hadoop/conf/kms.keytab</value>
    <description>
      The absolute path for the Kerberos keytab with the credentials to
      connect to ZooKeeper. This parameter is effective only when
      hadoop.kms.authentication.zk-dt-secret-manager.zkAuthType is set to 'sasl'.
    </description>
  </property>
  <property>
    <name>hadoop.kms.authentication.zk-dt-secret-manager.kerberos.principal</name>
    <value>kms/#HOSTNAME#</value>
    <description>
      The Kerberos service principal used to connect to ZooKeeper.
      This parameter is effective only when
      hadoop.kms.authentication.zk-dt-secret-manager.zkAuthType is set to 'sasl'.
    </description>
  </property>

KMS HTTP REST API

创建密钥

请求

POST http://HOST:PORT/kms/v1/keys
Content-Type: application/json

{
  "name"        : "<key-name>",
  "cipher"      : "<cipher>",
  "length"      : <length>,        //int
  "material"    : "<material>",    //base64
  "description" : "<description>"
}

响应

201 CREATED
LOCATION: http://HOST:PORT/kms/v1/key/<key-name>
Content-Type: application/json

{
  "name"        : "versionName",
  "material"    : "<material>",    //base64, not present without GET ACL
}

滚动密钥

请求

POST http://HOST:PORT/kms/v1/key/<key-name>
Content-Type: application/json

{
  "material"    : "<material>",
}

响应

200 OK
Content-Type: application/json

{
  "name"        : "versionName",
  "material"    : "<material>",    //base64, not present without GET ACL
}

使密钥缓存失效

请求

POST http://HOST:PORT/kms/v1/key/<key-name>/_invalidatecache

响应

200 OK

删除密钥

请求

DELETE http://HOST:PORT/kms/v1/key/<key-name>

响应

200 OK

获取密钥元数据

请求

GET http://HOST:PORT/kms/v1/key/<key-name>/_metadata

响应

200 OK
Content-Type: application/json

{
  "name"        : "<key-name>",
  "cipher"      : "<cipher>",
  "length"      : <length>,        //int
  "description" : "<description>",
  "created"     : <millis-epoc>,   //long
  "versions"    : <versions>       //int
}

获取当前密钥

请求

GET http://HOST:PORT/kms/v1/key/<key-name>/_currentversion

响应

200 OK
Content-Type: application/json

{
  "name"        : "versionName",
  "material"    : "<material>",    //base64
}

为当前 KeyVersion 生成加密密钥

请求

GET http://HOST:PORT/kms/v1/key/<key-name>/_eek?eek_op=generate&num_keys=<number-of-keys-to-generate>

响应

200 OK
Content-Type: application/json
[
  {
    "versionName"         : "<encryptionVersionName>",
    "iv"                  : "<iv>",          //base64
    "encryptedKeyVersion" : {
        "versionName"       : "EEK",
        "material"          : "<material>",    //base64
    }
  },
  {
    "versionName"         : "<encryptionVersionName>",
    "iv"                  : "<iv>",          //base64
    "encryptedKeyVersion" : {
        "versionName"       : "EEK",
        "material"          : "<material>",    //base64
    }
  },
  ...
]

解密加密密钥

请求

POST http://HOST:PORT/kms/v1/keyversion/<version-name>/_eek?eek_op=decrypt
Content-Type: application/json

{
  "name"        : "<key-name>",
  "iv"          : "<iv>",          //base64
  "material"    : "<material>",    //base64
}

响应

200 OK
Content-Type: application/json

{
  "name"        : "EK",
  "material"    : "<material>",    //base64
}

使用最新 KeyVersion 重新加密加密密钥

此命令获取先前生成的加密密钥，并使用 KeyProvider 中最新的 KeyVersion 加密密钥重新对其进行加密。如果最新的 KeyVersion 与用于生成加密密钥的 KeyVersion 相同，则返回相同的加密密钥。

这通常在加密密钥滚动后很有用。重新加密加密密钥将允许使用加密密钥的最新版本对其进行加密，但仍使用相同的密钥材料和初始化向量。

请求

POST http://HOST:PORT/kms/v1/keyversion/<version-name>/_eek?eek_op=reencrypt
Content-Type: application/json

{
  "name"        : "<key-name>",
  "iv"          : "<iv>",          //base64
  "material"    : "<material>",    //base64
}

响应

200 OK
Content-Type: application/json

{
  "versionName"         : "<encryptionVersionName>",
  "iv"                  : "<iv>",            //base64
  "encryptedKeyVersion" : {
      "versionName"       : "EEK",
      "material"          : "<material>",    //base64
  }
}

使用最新 KeyVersion 批量重新加密加密密钥

上述重新加密加密密钥的批处理版本。此命令获取先前生成加密密钥的列表，并使用 KeyProvider 中的最新 KeyVersion 加密密钥重新加密它们，并按相同顺序返回重新加密的加密密钥。对于每个加密密钥，如果最新的 KeyVersion 与用于生成加密密钥的 KeyVersion 相同，则不执行任何操作，并返回相同的加密密钥。

这通常在加密密钥滚动后很有用。重新加密加密密钥将允许使用加密密钥的最新版本对其进行加密，但仍使用相同的密钥材料和初始化向量。

批处理请求的所有加密密钥必须在相同的加密密钥名称下，但可能在加密密钥的不同版本下。

请求

POST http://HOST:PORT/kms/v1/key/<key-name>/_reencryptbatch
Content-Type: application/json

[
  {
    "versionName"         : "<encryptionVersionName>",
    "iv"                  : "<iv>",            //base64
    "encryptedKeyVersion" : {
        "versionName"       : "EEK",
        "material"          : "<material>",    //base64
    }
  },
  {
    "versionName"         : "<encryptionVersionName>",
    "iv"                  : "<iv>",            //base64
    "encryptedKeyVersion" : {
        "versionName"       : "EEK",
        "material"          : "<material>",    //base64
    }
  },
  ...
]

响应

200 OK
Content-Type: application/json

[
  {
    "versionName"         : "<encryptionVersionName>",
    "iv"                  : "<iv>",            //base64
    "encryptedKeyVersion" : {
        "versionName"       : "EEK",
        "material"          : "<material>",    //base64
    }
  },
  {
    "versionName"         : "<encryptionVersionName>",
    "iv"                  : "<iv>",            //base64
    "encryptedKeyVersion" : {
        "versionName"       : "EEK",
        "material"          : "<material>",    //base64
    }
  },
  ...
]

获取密钥版本

请求

GET http://HOST:PORT/kms/v1/keyversion/<version-name>

响应

200 OK
Content-Type: application/json

{
  "name"        : "<name>",
  "versionName" : "<version>",
  "material"    : "<material>",    //base64
}

获取密钥版本

请求

GET http://HOST:PORT/kms/v1/key/<key-name>/_versions

响应

200 OK
Content-Type: application/json

[
  {
    "name"        : "<name>",
    "versionName" : "<version>",
    "material"    : "<material>",    //base64
  },
  {
    "name"        : "<name>",
    "versionName" : "<version>",
    "material"    : "<material>",    //base64
  },
  ...
]

获取密钥名称

请求

GET http://HOST:PORT/kms/v1/keys/names

响应

200 OK
Content-Type: application/json

[
  "<key-name>",
  "<key-name>",
  ...
]

获取密钥元数据

GET http://HOST:PORT/kms/v1/keys/metadata?key=<key-name>&key=<key-name>,...

响应

200 OK
Content-Type: application/json

[
  {
    "name"        : "<key-name>",
    "cipher"      : "<cipher>",
    "length"      : <length>,        //int
    "description" : "<description>",
    "created"     : <millis-epoc>,   //long
    "versions"    : <versions>       //int
  },
  {
    "name"        : "<key-name>",
    "cipher"      : "<cipher>",
    "length"      : <length>,        //int
    "description" : "<description>",
    "created"     : <millis-epoc>,   //long
    "versions"    : <versions>       //int
  },
  ...
]

已弃用的环境变量

以下环境变量已弃用。请改用设置相应的配置属性。

环境变量	配置属性	配置文件
KMS_TEMP	hadoop.http.temp.dir	kms-site.xml
KMS_HTTP_PORT	hadoop.kms.http.port	kms-site.xml
KMS_MAX_HTTP_HEADER_SIZE	hadoop.http.max.request.header.size 和 hadoop.http.max.response.header.size	kms-site.xml
KMS_MAX_THREADS	hadoop.http.max.threads	kms-site.xml
KMS_SSL_ENABLED	hadoop.kms.ssl.enabled	kms-site.xml
KMS_SSL_KEYSTORE_FILE	ssl.server.keystore.location	ssl-server.xml
KMS_SSL_KEYSTORE_PASS	ssl.server.keystore.password	ssl-server.xml

默认 HTTP 服务

名称	说明
/conf	显示配置属性
/jmx	Java JMX 管理界面
/logLevel	获取或设置每个类的日志级别
/logs	显示日志文件
/stacks	显示 JVM 堆栈
/static/index.html	静态主页

若要控制对 servlet /conf、/jmx、/logLevel、/logs 和 /stacks 的访问，请在 kms-site.xml 中配置以下属性

  <property>
    <name>hadoop.security.authorization</name>
    <value>true</value>
    <description>Is service-level authorization enabled?</description>
  </property>

  <property>
    <name>hadoop.security.instrumentation.requires.admin</name>
    <value>true</value>
    <description>
      Indicates if administrator ACLs are required to access
      instrumentation servlets (JMX, METRICS, CONF, STACKS).
    </description>
  </property>

  <property>
    <name>hadoop.kms.http.administrators</name>
    <value></value>
    <description>ACL for the admins, this configuration is used to control
      who can access the default KMS servlets. The value should be a comma
      separated list of users and groups. The user list comes first and is
      separated by a space followed by the group list,
      e.g. "user1,user2 group1,group2". Both users and groups are optional,
      so "user1", " group1", "", "user1 group1", "user1,user2 group1,group2"
      are all valid (note the leading space in " group1"). '*' grants access
      to all users and groups, e.g. '*', '* ' and ' *' are all valid.
    </description>
  </property>

通用

通用

HDFS

MapReduce

MapReduce REST API

YARN

YARN REST API

YARN 服务

Hadoop 兼容文件系统

身份验证

工具

参考

配置

Hadoop 密钥管理服务器 (KMS) - 文档集

KMS 客户端配置

KMS

启动/停止 KMS

KMS 配置

KMS HTTP 配置

KMS 缓存

CachingKeyProvider

密钥提供程序

KMS 聚合审计日志

KMS 安全配置

启用 Kerberos HTTP SPNEGO 身份验证

KMS 代理用户配置

通过 HTTPS（SSL）使用 KMS

ACL（访问控制列表）

KMS ACL

密钥 ACL

KMS 委派令牌配置

高可用性

在负载均衡器或 VIP 后面

使用 LoadBalancingKMSClientProvider

HTTP Kerberos 主体配置

HTTP 身份验证签名

委派令牌

KMS HTTP REST API

创建密钥

滚动密钥

使密钥缓存失效

删除密钥

获取密钥元数据

获取当前密钥

为当前 KeyVersion 生成加密密钥

解密加密密钥

使用最新 KeyVersion 重新加密加密密钥

使用最新 KeyVersion 批量重新加密加密密钥

获取密钥版本

获取密钥版本

获取密钥名称

获取密钥元数据

已弃用的环境变量

默认 HTTP 服务