Creating root certificate authorities

With IBM Cloud® Secrets Manager, you can build and manage your own public key infrastructure (PKI) system by creating root and intermediate certificate authorities (CA).

A certificate authority (CA) is the entity that signs and issues your SSL/TLS certificates. If you're looking for the ability to quickly generate a self-signed certificate, you can use Secrets Manager to create an internally signed root CA. You can use this CA as the trust anchor for a certificates chain. After you create a root CA for your instance, you can use it to sign a lower-level or subordinate CA, for example other intermediate CAs that you create in the service.

You can create up to 10 root certificate authorities per instance. To view a list of the configurations that are available for your instance, go to the Secrets engines > Private certificates page in the Secrets Manager UI.

Before you begin

Before you get started, be sure that you have the required level of access. To manage engine configurations for your instance, you need the Manager service role or higher.

Creating a root certificate authority in the UI

You can create an internally signed root certificate authority for your service instance by using the Secrets Manager UI.

In the console, click the Menu icon > Resource List.
From the list of services, select your instance of Secrets Manager.
In the Secrets engines page, click the Private certificates tab.
In the Certificate authorities table, click Create certificate authority to start the creation wizard.
Specify the certificate authority type and options.
1. Select Root certificate authority as the authority type.
2. Enter a name to easily identify your certificate authority.
3. Select a maximum time-to-live (TTL) for the certificate to be generated for this CA. The TTL determines how long the CA certificate remains valid.
4. Select the maximum number of subordinate or lower-level intermediate certificates that can exist in the chain.
5. To encode the issuing CA certificate URL into intermediate CA certificates, set the Encode URL option to Enabled.
Enter the subject name fields for your root CA certificate.
Select the Key management service. Choose the Secrets Manager service for creating the root certificate authority keys internally by the service, or choose Hyper Protect Crypto Services (HPCS). In case HPCS is selected perform the following tasks:
1. Select your HPCS instance from the instances dropdown list or enter your HPCS instance CRN manually
2. Select the IAM Credentials secret that was created earlier for authenticating with HPCS.
  
  Once the IAM credential has been set in the CA configuration it cannot be later replaced.
3. Select the HPCS private keystore from the keystores dropdown list, or enter the keystore ID manually.
4. Choose to use existing keys or generate new keys. In case selecting an existing HPCS private key or entering a private key ID manually, make sure that a public key exists and it has the same ID as the private key in the private keystore.
  
  In case you choose to generate new keys, those keys will not be deleted by Secrets Manager in case the configuration will be deleted.
Select the key algorithm that you want to use to generate the public and private key for your CA certificate.
Determine whether to enable certificate revocation list (CRL) building and distribution points for your CA certificate.

A CRL is a list of certificates that are revoked by the issuing certificate authority before their scheduled expiration date. A certificate that is listed as part of a CRL can no longer be trusted by applications.
1. To build a CRL for your root CA with each certificate request, set the CRL building option to Enabled.
2. To encode the URL of the revocation list in the root CA certificate, set the CRL distribution points option to Enabled.
3. Select a time-to-live (TTL) of the generated CRL. The TTL determines how long the CRL remains valid.
Review your selections. To create the root CA, click Create.

You can now select this root CA when you create an intermediate CA with internal signing. To modify or remove an existing configuration, click Actions menu in the row of the certificate authority that you want to update.

Creating a root certificate authority with the API

You can create an internally signed root certificate authority for your service instance by calling the Secrets Manager API.

The following example shows a query that you can use to create a root certificate authority.

curl -X POST 
  --H "Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  --H "Content-Type: application/json" \
  --d '{
  "config_type": "private_cert_configuration_root_ca",
  "name": "test-root-CA",
  "common_name": "example.com",
  "crl_disable": false,
  "crl_distribution_points_encoded": true,
  "issuing_certificates_urls_encoded": true,
  "max_ttl": "43830h"
}' \  
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations"

If you are bringing your own HSM, include the following in the request:

"crypto_key": {
    "label": "my_key",
    "allow_generate_key": true,
    "provider": {
      "type": "hyper_protect_crypto_services",
      "instance_crn": "replace_with_hpcs_crn::",
      "pin_iam_credentials_secret_id": "replace_with_iam_credentials_secret_guid",
      "private_keystore_id": "replace_with_keystore_id"
    }
  }

A successful response adds the configuration to your service instance.

