启用密钥加密

本文档介绍了如何对存储在 Cassandra 数据库中的开发者应用使用方 Secret（客户端凭据）启用加密。

概览

传统上，Apigee Edge for Private Cloud 为键值映射 (KVM) 数据和 OAuth 访问令牌提供了可选加密功能。

下表介绍了适用于私有云版 Apigee 中静态数据的加密选项：

实体 默认启用加密 可选加密 相关文档
KVM 否 是 请参阅关于加密的 KVM。
OAuth 访问令牌 否 是 请参阅对令牌进行哈希处理以增强安全性。
开发者应用使用方密文 否 是 如需启用，请执行本文档中的配置步骤。

如需启用客户端凭据加密，您需要在所有消息处理器和管理服务器节点上执行以下任务：

  • 创建一个密钥库以存储密钥加密密钥 (KEK)。Apigee 使用此加密密钥来加密加密数据所需的密钥。
  • 修改所有管理服务器和消息处理器节点上的配置属性。
  • 创建一个开发者应用以触发密钥创建。
  • 重启节点。

本文档介绍了这些任务。

关于密钥加密功能的须知事项

本文档中的步骤介绍了如何启用 KEK 功能，让 Apigee 能够对用于加密开发者应用使用方密钥（当静态存储于 Cassandra 数据库中的密钥用于加密的密钥）进行加密。

默认情况下，数据库中的所有现有值（以纯文本形式）都将保持不变，并将继续按原样运行。

如果您对未加密的实体执行任何写入操作，系统会在保存操作时对其进行加密。例如，如果您撤消未加密的令牌，然后稍后批准该令牌，则新批准的令牌将会被加密。

确保密钥安全

请务必将存储 KEK 的密钥库的副本存储在安全的位置。我们建议您使用自己的安全机制来保存密钥库的副本。如本文档中的说明所述，必须在每个消息处理器和管理服务器节点上放置密钥库，以便本地配置文件可以引用它。不过，请务必将密钥库的副本存储在其他位置，以备安全保管和备份。

启用密钥加密

请按照以下步骤进行使用方密钥加密：

前提条件

您必须满足以下要求，才能执行本文档中的步骤：

  • 您必须安装或升级到 Apigee Edge for Private Cloud 4.50.00.10 或更高版本。
  • 您必须是适用于私有云的 Apigee Edge 管理员。

第 1 步：生成密钥库

请按照以下步骤创建用于存储密钥加密密钥 (KEK) 的密钥库：

  1. 执行以下命令以生成密钥库，用于存储将用于加密 KEK 的密钥。输入与以下内容完全一致的命令。（您可以提供任意密钥库名称）：
    keytool -genseckey -alias KEYSTORE_NAME -keyalg AES -keysize 256 \
-keystore kekstore.p12 -storetype PKCS12

    出现提示时，输入一个密码。在后面的部分中，配置管理服务器和消息处理器时会用到此密码。

    此命令会生成一个 kekstore.p12 密钥库文件，其中包含别名为 KEYSTORE_NAME 的密钥。

  2. （可选）使用以下命令验证文件是否已正确生成。如果文件正确无误，该命令会返回别名为 KEYSTORE_NAME 的密钥： 
    keytool -list -keystore kekstore.p12

使用适用于启用 FIPS 的操作系统的 BCFKS 密钥库

如果您在启用了 FIPS 的操作系统上使用 Edge for Private Cloud，则应生成类型为 BCFKS 的密钥库。此类密钥库可以在非 FIPS 机器上生成，然后传输到符合 FIPS 要求的机器。如需生成密钥库，请使用以下命令：

keytool -genseckey -alias <KEYSTORE_NAME> -keyalg AES -keysize 256 \
-storetype BCFKS -keystore keystore.bcfks \
-providerpath /opt/apigee/edge-gateway/lib/thirdparty/bc-fips-1.0.2.4.jar \
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
-keypass keystorepass -storepass keystorepass

您可能需要在生成此密钥库的机器上执行额外的 Java 设置。您可能需要修改机器的 Java 安全文件（通常位于 /usr/lib/jvm/jre/lib/security/java.security）。在此文件中，查找并修改以下属性：

# Don't rely on /dev/random for generating random numbers
securerandom.source=file:/dev/urandom
securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS

第 2 步：配置管理服务器

接下来，配置管理服务器。如果您在多个节点上安装了管理服务器，则必须在每个节点上重复执行这些步骤。

  1. 将您在第 1 步中生成的密钥库文件复制到管理服务器节点上的某个目录（例如 /opt/apigee/customer/application）。例如：
    cp certs/kekstore.p12 /opt/apigee/customer/application
  2. 确保 apigee 用户可以读取该文件： 
    chown apigee:apigee /opt/apigee/customer/application/kekstore.p12
     
    chmod 400 /opt/apigee/customer/application/kekstore.p12
  3. 将以下属性添加到 /opt/apigee/customer/application/management-server.properties。如果该文件不存在，请创建该文件。另请参阅属性文件参考文档。
    conf_keymanagement_kmscred.encryption.enabled=true

# Fallback is true to ensure your existing plaintext credentials continue to work
conf_keymanagement_kmscred.encryption.allowFallback=true

conf_keymanagement_kmscred.encryption.keystore.path=PATH_TO_KEYSTORE_FILE
conf_keymanagement_kmscred.encryption.kek.alias=KEYSTORE_NAME

