Using an issuance policy

Preview

This product is in a pre-release state and might change or have limited support. For more information, see the product launch stages.

During this launch phase, this product is subject to Google Cloud's Data Processing and Security Terms.

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.

Caution: The policy changes are effective immediately. Before using it in production on an enabled CA, it is strongly recommended to try out the policy changes on a test CA instance.

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
  

  Note: When using openssl to create a CSR, by default openssl does not include extensions in the CSR. If CSRs will be used for requesting certificates, using an overwriting policy can simplify certificate creation.

Restrict allowed subject fields

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

Note: Common Names (CNs), while technically part of the Subject, are treated separately below.

• 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.

Note: If any of the SAN types are configured, types without a restriction will deny any value to be specified. Adding an empty allowedSans section will continue to allow all certificate requests.

• 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
  

  Note: This policy will not allow actual wildcard DNS names (such as "*.cloud.google.com"). To match wildcard DNS names with glob patterns, set the allowGlobbingDnsWildcards field to true in the policy. To match literal wildcards in the DNS names, escape the * with a backslash: "\*.cloud.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 [e-mail] or matching the glob pattern *@google.org.

  policy.yaml

    allowedSans:
      allowedEmailAddresses:
      - [e-mail]
      - *@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.

Note: A certificate can never outlive its issuing CA. Any certificate requests with a lifetime that would exceed the CA's notAfter date will have their lifetime truncated to match the CA's notAfter date, even if the longer lifetime is allowed by the policy.

• 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

What's next

• Requesting certificates
• Configuring IAM policies