下位認証局を作成する

このドキュメントでは、下位認証局（下位 CA）の作成手順について説明します。

下位 CA は、ユーザー、コンピュータ、デバイスなどのエンド エンティティに直接証明書を発行します。これらは、親 CA（多くの場合ルート CA）によって暗号で署名されます。ルート CA を信頼するシステムは、サブ CA と、サブ CA が発行する証明書を自動的に信頼します。

CA 証明書の署名者は、CA Service で作成された別の CA（ルート CA など）または外部 CA のいずれかです。外部 CA の場合、CA Service は外部 CA が署名する必要がある証明書署名リクエスト（CSR）を生成します。

このドキュメントは、プロジェクト内の証明書のライフサイクルを管理するアプリケーション デベロッパーやデータ サイエンティストなど、アプリケーション オペレーター グループ内のユーザーを対象としています。詳細については、GDC エアギャップ ドキュメントの対象読者をご覧ください。

始める前に

下位 CA を作成する前に、必要な権限をリクエストして環境を準備する必要があります。

IAM ロールをリクエストする

認証局リソースを作成、更新、削除するには、IAM 組織管理者に連絡して、認証局のプロジェクト名前空間でCertificate Authority Service Admin（certificate-authority-service-admin）ロールをリクエストします。

環境を準備する

• まだインストールしていない場合は、gdcloud CLI をダウンロードしてインストールします。

• kubectl CLI をインストールします。

• kubectl アクセスを構成する kubeconfig ファイルを生成します。

マネージド下位 CA を作成する

マネージド下位 CA の場合、CA 証明書の署名者は CA Service で作成された別の CA（ルート CA）です。

マネージド Sub CA を作成するには、Distributed Cloud Appliance インスタンスにカスタム リソースを適用します。

1. CertificateAuthority リソースを作成し、subca.yaml という YAML ファイルとして保存します。

   apiVersion: pki.security.gdc.goog/v1
   kind: CertificateAuthority
   metadata:
     Name: SUB_CA_NAME
     namespace: USER_PROJECT_NAMESPACE
   spec:
     caProfile:
       commonName: COMMON_NAME
       duration: DURATION
       renewBefore: RENEW_BEFORE
       organizations:
       - ORGANIZATIONS
       organizationalUnits:
       - ORGANIZATIONAL_UNITS
       countries:
       - COUNTRIES
       localities:
       - LOCALITIES
       provinces:
       - PROVINCES
       streetAddresses:
       - STREET_ADDRESSES
       postalCodes:
       - POSTAL_CODES
     caCertificate:
       managedSubCA:
         certificateAuthorityRef:
           name: ROOT_CA_NAME
           namespace: USER_PROJECT_NAMESPACE
     certificateProfile:
       keyUsage:
         - digitalSignature
         - keyCertSign
         - crlSign
       extendedKeyUsage:
         - EXTENDED_KEY_USAGE
     secretConfig:
       secretName: SECRET_NAME
       privateKeyConfig:
         algorithm: KEY_ALGORITHM
         size: KEY_SIZE
     acme:
       enabled: ACME_ENABLED
   

   次の変数を置き換えます。

   変数	説明
   SUB_CA_NAME	下位 CA の名前。
   USER_PROJECT_NAMESPACE	ユーザー プロジェクトが存在する Namespace の名前。
   COMMON_NAME	CA 証明書の共通名。
   DURATION	CA 証明書のリクエストされた有効期間。時間単位で指定します（例: 1000h）。日（d）や年（y）などの単位はサポートされていません。
   ROOT_CA_NAME	ルート CA の名前。
   SECRET_NAME	秘密鍵と署名付き CA 証明書を保持する Kubernetes Secret の名前。

   次の変数はオプションの値です。

   変数	説明
   RENEW_BEFORE	CA 証明書の有効期限が切れる前のローテーション時間。
   ORGANIZATIONS	証明書で使用される組織。
   ORGANIZATIONAL_UNITS	証明書で使用される組織部門。
   COUNTRIES	証明書で使用される国。
   LOCALITIES	証明書で使用される都市。
   PROVINCES	証明書で使用する都道府県。
   STREET_ADDRESSES	証明書で使用する番地。
   POSTAL_CODES	証明書で使用する郵便番号。
   EXTENDED_KEY_USAGE	証明書の鍵の拡張的用途。指定する場合、使用できる値は serverAuth と clientAuth です。
   KEY_ALGORITHYM	この証明書に使用される秘密鍵アルゴリズム。指定できる値は、RSA、Ed25519、ECDSA です。サイズを指定しない場合、デフォルトは ECDSA の場合は 256、RSA の場合は 2048 です。Ed25519 では鍵サイズは無視されます。
   KEY_SIZE	この証明書の秘密鍵のサイズ（ビット単位）は、アルゴリズムによって異なります。RSA では、2048、3072、4096、8192 を使用できます（デフォルトは 2048）。ECDSA では、256、384、521（デフォルトは 256）を使用できます。Ed25519 はサイズを無視します。
   ACME_ENABLED	true に設定すると、CA は ACME モードで実行され、ACME サーバーの URL を出力します。その後、ACME クライアントとプロトコルを使用して証明書を管理できます。

