配置自定义 CA 证书

ENTERPRISE

配置 DC/OS Enterprise 以使用自定义 CA 证书

每个 DC/OS Enterprise 群集都有自己的 DC/OS 证书颁发机构 (CA)。默认情况下，CA 使用在安装 DC/OS 期间生成的全局唯一根 CA 证书。根 CA 证书用于为 DC/OS 组件（如 Admin Router）签署证书。您可以将 DC/OS Enterprise 配置为使用自定义 CA 证书，而不是使用自动生成的根 CA 证书，该证书可以是根 CA 证书，也可以是中间 CA 证书。（参见 以下 示例）

使用 DC/OS Enterprise 群集的自定义 CA 证书的好处包括：

  • 确保 DC/OS 群集中用于签名和加密的所有 X.509 证书都来自您组织的 X.509 证书层次结构。
  • 控制密钥对的安全属性，如类型和强度，用于签署 DC/OS 组件证书。
  • 确保所有 DC/OS 组件（包括 Admin Router）都提供浏览器信任的证书。

目录

受支持的 CA 证书

  • 仅支持具有关联 RSA 类型密钥对的自定义 CA 证书。不支持其他类型的证书，例如使用 ECC 类型密钥对的证书。
  • 只有全新安装的 DC/OS Enterprise 1.10 或更高版本才支持自定义 CA 证书。不支持较旧版本的 DC/OS，并且在升级期间无法添加自定义 CA 证书。

术语表

  • 自定义 CA 证书： PEM 格式的自定义 CA 证书，用于为 DC/OS 组件（如 Admin Router）颁发证书。自定义 CA 证书是中间 CA 证书（由其他 CA 颁发）或根 CA 证书（由自定义 CA 自签名）。

  • **与自定义 CA 证书相关联的私钥：**与自定义 CA 证书关联的 PKCS#8 格式的私钥。

  • **与自定义 CA 证书相关联的证书链：**终端实体证书验证所需的完整 CA 证书链。它必须包括中间自定义 CA 的所有父级 CA 证书，其中包括根 CA 证书。如果自定义 CA 证书为根 CA 证书，则证书链必须为空。

  • **安装目录：**DC/OS 安装程序驻留的 bootstrap 节点上的目录。在本文档中以 $DCOS_INSTALL_DIR 表示。

  • **配置：**管理安装过程特定方面的配置参数集。配置存储在 DC/OS 配置文件中。

  • **DC/OS 配置文件：**包含 DC/OS 配置参数的文件。DC/OS 配置文件通常被称为 config.yaml，并且必须在安装期间出现在 bootstrap 节点上的 $DCOS_INSTALL_DIR/genconf/ 的目录中。它由 DC/OS 安装程序使用。

要求

要使用自定义 CA 证书安装 DC/OS Enterprise，您需要：

  • 使用 高级 DC/OS 安装方法。不支持其他安装方法。
  • 包含自定义 CA 证书的文件。
  • 包含与自定义 CA 证书相关联的私钥的文件。
  • 包含与自定义 CA 证书相关联的证书链的文件，如果 CA 不是 自签名根 CA。

手动放置自定义 CA 证书

自定义 CA 证书、关联的私钥和证书链文件必须放在 bootstrap 节点上的 $DCOS_INSTALL_DIR/genconf/ 的目录中：

  1. cd $DCOS_INSTALL_DIR
  2. ls genconf/
  1. dcos-ca-certificate.crt
  2. dcos-ca-certificate-key.key
  3. dcos-ca-certificate-chain.crt

手动放置私钥

出于安全原因，安装程序不会将私钥从 bootstrap 节点复制到主节点。 在开始安装之前，必须手动将与自定义 CA 证书相关联的私钥分发到每个 DC/OS 主节点。

私钥文件的文件系统路径必须是 /var/lib/dcos/pki/tls/CA/private/custom_ca.key。 目录 /var/lib/dcos/pki/tls/CA/private/ 必须在将文件 custom_ca.key 放置在每个 DC/OS 主节点上的目录中之前使用以下命令手动创建。

  1.  mkdir -p /var/lib/dcos/pki/tls/CA/private

此外，包含与自定义 CA 证书对应的私钥 custom_ca.key 的文件必须由 root Unix 用户拥有，并且设置了 0600 权限。

