Using an issuance policy

This topic describes how to use a CA issuance policy with the Certificate Authority Service. To learn what an issuance policy is, see Issuance Policies.

Before you begin

Create a Certificate Authority by following the steps in the CA Service Quickstart.

Using a policy

A CA issuance policy can be used to specify restrictions on the certificates a CA can issue. It can be created by configuring the CertificateAuthorityPolicy field of a CertificateAuthority. The policy can be specified when the CA is created or updated. The policy can be updated at any time.

Policy file

The policy file is a YAML file that describes the restrictions on the certificates a CA can issue. The content corresponds to a CertificateAuthorityPolicy. This file can be used with gcloud command-line tool.

  • Example: Limit a CA to only issue certificates with Subject values which are either O="Joonix LLC" C=US or O="Joonix LLC" C=UK. Create a file policy.yaml with the following content:

      allowedLocationsAndOrganizations:
      - country: US
        organization: Joonix LLC
      - country: UK
        organization: Joonix LLC
    

    gcloud

      gcloud beta privateca roots update restricted-root \
          --issuance-policy policy.yaml
    
    

Supported restrictions

The following issuance policy restrictions are supported and can be combined as necessary to build a custom issuance policy:

Restrict or force allowed X.509 values

A CA can restrict the allowed X.509 values in certificate requests by configuring the allowedConfigList field. Alternatively, a CA can specify the configuration values all its issued certificates will use, overwriting any requested values by using the overwriteConfigValues field. These options are mutually exclusive.

You can specify restrictions by referencing an existing reusable config resource or by specifying the desired values inline.

  • Example: Restrict CA to only issue certificates with x.509 values for MTLS or code signing.

    policy.yaml

      allowedConfigList:
        allowedConfigValues:
        - reusableConfig: projects/privateca-data/locations/us-west1/reusableConfigs/leaf-server-tls
        - reusableConfig: projects/privateca-data/locations/us-west1/reusableConfigs/leaf-code-signing
    
  • Example: Force CA to overwrite any issued certificate to use the leaf-client-tls reusable config.

    policy.yaml

      overwriteConfigValues:
        reusableConfig: projects/privateca-data/locations/us-west1/reusableConfigs/leaf-client-tls
    

Restrict allowed subject fields

To restrict the Subject values of a CA's issued certificates, the allowedLocationsAndOrganizations field can be used.

  • Example Allow CA to issue only certificates matching a specified Subject.

    policy.yaml

      allowedLocationsAndOrganizations:
      - country: US
        organization: Joonix LLC
      - country: UK
        organization: Joonix LLC
    

Restrict allowed Subject Alternative Names (SAN) and allowed Common Names (CN)

To restrict the allowed Subject Alternative Names that can appear in issued certificates, the allowedSans field can be used. If configured, for each SAN type, the requested certificate's value needs to match at least one of the allowed values for that type.

  • Example: Allow only SANs having DNS Names as us.google.org or matching the glob pattern *.google.com.

    policy.yaml

      allowedSans:
        allowedDnsNames:
        - us.google.org
        - *.google.com
    
  • Example: Allow only SANs having DNS Names matching the glob pattern *.google.com, including wildcard DNS names.

    policy.yaml

      allowedSans:
        allowedDnsNames:
        - *.google.com
        allowGlobbingDnsWildcards: True
    
  • Example: Allow only SANs having URIs https://google.com/webhp or matching the glob pattern spiffe://joonix-trust-domain-1/ns/namespace1/sa/**.

    policy.yaml

      allowedSans:
        allowedUris:
        - https://google.com/webhp
        - spiffe://joonix-trust-domain-1/ns/namespace1/sa/**
    
  • Example: Allow only SANs having email addresses example@google.com or matching the glob pattern *@google.org.

    policy.yaml

      allowedSans:
        allowedEmailAddresses:
        - example@google.com
        - *@google.org
    
  • Example: Allow only SANs having IPs 2001:4860:4860::8888, in the subnet range 10.0.0.0/8 or matching the glob pattern 192.168.*.5.

    policy.yaml

      allowedSans:
        allowedIps:
        - 2001:4860:4860::8888
        - 10.0.0.0/8
        - 192.168.*.5
    
  • Example: Allow custom X509 extension values. By default, they are not allowed.

    policy.yaml

      allowedSans:
        allowCustomSans: True
    

Similarly, to restrict the allowed CN values that can appear in issued certificates, the allowedCommonNames field can be used.

  • Example: Restrict issuance only to certificates having the common name as google.org or Google LLC.

    policy.yaml

      allowedCommonNames:
      - google.org
      - Google LLC
    

Restrict maximum lifetime

To restrict the lifetime of the issued certificates, the maximumLifetime field can be used. If a certificate's requested lifetime is larger than the maximum lifetime, the certificate's lifetime will be explicitly truncated.

  • Example: Allow a maximum lifetime of 30 days.

policy.yaml

    maximumLifetime: 30d

Restrict allowed issuance modes

As explained in requesting certificates, by default, a certificate can be requested either through a CSR or an inline description of the requested values. Since the latter method does not require a proof of possession of the associated private key, some organizations may prefer to add limitations on which option can be used. To do this, the allowedIssuanceModes field can be used.

  • Example: Allow only CSR issuance.

policy.yaml

    allowedIssuanceModes:
      allowCsrBasedIssuance: True
      allowConfigBasedIssuance: False