2. カスタム リソースを Distributed Cloud インスタンスに適用します。

   kubectl apply -f subca.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG
   

   MANAGEMENT_API_SERVER_KUBECONFIG は、Management API サーバーの kubeconfig ファイルのパスに置き換えます。

3. 下位 CA の準備状況を確認します。CA が準備完了になるまでに約 40 分かかります。

   kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificateauthority.pki.security.gdc.goog/SUB_CA_NAME -ojson | jq -r ' 
   .status.conditions[] | select( .type as $id | "Ready" | index($id))'
   

   出力は次のようになります。

   {
     "lastTransitionTime": "2025-01-24T17:09:29Z",
     "message": "CA reconciled",
     "observedGeneration": 2,
     "reason": "Ready",
     "status": "True",
     "type": "Ready"
   }
   

外部 CA から下位 CA を作成する

この下位 CA は、外部 CA またはユーザー管理 CA を使用したリーフ証明書の署名をサポートしています。ユーザーが署名するための CSR を生成します。

1. CertificateAuthority リソースを作成し、subca-external.yaml という YAML ファイルとして保存します。

   apiVersion: pki.security.gdc.goog/v1
   kind: CertificateAuthority
   metadata:
     Name: SUB_CA_NAME
     namespace: USER_PROJECT_NAMESPACE
   spec:
     caProfile:
       commonName: COMMON_NAME
       duration: DURATION
       renewBefore: RENEW_BEFORE
       organizations:
       - ORGANIZATION
       organizationalUnits:
       - ORGANIZATIONAL_UNITS
       countries:
       - COUNTRIES
       localities:
       - LOCALITIES
       provinces:
       - PROVINCES
       streetAddresses:
       - STREET_ADDRESSES
       postalCodes:
       - POSTAL_CODES
     caCertificate:
       externalCA: {}
     certificateProfile:
       keyUsage:
         - digitalSignature
         - keyCertSign
         - crlSign
       extendedKeyUsage:
         - EXTENDED_KEY_USAGE
     secretConfig:
       secretName: SECRET_NAME
       privateKeyConfig:
         algorithm: KEY_ALGORITHM
         size: KEY_SIZE
     acme:
       enabled: ACME_ENABLED
   

   次の変数を置き換えます。

   変数	説明
   SUB_CA_NAME	subCA の名前。
   USER_PROJECT_NAMESPACE	イメージをインポートするプロジェクトのプロジェクト ID。
   COMMON_NAME	CA 証明書の共通名。
   DURATION	CA 証明書のリクエストされた有効期間。時間単位で指定します（例: 1000h）。日（d）や年（y）などの単位はサポートされていません。
   SECRET_NAME	秘密鍵と署名付き CA 証明書を保持する Kubernetes Secret の名前。

   次の変数はオプションの値です。

   変数	説明
   RENEW_BEFORE	CA 証明書の有効期限が切れる前のローテーション時間。
   ORGANIZATION	証明書で使用される組織。
   ORGANIZATIONAL_UNITS	証明書で使用される組織部門。
   COUNTRIES	証明書で使用される国。
   LOCALITIES	証明書で使用される都市。
   PROVINCES	証明書で使用する都道府県。
   STREET_ADDRESSES	証明書で使用する番地。
   POSTAL_CODES	証明書で使用する郵便番号。
   EXTENDED_KEY_USAGE	証明書の鍵の拡張的用途。指定する場合、使用できる値は serverAuth と clientAuth です。
   KEY_ALGORITHYM	この証明書に使用される秘密鍵アルゴリズム。指定できる値は RSA、Ed25519、ECDSA です。サイズが指定されていない場合、デフォルトは ECDSA の場合は 256、RSA の場合は 2048 です。Ed25519 の鍵サイズは無視されます。
   KEY_SIZE	この証明書の秘密鍵のサイズ（ビット単位）は、アルゴリズムによって異なります。RSA には、2048、3072、4096、8192 を指定できます（デフォルトは 2048）。ECDSA には、256、384、521 を指定できます（デフォルトは 256）。Ed25519 はサイズを無視します。
   ACME_ENABLED	true に設定すると、CA は ACME モードで実行され、ACME サーバーの URL を出力します。その後、ACME クライアントとプロトコルを使用して証明書を管理できます。

