Creating Total TLS

Total TLS allows CIS to issue individual certificates for your proxied hostnames. These certificates protect the proxied hostnames not covered by Universal certificates.

Total TLS certificates follow the Common Name (CN) restriction of 64 characters (RFC 5280). If you have a hostname that exceeds this length, you can create an Advanced Certificate through API to cover it.

The issued certificates have a type of Advanced - Total TLS, and their default validity period is 90 days.

Getting the Total TLS for CLI

To get the Total TLS, run the following command:

cis total-tls cert-get DNS_DOMAIN_ID [-i, --instance INSTANCE] [--output FORMAT]

Command options

DNS_DOMAIN_ID: The ID of DNS domain.
-i, --instance: Instance name or ID. If not set, the context instance specified by cis instance-set INSTANCE is used.
--output: Specify output format, only JSON is supported.

Updating the Total TLS with CLI

To update the Total TLS, run the following command:

cis total-tls cert-update DNS_DOMAIN_ID [-c, --certificate_authority CERTIFICATE_AUTHORITY] (--enabled true|false) [-i, --instance INSTANCE] [--output FORMAT]

You can also update a custom rule by providing a JSON file or a JSON string directly:

cis total-tls cert-update DNS_DOMAIN_ID (--json @JSON_FILE | JSON_STRING) [-i, --instance INSTANCE] [--output FORMAT]

Command options

DNS_DOMAIN_ID

The ID of the DNS domain.

--enabled

Enable or disable Total TLS setting for a zone. Valid values are true and false.

-c, --certificate_authority

The certificate authority. Valid values are google, lets_encrypt, and ssl_com.

--json value

The JSON file or JSON string that is used to set Total TLS Settings or disable the feature for a zone.

The required fields in JSON data are enabled.

enabled: Enable or disable Total TLS setting for a zone. Valid values are true and false.
The optional fields are certificate_authority.

certificate_authority: The certificate authority. Valid values are google, lets_encrypt, and ssl_com.

Sample JSON data:

{
  "certificate_authority": "lets_encrypt",
  "enabled": true
}

-i, --instance value: Instance name or ID. If not set, the context instance specified by cis instance-set INSTANCE is used.
--output value: Specify output format, only JSON is supported.

Getting the Total TLS with the API

Follow these steps to get the Total TLS:

Set up your API environment with the correct variables.
Store the following values in variables to be used in the API command:

CRN: The full URL-encoded Cloud Resource Name (CRN) of the service instance.

ZONE_ID: The domain ID.

When all variables are initiated, get the Total TLS:

curl --request GET \
  --url https://api.cis.cloud.ibm.com/v1/{CRN}/zones/{ZONE_ID}/acm/total_tls \
  --header 'Content-Type: application/json' \
  --header 'X-AUTH-USER-TOKEN: REDACTED'

Changing the Total TLS with API

Follow these steps to create the Total TLS:

Set up your API environment with the correct variables.
Store the following values in variables to be used in the API command:

CRN: The full URL-encoded Cloud Resource Name (CRN) of the service instance.

ZONE_ID: The domain ID.

When all variables are initiated, create the Total TLS:

curl --request POST \
  --url https://api.cis.cloud.ibm.com/v1/{CRN}/zones/{ZONE_ID}/acm/total_tls \
  --header 'Content-Type: application/json' \
  --header 'X-AUTH-USER-TOKEN: REDACTED' \
  --data '{
      "enabled": true,
      "certificate_authority": "google"
  }'

To enable Total TLS with the API, send a POST request with the enabled parameter set to either true or false. You can also specify a certificate authority by providing a value for the certificate_authority parameter.

Limitations

Total TLS has the following limitations:

Total TLS doesn't issue certificates for any hostnames that are used with:
- Global load balancers
- Range applications
Total TLS is not supported for partial CNAME setup.

You can use other types of certificates or manually order advanced certificates for these hostnames.

Deleting certificates

After Total TLS is enabled, be cautious when deleting Total TLS-managed certificates associated with proxied hostnames. Doing so signals that the hostname should be excluded from future Total TLS issuance. The system will not automatically provision new certificates for that hostname, even if its DNS record is deleted and re-created later.