Manage trust configs

This page describes how to create and manage trust configs for use in mutual TLS authentication (mTLS) scenarios.

For more information, see the following resources:

To learn more about trust configs, trust anchors, and intermediate certificates, see Trust configs in How Certificate Manager works.
To learn more about mTLS, see Mutual TLS authentication in the Cloud Load Balancing documentation.
To use a trust config to configure mTLS on your target proxy, see one of the following pages in the Cloud Load Balancing documentation:
- Set up mutual TLS with signed certificates
- Set up mutual TLS with a private CA

The gcloud instructions on this page assume that you are using Cloud Shell or another environment with bash installed. For more information about the gcloud commands used on this page, see the Certificate Manager CLI reference.

Create a trust config

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Editor (roles/certificatemanager.editor)
Certificate Manager Owner (roles/certificatemanager.owner)

For more information, see Roles and permissions.

To create a trust config, complete the following steps:

Console

In the Google Cloud console, go to the Certificate Manager page.

Go to Certificate Manager
On the Trust Configs tab, click Add Trust Config.
In the Name field, enter a name for the configuration.

The name must be unique for the project. Also, it must start with a lowercase letter, followed by up to 62 lowercase letters, numbers, or hyphens, and must not end with a hyphen.
Optional: In the Description field, enter a description for the configuration This description helps you identify a specific configuration later.
Optional: In the Labels field, specify labels to associate to the trust config. To add a label, click Add label, and specify a key and a value for your label.
For Location, select Global or Regional.

If you selected Regional, select the Region.
In the Trust store section, add trust anchors and intermediate CAs.

You can specify multiple trust anchors and intermediate certificates by using multiple instances of the complete PEM payload for the certificate, one certificate per instance.
1. In the Trust anchors section , click Add trust anchor and upload the PEM-encoded certificate file, or copy the contents of the certificate. When you have finished, click Add.
2. Optional: In the Intermediate CAs section, click Add intermediate CA and upload the PEM-encoded intermediate certificate file, or copy the contents of the intermediate certificate. When you have finished, click Add.
  
  This step lets you add another level of trust between the root certificate and your server certificate.
3. Optional: In the Allowlisted certificates section, click Add certificate and upload the PEM-encoded certificate file, or copy the contents of the certificate. This adds the certificate to an allowlist. When you have finished, click Add.
  
  A certificate that is added to an allowlist represents any certificate that can be encapsulated within the trust config so that it is always considered valid. To encapsulate multiple certificates on an allowlist within the trust config, use multiple instances of the pemCertificate field, one certificate per instance added to an allowlist. A certificate that is added to an allowlist is always considered valid as long as the certificate is parseable, proof of private key possession is established, and constraints on the SAN field of the certificate are met. Expired certificates are also considered valid when they are added to an allowlist. For more information about the PEM-encoded format, see RFC 7468.
Click Create.

Verify that the new trust config appears in the list of configurations.

gcloud

Create a trust config YAML file that specifies the trust config parameters.

The file has the following format:
```
trustStores:
- trustAnchors:
  - pemCertificate: "CERTIFICATE_PEM_PAYLOAD"
  intermediateCas:
  - pemCertificate: "INTER_CERT_PEM_PAYLOAD"
allowlistedCertificates:
- pemCertificate: "ALLOWLISTED_CERT1"
- pemCertificate: "ALLOWLISTED_CERT2"
```
Replace the following:
- CERTIFICATE_PEM_PAYLOAD: the complete PEM payload for the certificate to use for this trust config resource.
- INTER_CERT_PEM_PAYLOAD: the complete PEM payload for the intermediate certificate to use for this trust config resource. This value is optional.
- ALLOWLISTED_CERT1 and ALLOWLISTED_CERT2: the certificates that are added to an allowlist to use for this trust config resource. This value is optional.
You can specify multiple trust anchors and intermediate certificates by using multiple instances of the pemCertificate field, one certificate per instance, in their respective sections of the trust config resource specification.

A certificate that is added to an allowlist represents any certificate that can be encapsulated within the trust config so that it is always considered valid. To encapsulate multiple certificates on an allowlist within the trust config, use multiple instances of the pemCertificate field, one certificate per instance added to an allowlist. A certificate that is added to an allowlist is always considered valid as long as the certificate is parseable, proof of private key possession is established, and constraints on the SAN field of the certificate are met. Expired certificates are also considered valid when they are added to an allowlist. For more information about the PEM-encoded format, see RFC 7468.
To import the trust config YAML file, use the gcloud certificate-manager trust-configs import command:
```
gcloud certificate-manager trust-configs import TRUST_CONFIG_ID \
  --project=PROJECT_ID \
  --source=TRUST_CONFIG_FILE \
  --location=LOCATION
```
Replace the following:
- TRUST_CONFIG_ID: a unique ID that identifies this trust config resource.
- PROJECT_ID: the ID of the target Google Cloud project.
- TRUST_CONFIG_FILE: the full path and name of the trust config YAML file that you created in step 1.
- LOCATION: the region where the trust config resource is stored. The default location is global.

