Docs › Provisioning devices › Certificates and certificate authorities › Renewing device certificates › Certificate renewal tutorial

Certificate renewal tutorial

This tutorial guides you through the certificate renewal process step by step:

Initiated by the service.
Initiated by the device.

Initiated by service

Using the Certificate Enrollment API

To renew a certificate using the Device Management Certificate Enrollment API:

Build and flash the Device Management Client example code onto the device.

Make the following updates to the mbed_app.json file when you compile the code:
1. To enable certificate renewal, add this line:
```
"mbed-cloud-client.disable-certificate-enrollment": null
```
  The certificate renewal feature is disabled by default for all boards, except for the K66F board.
2. Increase the stack size:
```
"rtos.main-thread-stack-size"               : 8192,
```
Device Management Client example enables you to renew an LwM2M certificate. If you want to renew a custom certificate, you must inject the custom certificate to the device as part of the factory provisioning process, as described on the Pelion Device Management Factory Provisioning documentation site.
Connect your device to Device Management.
Optionally, register a user callback for the certificate renewal process. This is already a part of the Device Management Client example code. This callback is used for notifying the device application on the completion of the certificate renewal, its status and its initiator. The device application code may choose to omit the user callback registration, if there is no need for the notifications.
```
static void certificate_renewal_cb(const char *cert_name, ce_status_e status, ce_initiator_e initiator)
{
    printf("User callback. Certificate renewal completed:\n Certificate name: %s\nStatus: 0x%x\nInitiator: %d\n", cert_name, status,     initiator);
}

...

mbedClient.get_cloud_client().on_certificate_renewal(certificate_renewal_cb);
```
Use POST /v3/devices/{device-id}/certificates/{certificate-name}/renew from the Certificate Enrollment API to renew the certificate.
- Renew LwM2M certificate:
```
POST /v3/devices/:device_id/certificates/LWM2M/renew
```
- Renew custom certificate:
```
POST /v3/devices/:device_id/certificates/:cert_name/renew
```
Note: If you want to renew a custom certificate, you need to inject it to the device in advance.
When the renewal has completed successfully on the device, you will see the following log on the device:
```
Certificate renewal completed.
Certificate name: LWM2M
Status: 0x0
Initiator: 1
Certificate renewal status string: Renewal Success: Operation completed successfully
```
The log comes from certificate renewal user callback. You can see the certificate name that was renewed, the status of the operation according to ce_status.h and certificate renewal initiator according to ce_defs.h.

If you want to check the status of your specific renewal request, poll the Certificate enrollment API with GET /v3/certificate-enrollments/{certificate-enrollment-id}, and if you want to check the status of multiple renewal requests, with or without filters, poll with GET /v3/certificate-enrollments.

Renewing a certificate using the portal

Setting up a third-party CA

To renew custom certificates on your device, you must integrate with a third-party CA. If you are renewing a LwM2M certificate, this section is optional.

Renewing the certificate for a specific device

Open Device Management Portal.
Select Device directory > Devices from the side menu.
Identify your device from the list and click the Device ID to open the Device details view.
Select the Summary tab (it should be selected by default).
Scroll down to the parameter called Device Certificate.
From the Select the device certificate to renew dropdown, select the third-party CA that you created above.
Click Renew.

A message with the result of the operation appears. The device must be connected and online to renew the certificate successfully.

Initiated by device

This section explains how to renew a certificate using the Device Management Client APIs. There is no interaction with the cloud side in this scenario. On the device side, you may use the Device Management Client example code with minor changes.

Connect your device to Device Management.
Optionally, register a user callback for the certificate renewal process. This is already a part of the Device Management Client example code. The callback is used to notify the device application about the completion of the certificate renewal process, its status and its initiator. You may omit the user callback registration if there is no need for the notifications.
```
static void certificate_renewal_cb(const char *cert_name, ce_status_e status, ce_initiator_e initiator)
{
    printf("User callback. Certificate renewal completed:\n Certificate name: %s\nStatus: 0x%x\nInitiator: %d\n", cert_name, status, initiator);
}

...

mbedClient.get_cloud_client().on_certificate_renewal(certificate_renewal_cb);
```
Call the following API:

ce_status_e certificate_renew(const char *cert_name).

This isn't part of the Device Management Client example code. You have to add it.
- Renewal of LwM2M certificate:
```
mbedClient.get_cloud_client().certificate_renew("LWM2M");
```
- Renewal of custom certificate named "custom_cert":
```
mbedClient.get_cloud_client().certificate_renew("custom_cert");
```
When the certificate is renewed successfully on the device, you will see the following log on the device:
```
Certificate renewal completed.
Certificate name: LWM2M
Status: 0x0
Initiator: 0
Certificate renewal status string: Renewal Success: Operation completed successfully
```
The log comes from the certificate renewal user callback. You can see the name of the certificate that was renewed, the status of the operation according to ce_status.h and the certificate renewal initiator according to ce_defs.h

Note: Notifications are not sent to Device Management during the device-initiated flow.

Documentation