Add certificate issuance policies

Adding certificate issuance policies in CA Service involves defining rules and restrictions that govern the types of certificates issued by a certificate authority (CA). To learn more about certificate issuance policies, see About certificate issuance policies.

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.

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.

You can add a certificate issuance policy to a CA pool while creating a CA pool or when updating an existing CA pool.

Use one of the following methods:

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.

Define base key usage

This setting refers to the Key Usage field within a digital certificate. It specifies how the certificate's private key can be used, such as for key encipherment, data encipherment, certificate signing, and CRL signing. For more information, see Key usage.

1. To select the base key usages, click the Specify base key usages for certificates issued from this CA pool toggle, and then select from the options listed.
2. Click Next.

Define extended key usage

This setting refers to the Extended Key Usage (EKU) field in a digital certificate. It provides more specific and refined restrictions on how the key can be used, such as for server authentication, client authentication, code signing, and email protection. For more information, see Extended key usage.

Extended key usages are defined using object identifiers (OIDs). If you don't configure the extended key usages, all key usage scenarios are allowed.

1. To select the extended key usages, click the Write extended key usages for certificates issued from this CA pool toggle, and then select from the options listed.
2. 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. 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:

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

CA options

The CA options field within a certificate template defines how the resulting certificate can be used in a certificate authority (CA) hierarchy. CA options determine if a certificate can be used to sign other certificates and, if so, the restrictions on the certificates it issues.

Choose from the following options:

1. Include the configs to describe the CA X.509 extensions: Specify the settings within a certificate template that control the X.509 extensions.

2. Restrict issued certificates to be used only for CAs: This option appears only if you select the checkbox mentioned in the previous step. This boolean value indicates whether the certificate is a CA certificate. If set to true, the certificate can be used to sign other certificates. If false, the certificate is an end-entity certificate and cannot sign other certificates. If you click this toggle, you are further prompted to define name constraints for the extension in CA certificates.

3. Include the configs to describe the path length restriction X.509 extensions: Specify the settings that control how long a chain of certificates can be, stemming from a particular certificate. If the max issuer path length is set to 0, then the CA can only issue end-entity certificates. If it's set to 1, then the chain beneath this CA certificate can include only one subordinate CA. If a value isn't declared, then the number of subordinate CAs in the chain beneath this CA is unbounded.

4. Click Next.

Configure additional extensions

To configure additional custom extensions to include in the certificates issued by the CA pool, do the following:

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 --location LOCATION --issuance-policy FILE_PATH
   

   Replace the following:

   • POOL_NAME: the name of the CA pool.
   • LOCATION: the location of the CA pool. For the complete list of locations, see Locations.
   • 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:

• 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)][4]{: .external} 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 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 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.