API

Make a POST request to the trustConfigs.create method:

POST /v1/projects/PROJECT_ID/locations/LOCATION/trustConfigs?trust_config_id=TRUST_CONFIG_ID
{
  "description": "DESCRIPTION",
  "trust_stores": {
    "trust_anchors": [{
      "pem_certificate": "CERTIFICATE_PEM_PAYLOAD"
    }],
    "intermediate_cas": [{
      "pem_certificate": "INTER_CERT_PEM_PAYLOAD"
    }],
  },
  "allowlistedCertificates": [{
    "pem_certificate": "ALLOWLISTED_CERT"
  }],
}

Replace the following:

PROJECT_ID: the ID of the target Google Cloud project.
LOCATION: the location attribute specifies the region where the trust config resource is stored. The default location is global.
TRUST_CONFIG_ID: a unique ID that identifies this trust config resource.
DESCRIPTION: a meaningful description for this trust config resource. This value is optional.
CERTIFICATE_PEM_PAYLOAD: the complete PEM payload for the certificate to use for this trust config resource..
INTER_CERT_PEM_PAYLOAD: the complete PEM payload for the intermediate certificate to use for this trust config resource. This value is optional.
ALLOWLISTED_CERT: the certificate that is added to an allowlist to use for this trust config resource. This value is optional.

Update a trust config

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Editor (roles/certificatemanager.editor)
Certificate Manager Owner (roles/certificatemanager.owner)

For more information, see Roles and permissions.

To update a trust config, complete the following steps:

Console

In the Google Cloud console, go to the Certificate Manager page.

Go to Certificate Manager
On the Trust Configs tab, locate and select the trust config you want to update.
In the More Options column, click the icon for the config you want to update, and select Edit.
Make the required changes.
Click Save.

Verify that the configuration changes are updated.

gcloud

Create an updated trust config YAML file that specifies the new trust config parameters. The file has the following format:
```
name: "TRUST_CONFIG_ID"
trustStores:
- trustAnchors:
  - pemCertificate: "CERTIFICATE_PEM_PAYLOAD"
  intermediateCas:
  - pemCertificate: "INTER_CERT_PEM_PAYLOAD"
allowlistedCertificates:
- pemCertificate: "ALLOWLISTED_CERT1"
- pemCertificate: "ALLOWLISTED_CERT2"
```
Replace the following:
- TRUST_CONFIG_ID: a unique ID that identifies this trust config resource.
- CERTIFICATE_PEM_PAYLOAD: the complete PEM payload for the certificate to use for this trust config resource..
- INTER_CERT_PEM_PAYLOAD: the complete PEM payload for the intermediate certificate to use for this trust config resource. This value is optional.
- ALLOWLISTED_CERT1 and ALLOWLISTED_CERT2: the certificates that are added to an allowlist to use for this trust config resource. This value is optional.
Import the new trust config file into Certificate Manager against the existing trust config resource name:

Use the gcloud certificate-manager trust-configs import command:
```
gcloud certificate-manager trust-configs import TRUST_CONFIG_ID \
  --project=PROJECT_ID \
  --source=TRUST_CONFIG_FILE \
  --location=LOCATION
```
Replace the following:
- TRUST_CONFIG_ID: the ID of the target trust config resource.
- PROJECT_ID: the ID of the target Google Cloud project.
- TRUST_CONFIG_FILE: the full path and name of the updated trust config file.
- LOCATION: the location attribute specifies the region where the trust config resource is stored. The default location is global.

API

Make a PATCH request to the trustConfigs.update method:

PATCH /v1/projects/PROJECT_ID/locations/LOCATION/trustConfigs/TRUST_CONFIG_ID?update_mask=*
  {
    "description": "DESCRIPTION",
    "trust_stores": {
      "trust_anchors": [{
        "pem_certificate": "CERTIFICATE_PEM_PAYLOAD"
      }],
      "intermediate_cas": [{
        "pem_certificate": "INTER_CERT_PEM_PAYLOAD"
      }],
    },
    "allowlistedCertificates": [{
      "pem_certificate": "ALLOWLISTED_CERT"
  }],
  }

Replace the following:

PROJECT_ID: the ID of the target Google Cloud project.
LOCATION: the location attribute specifies the region where the trust config resource is stored. The default location is global.
TRUST_CONFIG_ID: the ID of the target trust config resource.
DESCRIPTION: a meaningful description for this trust config resource. This description is optional.
CERTIFICATE_PEM_PAYLOAD: the complete PEM payload for the certificate to use for this trust config resource.
INTER_CERT_PEM_PAYLOAD: the complete PEM payload for the intermediate certificate to use for this trust config config resource. This value is optional.
ALLOWLISTED_CERT: the certificate that is added to an allowlist to use for this trust config resource. This value is optional.

