Acquire and deploy certificates for EAP-TLS networks
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.
Before an Azure Sphere device can connect to an EAP-TLS network, it must have a client certificate that the RADIUS server can use to authenticate the device. If your network requires mutual authentication, each device must also have a Root CA certificate so that it can authenticate the RADIUS server.
How you acquire and deploy these certificates depends on the network resources that are available to your devices.
- If the EAP-TLS network is the only network available, you'll need to deploy the certificates manually.
- If another form of networking, such as an open network, is available, you can use a "bootstrap" approach. In the bootstrapping approach, an Azure Sphere high-level application acquires the certificates from the open network and then uses them to connect to the EAP-TLS network.
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 details.
Manual deployment
If the EAP-TLS network is the only network available to your devices, you'll need to deploy the certificates manually. Manual deployment involves acquiring the certificates by using a networked PC or Linux machine and then loading the certificates onto each Azure Sphere device by using the Azure Sphere CLI. This approach requires a physical connection between the PC or Linux machine and the Azure Sphere device.
Acquire the certificates manually
The Root CA and client certificates must be in the .PEM format to load onto the Azure Sphere device. You will need to acquire the Root CA certificate from the appropriate server, along with the client certificate and private key (and optionally a password for your private key) for your device. Each certificate must be generated and signed by the appropriate server in your EAP-TLS network. Your network administrator or security team can supply the details you need to get the certificates.
Save the certificates in the .PEM format on your PC or Linux machine, and then use the Azure Sphere CLI to store them on the Azure Sphere device.
Store the certificates using the CLI
Attach the Azure Sphere device to your networked PC or Linux machine and use the azsphere command to store the certificates on the device.
To store the Root CA certificate onto the Azure Sphere device:
azsphere device certificate add --cert-id "server-key-xyz" --cert-type rootca --public-key-file <filepath_to_server_ca_public.pem>
To store the client certificate onto the Azure Sphere device:
azsphere device certificate add --cert-id "client-key-abc" --cert-type client --public-key-file <filepath_to_client_public.pem> --private-key-file <filepath_to_client_private.pem> --private-key-password "_password_"
Bootstrap deployment
To connect Azure Sphere devices in large numbers or in many locations, consider using a "bootstrap" approach. To use this method, your devices must be able to connect to a network through which they can access a server that can supply the certificates. Your high-level Azure Sphere application connects to the server over the available network, requests the certificates, and stores them on the device.
The following figure summarizes this process.
The application on the Azure Sphere device connects to the open network and contacts the Azure Sphere Security Service to get its DAA certificate. It then installs the DAA certificate on the device. The device should use this certificate to authenticate with the certificate issuing service.
The application next connects to the certificate issuing service that the network administrator has designated. It presents its DAA certificate to validate its identity with the server and requests the Root CA certificate for the RADIUS server on the EAP-TLS network, along with the client certificate and private key. The service may pass other information to the application, such as the client identity, and the private key password if required. The application then installs the client certificate, the client private key, and the Root CA certificate on the device. It can then disconnect from the open network.
The application configures and enables the EAP-TLS network. It supplies the client certificate and private key to prove the identity of the device. If the network supports mutual authentication, the application also authenticates the RADIUS server by using the Root CA certificate.
Authenticate the device and get the client certificate during bootstrapping
An Azure Sphere device can use its device authentication and attestation (DAA) certificate to authenticate to a service that can supply the other required certificates. The DAA certificate is available from the Azure Sphere Security Service.
To get the DAA certificate:
- Specify the Azure Sphere tenant ID in the DeviceAuthentication section of the application manifest for the high-level application.
- Call DeviceAuth_CurlSslFunc from the high-level application to get the certificate chain for the current Azure Sphere tenant.
If the application manifest includes the Azure Sphere tenant ID for the current device, the DeviceAuth_CurlSslFunc function will use the DAA client certificate chain to authenticate, if the target service requires TLS mutual authentication.
Get the Root CA certificate for the RADIUS server
To get the Root CA certificate for the RADIUS server, the application connects to a certificate server endpoint that is accessible on its network and can supply the certificate. Your network administrator should be able to provide information about how to connect to the endpoint and retrieve the certificate.
Install the certificates using the CertStore API
The application uses the CertStore API to install the certificates onto the device. The CertStore_InstallClientCertificate function installs the client certificate and CertStore_InstallRootCACertificate installs the Root CA certificate for the RADIUS server. Manage certificates in high-level applications provides additional information about using the CertStore API for certificate management.
The Certificates sample application shows how an application can use these functions.