Administrar certificados en aplicaciones de alto nivel
La API CertStore permite a una aplicación de alto nivel administrar certificados para su uso en la autenticación de red. El certificado az sphere device le permite gestionar certificados desde la línea de comandos.
Los certificados se almacenan en almacenamiento no voladizo en el dispositivo Azure Sphere. El almacén de certificados, o almacén de certificados, puede contener hasta 24 KiB de certificados. El tamaño máximo de un certificado es de 8 KiB. Los certificados de CA raíz suelen ser mayores que los certificados de cliente. Además de usar el almacén de certificados, también puede obtener acceso al certificado de cliente administrado por Microsoft. El certificado de cliente administrado por Microsoft solo estará disponible para su uso cuando el dispositivo esté conectado a Internet al menos una vez cada 24 horas.
Usar el certificado de cliente administrado por Microsoft
Use estas dos funciones para obtener un certificado de cliente y determinar si está listo para usarse.
DeviceAuth_GetCertificatePath devuelve una ruta de acceso de archivo a un certificado de cliente administrado por el sistema operativo. Algunas bibliotecas necesitan esta ruta de acceso de archivo para cargar un certificado para las comunicaciones TLS.
Application_IsDeviceAuthReady para comprobar si la autenticación del dispositivo para la aplicación actual está lista.
Requisitos de CertStore
Las aplicaciones que usan la API CertStore deben incluir los archivos de encabezado adecuados y agregar la funcionalidad CertStore al manifiesto de la aplicación.
Archivos de encabezado
Incluya el encabezado CertStore en el proyecto:
#include <applibs\certstore.h>
Configuración de manifiesto de la aplicación
Para usar las API del almacén de certificados, debe agregar la capacidad de la CertStore aplicación al manifiesto de la aplicación y establecer el valor en true. El tema de manifiesto de la aplicación Azure Sphere tiene más detalles sobre el manifiesto de la aplicación.
{
"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
}
}
Identificadores de certificado
Cada certificado está asociado a un identificador de certificado (Id.). El id. de certificado es una cadena de 1-16 caracteres que identifica exclusivamente el certificado en el dispositivo. Los caracteres válidos son 'a'-'z', 'A'-'Z', '0'-'9', guión (-). y subrayado (_). Cada id. de certificado debe ser único en el dispositivo, independientemente del tipo de certificado que identifique.
El identificador de cada certificado se guarda en el almacén de certificados y se usa en todo el dispositivo: mediante la API CertStore , la API WifiConfig y la extensión de la CLI de Azure. Por lo tanto, si carga un certificado desde la línea de comandos, todas las aplicaciones que consultan, mueven o eliminan ese certificado deben usar el mismo identificador. De forma similar, si una aplicación carga el certificado, todos az sphere los comandos que manipulan el certificado deben usar el mismo identificador. Si instala un nuevo certificado con el mismo id. que un certificado existente de cualquier tipo, el nuevo certificado sobrescribirá el existente.
Precaución
Dado que los id. de certificado son de todo el sistema tanto para certificados de ca de cliente como de entidad de certificación raíz, un comando az sphere o una llamada de función que agrega un certificado nuevo puede sobrescribir un certificado agregado por una llamada de función o comando anterior, lo que puede provocar errores en la conexión de red. Le recomendamos encarecidamente que desarrolle procedimientos claros de actualización de certificados y elija cuidadosamente los identificadores de certificado.
Agregar un certificado al almacén de certificados
Para agregar un certificado al almacén de certificados, una aplicación llama a una de las siguientes funciones:
- CertStore_InstallClientCertificate instala un certificado de cliente, que consiste en un certificado público y una clave privada
- CertStore_InstallRootCACertificate instala un certificado de CA raíz, que consiste en un certificado público
El certificado debe estar presente en el dispositivo antes de que la aplicación pueda instalarlo. Los certificados deben estar en sintaxis PKCS1 o PKCS8 y el formato .pem para cargarse en el dispositivo Azure Sphere. Adquirir e implementar certificados para redes EAP-TLS describe cómo adquirir certificados y cargarlos en un dispositivo. Microsoft no suministra certificados.
La instalación de un certificado lo agrega al almacén de certificados y lo pone a disposición para su uso en la autenticación. En el almacén de certificados, los certificados se administran mediante índice y se pueden recuperar mediante índice. El intervalo de valores de índice se ejecuta de 0 a (CertStore_GetCertificateCount - 1).
Una aplicación puede obtener el identificador del certificado en un índice determinado llamando a la función CertStore_GetCertificateIdentifierAt. A continuación, puede usar el id. de certificado en las llamadas para obtener información sobre el certificado, para mover o eliminar el certificado y para usar un certificado para la autenticación.
Obtener información del certificado
La API CertStore incluye varias funciones que devuelven información sobre un certificado almacenado:
- CertStore_GetCertificateNotBefore obtiene el momento en que el certificado pasa a ser válido
- CertStore_GetCertificateNotAfter obtiene el tiempo en el que expira el certificado
- CertStore_GetCertificateIssuerName obtiene el nombre del emisor del certificado
- CertStore_GetCertificateSubjectName obtiene el nombre del asunto del certificado; es decir, lo que el certificado protege
Los tiempos de no antes y no después son útiles para administrar la duración del certificado y las actualizaciones. Consulte Ciclo de vida y renovación del certificado para obtener más información.
Cambiar el nombre o eliminar un certificado
Para cambiar el nombre o eliminar un certificado, una aplicación llama CertStore_MoveCertificate o CertStore_DeleteCertificate.
CertStore_MoveCertificate cambia el nombre de un certificado cambiando su id. de certificado. Dado que los identificadores de certificado deben ser únicos en un dispositivo, al cambiar el nombre de un certificado al darle el mismo identificador que otro certificado, se elimina ese certificado. Por ejemplo, si el almacén de certificados contiene y , pasando MyCert a YourCert los resultados en un único certificado con idYourCert., que contiene los datos del primero MyCert.YourCertMyCert No se devuelve ningún error.
CertStore_DeleteCertificate elimina un único certificado. Al eliminar un certificado, los certificados restantes se vuelven a indizar, empezando por 0. Por lo tanto, para eliminar todos los certificados en el almacén de certificados, debe repetir en función del número de certificados, pero eliminar el certificado en el índice 0 en cada iteración. Si intenta eliminar un certificado en un índice que ya no está en uso, CertStore_GetCertificateIdentifierAt devuelve ERANGE.
El siguiente método funciona correctamente:
for (int i = 0; i < CertStore_GetCertificateCount(); i++) {
struct CertStore_Identifier id;
result = CertStore_GetCertificateIdentifierAt(0, &id);
CertStore_DeleteCertificate(id.identifier);
}
Usar un certificado para la autenticación de red
La API WifiConfig proporciona funciones que establecen y devuelven los certificados habilitados para una configuración Wi-Fi determinada. Consulte Configurar la red EAP-TLS en una aplicación para obtener detalles sobre cómo una aplicación de alto nivel puede configurar una red EAP-TLS que utiliza certificados para la autenticación.
Ejemplo de certificado
La aplicación de ejemplo Certificados muestra cómo una aplicación puede usar las funciones CertStore.