如果通过网络将私钥文件复制到主节点上，则必须充分保护网络通道。下面提供了复制 CA 私钥的示例。命令将在 bootstrap 节点上执行。以下 W.X.Y.Z 表示主节点的 IP 地址：

  1. cd $DCOS_INSTALL_DIR/genconf
  2. scp dcos-ca-certificate-key.key centos@W.X.Y.Z:/var/lib/dcos/pki/tls/CA/private/custom_ca.key

指定位置

bootstrap 节点上 $DCOS_INSTALL_DIR/genconf/ 目录中的自定义 CA 证书、关联私钥和证书链文件的文件系统路径必须在 DC/OS 配置文件中分别使用 ca_certificate_path、ca_certificate_key_path 和 ca_certificate_chain_path 参数进行指定。路径必须相对于 $DCOS_INSTALL_DIR。

以下 用例示例 部分显示如何设置这些配置参数。

配置参数参考

ca_certificate_path

到包含 OpenSSL PEM 格式的单个 X.509 CA 证书的文件的路径（相对于 $DCOS_INSTALL_DIR）。例如：genconf/dcos-ca-certificate.crt它是根 CA 证书（“自签名”）或是由其他证书颁发机构签署的中间 CA 证书（“交叉认证”）。

如果提供，则这是自定义 CA 证书。它用作签名 CA 证书，即 DC/OS CA 将使用此证书签署终端实体证书；本证书的主体将是由 DC/OS CA 签署的证书的发行方。如果未提供，则 DC/OS 群集在初始 bootstrap 阶段中生成唯一根 CA 证书，并将其用作签名 CA 证书。

与自定义 CA 证书相关联的公钥必须为 RSA 类型。

ca_certificate_key_path

