配置 Cassandra 原生 mTLS

简介

默认情况下，Edge for Private Cloud 的不同组件（如消息处理器、管理服务器和路由器）通过明文通道连接到 Cassandra 节点。在此类通道上，与 Cassandra 之间的数据以明文形式进行通信。Apigee mTLS 是一项基于 Consul 服务网格的功能，可为 Edge for Private Cloud 集群中组件之间的通信增加安全性。Apigee 的这项服务还为客户端组件与 Cassandra 之间的通信通道增加了 TLS 安全性。

本文介绍 Apigee 提供的一项新的替代服务，其中 Edge for Private Cloud 中客户端组件与 Cassandra 之间的通信通过双向 TLS（也称为 2 向 TLS）进行保护，该服务使用 Cassandra 中原生提供的功能，而无需使用外部服务网格。

原生 mTLS 功能

本文中所述的 Cassandra 与客户端组件之间的 mTLS 依赖于 Apache Cassandra 原生提供的 TLS 功能。启用后，客户端与 Cassandra 的连接（在 CQL 原生传输端口 9042 上）会先与客户端执行 2 向 TLS 握手，然后才允许建立连接。对于此 2 向 TLS 连接，Cassandra 充当服务器，而连接到 Cassandra 的各种客户端（如 edge-message-processor、cqlsh 工具等）充当客户端。

对于 2 向 TLS（或双向 TLS 或 mTLS），Cassandra 和客户端都需要使用自己的密钥库进行设置。每个 Cassandra 节点的密钥库都应包含自己的密钥和证书。每个客户端应用的密钥库都应包含该特定客户端的密钥和证书。应在 Cassandra 和客户端上添加包含证书和关联的对等方链的 truststore。每个 Cassandra 节点的信任库都应包含客户端的证书，而每个客户端的信任库都应包含所有 Cassandra 节点的证书。如需详细了解双向 TLS 握手的一般工作方式，您可以参阅 Apigee 的双向 TLS/SSL 文章。

证书链

通常，在双向 TLS 中，服务器证书、客户端证书、证书链、密钥库和信任库可以通过多种方式创建。Cassandra 和客户端原生 mTLS 也是如此。考虑到组织通常如何运行 Edge for Private Cloud 集群以及可以建立的唯一客户端到 Cassandra 连接对的数量，Apigee 建议采用以下通用方法来为此功能配置密钥和证书。还有其他可行的方法，但以下方法可能会在安全性和维护开销之间取得良好的平衡。

  1. 获取根证书和由根证书签名的中间密钥/证书对。您可能已经拥有此类密钥和证书。如果没有，您可以按照附录 1中的步骤创建自签名根证书和中间证书及密钥。

  2. 使用上述通用中间密钥/证书对所有应用专用（叶）密钥和证书进行签名。

在一个集群中使用通用中间密钥/证书，这样一来，每个 Cassandra 和客户端节点上都会配置一个通用信任库（包含相同的根证书和中间证书链）。每个 Cassandra 节点和客户端应用都会获得由通用中间密钥/证书签名的唯一叶密钥和证书。

  1. 轮替 Cassandra 节点或客户端应用的叶证书非常简单。
  2. 轮替中间证书或根证书仍然是一项相当复杂的操作，但此类轮替的频率将远低于叶证书的轮替频率。

根据您组织的安全实践，决定是否在不同的私有云集群中使用通用根证书和中间证书。您可以参阅附录 2 了解替代证书设置。

本文的其余步骤详细介绍了上述密钥和证书设计方法。

限制和注意事项

此功能存在以下限制。

  • 客户端组件与 Cassandra 之间的原生 mTLS 服务与 apigee-mtls 不兼容。如果您使用此功能，则无法使用 apigee-mtls，反之亦然。
  • 在客户端组件与 Cassandra 之间启用 mTLS 会对客户端与 Cassandra 之间建立的连接产生一定的性能影响。由于 Cassandra 和客户端必须先协商 TLS，然后才能开始通信，因此客户端启动或 Cassandra 连接扩缩等操作可能会较慢。影响应该很小，通常不会被注意到。
  • 在 Cassandra 上，您可以选择对入站客户端连接强制执行 mTLS。虽然可以启用强制执行，但在执行 Apigee 软件升级、启用/停用 TLS 功能以及某些类型的证书轮替等操作任务期间，必须停用强制执行。如需了解详情，请参阅操作和配置部分。
  • 管理和维护证书是客户的责任。
  • 轮替证书有多种细微差别。如需了解详情，请参阅证书轮替部分

