Certificate Renewal

CORE certificates are used for mutual validation of appliances that are establishing SSLSecure Sockets Layer - a cryptographic protocol that provides communications security over a computer network.-based Client-Server and Server-Server connections. In addition, they carry information required for the CORE server or client access authorization. The certificates are generated for a limited time and are signed by the CORE Root CA certificate.

The certificate renewal does not simply extend its validity but creates a new certificate based on the new key material. The latter fact has a CORE-wide impact when the renewed certificate is the CORE Root CA certificate. This chapter specifies the certificate renewal procedures and best practices.

CORE Certificates

CORE appliance certificates:

CORE server certificate is created during the server bootstrap or when a server is added to the cluster.

CORE client identity certificate is created by the CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate request during the client's registration or when a client certificate is created by the EP server.

 

CORE CA certificates

CORE certificates are validated using CORE Root CA certificate. It is a self-signed certificate that is initially created during the bootstrap of EP. It is replaced by the next Root CA certificate (self-signed by the next Root CA key) towards its expiration. See the Root CA Renewal Overview.

 

CORE Trust Stores

CORE server - the root_ca.ks file in the CORE Server Certificates Folder.

CORE client - the server-ca.p7b file in the CORE Client Certificates Folder.

 

The trust stores are updated during the Root CA transition period. See Root CA Renewal Overview.

Certificate's Validity and Alerts

A certificate is valid for the specified period. The default validity duration is as follows:

• CORE Root CA certificate: 8 yearsFor any time interval setting in years, 1 year is converted to 365 days.
• CORE server certificate: 2 yearsFor any time interval setting in years, 1 year is converted to 365 days.
• CORE client certificate: 3 yearsFor any time interval setting in years, 1 year is converted to 365 days.

To change the default values, refer to the system settings (see CORE PKI settings). To apply a new setting to an already created certificate, renew the certificate (see Appliance Certificate Renewal).

Admins of the CORE clients and servers are alerted to renew their certificates before they expire. CORE system settings control the alert timing relative to the expiration date.

Appliance Certificate Renewal

To renew the CORE appliance's identity certificate, use the following:

• CORE client. Run the ucl renew command from the client.
• CORE server. Run the ekm_renew_server_certificate from the server.

The certificate renewal on a CORE appliance results in the following:

• Creation of a new private-public key pair.
• CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate request to EP. (EP signs it using the current Root CA certificate).
• Replacement of the old certificate.
• Replacement of the trust store with (p7b) with the latest trust store from EP.

Root CA Renewal Overview

Issue: If the Root CA certificate is replaced by the new certificate, then it will error certificates of all clients that are certified by the previous Root CA certificate. Not applicable to validate certificates of all clients and servers that identify themselves using certificates signed by the previous Root CA.

Solution: A gradual transition from the old certificate to the new one. The lifecycle of the next Root CA certificate is divided into three periods that partially overlap with the lifecycle of the current Root CA and the one that will follow it (the next-next certificate):

1. On-ramp period starts by generating the next Root CA key and certificate. During this period:
   1. CORE servers and clients gradually update their trust stores with the next Root CA certificate. They can do it:
      • directly - by using the dedicated command.
      • indirectly by renewing their certificates or registering as new clients.
   2. The EP keeps using the current Root CA key to sign CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate requests.
2. Activity period starts by endorsing the next Root CA key as the Root CA key. During this period:
   1. The next Root CA key signs all new and renewed certificates. In particular, it signs the renewed EP certificate.
   2. SOs of partitions are alerted about clients that have not yet updated their CORE trust stores.
   3. The previous Root CA certificate remains valid (not expired) for a period allowing validation of certificates signed by it (at least 3 yearsFor any time interval setting in years, 1 year is converted to 365 days, based on the default client certificate validity period).
   4. At some point, the new next Root CA key goes on-ramp. Its certificate starts being added to the trust store of CORE appliances - see #1a above.
      
3. Off-ramp period starts when a new next Root CA key takes over and enters its activity period.
   1. Regarding our Root CA certificate - see #2c above.