到包含私匙文件的路径（相对于 $DCOS_INSTALL_DIR），该私匙对应于自定义 CA 证书，以 OpenSSL (PKCS#8) PEM 格式编码。例如：genconf/CA_cert.key。

这是高度敏感的数据。配置处理器仅为配置验证目的访问此文件，并且不复制数据。成功配置验证后，需要将此文件从带外放置到路径 /var/lib/dcos/pki/tls/CA/private/custom_ca.key 上所有 DC/OS 主节点的文件系统中，然后再启动大多数 DC/OS systemd 单元。该文件必须是根用户可读取的，并且应该具有 0600 权限集。

如果指定了 ca_certificate_path，则此路径是必需的。

ca_certificate_chain_path

到包含完整 CA 证书链文件的路径（相对于 $DCOS_INSTALL_DIR），该证书链是终端实体证书验证所需的，采用 OpenSSL PEM 格式。例如：genconf/CA_cert_chain.pem。

如果 ca_certificate_path 指向自签名根 CA 证书，则不能定义此参数。

否则，ca_certificate_chain_path 指向一个文件，该文件包含 CA 证书到自签名根 CA 证书的完整链，但不包括 ca_certificate_path 中的签名证书。顺序很重要：第一个证书必须验证 ca_certificate_path 中的签名证书，而每个后续证书都必须验证先前的证书。

使用自定义 CA 证书安装 DC/OS Enterprise

先决条件

  • 通过高级安装程序安装 DC/OS Enterprise 是根据相应文档编写，直至文档的安装 DC/OS部分。

  • 在 bootstrap 节点上，带有自定义 CA 证书、关联的私钥和可选的 CA 证书链的文件已放入 $DCOS_INSTALL_DIR/genconf/ 的目录中。（请参阅上面的部分，了解更多详细说明）

  • 与自定义 CA 证书相关联的私钥已安全地放置在所有 DC/OS 主节点上（有关更多信息，请参阅本部分）。在 DC/OS 主节点之一上发出命令的示例：

  1. stat /var/lib/dcos/pki/tls/CA/private/custom_ca.key
  1. File: ‘/var/lib/dcos/pki/tls/CA/private/custom_ca.key’
  2. Size: 9             Blocks: 8          IO Block: 4096   regular file
  3. Device: ca01h/51713d    Inode: 100671105   Links: 1
  4. Access: (0600/-rw-------)  Uid: (    0/    root)   Gid: (    0/    root)
  5. Context: unconfined_u:object_r:var_lib_t:s0
  6. Access: 2017-12-27 12:35:58.643278377 +0000
  7. Modify: 2017-12-27 12:35:58.643278377 +0000
  8. Change: 2017-12-27 12:36:13.019162417 +0000
  9. Birth: -
  • 配置参数 ca_certificate_path、ca_certificate_key_path 和 ca_certificate_chain_path 在 DC/OS 配置文件 $DCOS_INSTALL_DIR/genconf/config.yaml 中指定并指向文件系统中的相关位置。在 bootstrap 节点上发出命令的示例：
  1. cd $DCOS_INSTALL_DIR
  2. cat genconf/config.yaml
  1. [...]
  2. ca_certificate_path: genconf/dcos-ca-certificate.crt
  3. ca_certificate_key_path: genconf/dcos-ca-certificate-key.key
  4. ca_certificate_chain_path: genconf/dcos-ca-certificate-chain.crt
  5. [...]

请注意，在使用根证书作为自定义 CA 证书设置 DC/OS Enterprise 时，不得存在 ca_certificate_chain_path。

安装

按照高级安装程序文档中的说明继续安装。请注意，当执行 dcos_generate_config.ee.sh 时，当前工作目录必须是 $DCOS_INSTALL_DIR 目录。

验证安装

验证是否使用自定义 CA 证书正确安装 DC/OS Enterprise 群集的一种方法是启动到 Admin Router 的 TLS 连接，Admin Router 在安装后会显示自定义 CA 签署的证书。为此，您首先需要获取已部署群集的 DC/OS CA 捆绑包。本页面显示了您如何做到这一点。

如果您已经获得 DC/OS CA 捆绑包，并将其存储在名为 dcos-ca.crt 的文件中，在包含 dcos-ca.crt 文件的目录中发出以下命令，以检查主节点上的 Admin Router 是否使用自定义 CA 签署的证书：

  1. openssl s_client -verify_ip <private_ip_master_node_X> -CAfile dcos-ca.crt -connect <public_ip_master_node_X>:443 | grep -e "s:" -e "i:" -e "return code:"

输出应如下所示：

  1. depth=3 DC = io, DC = integration-test, C = DE, ST = Utopia, O = DC/OS, OU = Programmer Unit, CN = Integration Test Root CA
  2. verify return:1
  3. depth=2 DC = io, DC = integration-test, C = DE, ST = Utopia, O = DC/OS, OU = Programmer Unit, CN = Integration Test Intermediate CA 01
  4. verify return:1
  5. depth=1 DC = io, DC = integration-test, C = DE, ST = Utopia, O = DC/OS, OU = Programmer Unit, CN = Integration Test Intermediate CA 02
  6. verify return:1
  7. depth=0 C = US, ST = CA, L = San Francisco, O = "Mesosphere, Inc.", CN = AdminRouter on 172.31.12.45
  8. verify return:1
  9.  0 s:/C=US/ST=CA/L=San Francisco/O=Mesosphere, Inc./CN=AdminRouter on 172.31.12.45
  10.    i:/DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Intermediate CA 02
  11.  1 s:/DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Intermediate CA 02
  12.    i:/DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Intermediate CA 01
  13.  2 s:/DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Intermediate CA 01
  14.    i:/DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Root CA
  15.     Verify return code: 0 (ok)

用例示例

本部分介绍了如何在 $DCOS_INSTALL_DIR/genconf/config.yaml DC/OS 配置文件中为自定义 CA 证书层次结构的最常见用例指定三个配置参数 ca_certificate_path、ca_certificate_key_path 和 ca_certificate_chain_path。

用例 1：

自定义 CA 证书是自签名根 CA 证书。CA 没有“父” CA，因此 CA 证书链为空。

存在以下文件：

  • 在 botstrap 节点上：

    • 包含自定义 CA 证书的 $DCOS_INSTALL_DIR/genconf/dcos-ca-certificate.crt 文件
    • 包含与自定义 CA 证书相关联的私钥的 $DCOS_INSTALL_DIR/genconf/dcos-ca-certificate-key.key 文件

  • 在主节点：

    • 包含与自定义 CA 证书相关联的私钥的 /var/lib/dcos/pki/tls/CA/private/custom_ca.key 文件。

以下是自定义根 CA 证书的 issuer 和 subject 字段示例：

  1. cd $DCOS_INSTALL_DIR
  2. openssl x509 -in genconf/dcos-ca-certificate.crt -issuer -subject -noout
  1. issuer= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Root CA
  2. subject= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Root CA

由于自定义 CA 证书是根 CA 证书，且相应的 CA 证书链为空，因此我们必须省略 DC/OS 配置文件中的 ca_certificate_chain_path 参数。必须在 bootstrap 节点上的 $DCOS_INSTALL_DIR/genconf/config.yaml 文件中指定如下内容的配置参数：

  1. ca_certificate_path: genconf/dcos-ca-certificate.crt
  2. ca_certificate_key_path: genconf/dcos-ca-certificate-key.key

用例 2：

在该用例中，自定义 CA 证书是由 root CA 直接颁发的中间 CA 证书。CA 证书链只包含该根 CA 证书。存在以下文件：

  • 在 bootstrap 节点上：

    • 包含自定义 CA 证书的 $DCOS_INSTALL_DIR/genconf/dcos-ca-certificate.crt 文件， 格式为 PEM
    • 包含与自定义 CA 证书相关联的私钥的 $DCOS_INSTALL_DIR/genconf/dcos-ca-certificate-key.key 文件，格式为 PKCS#8
    • 仅包含根 CA 证书的 $DCOS_INSTALL_DIR/genconf/dcos-ca-certificate-chain.crt 文件， 格式为 PEM

  • 在主节点

    • 包含与自定义 CA 证书相关联的私钥的 /var/lib/dcos/pki/tls/CA/private/custom_ca.key 文件，格式为 PKCS#8

以下是适当的中间自定义 CA 证书示例：

  1. cd $DCOS_INSTALL_DIR
  2. openssl x509 -in genconf/dcos-ca-certificate.crt -issuer -subject -noout
  1. issuer= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Root CA
  2. subject= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Intermediate CA 01

以下是相应的 CA 证书链的示例：

  1. cd $DCOS_INSTALL_DIR
  2. cat genconf/dcos-ca-certificate-chain.crt | awk -v cmd="openssl x509 -issuer -subject -noout && echo" '/-----BEGIN/ { c = $0; next } c { c = c "\n" $0 } /-----END/ { print c|cmd; close(cmd); c = 0 }'
  1. issuer= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Root CA
  2. subject= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Root CA

必须在 bootstrap 节点上的 $DCOS_INSTALL_DIR/genconf/config.yaml DC/OS 配置文件中指定类似于以下内容的配置参数：

  1. ca_certificate_path: genconf/dcos-ca-certificate.crt
  2. ca_certificate_key_path: genconf/dcos-ca-certificate-key.key
  3. ca_certificate_chain_path: genconf/dcos-ca-certificate-chain.crt

用例 3：

在该用例中，自定义 CA 证书是其他中间 CA 直接颁发的中间 CA 证书，而后者的证书又由根 CA 颁发。

CA 证书链包括

  1. 颁发中间 CA 的 CA 证书，以及
  2. 根 CA

按以上顺序。

存在以下文件：

  • 在 bootstrap 节点上：

    • 包含自定义 CA 证书的 $DCOS_INSTALL_DIR/genconf/dcos-ca-certificate.crt 文件， 格式为 PEM
    • 包含与自定义 CA 证书相关联的私钥的 $DCOS_INSTALL_DIR/genconf/dcos-ca-certificate-key.key 文件，格式为 PKCS#8
    • 包含证书链的 $DCOS_INSTALL_DIR/genconf/dcos-ca-certificate-chain.crt 文件， 格式为 PEM

  • 在主节点

    • 包含与自定义 CA 证书相关联的私钥的 /var/lib/dcos/pki/tls/CA/private/custom_ca.key 文件，格式为 PKCS#8

以下是适当的自定义中间 CA 证书示例：

  1. cd $DCOS_INSTALL_DIR
  2. openssl x509 -in genconf/dcos-ca-certificate.crt -issuer -subject -noout
  1. issuer= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Intermediate CA 01
  2. subject= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Intermediate CA 02

以下是相应的 CA 证书链的示例：

  1. cd $DCOS_INSTALL_DIR
  2. cat genconf/dcos-ca-certificate-chain.crt | awk -v cmd="openssl x509 -issuer -subject -noout && echo" '/-----BEGIN/ { c = $0; next } c { c = c "\n" $0 } /-----END/ { print c|cmd; close(cmd); c = 0 }'
  1. issuer= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Root CA
  2. subject= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Intermediate CA 01
  3. issuer= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Root CA
  4. subject= /DC=io/DC=integration-test/C=DE/ST=Utopia/O=DC/OS/OU=Programmer Unit/CN=Integration Test Root CA

必须在 bootstrap 节点上的 $DCOS_INSTALL_DIR/genconf/config.yaml DC/OS 配置文件中指定如下内容的配置参数：

  1. ca_certificate_path: genconf/dcos-ca-certificate.crt
  2. ca_certificate_key_path: genconf/dcos-ca-certificate-key.key
  3. ca_certificate_chain_path: genconf/dcos-ca-certificate-chain.crt