{
  "common_name": "example.com",
  "config_type": "private_cert_configuration_root_ca",
  "created_at": "2022-06-27T11:58:15Z",
  "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21",
  "crl_disable": false,
  "crl_distribution_points_encoded": true,
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIGRjCCBS6gAwIBAgIUSKW6zI+E9JU4bva\n-----END CERTIFICATE-----",
    "expiration": 1825612535,
    "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIGRjCCBS6gAwIBAgIUSKW6zI+E9JU4bvad\n-----END CERTIFICATE-----",
    "serial_number": "48:a5:ba:cc:8f:84:f4:95:38:6e:f6:9d:9e:d7:8f:d8:43:d3:55:bd"
  },
  "exclude_cn_from_sans": false,
  "format": "pem",
  "issuing_certificates_urls_encoded": true,
  "max_path_length": -1,
  "max_ttl_seconds": 31536000,
  "name": "test-root-CA",
  "private_key_format": "der",
  "secret_type": "private_cert",
  "updated_at": "2022-10-05T21:33:11Z"
}

For more information about the required and optional request parameters, see Add a configuration.

Creating a root certificate authority from the CLI

You can create an internally signed root certificate authority for your service instance by using the ibmcloud secrets-manager configuration-create command.

The following example shows a command that you can use to create a root certificate authority.

ibmcloud secrets-manager configuration-create 
  --configuration-prototype='{
    "config_type": "private_cert_configuration_root_ca",
    "name": "example-root-CA", 
    "max_ttl": "43830h", 
    "crl_expiry": "72h", 
    "crl_disable": false, 
    "crl_distribution_points_encoded": true, 
    "issuing_certificates_urls_encoded": true, 
    "common_name": "example.com", 
    "alt_names": [
      "alt-name-1","alt-name-2"
      ], 
    "ip_sans": "127.0.0.1", 
    "uri_sans": "https://www.example.com/test", 
    "other_sans": ["1.2.3.5.4.3.201.10.4.3;utf8:test@example.com"], 
    "ttl": "2190h", 
    "format": "pem", 
    "private_key_format": "der", 
    "key_type": "rsa", 
    "key_bits": 4096, 
    "max_path_length": -1, 
    "exclude_cn_from_sans": false, 
    "permitted_dns_domains": ["exampleString"], 
    "ou": ["exampleString"], 
    "organization": ["exampleString"], 
    "country": ["exampleString"], 
    "locality": ["exampleString"], 
    "province": ["exampleString"], 
    "street_address": ["exampleString"], 
    "postal_code": ["exampleString"], 
    "serial_number": "d9:be:fe:35:ba:09:42:b5:35:ba:09:42:b5"
  }'

If you are bringing your own HSM, include the following in the command:

"crypto_key": {
    "label": "my_key",
    "allow_generate_key": true,
    "provider": {
      "type": "hyper_protect_crypto_services",
      "instance_crn": "replace_with_hpcs_crn::",
      "pin_iam_credentials_secret_id": "replace_with_iam_credentials_secret_guid",
      "private_keystore_id": "replace_with_keystore_id"
    }
  }

Creating a root certificate authority with Terraform

You can create an internally signed root certificate authority for your service instance by using Terraform for Secrets Manager.

The following example shows a configuration that you can use to create a root certificate authority.

    resource "ibm_sm_private_certificate_configuration_root_ca" "test_root_ca" {
        instance_id = local.instance_id
        region = local.region
        name = "test-root-ca"
        common_name = "root.example.com"
        max_ttl = "3650d"
        issuing_certificates_urls_encoded = true
    }

If you are bringing your own HSM, include the following in the configuration:

crypto_key {
    label = "my_key"
    allow_generate_key = true
    provider {
      type = "hyper_protect_crypto_services"
      instance_crn = "replace_with_hpcs_crn::"
      pin_iam_credentials_secret_id = "replace_with_iam_credentials_secret_guid"
      private_keystore_id = "replace_with_keystore_id"
    }
  }

Retrieving a root certificate authority in the UI

You can retrieve the root certificate authority value by using the Secrets Manager UI.

In the Public certificates secret engine, click the Actions menu to open a list of options for your engine configuration.
To view the configuration value, click View configurationt.
Click Confirm after you ensure that you are in a safe environment.

The secret value is displayed for 15 seconds, then the dialog closes.

Retrieving a root certificate authority using CLI

You can retrieve the root certificate authority value by using the Secrets Manager CLI. In the following example command, replace the engine configuration name with your configuration's name.

ibmcloud secrets-manager configuration --name EXAMPLE_CONFIG --service-url https://{instance_ID}.{region}.secrets-manager.appdomain.cloud

Replace {instance_ID} and {region} with the values that apply to your Secrets Manager service instance. To find the endpoint URL that is specific to your instance, you can copy it from the Endpoints page in the Secrets Manager UI. For more information, see Viewing your endpoint URLs

Retrieving a root certificate authority using API

You can retrieve the root certificate authority value by using the Secrets Manager API. In the following example request, replace the engine configuration name with your configuration's name.

curl -X GET --location --header "Authorization: Bearer {iam_token}" \
--header "Accept: application/json" \
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations/{name}"

A successful response returns the value of the engine configuration, along with other metadata. For more information about the required and optional request parameters, see Get a secret.

Next steps

Create an intermediate certificate authority