Root CA Renewal Quickstart

The following chart provides an example of the Root CA certificate rotation plan. We assume the following:

•  The longest duration of the CORE appliance certificate is 3 yearsFor any time interval setting in years, 1 year is converted to 365 days.

To calculate the date of the next certificate's on-ramp, we consider the following:

• Since the longest certificate duration is 3 yearsFor any time interval setting in years, 1 year is converted to 365 days, the signing Root CA must hand over its signing privilege to the next Root CA at least 3 yearsFor any time interval setting in years, 1 year is converted to 365 days before the signing Root CA expires.
• To allow for the gradual addition of the next Root CA certificate to the trust stores of all clients, we on-ramp it long before it becomes the signing Root CA (for example, 2 yearsFor any time interval setting in years, 1 year is converted to 365 days earlier).

The On-ramp Period

Start this period 3 yearsFor any time interval setting in years, 1 year is converted to 365 days and N-months before the expiration of the current Root CA certificate.

Note
The N-months period is required to update trust stores of all CORE appliances with the next Root CA certificate.

1. Select an EP and its Partner. On both servers;
   1. Stop the EKMEnterprise Key Management - previous name of the product. Service.
   2. Run the ekm_root_ca_prepare_next script.
      
   3. Start the EKMEnterprise Key Management - previous name of the product. Service.
2. Run the ucl list -p root command on EP.

   It shows the next-root-ca-key and the next root-ca-key-certificate in addition to the current root-ca-key and the root-ca-key-certificate.

   Run the ucl list -p root command on another EP.
   If it doesn't show the new keys:

   Run ekm_sync_key for these keys from the updated EP to all other EPs.

   For example: on the EP server from step #1 run:

   ekm_sync_key.sh --uid <next-root-ca-key> --partition root --target EP2
   ekm_sync_key.sh --uid <next root-ca-key-certificate> --partition root --target EP2

3. On all CORE servers (including the above EP and Partner) - update their CORE trust stores by running the ekm_root_ca_trust_next script.
4. On each CORE client (including the embedded client on EP), delete the current trust store and obtain the updated one:
   • Windows:

     del C:\ProgramData\Dyadic\ekm\server-ca.p7b
     ucl root_ca

   • Linux:

     sudo rm /etc/ekm/server-ca.p7b
     sudo ucl root_ca

Optionally, to review the content of the updated trust store, use OpenSSL:

openssl pkcs7 -print -text -inform der -noout -in /etc/ekm/server-ca.p7b

The output shows certificates in the store. Each certificate specifies its issuer: issuer: CN=Unbound UKC Root CA G<n>. The G<n> in the above indicates the generation of the Root CA certificate, starting with G1.

The Activity Period

Start this period at least 3 yearsFor any time interval setting in years, 1 year is converted to 365 days before the expiration of the current Root CA certificate.

At this point, trust stores of all appliances should include the next Root CA certificate. It becomes critical once the EP renews its certificate. In such a case, the certificate of EP becomes signed by the new Root CA key. For a client to validate this signature it must have the new Root CA certificate.

To endorse the next-root-ca-key as the key that signs CORE CSRs and certificate renewal, run ekm_root_ca_move_next on the EP server. The change of the Root CA certificates is indicated as follows:

• In the key material list of the Root partition (ucl list -p root): 
  • the name of current Root CA receives -G<N> appendix, for example: "root-ca-certificate-G1" and "root-ca-key-G1".
  • the "next-root-ca-<key | certificate>" becomes the current Root CA key and certificate.
• In UI of each partition:

The Client Trust Store Alert will appear if there are clients with outdated trust stores. Such clients are highlighted in the partition's clients list.

The Off-ramp Period

This period starts when the next-next Root CA certificate is activated by its ekm_root_ca_move_next script.

Root CA Pre-Expiration Time Frame

CORE has a dedicated setting that controls how many days before the Root CA expiration the system provides an alert. The default value is 180 days. The setting is referred to as:

root-ca-pre-expiry OR x-DY_ROOT_CA_CERTIFICATE_PRE_EXPIRY