List trust configs

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Viewer (roles/certificatemanager.viewer)
Certificate Manager Editor (roles/certificatemanager.editor)
Certificate Manager Owner (roles/certificatemanager.owner)

For more information, see Roles and permissions.

To list the configured trust configs, complete the following steps.

Console

In the Google Cloud console, go to the Certificate Manager page.

Go to Certificate Manager.
Click the Trust Configs tab.

The tab displays a list of configured trust config resources.

gcloud

Use the gcloud certificate-manager trust-configs list command:

gcloud certificate-manager trust-configs list \
    --filter="FILTER" \
    --page-size="PAGE_SIZE" \
    --limit="LIMIT" \
    --sort-by="SORT_BY" \
    --location=LOCATION

Replace the following:

FILTER: an expression that constrains the returned results to specific values.

For example, you can filter results by the following criteria:
- Labels and creation time: --filter='labels.key:value AND create_time > "2021-09-01T00:00:00Z"'
For more filtering examples that you can use with Certificate Manager, see Sorting and filtering list results in the Cloud Key Management Service documentation.
PAGE_SIZE: the number of results to return per page.
LIMIT: the maximum number of results to return.
SORT_BY: a comma-delimited list of name fields by which the returned results are sorted.

The default sort order is ascending. For descending sort order, prefix the chosen field with a tilde (~).
LOCATION: the location attribute specifies the region where the trust config resource is stored. The default location is global.

API

Make a GET request to the trustConfigs.list method:

GET /v1/projects/PROJECT_ID/locations/LOCATION/trustConfigs?filter=FILTER&pageSize=PAGE_SIZE&sortBy=SORT_BY

Replace the following:

PROJECT_ID: the ID of the target Google Cloud project.
FILTER: an expression that constrains the returned results to specific values.
PAGE_SIZE: the number of results to return per page.
SORT_BY: a comma-delimited list of field names by which the returned results are sorted.

The default sort order is ascending. For descending sort order, prefix the selected field with a tilde (~).
LOCATION: the location attribute specifies the region where the trust config resource is stored. The default location is global.

View trust configs

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Viewer (roles/certificatemanager.viewer)
Certificate Manager Editor (roles/certificatemanager.editor)
Certificate Manager Owner (roles/certificatemanager.owner)

For more information, see Roles and permissions.

To view a trust config, complete the following steps.

Console

In the Google Cloud console, go to the Certificate Manager page.

Go to Certificate Manager.
Click the Trust Configs tab. The tab displays a list of configured trust config resources.
Select the trust config resource to view its details.

The Trust Config details page displays detailed information about the selected trust config.

gcloud

Use the gcloud certificate-manager trust-configs describe command:

gcloud certificate-manager trust-configs describe TRUST_CONFIG_ID \
    --location=LOCATION

Replace the following:

TRUST_CONFIG_ID: the ID of the target trust config.
LOCATION: the region where the trust config resource is stored. The default location is global.

API

Make a GET request to the trustConfigs.get method:

GET /v1/projects/PROJECT_ID/locations/LOCATION/trustConfigs/TRUST_CONFIG_ID

Replace the following:

PROJECT_ID: the ID of the target Google Cloud project.
TRUST_CONFIG_ID: the ID of the target trust config.
LOCATION: the location attribute specifies the region where the trust config resource is stored. The default location is global.

Delete a trust config

To complete this task, you must have the Certificate Manager Owner role (roles/certificatemanager.owner) on the target Google Cloud project.

For more information, see Roles and permissions.

To delete a trust config, complete the following steps.

Console

In the Google Cloud console, go to the Certificate Manager page.

Go to Certificate Manager
On the Trust Configs tab, select the checkbox of the trust config that you want to delete.
Click Delete.
In the dialog that appears, click Delete to confirm.

gcloud

Use the gcloud certificate-manager trust-configs delete command:

gcloud certificate-manager trust-configs delete TRUST_CONFIG_ID \
    --location=LOCATION

Replace the following:

TRUST_CONFIG_ID: the ID of the target trust config.
LOCATION: the region where the trust config resource is stored. The default location is global.

API

Make a DELETE request to the trustConfigs.delete method:

DELETE /v1/projects/PROJECT_ID/locations/LOCATION/trustConfigs/TRUST_CONFIG_ID

Replace the following:

PROJECT_ID: the ID of the target Google Cloud project.
LOCATION: the region where the trust config resource is stored. The default location is global.
TRUST_CONFIG_ID: the ID of the target trust config.

Manage trust configs

Create a trust config

Console

gcloud

API

Update a trust config

Console

gcloud

API

List trust configs

Console

gcloud

API

View trust configs

Console

gcloud

API

Delete a trust config

Console

gcloud

API

What's next