启用原生 mTLS

从总体上讲，启用原生 mTLS 是一个包含 3 个步骤的过程，如下所述：

  1. 获取根证书和中间密钥/证书对。
  2. 创建一个 Cassandra 节点的叶密钥/证书对，对其进行签名，将其存储在密钥库中，并为 可选 mTLS 配置 Cassandra。一次对每个 Cassandra 节点重复这些步骤。
  3. 创建一个客户端应用的叶密钥/证书对，对其进行签名，将其存储在密钥库中，并为 mTLS 配置客户端应用。一次对每个客户端应用重复这些步骤。客户端应用：
    1. edge-management-server
    2. edge-message-processor
    3. edge-router

以下详细介绍了这些步骤：

获取根证书和中间证书

获取根证书和由根证书签名的中间密钥/证书对。使用您组织的 CA 签名的根证书和中间证书，或创建自签名证书。将根证书和中间证书链存储在信任库中。如需了解有用的命令，请参阅附录 1。后续命令假定您可以访问以下文件：

  • intermediate.key - 用于对叶证书进行签名的中间证书的密钥文件
  • intermediate-cert.pem \- 中间证书

配置 Cassandra 节点

  1. 选择一个 Cassandra 节点
  2. 生成叶密钥和证书对，并使用中间证书对其进行签名。将密钥和签名证书存储到密钥库中。示例如下： 
    
# Generate Leaf key and csr
openssl req -newkey rsa:2048 -keyout cass-node1.key -out cass-node1-req.pem -sha256 -days 365 -nodes -subj "/C=yourc/ST=yourst/L=yourl/O=youro/OU=yourou/CN=yourip/emailAddress=cassnode1@yourorg.com"

# leaf cert signed by intermediate
openssl x509 -req -in cass-node1-req.pem -CAkey intermediate.key -CA intermediate-cert.pem -days 365 -CAcreateserial -out cass-node1-cert.pem

# keystore packaging leaf key and cert
openssl pkcs12 -export -clcerts -in cass-node1-cert.pem -inkey cass-node1.key -out cass-node1-keystore.pfx -name nativemtls -password pass:keystorepass

    将密钥库和信任库文件放在节点上的特定位置，并确保 apigee 用户可以访问它们 

    cp cass-node1-keystore.pfx /opt/apigee/customer/application/
cp truststore.pfx /opt/apigee/customer/application/

chown apigee:apigee /opt/apigee/customer/application/cass-node1-keystore.pfx
chown apigee:apigee /opt/apigee/customer/application/truststore.pfx

  3. 创建或修改文件 /opt/apigee/customer/application/cassandra.properties。在此文件中添加以下内容： 
    ### Enable Cassandra TLS on CQL connections
conf_cassandra_client_encryption_enabled=true

### Optional TLS - true or false
conf_cassandra_client_encryption_optional=true

### Keystore details
conf_cassandra_client_encryption_keystore=/opt/apigee/customer/application/cass-node1-keystore.pfx
conf_cassandra_client_encryption_keystore_password=keystorepass
conf_cassandra_server_encryption_store_type=PKCS12

### Whether to enable 2-way TLS (or mTLS) - true or false
conf_cassandra_client_encryption_require_client_auth=true

### When 2-way TLS is enabled, client certificate details need to be provided via a truststore
conf_cassandra_client_encryption_truststore=/opt/apigee/customer/application/truststore.pfx
conf_cassandra_client_encryption_truststore_password=trustpass
conf_cassandra_client_encryption_store_type=PKCS12

    确保该文件归 apigee 用户所有且可供其读取：

    chown apigee:apigee /opt/apigee/customer/application/cassandra.properties
  4. 配置并重启 Cassandra 节点 
    apigee-service apigee-cassandra configure