Note
If you are checking the pre-expiration value for the server certificates (e.g., for an Entry Point), it is controlled by the server-pre-expiry OR x-DY_SERVER_CERTIFICATE_PRE_EXPIRY setting. See Other System Certificates for more information.

This setting can be managed by the Root SOSecurity officer - UKC partition administrator role. by any of the following methods.

Method 1: Command line - UCL

Retrieve the expiration time:

ucl system-settings get -k x-DY_ROOT_CA_CERTIFICATE_PRE_EXPIRY

Set the expiration time:

ucl system-settings set -k x-DY_ROOT_CA_CERTIFICATE_PRE_EXPIRY -v [PRE_EXPIRY_DAYS]

Method 2: REST API

Retrieve the expiration time:

curl --location --request GET 'https://<EP>/api/v1/system/settings' \
--header 'Authorization: Basic c29Acm9vdDpQYXNzd29yZDEh' \
--header 'Cookie: JSESSIONID=59367E1E71FF5008295C3306E0554AC0'

Set the expiration time:

curl --location --request PUT 'https://<EP>/api/v1/system/settings/root-ca-pre-expiry' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic c29Acm9vdDpQYXNzd29yZDEh' \
--header 'Cookie: JSESSIONID=59367E1E71FF5008295C3306E0554AC0' \
--data-raw '[PRE_EXPIRY_DAYS]'

Method 3: User Interface

1. Select the Config menu option.

2. Click the System Settings tab.

3. Set the expiration time.

Root CA Expiration Validation

The following methods are available to verify if the Root CA is about to expire. It is recommended to start the renewal process at least 6 months before the expiration date.

Method 1: Command line - UCL

Get the Root CA Certificate information with the ucl show command. The return value of Not After is the expiration date of the certificate.

ucl show --name root-ca-certificate -p root

Response:

Validity
Not Before: Jul 27 16:58:53 2021 GMT
Not After : Jul 27 16:58:53 2029 GMT

Method 2: REST API

Get the Root CA Certificate information with a RESTRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. API call.

curl --location --request GET 'https://<EP>/api/v1/system/certificates/root_ca?detailed=false' \
--header 'Authorization: Basic c29Acm9vdDpQYXNzd29yZDEh' \
--header 'Cookie: JSESSIONID=59367E1E71FF5008295C3306E0554AC0'

The certificate expiration date is shown in the validUntil value. If the current date is close to the expiration date (as defined in the section above, with the value of root-ca-pre-expiry), the response contains "alertLevel": "WARN".

For example:

{
"id": "root_ca",
"role": "ROOT_CA",
"subject": "CN=Unbound UKC Root CA G1",
"validUntil": "2023-02-27T16:58:53Z",
"alertLevel": "WARN"
}

You can use the following API to get detailed information about the expiration date when the alertLevel is WARN.

curl --location --request GET 'https://<EP>/api/v1/system/certificates/root_ca/alerts' \
--header 'Authorization: Basic c29Acm9vdDpQYXNzd29yZDEh' \
--header 'Cookie: JSESSIONID=59367E1E71FF5008295C3306E0554AC0'

The following is a sample response:

[
{
"alertType": "CERT_ABOUT_TO_EXPIRE",
"alertLevel": "WARN",
"title": "Root CA certificate expires in 1 years, 10 months, 2 weeks, 3 days"
}
]

Method 3: User Interface

If the Root CA certificate is about to expire, an alert is shown in the Config menu.

Other System Certificates

The above process can be applied for all other system certificates, such as:

1. Entry Point certificates

2. Partner certificates

3. Auxiliary certificates

All three methods described in the previous sections can be used for these other certificates.

As an example, to return all certificates, you can use this RESTRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. API call:

curl --location --request GET 'https://<EP>/api/v1/system/certificates/' \
--header 'Authorization: Basic c29Acm9vdDpQYXNzd29yZDEh' \
--header 'Cookie: JSESSIONID=59367E1E71FF5008295C3306E0554AC0'

A sample response:

[
{
"id": "<EP>",
"role": "ENTRYPOINT",
"subject": "O=SERVER, CN=<EP>",
"validUntil": "2023-09-02T19:28:16Z",
"subjectAlternativeNames": {
"names": [
...
],
"uid": "2.5.29.17",
"isCritical": false
},
"alertLevel": "WARN"
},
{
"id": "<PT>",
"role": "PARTNER",
"subject": "O=SERVER, CN=<PT>",
"validUntil": "2023-07-27T17:00:46Z",
"subjectAlternativeNames": {
"names": [
...
],
"uid": "2.5.29.17",
"isCritical": false
},
"alertLevel": "WARN"
},
{
"id": "<AUX>",
"role": "AUXILIARY",
"subject": "O=SERVER, CN=<AUX>",
"validUntil": "2023-07-27T17:00:26Z",
"subjectAlternativeNames": {
"names": [
...
],
"uid": "2.5.29.17",
"isCritical": false
},
"alertLevel": "WARN"
},
{
"id": "root_ca",
"role": "ROOT_CA",
"subject": "CN=Unbound UKC Root CA G1",
"validUntil": "2029-07-27T16:58:53Z",
"alertLevel": "WARN"
}
]

You can retrieve all the certificate alerts by calling:

curl --location --request GET 'https://<EP>/api/v1/system/certificates/alerts' \
--header 'Authorization: Basic c29Acm9vdDpQYXNzd29yZDEh' \
--header 'Cookie: JSESSIONID=59367E1E71FF5008295C3306E0554AC0'

A sample response:

[
{
"category": "SYSTEM",
"alertType": "CERT_ABOUT_TO_EXPIRE",
"alertLevel": "WARN",
"counter": 4,
"title": "4 system certificates are about to be expired"
}
]

Renew Root CA Process

Relevant Keys and Files

• root_ca.ks - The trust store containing CA certificates trusted by CORE Server (used by Tomcat).

• server-ca.p7b - The trust store containing CA certificates trusted by CORE Client.

• key.pfx - The private key and certificate of the CORE server.

• cert.crt - Only the certificate of the CORE server.

• <PART_NAME>.pfx - The private key and certificate of a CORE Client.

The Process

ekm_root_ca_prepare_next

This script is executed on an EP and its Partner.

Prerequisites:

• Both EKMEnterprise Key Management - previous name of the product. services are down.

This process generates the next Root CA in such way that both parties agree on.

The output of this step is a new key (next-root-ca-key) and certificate (next-root-ca-certificate) on the Root Partition, but no file is affected yet.

ucl list -p root

Response:

Partition 0 root: 9 objects found
Private ECC key : UID=909fc0ad90b8e81d Name="next-root-ca-key" Private ECC key : UID=cfb02c2206e63b7c Name="integrity-key" Private ECC key : UID=dbd9458f05f49e3c Name="secret-data-key" Private ECC key : UID=df3cd28a07321081 Name="saml-key" Certificate : UID=f2ee5fab54a4575d Name="root-ca-certificate" PWD : UID=f54745e3d2a7821b Name="pwd-key"
Private ECC key : UID=0d11a054ab5ba8a2 Name="root-ca-key" Certificate : UID=20c32d75f8cdef7e Name="saml-certificate"
Certificate : UID=6f603f526f4717e2 Name="next-root-ca-certificate"

ekm_root_ca_trust_next

This script adds the Next CA (next-root-ca-certificate) to the CORE server trust store - root_ca.ks.

It must be:

• Run on each CORE server.

• Executed before the next step so that all CORE servers will trust certificates that will be signed by the new Root CA following its execution. The root_ca.ks contains 2 certificates: (g1 - the original, and g2 - the new one).

keytool -list -keystore root_ca.ks

Response:

Enter keystore password:
Keystore type: JKS Keystore provider: SUN
Your keystore contains 2 entries
unbound ukc root ca g1, Mar 21, 2021, trustedCertEntry,
Certificate fingerprint (SHA1): 80:B0:85:10:8A:5F:B3:FF:CD:2E:57:AF:F3: 03:86:CE:4E:85:39:CC
unbound ukc root ca g2, Mar 21, 2021, trustedCertEntry,
Certificate fingerprint (SHA1): 39:32:48:DE:6D:81:85:04:4C:DD:CC:B3:36: 12:C1:10:C0:C0:91:10

