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:

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:
- 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 allowlisted certificate 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.
  
  An allowlisted certificate represents any certificate that can be encapsulated within the trust config so that they are always considered as valid. You can specify multiple allowlisted certificates by using multiple instances of the pemCertificate field, one certificate per instance to the trust config. You don't need a trust store while using allowlisted certificates. An allowlisted certificate 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 allowlisted.
Import the trust config file into Certificate Manager:
gcloud
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 allowlisted certificate 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:

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_CERT1: the allowlisted certificate 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
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 allowlisted certificate 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.

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

gcloud

API

Update a trust config

gcloud

API

List trust configs

Console

gcloud

API

View trust configs

Console

gcloud

API

Delete a trust config

gcloud

API

What's next