Add a certificate issuance policy to a CA pool
This page describes how to add a certificate issuance policy to a certificate authority (CA) pool.
A certificate issuance policy lets you specify the subject and subject alternative names (SANs) that can be included in the issued certificates. You can specify the certificate issuance policy while creating a CA pool or you can update an existing CA pool to add an issuance policy.
For more information, see Overview of templates and issuance policies.
Before you begin
Make sure you have the CA Service Operation Manager (
roles/privateca.caManager
) or the CA Service Admin (roles/privateca.admin
) IAM role. For information about granting an IAM to a principal, see Grant a single role.
Add a certificate issuance policy file
To add a certificate issuance policy to an existing CA pool, do the following:
Console
Go to the Certificate Authority Service page in the Google Cloud console.
On the CA pool manager page, click the name of the CA pool for which you want to add a certificate issuance policy.
On the CA pool page, click
Edit.
To configure baseline values in the certificates issued from the CA pool, do the following:
- Click the toggle.
- Click Configure baseline values.
You can use this setting to configure the ways in which the key contained in the certificate can be used. The options for key usage include key encipherment, data encipherment, certificate signing, CRL signing, and more.
For more information, see Key usage.
To define the base key usages, do the following:
- Optional: In the window that appears, click the toggle, if you want to specify base key usages for the certificates.
- Select the checkboxes for the ways in which you want a key to be used.
- Click Next.
You can use this setting to select more granular scenarios for which the key contained in the certificate can be used. The options include server authentication, client authentication, code signing, email protection, and more.
Extended key usages are defined using object identifiers (OIDs). If you don't configure the extended key usages, all key usage scenarios are allowed.
For more information, see Extended key usage.
To define the extended key usages, do the following:
- Optional: To specify the extended key usages for the certificates that the CA pool issues, click the toggle.
- Select the checkboxes for the extended key usage scenarios.
- Click Next.
The certificate policies extension in the certificate expresses the policies that the issuing CA pool follows. This extension can include information about how identities are validated before certificate issuance, how certificates are revoked, and how the CA pool's integrity is ensured. This extension helps you verify the certificates that the CA pool issues and see how the certificates are used.
For more information, see Certificate policies.
To specify the policy that defines the certificate usage, do the following:
- Optional: Add the policy identifier in the Policy identifiers field.
- Click Next.
The AIA extension in a certificate provides the following information:
- Address of the OCSP servers from where you can check the revocation status of the certificate.
- The access method for the issuer of the certificate.
For more information, see Authority information access.
To add the OCSP servers that appear in the AIA extension field in the certificates, do the following. The following procedure is optional.
- Optional: Click Add item.
- In the Server URL field, add the URL of the OCSP server.
- Click Done.
- Click Next.
To configure additional custom extensions to include in the certificates issued by the CA pool, do the following. The following procedure is optional.
- Click Add item.
- In the Object identifier field, add a valid object identifier that is formatted as dot-separated digits.
- In the Value field, add the base64-encoded value for the identifier.
- If the extension is critical, select Extension is critical.
To save all the baseline value configurations, click Done.
Configure extension constraintsTo disallow all extensions from certificate requests from being included in the issued certificates, click the toggle.
After you click the toggle, you will see the Known certificate extensions field that you can use to select the certificate extensions. To select the certificate extensions, do the following:
- Optional: Click the Known certificate extensions field, and clear the unrequired extensions from the menu.
- Optional: In the Custom extensions field, add the object identifiers for extensions you want to be included in the certificates that the CA pool issues.
To configure constraints on the subject and SANs in the certificates that the CA pool issues, do the following:
- Optional: To disallow subject in certificate requests from being passed through, click the toggle.
- Optional: To disallow subject alternative names in certificate requests from being passed through, click the toggle.
- Optional: Add a Common Expression Language (CEL) expression to place restrictions on certificate subjects. For more information, see Using CEL.
- Click Next.
To learn how to configure additional parameters in the certificate issuance policy, see IssuancePolicy.
gcloud
To use the Google Cloud CLI to add a certificate issuance policy to a CA pool, you must create a YAML file that describes the restrictions on the certificates that the CA pool can issue. The content corresponds to an IssuancePolicy.
Using the Cloud Shell Editor, create a file
policy.yaml
with the following content:identityConstraints: allowSubjectPassthrough: true allowSubjectAltNamesPassthrough: true
Where:
- The
allowSubjectPassthrough
field is required. If theallowSubjectPassthrough
field is set totrue
, the subject field is copied from a certificate request into the signed certificate. Otherwise, the requested Subject is discarded. - If the
allowSubjectAltNamesPassthrough
field is set totrue
, the SubjectAltNames extension is copied from a certificate request into the signed certificate. Otherwise, the requested SubjectAltNames is discarded.
- The
To update a CA pool's certificate issuance policy using the file created in the previous step, run the following command:
gcloud privateca pools update POOL_NAME \ --issuance-policy FILE_PATH
Replace the following:
- POOL_NAME: Name of the CA pool.
- FILE_PATH: The path of the
policy.yaml
file.
For more information about the
gcloud privateca pools update
command, see gcloud privateca pools update.
Supported restrictions
CA Service supports the following issuance policy restrictions. You can combine the following restrictions as necessary to build a custom certificate issuance policy.
Restrict or force allowed X.509 values
A CA pool can restrict the allowed X.509 values in certificate requests by configuring the passthrough_extensions field.
A CA pool can also explicitly specify X.509 values to be added to all its issued certificates, overwriting any requested values, by using the baseline_values field.
The baseline_values values of a CA pool allow specifying the following properties:
You can also use these options together.
If you update any part of the baseline_values
field, the update replaces
the entire set of values in the baseline_values
field.
Example: Restrict a CA to issue only end-entity certificates with X.509 values for mutual TLS (mTLS).
policy.yaml
baselineValues: caOptions: isCa: false keyUsage: baseKeyUsage: digitalSignature: true keyEncipherment: true extendedKeyUsage: clientAuth: true serverAuth: true
Example: Restrict a CA to issue only end-entity code signing certificates with a baseline AIA OCSP URL.
policy.yaml
baselineValues: caOptions: isCa: false keyUsage: baseKeyUsage: digitalSignature: true extendedKeyUsage: codeSigning: true aiaOcspServers: - "http://foo.bar/revocation" additionalExtensions: - objectId: objectIdPath: - 1 - 2 - 3 critical: false value: "base64 encoded extension value"
For more information about the certificate profile for end-entity mTLS, see End-entity mTLS.
Restrict allowed identity fields
To restrict the identity of certificates issued through a CA pool, you can add a Common Expression Language (CEL) expression to the issuance policy's identity_constraints field. The CEL expressions allow arbitrary restrictions over the Subject Domain Name (including the common name) and the SANs of a certificate.
For more information about using a CEL expression to restrict Subject and SANs, see Using CEL.
Example Allow the CA to issue only certificates matching a specified Subject.
policy.yaml
identityConstraints: allowSubjectPassthrough: true allowSubjectAltNamesPassthrough: false celExpression: expression: 'subject.organization == "Example LLC" && subject.country_code in ["US", "UK"]'
The
celExpression
field is optional. Use a Common Expression Language (CEL) expression to validate the resolved X.509 subject and SAN before a certificate is signed. For more information about using CEL expressions, see Using CEL.Example: Allow only SANs having DNS Names as
us.google.org
or ending in.google.com
.policy.yaml
identityConstraints: allowSubjectPassthrough: false allowSubjectAltNamesPassthrough: true celExpression: expression: 'subject_alt_names.all(san, san.type == DNS && (san.value == "us.google.org" || san.value.endsWith(".google.com")) )'
Example: Allow only SANs having URIs
https://google.com/webhp
or starting withspiffe://example-trust-domain-1/ns/namespace1/sa/
.policy.yaml
identityConstraints: allowSubjectPassthrough: false allowSubjectAltNamesPassthrough: true celExpression: expression: 'subject_alt_names.all(san, san.type == URI && (san.value == "https://google.com/webhp" || san.value.startsWith("spiffe://example-trust-domain-1/ns/namespace1/sa/")) )'
Example: Allow only SANs having email addresses
example@google.com
or ending with@google.org
.policy.yaml
identityConstraints: allowSubjectPassthrough: false allowSubjectAltNamesPassthrough: true celExpression: expression: 'subject_alt_names.all(san, san.type == EMAIL && (san.value == "example@google.com" || san.value.endsWith("@google.org")) )'
Example: Allow only custom SANs having a specific OID and a custom value.
policy.yaml
identityConstraints: allowSubjectPassthrough: false allowSubjectAltNamesPassthrough: true celExpression: expression: 'subject_alt_names.all(san, san.type == CUSTOM && san.oid == [1, 2, 3, 4] && san.value == "custom-data" )'
Restrict maximum lifetime of the issued certificates
To restrict the lifetime of the issued certificates, use the maximum_lifetime field. If a certificate's requested lifetime is larger than the maximum lifetime, the certificate's lifetime is explicitly truncated.
Example
To allow a maximum lifetime of 30 days, use the following policy.yaml
file:
policy.yaml
maximumLifetime: 2592000s
Restrict allowed certificate issuance modes
You can request a certificate either through a Certificate Signing Request (CSR) or an inline description of the requested values. Some organizations might prefer to add limitations on the option that can be used because the latter method doesn't require a proof of possession of the associated private key. You can set these limitations using the allowedIssuanceModes field.
For more information about specifying the ways in which certificates can be requested from a CA pool, see IssuanceModes.
For more information about requesting certificates, see Create a certificate request.
Example: Allow only CSR issuance.
policy.yaml
allowedIssuanceModes:
allowCsrBasedIssuance: True
allowConfigBasedIssuance: False
Restrict the public key algorithms of the certificate request
To restrict the minimum key length and the public key algorithms that certificates can use, you can use the allowedKeyTypes field in the certificate issuance policy YAML file. If this field is specified, then the certificate request's public key must match one of the key types listed in the YAML file. If this field isn't specified, then you can use any key, with the exception of RSA keys whose modulus size is less than 2048 bits. If you want to use a RSA key with modulus size less than 2048 bits, you must explicitly allow it using the certificate issuance policy.
Example: Allow RSA keys with a modulus size between 3072 bits and 4096 bits (inclusive), or Elliptic Curve Digital Signature Algorithm (ECDSA) keys over the NIST P-256 curve.
policy.yaml
allowedKeyTypes:
- rsa:
minModulusSize: 3072
maxModulusSize: 4096
- ellipticCurve:
signatureAlgorithm: ECDSA_P256
You can choose one of the following elliptic curve signature algorithms:
EC_SIGNATURE_ALGORITHM_UNSPECIFIED
- Any signature algorithm may be used.ECDSA_P256
- Elliptic Curve Digital Signature over the NIST P-256 curve.ECDSA_P384
- Elliptic Curve Digital Signature over the NIST P-384 curve.EDDSA_25519
- Edwards-curve Digital Signature Algorithm over curve 25519, as described in RFC 8410.
What's next
- Learn more about certificate profiles.
- Learn more about requesting certificates.
- Learn how to configure IAM policies.
- Learn how to use Common Expression Language (CEL).
- Learn how to manage various policy controls.