設定 Cassandra 原生 mTLS

簡介

根據預設，Private Cloud 專用 Edge 的不同元件 (例如訊息處理器、管理伺服器和路由器) 會透過純文字管道連線至 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) (或雙向傳輸層安全標準或 mTLS)，Cassandra 和用戶端都必須設定自己的金鑰儲存區。每個 Cassandra 節點的 KeyStore 都應包含自己的金鑰和憑證。每個用戶端應用程式的 KeyStore 都應包含該特定用戶端的金鑰和憑證。您應在 Cassandra 和用戶端上新增信任儲存區，其中包含對應項目的憑證和相關聯的鏈結。每個 Cassandra 節點的信任儲存區都應包含用戶端的憑證，且每個用戶端的信任儲存區都應包含所有 Cassandra 節點的憑證。如要進一步瞭解雙向 TLS 交握的運作方式，請參閱 Apigee 的雙向 TLS/SSL 文章。

憑證鏈結

一般來說，在雙向 TLS 中，伺服器憑證、用戶端憑證、憑證鏈結、金鑰儲存區和信任儲存區可以透過各種方式建立。Cassandra 和用戶端原生 mTLS 也是如此。考量機構通常如何運作 Edge for Private Cloud 叢集，以及可建立的 Cassandra 連線用戶端不重複配對數量，Apigee 建議採用下列一般方法，為這項功能設定金鑰和憑證。雖然還有其他可行方法，但下列方法可能在安全性和維護成本之間取得良好平衡。

  1. 取得根憑證，以及由根憑證簽署的中繼金鑰/憑證組。您可能已擁有這類金鑰和憑證。如果沒有，請按照附錄 1 中的步驟，建立自行簽署的根憑證、中繼憑證和金鑰。

  2. 使用上述常見的中繼金鑰/憑證，簽署所有應用程式專屬 (葉片) 金鑰和憑證。

在 1 個叢集中使用通用中繼金鑰/憑證，可在每個 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. 建立 1 個 Cassandra 節點的葉節點金鑰/憑證配對、簽署該配對、將其儲存在金鑰儲存區，並設定 Cassandra 選用的 mTLS。一次為一個 Cassandra 節點重複執行上述步驟。
  3. 為 1 個用戶端應用程式建立葉節點金鑰/憑證配對、簽署該配對、將其儲存在金鑰庫中，並設定用戶端應用程式的 mTLS。請一次為一個用戶端應用程式重複執行上述步驟。用戶端應用程式：
    1. edge-management-server
    2. edge-message-processor
    3. edge-router

詳細步驟如下：

取得根憑證和中繼憑證

取得根憑證，以及由根憑證簽署的中繼金鑰/憑證組。使用貴機構的 CA 簽署根憑證和中繼憑證，或建立自行簽署的憑證。將根憑證和中繼憑證鏈結儲存在信任儲存區。如需實用指令，請參閱附錄 1。後續指令會假設您有權存取下列檔案：

  • intermediate.key - 中繼憑證的金鑰檔案，用於簽署分葉憑證
  • intermediate-cert.pem - 中繼憑證

設定 Cassandra 節點

  1. 挑選一個 Cassandra 節點
  2. 產生葉節點金鑰和憑證組，並使用中繼憑證簽署。將金鑰和已簽署憑證儲存在 KeyStore。範例如下： 
    
# 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

    將 KeyStore 和 TrustStore 檔案放在節點上的特定位置，並確保 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-management-server
  • edge-message-processor
  • edge-router

  1. 選擇一個用戶端元件
  2. 產生葉節點金鑰和憑證組，並使用中繼憑證簽署。將金鑰和已簽署憑證儲存在 KeyStore。範例如下： 
    
# 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

    將 KeyStore 和 TrustStore 檔案放在節點的特定位置，並確保 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 的雙向傳輸層安全標準強制執行功能

如要在 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 的信任存放區應包含用戶端的根/中繼憑證，而用戶端應用程式的信任存放區應包含 Cassandra 節點的根/中繼鏈。
  3. 與上述類似，您可以為不同區域提供多組根憑證和中繼憑證，但所有區域中的所有用戶端和伺服器，都必須在設定的信任存放區中加入所有根憑證和中繼憑證鏈，才能識別這些憑證。