# These could alternately be set as environment variables. These variables should be
# accessible to Apigee user during bootup of the Java process. If environment
# variables are specified, you can skip the password configs below.
# KMSCRED_ENCRYPTION_KEYSTORE_PASS=
# KMSCRED_ENCRYPTION_KEK_PASS=
See also Using environment variables for configuration properties.

conf_keymanagement_kmscred.encryption.keystore.pass=KEYSTORE_PASSWORD
conf_keymanagement_kmscred.encryption.kek.pass=KEK_PASSWORD

    请注意，KEK_PASSWORD 可能与 KEYSTORE_PASSWORD 相同，具体取决于用于生成密钥库的工具。

  4. 使用以下命令重启管理服务器： 
    /opt/apigee/apigee-service/bin/apigee-service edge-management-server restart
     
    /opt/apigee/apigee-service/bin/apigee-service edge-management-server wait_for_ready

    管理服务器准备就绪后，wait_for_ready 命令会返回以下消息：

    Checking if management-server is up: management-server is up.
  5. 如果在多个节点上安装了管理服务器，请对每个管理服务器节点重复执行上面的第 1-4 步。

第 3 步：创建开发者应用

现在，管理服务器已更新，您必须创建一个开发者应用，以触发生成用于加密客户端凭据数据的密钥：

  1. 创建一个开发者应用以触发创建数据加密密钥 (KEK)。如需了解相关步骤，请参阅注册应用。
  2. 如有需要，请删除开发者应用。生成加密密钥后，无需保留该密钥。

第 4 步：配置消息处理程序

在消息处理器中启用加密之前，运行时请求将无法处理任何加密的凭据。

  1. 将您在第 1 步中生成的密钥库文件复制到消息处理器节点上的某个目录，例如 /opt/apigee/customer/application。例如：
    cp certs/kekstore.p12 /opt/apigee/customer/application
  2. 确保 apigee 用户可以读取该文件： 
    chown apigee:apigee /opt/apigee/customer/application/kekstore.p12
  3. 将以下属性添加到 /opt/apigee/customer/application/message-processor.properties。 如果该文件不存在，请创建一个。另请参阅属性文件参考文档。 
    conf_keymanagement_kmscred.encryption.enabled=true

# Fallback is true to ensure your existing plaintext credentials continue to work
conf_keymanagement_kmscred.encryption.allowFallback=true

conf_keymanagement_kmscred.encryption.keystore.path=PATH_TO_KEYSTORE_FILE
conf_keymanagement_kmscred.encryption.kek.alias=KEYSTORE_NAME

# These could alternately be set as environment variables. These variables should be
# accessible to Apigee user during bootup of the Java process. If environment
# variables are specified, you can skip the password configs below.
# KMSCRED_ENCRYPTION_KEYSTORE_PASS=
# KMSCRED_ENCRYPTION_KEK_PASS=
See also Using environment variables for configuration properties.


conf_keymanagement_kmscred.encryption.keystore.pass=KEYSTORE_PASSWORD
conf_keymanagement_kmscred.encryption.kek.pass=KEK_PASSWORD

    请注意，KEK_PASSWORD 可能与 KEYSTORE_PASSWORD 相同，具体取决于用于生成密钥库的工具。

  4. 使用以下命令重启消息处理器： 
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
     
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor wait_for_ready

    当消息处理器准备好处理消息时，wait_for_ready 命令会返回以下消息：

    Checking if message-processor is up: message-processor is up.
  5. 如果您在多个节点上安装了消息处理器，请在每个消息处理器节点上重复第 1-4 步。

摘要

从现在起，您创建的任何开发者应用的凭据 Secret 都会在 Cassandra 数据库中以静态加密形式存储。

将环境变量用于配置属性

或者，您也可以使用环境变量设置以下消息处理器和管理服务器配置属性。如果设置了环境变量，则这些环境变量会替换消息处理器或管理服务器配置文件中设置的属性。

conf_keymanagement_kmscred.encryption.keystore.pass=
conf_keymanagement_kmscred.encryption.kek.pass=

相应的环境变量如下： 

export KMSCRED_ENCRYPTION_KEYSTORE_PASS=KEYSTORE_PASSWORD
 
export KMSCRED_ENCRYPTION_KEK_PASS=KEK_PASSWORD

如果您设置了这些环境变量，则可以从消息处理器和管理服务器节点上的配置文件中省略这些配置属性，因为系统会忽略这些属性： 

conf_keymanagement_kmscred.encryption.keystore.pass
conf_keymanagement_kmscred.encryption.kek.pass

属性文件参考

本部分介绍了您必须在所有消息处理器和管理服务器节点上设置的配置属性，如本文档前面的说明。

属性 默认 说明
conf_keymanagement_kmscred.encryption.enabled false 必须为 true，才能启用密钥加密。
conf_keymanagement_kmscred.encryption.allowFallback false 将 allowFallback 设置为 true，以确保现有的明文凭据继续有效。
conf_keymanagement_kmscred.encryption.keystore.path 不适用 提供消息处理器或管理服务器节点上 KEK 密钥库的路径。 请参阅第 2 步：配置管理服务器和第 3 步：配置消息处理器。
conf_keymanagement_kmscred.encryption.kek.alias 不适用 密钥库中存储 KEK 的别名。
conf_keymanagement_kmscred.encryption.keystore.pass 不适用 如果您使用环境变量设置这些属性，则为可选。另请参阅为配置属性使用环境变量。
conf_keymanagement_kmscred.encryption.kek.pass 不适用 如果您使用环境变量设置这些属性，则为可选。另请参阅为配置属性使用环境变量。