IBM Cloud Docs
Preparing to create private certificates

Preparing to create private certificates

You can enable your IBM Cloud® Secrets Manager service instance to generate private certificates by configuring the private certificates engine.

In Secrets Manager, the private certificates engine serves as the back end for the private_cert secret type. Private certificates are SSL/TLS certificates that you can sign, issue, and manage in the service. Before you can create a private certificate, you must enable your service instance by creating certificate authorities (CA)A trusted third-party organization or company that issues the digital certificates. The certificate authority typically verifies the identity of the individuals who are granted the unique certificate. and a valid chain of trust for your certificates.

Learning about certificate hierarchies

With Secrets Manager, you can build your own public-key infrastructure (PKI) system by creating certificate authorities (CA) that can sign and issue SSL/TLS certificates to your applications. With a certificates chain in place, you can use your Secrets Manager instance to create private certificates for your client and server apps.

A valid chain of certificates begins at a trusted root CA, passes through one or more subordinate CAs, and ends with a leaf certificate that is issued to your end-entity application. For example, check out the following simple CA hierarchy:

The diagram shows a three-level hierarchy of certificates that begins with a root certificate authority in the first level.
Figure 1. Example three-level CA hierarchy

  1. The root CA serves as the trust anchor for your entire chain of certificates.

  2. The subordinate CAs in level 2 are signed and issued by the root CA. These subordinate CAs sign other subordinate CA certificates.

  3. Finally, the subordinate CA certificates in level 3 sign and issue leaf certificates to your end-entity applications.

    In Secrets Manager, leaf certificates are the private certificates that you create and deploy to your applications.

Designing your CA hierarchy

With Secrets Manager, you can create up to 10 root CAs and 10 intermediate CAs in your service instance that contain multiple branches and hierarchies.

Table 1. Certificate authority options
Authority type Description
Root certificate authority A trust anchor for your certificates chain. In a hierarchy of certificates, a root CA is at the top of a certificates chain. This CA is used to sign the certificates of CAs that are subordinate to them, for example intermediate CAs.
Intermediate certificate authority A subordinate or lower-level certificate authority that signs and issues other intermediate CA certificates. An intermediate CA is also used to issue leaf certificates to end-entities, for example a client or server application. In Secrets Manager, you can create intermediate CAs that are signed internally or externally.

Planning the structure of a CA hierarchy

As a best practice, plan a hierarchy of certificate authorities that corresponds with the structure of your organization. Usually, you can implement one of the following common CA structures.

Two levels: Root CA and subordinate CA

Use this option if your workload requires the simplest CA structure. In this scenario, you create a single trusted root CA. Then, you create a subordinate CA, for example an intermediate CA, to issue leaf certificates to your apps and services.

The diagram shows a two-level hierarchy of certificates that begins with a root certificate authority in the first level.
Figure 2. Two-level certificate authority hierarchy

Three levels: Root CA and two subordinate CAs

Use this option if your workload requires an additional layer between the root CA and lower-level CA operations. In this scenario, the middle subordinate CA is used only to sign subordinate CAs that issue leaf certificates to your apps.

The diagram shows a three-level hierarchy of certificates that begins with a root certificate authority in the first level.
Figure 3. Three-level certificate authority hierarchy

Setting the depth of your CA hierarchy

When you're creating a certificate authority in Secrets Manager, you can set the Maximum path length parameter to determine how many CA certificates can exist in its authority chain. This value enforces how many CA certificates can exist in the certification path of your CA.

Generally, you can configure a root CA that doesn't limit the number of subordinate CAs that it can create in its certification path. However, defining a maximum path length on subordinate CAs is an important security step to avoid misconfigured CAs. Depending on the placement of a subordinate CA in your hierarchy, make sure to specify a maximum path length so that its signing authority power is limited to only the intended depth.

The diagram shows a four-level hierarchy of certificates that begins with a root certificate authority in the first level.
Figure 3. Three-level certificate authority hierarchy

The maximum path length that you define does not include leaf certificates. In the previous example, the subordinate CA in level 4 can issue leaf certificates but is unable to have more CA certificates in its path.

Choosing a validity period for your certificates

The validity period of an X.509 certificate is a required field that determines how long the certificate is trusted and remains valid. When you plan your CA hierarchy, work backwards from your preferred lifespan for the leaf certificates that you want to issue to your applications. Then, determine the validity period of the CA certificates.