apigee-service apigee-cassandra restart
  5. 一次对每个 Cassandra 节点重复上述步骤

配置客户端应用

本部分适用于连接到 Cassandra 的以下客户端组件：

  • edge-management-server
  • edge-message-processor
  • edge-router

  1. 选择一个客户端组件
  2. 生成叶密钥和证书对，并使用中间证书对其进行签名。将密钥和签名证书存储到密钥库中。示例如下： 
    
# Generate Leaf key and csr
openssl req -newkey rsa:2048 -keyout mgmt-node1.key -out mgmt-node1-req.pem -sha256 -days 365 -nodes -subj "/C=yourc/ST=yourst/L=yourl/O=youro/OU=yourou/CN=yourip/emailAddress=mgmtnode1@yourorg.com"

# leaf cert signed by intermediate
openssl x509 -req -in mgmt-node1-req.pem -CAkey intermediate.key -CA intermediate-cert.pem -days 365 -CAcreateserial -out mgmt-node1-cert.pem

# keystore packaging leaf key and cert
openssl pkcs12 -export -clcerts -in mgmt-node1-cert.pem -inkey mgmt-node1.key -out mgmt-node1-keystore.pfx -name nativemtls -password pass:keystorepass

    将密钥库和信任库文件放在节点上的特定位置，并确保 apigee 用户可以访问它们

    cp mgmt-node1-keystore.pfx /opt/apigee/customer/application/
cp truststore.pfx /opt/apigee/customer/application/

chown apigee:apigee /opt/apigee/customer/application/mgmt-node1-keystore.pfx
chown apigee:apigee /opt/apigee/customer/application/truststore.pfx

  3. 根据您要配置的应用创建和修改配置文件
    应用 配置文件
    管理服务器 /opt/apigee/customer/application/management-server.properties
    管理处理器 /opt/apigee/customer/application/message-processor.properties
    路由器 /opt/apigee/customer/application/router.properties

    在该文件中添加以下配置： 

    ### Enable TLS on CQL connections
conf_cassandra_sslconfig.enable.tls=true
conf_cassandra_sslconfig.enable.mtls=true

### Keystore Details
conf_cassandra_sslconfig.keystore.path=/opt/apigee/customer/application/mgmt-node1-keystore.pfx
conf_cassandra_sslconfig.keystore.password=keystorepass
conf_cassandra_sslconfig.keystore.type=PKCS12

### Truststore Details
conf_cassandra_sslconfig.truststore.path=/opt/apigee/customer/application/truststore.pfx
conf_cassandra_sslconfig.truststore.password=trustpass
conf_cassandra_sslconfig.truststore.type=PKCS12

    确保该配置文件归 apigee 用户所有且可供其读取 

    chown apigee:apigee configuration file

### Example:
chown apigee:apigee /opt/apigee/customer/application/management-server.properties

  4. 重启客户端应用 
    # Configure and restart service:
apigee-service component configure
apigee-service component restart
# Example, to configure and restart message processor application
apigee-service edge-message-processor configure
apigee-service edge-message-processor restart
  5. 您可以在相应应用的系统日志中查找与以下行类似的日志，以验证 SSL 是否已在客户端应用中正确配置：

    已向 Cassandra 连接添加 SSL 选项

  6. 一次对每个客户端应用重复上述步骤

操作和配置

强制执行 mTLS

如果未在 Cassandra 中强制执行 mTLS，Cassandra 会接受来自客户端的明文连接，或者接受可以成功执行 2 向 TLS 握手的客户端。如需使 mTLS 强制执行正常运行，应先在 Cassandra 中配置 mTLS。您可以按照以下步骤在 Cassandra 中设置 mTLS 强制执行：

  1. 选择一个 Cassandra 节点
  2. 创建或修改文件 /opt/apigee/customer/application/cassandra.properties。在此文件中添加或修改以下属性： 
    ### Optional TLS - true or false
