Using a certificate issuance policy

This topic describes how to use a certificate issuance policy on 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 Certificate issuance policies.

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.

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.

• Create a CA pool by using the instructions in the quickstart.

Add a certificate issuance policy file

To add a certificate issuance policy to an existing CA pool, do the following:

Console

1. Go to the Certificate Authority Service page in the Google Cloud console.

   Go to Certificate Authority Service

2. On the CA pool manager page, click the name of the CA pool for which you want to add a certificate issuance policy.

3. On the CA pool page, click Edit.

Configure identity constraints

To configure constraints on the subject and SANs in the certificates that the CA pool issues, do the following:

1. Optional: To disallow subject in certificate requests from being passed through, click the toggle.
2. Optional: To disallow subject alternative names in certificate requests from being passed through, click the toggle.
3. Optional: Add a Common Expression Language (CEL) expression to place restrictions on certificate subjects. For more information, see Using CEL.
4. Click Next.

Configure extension constraints

To 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:

1. Optional: Click the Known certificate extensions field, and clear the unrequired extensions from the menu.
2. 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.

Configure baseline values

To configure baseline values in the certificates issued from the CA pool, do the following:

1. Click the toggle.
2. Click Configure baseline values.

Define base key usage

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:

1. Optional: In the window that appears, click the toggle, if you want to specify base key usages for the certificates.
2. Select the checkboxes for the ways in which you want a key to be used.

3. Click Next.

Define extended key usage

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:

1. Optional: To specify the extended key usages for the certificates that the CA pool issues, click the toggle.
2. Select the checkboxes for the extended key usage scenarios.
3. Click Next.

Define policy identifiers

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:

1. Optional: Add the policy identifier in the Policy identifiers field.
2. Click Next.

Add Authority information access (AIA) OCSP servers

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.

1. Optional: Click Add item.
2. In the Server URL field, add the URL of the OCSP server.
3. Click Done.
4. Click Next.

Configure additional extensions

To configure additional custom extensions to include in the certificates issued by the CA pool, do the following. The following procedure is optional.

1. Click Add item.
2. In the Object identifier field, add a valid object identifier that is formatted as dot-separated digits.
3. In the Value field, add the base64-encoded value for the identifier.
4. If the extension is critical, select Extension is critical.

To save all the baseline value configurations, click Done.

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.

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

For more information, see Creating CA pools.

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:

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

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/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://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 [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 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.

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: 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 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, 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.