ekm_root_ca_move_next

This script “moves” the Root CA pointer to the Next Root CA. From now on, all new or renewed CORE certificates are signed by the new Root CA, but no file is affected.

All cluster servers must trust on the next Root CA key before moving. This is validated on the EP that performs this operation. Please compare 909fc0ad90b8e81d and 6f603f526f4717e2 in the previous and in the following capture.

ucl list -p root

Response:

Partition 0 root: 9 objects found
Private ECC key : UID=909fc0ad90b8e81d Name="root-ca-key" Private ECC key : UID=cfb02c2206e63b7c Name="integrity-key" Private ECC key : UID=dbd9458f05f49e3c Name="secret-data-key" Private ECC key : UID=df3cd28a07321081 Name="saml-key"
Certificate : UID=f2ee5fab54a4575d Name="root-ca-certificate-G1" PWD : UID=f54745e3d2a7821b Name="pwd-key"
Private ECC key : UID=0d11a054ab5ba8a2 Name="root-ca-key-G1" Certificate : UID=20c32d75f8cdef7e Name="saml-certificate" Certificate : UID=6f603f526f4717e2 Name="root-ca-certificate"

Certificate Renewal

Server Certificate Renewal

To renew a server certificate, run the ekm_renew_server_certificate script. It refreshes the key.pfx and cert.crt files with the new content that is signed by the new Root CA. At some point, some CORE servers are using old certificates, and some are using the new ones. This is OK since we already included the new Root CA in their trust stores.

However, we have not yet updated the trust stores of the EP clients.

Note
A CORE client returns the following alert if the EP server’s certificate has been signed by a certificate that is missing from the client’s trust store:

GET {{baseUrl}}/api/v1/clients/<CLIENT_NAME>/alerts
[
{
"alertType": "RENEW_REQUIRED", "alertLevel": "WARN",
"title": " Client trust repository must be renewed"
}
]

The renewal of the EP server certificate requires preparing CORE clients to accept the new certificate. See the next topic.

Client Trust Store Renewal

If you have to renew an EP server certificate, then the trust store (server-ca.p7b) of its clients must include the new trust certificate that will sign the renewed certificate of EP.

You have two options to update the trust store:

1. Without renewing any of client’s certificates on the machine. In this case, delete the current (server-ca.p7b) and run the ucl root_ca command to obtain the updated trust store from the EP.

2. With renewing the client’s certificate for selected partitions. In this case, run the ucl renew command for the required partitions. It refreshes the client’s certificate <PART_NAME>.pfx file and updates the trust store server-ca.p7b. Unless you do not plan to renew the client’s certificate, this is the recommended option.

Example of Client Trust Store Before and After Renewal

The old server-ca.p7b:

openssl pkcs7 -in server-ca.p7b -inform DER -print_certs subject=/CN=Unbound UKC Root CA G1
issuer=/CN=Unbound UKC Root CA G1
-----BEGIN CERTIFICATE-----
MIIBszCCAVqgAwIBAgIJAMcDn1TXZIYZMAoGCCqGSM49BAMCMCExHzAdBgNVBAMT
FlVuYm91bmQgVUtDIFJvb3QgQ0EgRzEwHhcNMjEwMzA3MDczMTM0WhcNMzEwMzA3 MDczMTM0WjAhMR8wHQYDVQQDExZVbmJvdW5kIFVLQyBSb290IENBIEcxMFkwEwYH
KoZIzj0CAQYIKoZIzj0DAQcDQgAEgCiy3DLnIifIBfl4lzjnJjtDHfrakOocBdGG YsoKxnxghAnZTwOeIpIP6uP8JF4KuJehojQf2DyubRQw+aszFaN7MHkwKwYDVR0j BCQwIoAgPPafQLuD1V/joOZ3tvw6SNb7onfhUw0EtseSA4RKTx8wDwYDVR0TAQH/ BAUwAwEB/zAOBgNVHQ8BAf8EBAMCAcYwKQYDVR0OBCIEIDz2n0C7g9Vf46Dmd7b8 OkjW+6J34VMNBLbHkgOESk8fMAoGCCqGSM49BAMCA0cAMEQCIHWfdPe0dh5+7AGi
s81Z+eI6Y33ie1nFseor0K2YhFugAiBgZheN0qTNXjPjwERYpok0m7tWN+H4Ff6g 9Oi8YU7NmA==
-----END CERTIFICATE-----

