Manage certificates in high-level applications

  • Article

The CertStore API lets a high-level application manage certificates for use in network authentication. The az sphere device certificate lets you manage certificates from the command line.

Certificates are stored in nonvolatile storage on the Azure Sphere device. The certificate store, or cert store, can hold up to 24 KiB of certificates. The maximum size for a certificate is 8 KiB. Root CA certificates are typically larger than client certificates. In addition to using the cert store, you can also access the Microsoft-managed client certificate. The Microsoft-managed client certificate will only be available for use when the device is connected to the internet at least once every 24 hours.

Use the Microsoft-managed client certificate

Use these two functions to obtain a client certificate and determine whether it is ready for use.

  • DeviceAuth_GetCertificatePath returns a file path to a client certificate managed by the OS. This file path is required by some libraries to load a certificate for TLS communications.

  • Application_IsDeviceAuthReady to verify whether device authentication for the current application is ready.

CertStore requirements

Applications that use the CertStore API must include the appropriate header files and add the CertStore capability to the application manifest.

Header files

Include the CertStore header in your project:

 #include <applibs\certstore.h>

Application manifest settings

To use the certificate store APIs, you must add the CertStore application capability to the application manifest and set the value to true. The Azure Sphere application manifest topic has more details about the application manifest.

{
  "SchemaVersion": 1,
  "Name" : "Mt3620App3",
  "ComponentId" : "bb267cbd-4d2a-4937-8dd8-3603f48cb8f6",
  "EntryPoint": "/bin/app",
  "CmdArgs": [],
   "Capabilities": {
    "AllowedConnections": [],
    "AllowedTcpServerPorts": [],
    "AllowedUdpServerPorts": [],
    "CertStore" : true,
    "Gpio": [],
    "Uart": [],
    "EnterpriseWifiConfig": true,
    "WifiConfig": true,
    "NetworkConfig": false,
    "SystemTime": true
  }
}

Certificate IDs

Every certificate is associated with a certificate identifier (ID). The certificate ID is a string of 1-16 characters that uniquely identifies the certificate on the device. Valid characters are 'a'-'z', 'A'-'Z', '0'-'9', hyphen (-). and underscore (_). Every certificate ID must be unique across the device, regardless of the type of certificate that it identifies.

Each certificate's identifier is saved in the certificate store and is used device-wide: by the CertStore API, the WifiConfig API, and the Azure CLI extension. Consequently, if you load a certificate from the command line, any applications that query, move, or delete that certificate must use the same ID. Similarly, if an app loads the certificate, any az sphere commands that manipulate the certificate must use the same ID. If you install a new certificate with the same ID as an existing certificate of any type, the new certificate will overwrite the existing one.

Caution

Because certificate IDs are system-wide for both client and Root CA certificates, an az sphere 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.

Add a certificate to the certificate store

To add a certificate to the certificate store, an app calls one of the following functions:

  • CertStore_InstallClientCertificate installs a client certificate, which consists of a public certificate and a private key
  • CertStore_InstallRootCACertificate installs a Root CA certificate, which consists of a public certificate

The certificate must be present on the device before the app can install it. Certificates must be in PKCS1 or PKCS8 syntax and the .pem format to load onto the Azure Sphere device. Acquire and deploy certificates for EAP-TLS networks describes how to acquire certificates and load them onto a device. Microsoft does not supply certificates.

Installing a certificate adds it to the certificate store and makes it available for use in authentication. Within the certificate store, certificates are managed by index and can be retrieved by index. The range of index values runs from 0 to (CertStore_GetCertificateCount - 1).

An app can get the ID of the certificate at a particular index by calling the CertStore_GetCertificateIdentifierAt function. It can then use the certificate ID in calls to get information about the certificate, to move or delete the certificate, and to use a certificate for authentication.

Get certificate information

The CertStore API includes several functions that return information about a stored certificate:

The not-before and not-after times are useful in managing certificate lifetime and updates. See Certificate life cycle and renewal for details.

Rename or delete a certificate

To rename or delete a certificate, an app calls CertStore_MoveCertificate or CertStore_DeleteCertificate.

CertStore_MoveCertificate renames a certificate by changing its certificate ID. Because certificate IDs must be unique across a device, renaming a certificate by giving it the same ID as another certificate deletes that certificate. For example, if the certificate store contains MyCert and YourCert, moving MyCert to YourCert results in a single certificate with ID YourCert, which contains the data from the former MyCert. No error is returned.

CertStore_DeleteCertificate deletes a single certificate. Deleting a certificate causes the remaining certificates to be reindexed, starting at 0. Therefore, to delete all the certificates in the certificate store, you need to loop based on the number of certificates but delete the certificate at index 0 in each iteration. If you try to delete a certificate at an index that is no longer in use, CertStore_GetCertificateIdentifierAt returns ERANGE.

The following method works correctly:

for (int i = 0; i < CertStore_GetCertificateCount(); i++) {
    struct CertStore_Identifier id;
    result = CertStore_GetCertificateIdentifierAt(0, &id);
    CertStore_DeleteCertificate(id.identifier);
}

Use a certificate for network authentication

The WifiConfig API provides functions that set and return the certificates that are enabled for a particular Wi-Fi configuration. See Set up EAP-TLS network in an app for details about how a high-level application can set up an EAP-TLS network that uses certificates for authentication.

Certificate sample

The Certificates sample application shows how an application can use the CertStore functions.