This document describes the steps to create a subordinate certificate authority
(Sub CA).

Sub CAs are responsible for issuing certificates directly to end entities,
such as users, computers, and devices. They are cryptographically signed by a
parent CA, often the root CA. Systems that trust the root CA automatically trust
the Sub CAs and the certificates they issue.

The CA certificate signer could be either another CA created in CA Service, for
example, root CA, or an external CA. With external CAs, CA Service generates a
certificate signing request (CSR) that the external CA must sign.

This document is for audiences within the application operator group, such as
application developers or data scientists, who manage certificate lifecycles
within their project. For more information, see
[Audiences for GDC air-gapped documentation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/audiences.md.txt).

## Before you begin

Before you can create a Sub CA, you must request the necessary permissions and
prepare your environment.

### Request IAM roles

To create, update, and delete certificate authority resources, contact your
IAM Org Admin to request the **Certificate Authority Service Admin**
(`certificate-authority-service-admin`) role in the project namespace of the
certificate authority.

### Prepare your environment

- [Download](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-download.md.txt) and
  [install](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-install.md.txt) the gdcloud CLI,
  if you haven't already done so.

- [Install the kubectl CLI](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/get-started/kubectl.md.txt).

- [Generate a kubeconfig file](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-auth.md.txt#get-kubeconfig)
  to configure `kubectl` access.

## Create a managed Sub CA

For a managed Sub CA, the signer of the CA certificate is another CA (root CA)
created in CA Service.

To create a managed Sub CA, apply a custom resource to your
Distributed Cloud Appliance instance.

1. Create a `CertificateAuthority` resource and save it as a YAML file called
   `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
   ```

   Replace the following variables:

   | Variable | Description |
   |---|---|
   | <var translate="no">SUB_CA_NAME</var> | The name of the Sub CA. |
   | <var translate="no">USER_PROJECT_NAMESPACE</var> | The name of the namespace where the user project resides. |
   | <var translate="no">COMMON_NAME</var> | The common name of the CA certificate. |
   | <var translate="no">DURATION</var> | The requested lifetime of the CA certificate. Specify as a duration in hours (for example, `1000h`). Units such as days (`d`) or years (`y`) are not supported. |
   | <var translate="no">ROOT_CA_NAME</var> | The name of the root CA. |
   | <var translate="no">SECRET_NAME</var> | The name of the Kubernetes Secret that holds the private key and signed CA certificate. |

   The following variables are optional values:

   | Variable | Description |
   |---|---|
   | <var translate="no">RENEW_BEFORE</var> | The rotation time before the CA certificate expires. |
   | <var translate="no">ORGANIZATIONS</var> | Organizations to be used on the certificate. |
   | <var translate="no">ORGANIZATIONAL_UNITS</var> | Organizational units to be used on the certificate. |
   | <var translate="no">COUNTRIES</var> | Countries to be used on the certificate. |
   | <var translate="no">LOCALITIES</var> | Cities to be used on the certificate. |
   | <var translate="no">PROVINCES</var> | State or Provinces to be used on the certificate. |
   | <var translate="no">STREET_ADDRESSES</var> | Street addresses to be used on the certificate. |
   | <var translate="no">POSTAL_CODES</var> | Postal codes to be used on the certificate. |
   | <var translate="no">EXTENDED_KEY_USAGE</var> | The extended key usage for the certificate. If provided, the allowed values are `serverAuth` and `clientAuth`. |
   | <var translate="no">KEY_ALGORITHYM</var> | The private key algorithm used for this certificate. Allowed values are RSA, Ed25519, or ECDSA. If the size is not provided, it defaults to 256 for ECDSA and 2048 for RSA. Key size is ignored for Ed25519. |
   | <var translate="no">KEY_SIZE</var> | The size, in bits, of the private key for this certificate depends on the algorithm. RSA allows 2048, 3072, 4096, or 8192 (default 2048). ECDSA allows 256, 384, or 521 (default 256). Ed25519 ignores size. |
   | <var translate="no">ACME_ENABLED</var> | If set to `true`, CA runs in ACME mode and outputs the ACME server URL. You can then use the ACME client and protocol to manage certificates. |

2. Apply the custom resource to your Distributed Cloud instance:

   ```bash
   kubectl apply -f subca.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG
   ```

   Replace `MANAGEMENT_API_SERVER_KUBECONFIG` with the
   path to the kubeconfig file of the Management API server.
3. Verify the readiness of the Sub CA. It takes \~40 minutes for the CA to become
   ready:

   ```bash
   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))'
   ```

   The output looks similar to the following:

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

## Create a Sub CA from an external CA

This Sub CA supports signing leaf certificates with external or user managed
CAs. It generates a CSR for users to sign.

1. Create a `CertificateAuthority` resource and save it as a YAML file called
   `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
   ```

   Replace the following variables:

   | Variable | Description |
   |---|---|
   | <var translate="no">SUB_CA_NAME</var> | The name of the subCA. |
   | <var translate="no">USER_PROJECT_NAMESPACE</var> | The project ID for the project where you want to import the image. |
   | <var translate="no">COMMON_NAME</var> | The common name of the CA certificate. |
   | <var translate="no">DURATION</var> | The requested lifetime of the CA certificate. Specify as a duration in hours (for example, `1000h`). Units such as days (`d`) or years (`y`) are not supported. |
   | <var translate="no">SECRET_NAME</var> | The name of the Kubernetes Secret that holds the private key and signed CA certificate. |

   The following variables are optional values:

   | Variable | Description |
   |---|---|
   | <var translate="no">RENEW_BEFORE</var> | The rotation time before the CA certificate expires. |
   | <var translate="no">ORGANIZATION</var> | Organization to be used on the certificate. |
   | <var translate="no">ORGANIZATIONAL_UNITS</var> | Organizational units to be used on the certificate. |
   | <var translate="no">COUNTRIES</var> | Countries to be used on the certificate. |
   | <var translate="no">LOCALITIES</var> | Cities to be used on the certificate. |
   | <var translate="no">PROVINCES</var> | State or Provinces to be used on the certificate. |
   | <var translate="no">STREET_ADDRESSES</var> | Street addresses to be used on the certificate. |
   | <var translate="no">POSTAL_CODES</var> | Postal codes to be used on the certificate. |
   | <var translate="no">EXTENDED_KEY_USAGE</var> | The extended key usage for the certificate. If provided, the allowed values are `serverAuth` and `clientAuth`. |
   | <var translate="no">KEY_ALGORITHYM</var> | The private key algorithm used for this certificate. Allowed values are `RSA`, `Ed25519`, or `ECDSA`. If the size is not provided, it defaults to 256 for `ECDSA` and 2048 for `RSA`. Key size is ignored for `Ed25519`. |
   | <var translate="no">KEY_SIZE</var> | The size, in bits, of the private key for this certificate depends on the algorithm. `RSA` allows 2048, 3072, 4096, or 8192 (default 2048). `ECDSA` allows 256, 384, or 521 (default 256). `Ed25519` ignores size. |
   | <var translate="no">ACME_ENABLED</var> | If set to `true`, CA runs in ACME mode and outputs the ACME server URL. You can then use the ACME client and protocol to manage certificates. |

2. Apply the custom resource to your Distributed Cloud instance:

   ```bash
   kubectl apply -f subca-external.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG
   ```
3. A CSR for the Sub-CA is generated within the GDC
   Management API server. You must download the CSR and sign it. Once signed,
   you can upload the signed certificate into the GDC
   Management API server.

4. Gather the certificate signing requests (CSR) from your Distributed Cloud
   environment:

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

   The command generates a CSR file called `sub_ca.csr` in the current directory.
   This file contains a CSR for an `X.509` CA certificate.
5. Use the customer's root CA to request signed CA certificates for the
   `sub_ca.csr` file.

6. For an approved certificate signing request, you must obtain a CA certificate
   signed by the customer's root CA. Store the certificate in the `sub_ca.crt`
   file in the current directory.

7. If applicable, obtain the customer's root CA certificate and store it in the
   `ca.crt` file in the current directory.

8. Verify the CA certificate's Common Name (CN):

   ```bash
   openssl x509 -noout -subject -in sub_ca.crt
   ```

   If your setup requires Subject Alternative Name (SAN) extensions,
   verify the SAN extensions in the certificate:

   ```bash
   openssl x509 -text -noout -in sub_ca.crt | grep -A 1 "Subject Alternative Name"
   ```
9. Generate the `spec` to patch the `CertificateAuthority` resource:

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

   The content in the `patch.txt` file looks similar to the following:

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

10. Edit the `spec` field of the `CertificateAuthority` resource:

    ```bash
    kubectl patch certificateauthority SUB_CA_NAME -n USER_PROJECT_NAMESPACE--patch-file patch.txt --type='merge'
    ```
11. Verify the readiness of the bring your own (BYO) Sub CA. It normally takes
    around 40 minutes for the CA to become ready:

    ```bash
    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))'
    ```

    The output looks similar to the following:

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

12. Verify the expiration date of the signed CA certificates:

    ```bash
    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
    ```

## List CAs

To list all of the Certificate Authority Service resources in your
Distributed Cloud air-gapped instance, do the following:

Use the `certificateauthorities` parameter to list all `CertificateAuthority`
resources:

```bash
   kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificateauthorities
```

The output looks similar to the following:

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