A certificate must have a validity period that is shorter than or equal to the validity period for the CA that issued it. For example, if you create a root CA with a time-to-live (TTL) of 10 years, any intermediate CAs that are subordinate to it must have a TTL that is equal to or less than 10 years. Likewise, if an intermediate CA has TTL of 3 years, any leaf certificates must have a TTL that is equal to or less than 3 years.

  1. Choose a validity period for your leaf certificates that is appropriate for your use case.

    The private certificates that you can create with Secrets Manager are considered leaf certificates that can be issued to an end-entity, such as a client or server app. With Secrets Manager, you can create certificates with a maximum validity period of three years or 36 months. After you determine a TTL or validity period for leaf certificates, you set the value by using a certificate template so that your preferred TTL is applied each time a new leaf certificate is generated.

    The shorter the TTL of your leaf certificates, the more protected you are against inadvertent exposure or compromise of your certificate and its private key. A shorter validity period for your certificates means that you reduce the likelihood of compromise, but it also requires that you rotate the certificate more frequently to ensure that it stays valid. To avoid an inadvertent outage, you can schedule automatic rotation of your private certificates.

  2. Choose a validity period for the subordinate CA.

    As a best practice, set a validity period for a subordinate CA certificate that is significantly longer than the validity periods of the certificates that they issue. Define a validity period of a parent CA that is two to five times the period of any child CA certificate or leaf certificate that it issues. For example, if you have a two-level CA hierarchy and you want to issue leaf certificates with a TTL of one year, configure the subordinate issuing CA with a TTL of three years. You can always update subordinate CA certificates without replacing the root CA certificate.

  3. Choose a validity period for your root CA.

    When you update a root CA certificate, the change impacts your entire public-key infrastructure. To minimize impact, it is recommended that you set a long validity period for your root CA certificate. In Secrets Manager, the default TTL for root certificates is 10 years.

Choosing an algorithm for generating keys

Before you create a certificate authority in Secrets Manager, you must choose a key algorithm for generating the public and private keys for your CA. The public and private key-pair is used to authenticate an SSL/TLS connection. If you're not sure where to start, you can use the following suggested guide for selecting a key algorithm.

  1. Choose an algorithm family.

    The key algorithm that you select determines the encryption algorithm and key size to use to generate keys and sign certificates. As a best practice, use the same algorithm family for all certificates that belong to a certificate chain. Secrets Manager supports the following families of algorithms.

    Table 2. Supported algorithm families and key sizes
    Algorithm family Description Supported key sizes
    RSA Widely used and compatible with most browsers and servers, RSA is the industry standard for public-key cryptography. 2048 bits
    4096 bits
    Elliptic curve (EC) Generates stronger keys and smaller certificates. For example, a 256-bit EC key is equivalent in encryption strength to a 3072-bit RSA key. 224 bits
    256 bits
    384 bits
    521 bits

  2. Choose a key size.

    The key size or length that you select determines the encryption strength. The larger the key size for an algorithm family, the more difficult it is to break. Keep in mind that longer key lengths results in more data to store and transmit, which can impact the performance of your certificate. As a best practice, choose a key size that is appropriate for the TTL or validity period of your certificate.

    For longer living certificates, it is recommended to use longer key lengths to provide more encryption protection.

Using certificate authority unauthenticated endpoints

If you're using leaf certificates that are issued by a CA in Secrets Manager for your applications, use the following API calls to gain access to the issuing CA Certificate Revocation List (CRL) and CA certificate.

Read Certificate Revocation List

Wit this endpoint, you can retrieve the current CRL in raw DER-encoded form. If /pem is added to the endpoint, the CRL is returned in PEM format.

GET v1/ibmcloud/private_cert/config/certificate_authorities/:ca-name/crl(/pem)

Response 200 OK
<binary DER-encoded CRL>

To validate that your leaf or intermediate CA certificates are not revoked from the context of a leaf certificate, you can configure your CA with the property "crl_distribution_points_encoded": true. This configuration encodes the URL that is used for downloading the issuing CA CRL in the property such as X509v3 CRL Distribution Points in each leaf or intermediate CA certificate. Then, your CA validator can check whether the leaf or intermediate CA certificates are revoked.

Read CA certificate

With this endpoint, you can retrieve the CA certificate in raw DER-encoded form. If /pem is added to the endpoint, the CA certificate is returned in PEM format.

GET v1/ibmcloud/private_cert/config/certificate_authorities/:ca-name/ca(/pem)

Response 200 OK
<binary DER-encoded certificate >

Read CA certificate chain

You can retrieve with this endpoint the CA certificate chain, which includes the CA in PEM format. This endpoint is bare. It doesn't return a standard Vault data structure and the Vault CLI can't read it.

GET v1/ibmcloud/private_cert/config/certificate_authorities/:ca-name/ca_chain

Response 200 OK
<PEM-encoded certificate chain>

To verify that the CA chain is from the context of a leaf certificate, you can configure your CAs in Secrets Manager with the property "issuing_certificates_urls_encoded": true. In each leaf or intermediate CA certificate, this configuration encodes the URL that is used for downloading the issuing CA certificate in the property Authority Information Access/CA Issuers. Then, your CA validator can validate each CA certificate.

Next steps

Now you're ready to create certificate authorities for your instance.