2. カスタム リソースを Distributed Cloud インスタンスに適用します。

   kubectl apply -f subca-external.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG
   

3. 下位 CA の CSR が GDC Management API サーバー内で生成されます。CSR をダウンロードして署名する必要があります。署名が完了したら、署名済みの証明書を GDC Management API サーバーにアップロードできます。

4. Distributed Cloud 環境から証明書署名リクエスト（CSR）を収集します。

   kubectl get certificateauthorities SUB_CA_NAME -n USER_PROJECT_NAMESPACE -ojson | jq -j '"echo ", .status.externalCA.csr, " | base64 -d > ","sub_ca.csr\n"' | bash
   

   このコマンドにより、現在のディレクトリに sub_ca.csr という CSR ファイルが生成されます。このファイルには、X.509 CA 証明書の CSR が含まれています。

5. お客様のルート CA を使用して、sub_ca.csr ファイルの署名付き CA 証明書をリクエストします。

6. 承認された証明書署名リクエストの場合は、お客様のルート CA によって署名された CA 証明書を取得する必要があります。現在のディレクトリの sub_ca.crt ファイルに証明書を保存します。

7. 該当する場合は、お客様のルート CA 証明書を取得し、現在のディレクトリの ca.crt ファイルに保存します。

8. CA 証明書の共通名（CN）を確認します。

   openssl x509 -noout -subject -in sub_ca.crt
   

   設定でサブジェクト代替名（SAN）拡張機能が必要な場合は、証明書の SAN 拡張機能を確認します。

   openssl x509 -text -noout -in sub_ca.crt | grep -A 1 "Subject Alternative Name"
   

9. spec を生成して CertificateAuthority リソースにパッチを適用します。

   echo "spec:
     caCertificate:
       externalCA:
         signedCertificate:
           certificate: $(base64 -w0 SUB_CA_NAME.crt)
           ca: $(base64 -w0 ca.crt)" > patch.txt
   

   patch.txt ファイルの内容は次のようになります。

   spec:
     caCertificate:
       externalCA:
         signedCertificate:
           certificate: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURSekNDQ…
           ca: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURRVENDQ…
   

10. CertificateAuthority リソースの spec フィールドを編集します。

    kubectl patch certificateauthority SUB_CA_NAME -n USER_PROJECT_NAMESPACE--patch-file patch.txt --type='merge'
    

11. Bring Your Own（BYO）サブ CA の準備状況を確認します。通常、CA が準備完了になるまでに 40 分ほどかかります。

    kubectl -n USER_PROJECT_NAMESPACE get certificateauthority.pki.security.gdc.goog/SUB_CA_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'
    

    出力は次のようになります。

    {
      "lastTransitionTime": "2024-04-30T22:10:50Z",
      "message": "Certificate authority is ready for use",
      "observedGeneration": 3,
      "reason": "Ready",
      "status": "True",
      "type": "Ready"
    }
    

12. 署名付き CA 証明書の有効期限を確認します。

    kubectl -n USER_PROJECT_NAMESPACE get secret SECRET_NAME -ojson | jq -j '"echo ", .metadata.name, " $(echo ", .data["tls.crt"], "| base64 -d | openssl x509 -enddate -noout)\n"' | bash
    

CA を一覧表示する

Distributed Cloud のエアギャップ インスタンス内のすべての Certificate Authority Service リソースを一覧表示するには、次の操作を行います。

certificateauthorities パラメータを使用して、すべての CertificateAuthority リソースを一覧表示します。

   kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificateauthorities

出力は次のようになります。

   NAMESPACE    NAME              READY   REASON   AGE
   foo          root-ca           True    Ready    7h24m
   foo          sub-ca            True    Ready    7h24m