Certificate life cycle and renewal

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

Client certificate-key pairs and CA certificates expire regularly. Your network infrastructure and devices must be able to handle certificate expiration and present a new certificate without losing connectivity. Root CA certificates, which are used in RADIUS server authentication, and client certificates, which are used in device authentication, require different approaches to update.

Caution

Because certificate IDs are system-wide, an azsphere command or a function call that adds a new certificate can overwrite a certificate that was added by an earlier command or function call, potentially causing network connection failures. We strongly recommend that you develop clear certificate update procedures and choose certificate IDs carefully.

See Certificate IDs for more information about how Azure Sphere uses certificate IDs.

Update a Root CA certificate

A CA certificate is the Root CA of the authentication certificate on the RADIUS server. If the CA certificate expires or the PKI for the server changes—for example, if the server acquires a new Root CA from a different certificate authority—Azure Sphere devices can no longer authenticate the RADIUS authentication server. However, the devices need to continue functioning.

On a typical wireless network, it isn't possible to perform a "knife-edge" cutover; that is, you can't update all the Azure Sphere devices at the exact instant when the Root CA becomes invalid. Devices may be offline at the critical moment or timekeeping accuracy may vary across installations. Your high-level application must be able to get the new Root CA certificate before the current one expires or changes, so that the new certificate is ready for use when required.

The recommended approach is to create and enable a second network that has the same configuration as the existing network but uses the new Root CA certificate. When the existing Root CA certificate fails on the original network, the OS will automatically try to connect to the second network. The application can then replace the certificate on the original network with the new Root CA and delete the second network. The device can then connect using the original network, which now has the new Root CA. The following figure summarizes this approach.

A high-level application should follow these steps to seamlessly handle an update to the Root CA certificate:

1. As part of normal operation, the application configures Network1 of type WifiConfig_Security_Wpa2_EAP_TLS. This network is linked to the client certificate for the device and to Root CA1, which is the original Root CA for the RADIUS server.

2. About 90 days before the RootCA expires, the device receives a cloud-to-device notification that a new Root CA certificate for the RADIUS server will be required soon. The notification can be triggered by a network administrator or other operator; possible notification mechanisms include an Azure IoT Hub or Azure IoT Central cloud-to-device message.

   The network administrator is responsible for updating the certificate on the RADIUS server and for ensuring that the Azure Sphere devices will be updated appropriately.

3. The app acquires a new Root CA and calls CertStore_InstallRootCACertificate to save it as Root CA2.

4. The app creates a new network, Network2, by calling WifiConfig_AddDuplicateNetwork to duplicate the Network1 configuration. It then links Root CA2 to Network 2 and enables Network2. If Network2 is enabled on the device and can connect to the internet, the device will use it if Network1 is not available.

5. The app polls daily by calling WifiConfig_GetConnectedNetworkId to determine which network the device is connected to.

   If the daily check of the connected network fails, the error could result from a certificate issue on either the server or device side, or from some other problem. See Troubleshooting network problems for help.

   If the device is connected to Network1, this means that the certificate hasn't expired yet and everything is working properly. The app repeats this step until the device connects to Network2.

   If the device is connected to Network2, this means that the old certificate has expired, the updated PKI is set up on the RADIUS server, and the device is able to authenticate the server using Root CA2.

6. When the device is working properly with Network2, the app completes the changes to the network configuration:

   • Renames Root CA2 to Root CA1 by calling CertStore_MoveCertificate. This function overwrites the expired Root CA1 with the contents of Root CA2.
   • Reloads the Network1 configuration by calling WifiConfig_ReloadConfig. The Network1 configuration now matches the current network.
   • Deletes the Network2 configuration by calling WifiConfig_ForgetNetworkById.

Update a client certificate

The client certificate comprises the public and private key pair that are used to authenticate the Azure Sphere device. Like the Root CA certificate, the client certificate will expire from time to time, and the device must be able to present a new certificate. Your high-level application is responsible for obtaining the new certificate before the existing certificate expires. An app can get the date and time at which a certificate expires by calling CertStore_GetCertificateNotAfter.

The following figure summarizes this procedure. This pattern enables your certificate update code to use constant certificate IDs, such as ClientCert1 and ClientCert2, instead of creating a unique name for each new certificate. In addition, it requires no network swaps or client certificate cleanup.

A high-level application should follow these steps to seamlessly handle an update to the client certificate:

1. As part of normal operation, the application configures Network1 of type WifiConfig_Security_Wpa2_EAP_TLS. This network is linked to the client certificate for the device (ClientCert1) and to the Root CA for the RADIUS server. Before the app starts the update procedure, it verifies that the device is connected to Network1 by calling WifiConfig_GetNetworkIdByConfigName and WifiConfig_GetConnectedNetworkId. If the network IDs match, the app can be certain it is connected to the intended network.

2. The app calls CertStore_GetCertificateNotAfter at regular intervals to determine when the client certificate will expire. Alternatively, the application could store the expiration date in mutable storage; however, it should still check the expiration date daily and after every reboot.

   The app compares the expiration date and time with the current date and time. If the certificate expires within a predetermined threshold period, the app gets a new certificate. The length of the threshold period is your choice. As a best practice, we recommend obtaining a new certificate at least four weeks in advance of expiration in case the device is offline for a long period of time or encounters repeated network or server problems. The earlier you check, the more time you'll have to resolve any problems.

3. The app gets a new certificate from the appropriate certificate issuer. The choice of a certificate issuer is the responsibility of the local network administrator.

4. The app saves the new certificate as ClientCert2 by calling CertStore_InstallClientCertificate, and adds it to the Network1 Wi-Fi configuration by calling WifiConfig_SetClientCertStoreIdentifier.

5. The app reloads the Wi-Fi configuration by calling WifiConfig_ReloadConfig. This step makes ClientCert2 available to the device for use in network connections.

6. Check whether the network connection succeeded.

   • Successful connection means that ClientCert2 is now valid.

     • Rename ClientCert2 to ClientCert1 by calling CertStore_MoveCertificate.

     • Disable Network1 by calling WifiConfig_SetNetworkEnabled to set the network's Enabled state to false, and then re-enable Network1 by calling WifiConfig_SetNetworkEnabled to set the Enabled state to true. Disabling and re-enabling the configuration makes the contents of the renamed certificate available to the application.

   • Failure to connect means either that ClientCert2 isn't valid yet or that some other error occurred.

     • If the certificate isn't valid yet, continue with step 7 to return the network configuration to its original state.
     • If some other error occurred, see Troubleshooting network problems for help and retry the connection.

7. Regardless of whether the network connection succeeded, reload the Wi-Fi configuration by calling WifiConfig_ReloadConfig. If connection succeeded, the reloaded configuration will use the new ClientCert1, which was replaced by ClientCert2. If connection failed, the reloaded configuration will use ClientCert1.