Manage trust configs

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

For more information about mTLS, see the following resources:

To understand the concepts of trust configs, trust anchors, and intermediate certificates, see Trust configs.
To learn more about mTLS, see Mutual TLS overview in the Cloud Load Balancing documentation.
To use a trust config to configure mTLS on your target proxy, see the following pages in the Cloud Load Balancing documentation:
- Set up mutual TLS with user-provided certificates
- Set up mutual TLS with a private CA

Create a trust config

When you create a trust config, you must specify the trust anchors that are used to validate the certificate.

Roles required for this task

To perform this task, you must have one of the following IAM roles on the target Google Cloud project.

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

For more information, see Roles and permissions.

Note: If you aren't assigned the required roles, contact the IAM Administrator who has the Project IAM Admin role (roles/resourcemanager.projectIamAdmin) to grant you the missing roles.

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.
To specify multiple trust anchors or intermediate certificates within the trust config resource specification, use multiple instances of the pemCertificate field. Each instance of the field contains a single certificate.

The trust config always considers a certificate on an allowlist as valid. To encapsulate multiple certificates on an allowlist, use multiple instances of the pemCertificate field, one certificate per instance. You don't need a trust store when using certificates added to an allowlist.

The trust config always considers a certificate on an allowlist valid if it fulfills specific conditions: it must be parseable, possess proof of private key ownership, and adhere to constraints on the certificate's SAN field. 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:
```
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: the ID of the trust config resource.
- CERTIFICATE_PEM_PAYLOAD: the complete PEM payload for the certificate to use for the trust config resource.
- INTER_CERT_PEM_PAYLOAD: the complete PEM payload for the intermediate certificate to use for the trust config resource.
- ALLOWLISTED_CERT1 and ALLOWLISTED_CERT2: the certificates that are added to an allowlist to use for this trust config resource.
To specify multiple trust anchors or intermediate certificates within the trust config resource specification, use multiple instances of the pemCertificate field. Each instance of the field contains a single certificate.

The trust config always considers a certificate on an allowlist as valid. To encapsulate multiple certificates on an allowlist, use multiple instances of the pemCertificate field, one certificate per instance. You don't need a trust store when using certificates added to an allowlist.

The trust config always considers a certificate on an allowlist valid if it fulfills specific conditions: it must be parseable, possess proof of private key ownership, and adhere to constraints on the certificate's SAN field. 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: the ID of the trust config resource.
- PROJECT_ID: the ID of the 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 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 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 the trust config resource.
INTER_CERT_PEM_PAYLOAD: the complete PEM payload for the intermediate certificate to use for the 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 update a trust config, you create another trust config YAML file that specifies the new trust config parameters and import this file into Certificate Manager.

Roles required for this task

To perform this task, you must have one of the following IAM roles on the target Google Cloud project.

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

For more information, see Roles and permissions.

Note: If you aren't assigned the required roles, contact the IAM Administrator who has the Project IAM Admin role (roles/resourcemanager.projectIamAdmin) to grant you the missing roles.

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 More actions for the config you want to update, and select Edit.
Make the required changes.
Click Save.

Verify that the configuration changes are updated.

gcloud

Export the trust config YAML file.
```
gcloud certificate-manager trust-configs export TRUST_CONFIG_ID \
    --project=PROJECT_ID \
    --destination=TRUST_CONFIG_FILE \
    --location=LOCATION
```
Replace the following:
- TRUST_CONFIG_ID: the ID of the trust config resource.
- PROJECT_ID: the ID of the Google Cloud project.
- TRUST_CONFIG_FILE: the full path and name of the trust config YAML file.
- LOCATION: the region where the trust config resource is stored. The default location is global.
Edit the trust config YAML file.

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: the ID of the trust config resource.
- CERTIFICATE_PEM_PAYLOAD: the complete PEM payload for the certificate to use for the trust config resource.
- INTER_CERT_PEM_PAYLOAD: the complete PEM payload for the intermediate certificate to use for the 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.
```
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 trust config resource.
- PROJECT_ID: the ID of the Google Cloud project.
- TRUST_CONFIG_FILE: the full path and name of the trust config YAML file.
- LOCATION: 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 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 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 the trust config resource.
INTER_CERT_PEM_PAYLOAD: the complete PEM payload for the intermediate certificate to use for the 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.

List trust configs

You can see all configured trust configs of your project.

Roles required for this task

To perform this task, you must have one of the following IAM roles on the target Google Cloud project.

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

For more information, see Roles and permissions.

Note: If you aren't assigned the required roles, contact the IAM Administrator who has the Project IAM Admin role (roles/resourcemanager.projectIamAdmin) to grant you the missing roles.

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, to filter results by the labels and creation time, you can specify: --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 field with a tilde (~).
LOCATION: the region where the trust config resource is stored. The default location is global. To see all trust configs across all locations, specify a single hyphen (-).

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 Google Cloud project.
LOCATION: the region where the trust config resource is stored. To see all trust configs across all locations, specify a single hyphen (-).
FILTER: an expression that constrains the returned results to specific values.

For example, to filter results by the labels and creation time, you can specify: --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.
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 field with a tilde (~).

View trust configs

You can see details of a specific trust config.

Roles required for this task

To perform this task, you must have one of the following IAM roles on the target Google Cloud project.

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

For more information, see Roles and permissions.

Note: If you aren't assigned the required roles, contact the IAM Administrator who has the Project IAM Admin role (roles/resourcemanager.projectIamAdmin) to grant you the missing roles.

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 trust config resource.
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 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 trust config resource.

Delete a trust config

Before deleting a trust config, detach the trust config from the Client Authentication (ServerTlsPolicy) resource.

Roles required for this task

To perform this task, you must have one of the following IAM roles on the target Google Cloud project.

Certificate Manager Owner role (roles/certificatemanager.owner)

For more information, see Roles and permissions.

Note: If you aren't assigned the required roles, contact the IAM Administrator who has the Project IAM Admin role (roles/resourcemanager.projectIamAdmin) to grant you the missing roles.

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 trust config resource.
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 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 trust config resource.

Manage trust configs

Create a trust config

Roles required for this task

Console

gcloud

API

Update a trust config

Roles required for this task

Console

gcloud

API

List trust configs

Roles required for this task

Console

gcloud

API

View trust configs

Roles required for this task

Console

gcloud

API

Delete a trust config

Roles required for this task

Console

gcloud

API

What's next