Using a certificate issuance policy

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.

Caution: The issuance policy changes are effective immediately. Before using the issuance policy in production, we recommend that you try out the policy changes on a test CA pool instance.

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.

1. Create a file policy.yaml with the following content:

   policy.yaml

   identityConstraints:
     allowSubjectPassthrough: true
     allowSubjectAltNamesPassthrough: true
   

   Where:

   • The allowSubjectPassthrough field is required. If the allowSubjectPassthrough field 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 allowSubjectAltNamesPassthrough field is set to true, the SubjectAltNames extension is copied from a certificate request into the signed certificate. Otherwise, the requested SubjectAltNames is discarded.

2. To create a CA pool with the certificate issuance policy file created in the previous step, use the following gcloud command:

   gcloud

   gcloud privateca pools update POOL_NAME \
     --issuance-policy policy.yaml
   

   Where:

   • policy.yaml is 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 update command, see gcloud privateca pools update.

Supported restrictions

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:

• Key Usage
• CA Options
• AIA OCSP Servers
• Additional X.509 Extensions

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

  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 == "Joonix 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/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.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 with spiffe://joonix-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://joonix-trust-domain-1/ns/namespace1/sa/")) )'
  

• Example: Allow only SANs having email addresses [e-mail] or ending with @google.org.

  policy.yaml

  identityConstraints:
    allowSubjectPassthrough: false
    allowSubjectAltNamesPassthrough: true
    celExpression:
      expression: 'subject_alt_names.all(san, san.type == EMAIL && (san.value == "[e-mail]" || 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

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.

Note: A certificate can never outlive its issuing CA. If a certificate request mentions a lifetime that exceeds the CA's not_after_time date, its lifetime is truncated to match the CA's not_after_time date. The certificate's lifetime is truncated even if the certificate issuance policy allows a longer lifetime.

Example

To allow a maximum lifetime of 30 days, use the following policy.yaml file:

policy.yaml

maximumLifetime: 30d

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.

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.

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