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
orO="Joonix LLC" C=UK
. Create a filepolicy.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 patternspiffe://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 range10.0.0.0/8
or matching the glob pattern192.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
orGoogle 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