Gérer les certificats dans les applications de haut niveau

Article
11/05/2024

Important

Il s’agit de la documentation Azure Sphere (héritée). Azure Sphere (hérité) prend sa retraite le 27 septembre 2027 et les utilisateurs doivent migrer vers Azure Sphere (intégré) pour l’instant. Utilisez le sélecteur de version situé au-dessus du TOC pour afficher la documentation Azure Sphere (intégrée).

L’API CertStore permet de gérer les certificats utilisés dans les applications de haut niveau pour l’authentification réseau. azsphere device certificate vous permet de gérer les certificats à partir de la ligne de commande.

Les certificats sont conservés dans un stockage non volatile sur l’appareil Azure Sphere. Le magasin de certificats, ou certstore, peut contenir jusqu’à 24 Kio de certificats. La taille maximale d’un certificat est de 8 Kio. La taille des certificats d’autorité de certification racine est généralement supérieure à celle des certificats clients. Outre l’utilisation du magasin de certificats, vous pouvez également accéder au certificat client géré par Microsoft. Le certificat client géré par Microsoft est disponible uniquement lorsque l’appareil est connecté à Internet au moins une fois toutes les 24 heures.

Utiliser le certificat client géré par Microsoft

Utilisez ces deux fonctions pour obtenir un certificat client et déterminer s’il est prêt à être utilisé.

DeviceAuth_GetCertificatePath retourne un chemin d’accès de fichier à un certificat client géré par le système d’exploitation. Ce chemin d’accès de fichier est requis par certaines bibliothèques pour charger un certificat pour les communications TLS.
Application_IsDeviceAuthReady pour vérifier si l’authentification de l’appareil pour l’application actuelle est prête.

Exigences pour CertStore

Les applications qui utilisent l’API CertStore doivent inclure les fichiers d’en-tête appropriés et ajouter la fonctionnalité CertStore dans le manifeste de l’application.

Fichiers d’en-tête

Incluez l’en-tête CertStore dans votre projet :

 #include <applibs\certstore.h>

Paramètres de manifeste de l’application

Pour utiliser les API du magasin de certificats, vous devez ajouter la fonctionnalité d’application CertStore dans le manifeste de l’application et définir sa valeur sur true. Pour plus de détails sur le manifeste d’application, consultez la rubrique Manifeste d’application Azure Sphere.

{
  "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
  }
}

ID de certificat

Chaque certificat est associé à un identificateur (ID) de certificat. L’ID de certificat est une chaîne composée de 1 à 16 caractères qui identifie de façon unique le certificat sur l’appareil. Les caractères valides sont les lettres « a » à « z » et « A » à « Z », les chiffres « 0 » à « 9 », le trait d’union (-) et le trait de soulignement (_). Chaque ID de certificat doit être unique sur l’appareil, quel que soit le type de certificat qu’il identifie.

L’identificateur de chaque certificat est enregistré dans le magasin de certificats et est utilisé à l’échelle de l’appareil : par l’API CertStore , l’API WifiConfig et l’interface CLI azsphere. Par conséquent, si vous chargez un certificat à partir de la ligne de commande, toutes les applications qui demandent, déplacent ou suppriment ce certificat doivent le faire en employant le même ID. De la même façon, si une application charge le certificat, les commandes azsphere qui manipulent le certificat doivent utiliser le même ID. Si vous installez un nouveau certificat dont l’ID est le même que celui d’un certificat existant d’un quelconque type, le nouveau certificat remplacera le certificat existant.

Attention

Les ID de certificat étant à l’échelle du système pour les certificats d’autorité de certification racine et client, un appel de fonction ou une commande azsphere qui ajoute un nouveau certificat peut remplacer un certificat qui a été ajouté par un appel de fonction ou une commande antérieur, provoquant potentiellement des échecs de connexion réseau. Nous vous recommandons fortement de développer des procédures de mise à jour de certificats claires et de choisir les ID de certificat avec soin.

Ajouter un certificat au magasin de certificats

Pour ajouter un certificat au magasin de certificats, une application appelle l’une des fonctions suivantes :

CertStore_InstallClientCertificate installe un certificat client composé d’un certificat public et d’une clé privée
CertStore_InstallRootCACertificate installe un certificat d’autorité de certification racine composé d’un certificat public

Le certificat doit être présent sur l’appareil pour que l’application puisse l’installer. Les certificats doivent respecter la syntaxe PKCS1 ou PKCS8 et être au format .pem pour être chargés sur l’appareil Azure Sphere. L’article Acquérir et déployer des certificats pour les réseaux EAP-TLS décrit comment acquérir des certificats et les charger sur un appareil. Microsoft ne fournit pas de certificats.

Quand un certificat est installé, il est de facto ajouté au magasin de certificats et utilisable pour l’authentification. Dans le magasin de certificats, les certificats sont gérés et récupérés par index. La plage de valeurs d’index est comprise entre 0 et (CertStore_GetCertificateCount - 1).

Une application peut obtenir l’ID du certificat à un index particulier en appelant la fonction CertStore_GetCertificateIdentifierAt. Elle peut ensuite utiliser l’ID du certificat dans les appels pour obtenir des informations sur le certificat, déplacer ou supprimer le certificat et utiliser un certificat pour l’authentification.

Obtenir des informations sur un certificat

L’API CertStore contient plusieurs fonctions qui retournent des informations sur un certificat stocké :

CertStore_GetCertificateNotBefore retourne l’heure d’activation du certificat
CertStore_GetCertificateNotAfter retourne l’heure d’expiration du certificat
CertStore_GetCertificateIssuerName retourne le nom de l’émetteur du certificat
CertStore_GetCertificateSubjectName retourne le nom de l’objet du certificat, qui indique ce que le certificat protège

Les heures « NotBefore » et « NotAfter » sont utiles pour gérer la durée de vie et les mises à jour des certificats. Pour plus d’informations, consultez Cycle de vie et renouvellement de certificat.

Renommer ou supprimer un certificat

Pour renommer ou supprimer un certificat, une application appelle CertStore_MoveCertificate ou CertStore_DeleteCertificate, respectivement.

CertStore_MoveCertificate renomme un certificat en changeant son ID de certificat. Étant donné que les ID de certificats doivent être uniques sur un appareil, le fait de renommer un certificat en lui attribuant le même ID qu’un autre certificat entraîne la suppression du certificat existant. Par exemple, si le magasin de certificats contient MyCert et YourCert, et que vous renommez MyCert en YourCert, vous obtenez au final un seul certificat avec l’ID YourCert, qui contient les données de l’ancien MyCert. Aucune erreur n’est retournée dans ce cas.

CertStore_DeleteCertificate supprime un seul certificat. La suppression d’un certificat entraîne la réindexation des certificats restants, en commençant à l’index 0. Si vous souhaitez supprimer tous les certificats dans le magasin de certificats, vous devez donc effectuer une boucle basée sur le nombre de certificats, en supprimant le certificat à l’index 0 dans chaque itération. Si vous essayez de supprimer un certificat à un index qui n’est plus utilisé, CertStore_GetCertificateIdentifierAt retourne ERANGE.

La méthode correcte est celle-ci :

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

Utiliser un certificat pour l’authentification réseau

L’API WifiConfig fournit des fonctions qui définissent et retournent les certificats qui sont activés pour une configuration WiFi spécifique. Consultez Configurer un réseau EAP-TLS dans une application pour avoir plus d’informations sur la façon dont une application de haut niveau peut configurer un réseau EAP-TLS qui utilise des certificats pour l’authentification.

Exemple de certificat

L’exemple d’application Certificates montre comment une application peut utiliser les fonctions CertStore.

Partage via