conf_cassandra_client_encryption_optional=false

    确保该文件归 apigee 用户所有且可供其读取

    chown apigee:apigee /opt/apigee/customer/application/cassandra.properties
  3. 配置并重启 Cassandra 节点 
    apigee-service apigee-cassandra configure
apigee-service apigee-cassandra restart
  4. 一次对每个 Cassandra 节点重复上述步骤

在 Cassandra 中强制执行 mTLS 后，标准 Cassandra 查询工具 cqlsh 无法直接连接到 Cassandra。如需为 SSL 配置 cqlsh，请生成新的叶密钥和证书（类似于 客户端应用的叶密钥和证书），然后执行以下操作：

  1. 创建或修改文件 $HOME/.cassandra/cqlshrc
  2. 在该文件中添加以下内容： 
    [ssl]
certfile = /home/admin-user/certs/inter-root.pem
validate = false
userkey = /home/admin-user/certs/cqlsh1.key
usercert = /home/admin-user/certs/cqlsh1-cert.pem
    • certfile - 包含根证书和中间证书链的证书文件
    • userkey - cqlsh 要使用的客户端密钥。这应该是您可以使用中间证书生成和签名的叶密钥/证书对。
    • usercert - cqlsh 要使用的客户端证书。这应该是您可以使用中间证书生成和签名的叶密钥/证书。
  3. 像往常一样运行 cqlsh 命令，同时提供 --ssl 实参。 例如： 
    $  /opt/apigee/apigee-cassandra/bin/cqlsh --ssl X.X.X.X
Connected to Apigee at X.X.X.X:9042
[cqlsh 6.0.0 | Cassandra 4.0.13 | CQL spec 3.4.5 | Native protocol v5]
Use HELP for help.
cqlsh>

停用在 Cassandra 上强制执行 mTLS

如需在 Cassandra 中停用 mTLS 强制执行，请按照以下步骤操作：

  1. 选择一个 Cassandra 节点
  2. 创建或修改文件 /opt/apigee/customer/application/cassandra.properties。在此文件中添加或修改以下属性： 
    ### Optional TLS - true or false
conf_cassandra_client_encryption_optional=true

    确保该文件归 apigee 用户所有且可供其读取

    chown apigee:apigee /opt/apigee/customer/application/cassandra.properties
  3. 配置并重启 Cassandra 节点 
    apigee-service apigee-cassandra configure
apigee-service apigee-cassandra restart
  4. 一次对每个 Cassandra 节点重复上述步骤

停用原生 mTLS

停用原生 mTLS 是一个多步骤过程，类似于启用原生 mTLS。总体步骤如下：

  1. 停用在 Cassandra 中强制执行 mTLS（如果已强制执行）
  2. 在以下客户端应用的所有节点中逐个停用 mTLS：
    • edge-management-server
    • edge-message-processor
    • edge-router
    1. 根据您要配置的应用创建和修改配置文件：
      应用 配置文件
      管理服务器 /opt/apigee/customer/application/management-server.properties
      管理处理器 /opt/apigee/customer/application/message-processor.properties
      路由器 /opt/apigee/customer/application/router.properties
    2. 在配置文件中添加或修改以下属性： 
      ### TLS on CQL connections
conf_cassandra_sslconfig.enable.tls=false
conf_cassandra_sslconfig.enable.mtls=false
    3. 确保该配置文件归 apigee 用户所有且可供其读取： 
      chown apigee:apigee configuration file

### Example:
chown apigee:apigee /opt/apigee/customer/application/management-server.properties
    4. 重启客户端应用： 
      
# Configure and restart service:
apigee-service component configure
apigee-service component restart

# Example, to configure and restart message processor application
apigee-service edge-message-processor configure
apigee-service edge-message-processor restart
    5. 一次对每个客户端应用重复步骤 #a 到 #d。
  3. 在所有 Cassandra 节点中逐个停用 mTLS：
    1. 选择一个 Cassandra 节点。
    2. 创建或修改文件 /opt/apigee/customer/application/cassandra.properties。在此文件中添加或修改以下属性： 
      ### Cassandra TLS on CQL connections
