This topic describes how to use a certificate issuance policy on a certificate authority (CA) pool. To learn more about certificate issuance policy, see Certificate issuance policies.
Before you begin
Create a CA pool by following the steps mentioned in the Quickstart.
Using a certificate issuance policy
A certificate issuance policy lets you specify restrictions on the certificates that the CA pool can issue. You can set a certificate issuance policy by configuring the IssuancePolicy field of a CaPool. You can specify the certificate issuance policy when the CA pool is created or updated, and update the issuance policy at any time.
Certificate issuance policy file
The certificate issuance policy file is a YAML file that describes the restrictions on the certificates a CA can
issue. The content corresponds to an IssuancePolicy. You can set the certificate issuance policy on a CA pool using the
gcloud command-line tool.
Create a CA pool with a certificate issuance policy file
This section demonstrates how you can create a CA pool that lets you specify Subject and Subject Alternative Names (SANs) in certificate requests.
Create a file
policy.yamlwith the following content:
identityConstraints: allowSubjectPassthrough: true allowSubjectAltNamesPassthrough: true
allowSubjectPassthroughfield is required. If the
allowSubjectPassthroughfield is set to
true, the subject field is copied from a certificate request into the signed certificate. Otherwise, the requested Subject is discarded.
- If the
allowSubjectAltNamesPassthroughfield is set to
true, the SubjectAltNames extension is copied from a certificate request into the signed certificate. Otherwise, the requested SubjectAltNames is discarded.
To create a CA pool with the certificate issuance policy file created in the previous step, use the following
gcloud privateca pools update POOL_NAME \ --issuance-policy policy.yaml
policy.yamlis the name of the certificate issuance policy YAML file.
For more information about creating CA pools, see Creating CA pools.
For more information about the
gcloud privateca pools updatecommand, see gcloud privateca pools update.
The following issuance policy restrictions are supported and you can combine them as necessary to build a custom 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.
Example: Restrict a CA to issue only end-entity certificates with X.509 values for mutual TLS (mTLS).
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.
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.
identityConstraints: allowSubjectPassthrough: true allowSubjectAltNamesPassthrough: false celExpression: expression: 'subject.organization == "Joonix LLC" && subject.country_code in ["US", "UK"]'
celExpressionfield is optional. Use a Common Expression Language (CEL) expression to validate the resolved X.509 subject and/or 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.orgor ending in
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/webhpor starting with
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://joonix-trust-domain-1/ns/namespace1/sa/")) )'
Example: Allow only SANs having email addresses
firstname.lastname@example.org ending with
identityConstraints: allowSubjectPassthrough: false allowSubjectAltNamesPassthrough: true celExpression: expression: 'subject_alt_names.all(san, san.type == EMAIL && (san.value == "email@example.com" || san.value.endsWith("@google.org")) )'
Example: Allow only custom SANs having a specific OID and a custom value.
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
To restrict the lifetime of the issued certificates, you can use the maximum_lifetime field. If a certificate's requested lifetime is larger than the maximum lifetime, the certificate's lifetime is explicitly truncated.
To allow a maximum lifetime of 30 days, use the following
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 Requesting certificates.
Example: Allow only CSR issuance.
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.
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.
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.
- 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 policy controls.