启用密钥加密

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

概览

过去，适用于私有云的 Apigee Edge 为键值对映射 (KVM) 数据和 OAuth 访问令牌提供可选加密。

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

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

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

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

本文档介绍了这些任务。

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

本文档中的步骤介绍了如何启用 KEK 功能。KEK 功能可让 Apigee 对以静态方式存储在 Cassandra 数据库中的开发者应用使用方密文进行加密。

默认情况下，数据库中的任何现有值都将保持不变（以纯文本形式），并且将继续像以前一样工作。

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

保障密钥安全

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

启用密钥加密

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

前提条件

在执行本文档中的步骤之前，必须满足以下要求：

• 您必须安装或升级到适用于私有云 4.50.00.10 或更高版本的 Apigee Edge。
• 您必须是适用于私有云的 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

第 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 步。

摘要

您今后创建的所有开发者应用都会将其凭据密钥在 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	不适用	如果您使用环境变量设置这些属性，那么可选。另请参阅将环境变量用于配置属性。