The new server-ca.p7b:

openssl pkcs7 -in server-ca.p7b -inform DER -print_certs subject=/CN=Unbound UKC Root CA G1
issuer=/CN=Unbound UKC Root CA G1
-----BEGIN CERTIFICATE-----
MIIBszCCAVqgAwIBAgIJAMcDn1TXZIYZMAoGCCqGSM49BAMCMCExHzAdBgNVBAMT
FlVuYm91bmQgVUtDIFJvb3QgQ0EgRzEwHhcNMjEwMzA3MDczMTM0WhcNMzEwMzA3 MDczMTM0WjAhMR8wHQYDVQQDExZVbmJvdW5kIFVLQyBSb290IENBIEcxMFkwEwYH
KoZIzj0CAQYIKoZIzj0DAQcDQgAEgCiy3DLnIifIBfl4lzjnJjtDHfrakOocBdGG YsoKxnxghAnZTwOeIpIP6uP8JF4KuJehojQf2DyubRQw+aszFaN7MHkwKwYDVR0j BCQwIoAgPPafQLuD1V/joOZ3tvw6SNb7onfhUw0EtseSA4RKTx8wDwYDVR0TAQH/ BAUwAwEB/zAOBgNVHQ8BAf8EBAMCAcYwKQYDVR0OBCIEIDz2n0C7g9Vf46Dmd7b8 OkjW+6J34VMNBLbHkgOESk8fMAoGCCqGSM49BAMCA0cAMEQCIHWfdPe0dh5+7AGi
s81Z+eI6Y33ie1nFseor0K2YhFugAiBgZheN0qTNXjPjwERYpok0m7tWN+H4Ff6g 9Oi8YU7NmA==
-----END CERTIFICATE-----
subject=/CN=Unbound UKC Root CA G2 issuer=/CN=Unbound UKC Root CA G2
-----BEGIN CERTIFICATE-----
MIIBszCCAVqgAwIBAgIJBKhLhchpSVzHMAoGCCqGSM49BAMCMCExHzAdBgNVBAMT
FlVuYm91bmQgVUtDIFJvb3QgQ0EgRzIwHhcNMjEwMzA2MDczMTM0WhcNMzEwMzA2 MDczMTM0WjAhMR8wHQYDVQQDExZVbmJvdW5kIFVLQyBSb290IENBIEcyMFkwEwYH
KoZIzj0CAQYIKoZIzj0DAQcDQgAE+O++CY92oH4efifkS2j9jca7aGwROMYYwhZG mNkcTc+aphBXnzx6Vqmz3O2MKXFG857p3mRzrYuW04COEwVKGqN7MHkwKwYDVR0j BCQwIoAgaNj+QcyaK9pEyh1HwjyxYEwINSxeB4K7BTd1p31qxq8wDwYDVR0TAQH/ BAUwAwEB/zAOBgNVHQ8BAf8EBAMCAcYwKQYDVR0OBCIEIGjY/kHMmivaRModR8I8
sWBMCDUsXgeCuwU3dad9asavMAoGCCqGSM49BAMCA0cAMEQCIERR4A8QuM11bWk/ 2XPSQMdxIQfFc55sytyjUwwMS6hSAiAnp2unSC+mch8Dhe7/zfyCjGhJ4fLNhq8G AIU7jhPLQQ==
-----END CERTIFICATE-----

Client Certificate Renewal

To renew a client’s certificate, run the ucl renew command. It refreshes the client’s partition’s certificate for <PART_NAME>.pfx file and its trust store server-ca.p7b.