配置 Cassandra 原生 mTLS

简介

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

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

原生 mTLS 功能

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

对于双向 TLS（或双向 [mutual] TLS 或 mTLS），Cassandra 和客户端都需要设置自己的密钥库。每个 Cassandra 节点的密钥库都应包含自己的密钥和证书。每个客户端应用的密钥库都应包含相应客户端的密钥和证书。应在 Cassandra 和客户端上添加包含对等方证书和关联链的信任库。每个 Cassandra 节点的信任库都应包含客户端的证书，并且每个客户端的信任库都应包含所有 Cassandra 节点的证书。您可以参阅 Apigee 的双向 TLS/SSL 文章，详细了解双向 TLS 握手通常如何运作。

证书链

一般来说，在双向 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. 边缘管理服务器
    2. edge-message-processor
    3. 边缘路由器

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

获取根证书和中间证书

获取根证书和由根证书签名的中间密钥/证书对。使用组织 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

    此外，对于已启用 FIPS 的操作系统，请将以下属性添加到 /opt/apigee/customer/application/cassandra.properties 文件中： 

    conf_cassandra_client_encryption_protocol=TLSv1.2

    确保该文件归 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-message-processor
  • 边缘路由器

  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 会接受来自客户端的明文连接，或者接受可以成功执行双向 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。如需为 cqlsh 配置 SSL，请生成新的叶密钥和证书（类似于客户端应用的叶密钥和证书），然后执行以下操作：

  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-message-processor
    • 边缘路由器
    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 的信任库应包含客户端的根证书/中间证书，而客户端应用的信任库应包含 Cassandra 节点的根证书/中间证书链。
  3. 与上述类似，您可以为不同区域设置多个根证书和中间证书集，但所有区域中的所有客户端和所有区域中的所有服务器都需要通过在配置的信任库中添加所有根证书和中间证书链来了解所有这些证书。