conf_cassandra_client_encryption_enabled=false

      确保该文件归 apigee 用户所有且可供其读取

      chown apigee:apigee /opt/apigee/customer/application/cassandra.properties
    3. 配置并重启 Cassandra 节点
      4. apigee-service apigee-cassandra configure
apigee-service apigee-cassandra restart
    4. 一次对每个 Cassandra 节点重复步骤 #a 到 #c。

证书轮替

仅轮替叶证书（保留相同的中间证书和根证书）

可以按照与配置客户端应用类似的步骤操作：

  1. 使用相同的中间密钥/证书为应用生成新的叶密钥/证书
  2. 在应用中配置新叶密钥/证书的路径以及密码和密钥库类型
  3. 重启应用
轮替根证书或中间证书

如果您计划轮替中间证书或根证书，建议您执行以下多步骤过程：

  1. 在整个集群中停用 Cassandra 原生 mTLS。
  2. 使用新的根证书和中间证书生成全新的叶证书或应用证书。
  3. 按照相应的步骤使用新的密钥和证书集启用 Cassandra 原生 mTLS。

一般 Apigee 操作

如需执行一般 Apigee 操作（例如升级 Apigee 软件、添加或移除 Cassandra 节点、添加或移除数据中心、启用或停用 Cassandra 身份验证等），请确保未在 Cassandra 中强制执行 mTLS。如果您已强制执行 mTLS，请先停用强制执行，然后再继续执行这些操作。

附录 1

您可以按照本附录中的步骤生成自签名根密钥/证书对和中间密钥/证书对，并将此证书链添加到信任库中。

生成自签名根证书和中间证书

# Create self-signed root key and cert
openssl req -x509 -newkey rsa:2048 -keyout root.key -out root-cert.pem -sha256 -days 3650 -nodes -subj "/C=yourc/ST=yourst/L=yourl/O=youro/OU=yourou/CN=root.yourorg.com/emailAddress=apigeeroot@yourorg.com"

# Create intermediate key and cert (signed by root)
openssl req -newkey rsa:2048 -keyout intermediate.key -out intermediate-req.pem -sha256 -days 3650 -nodes -subj "/C=yourc/ST=yourst/L=yourl/O=youro/OU=yourou/CN=inter.yourorg.com/emailAddress=apigeeinter@yourorg.com"

openssl x509 -req -in intermediate-req.pem -CAkey root.key -CA root-cert.pem -days 3650 -CAcreateserial -out intermediate-cert.pem

生成信任库

# Merge root and intermediate cert into 1 file
cat intermediate-cert.pem > inter-root.pem
cat root-cert.pem >> inter-root.pem

# Create truststore to be used everywhere
keytool -keystore truststore.pfx -storetype PKCS12 -importcert -file inter-root.pem -keypass trustpass -storepass trustpass -alias nativemtls -noprompt

附录 2：替代证书链设置

虽然本文推荐了一种在安全性和操作简易性之间取得平衡的特定证书链设置，但还存在替代设置，如下所述。大多数一般原则也适用于其他方法，例如：

  1. 为每个 Cassandra 节点或客户端应用提供直接叶密钥和证书 （没有任何签名根证书或中间证书）。这可能会使证书轮替变得复杂。
  2. 为不同的使用场景提供多个根证书和中间证书集 。例如，Cassandra 节点具有 1 个根证书/中间证书集，使用该证书集对 Cassandra 的所有叶证书进行签名。同样，所有客户端应用可能都有一个单独的根证书/中间证书集，用于对应用叶证书进行签名。此类设置是可行的，但需要将根证书/中间证书链添加到相应的信任库中。在此示例中，Cassandra 的 truststore 应包含客户端的根证书/中间证书，而客户端应用应在其 truststore 中包含 Cassandra 节点的根证书/中间证书链。
  3. 与上述类似，您可以为不同的区域提供多个根证书和中间证书集 ，但需要通过在配置的 truststore 中添加所有根证书和中间证书链，让所有区域中的所有客户端和所有区域中的所有服务器都知道所有根证书和中间证书链。