Administración de certificados en aplicaciones de alto nivel

Importante

Esta es la documentación de Azure Sphere (heredado). Azure Sphere (heredado) se retira el 27 de septiembre de 2027 y los usuarios deben migrar a Azure Sphere (integrado) en este momento. Use el selector de versiones situado encima de la TOC para ver la documentación de Azure Sphere (integrado).

CertStore API permite a una aplicación de alto nivel administrar certificados para utilizarlos en la autenticación de red. azsphere device certificate permite administrar certificados desde la línea de comandos.

Los certificados se almacenan en un almacenamiento no volátil en el dispositivo Azure Sphere. El almacén de certificados, o cert store, 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 más grandes que los certificados de cliente. Además de usar el almacén de certificados, también puede acceder 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.

Uso del certificado de cliente administrado por Microsoft

Use estas dos funciones para obtener un certificado de cliente y determinar si está listo para su uso.

• DeviceAuth_GetCertificatePath devuelve una ruta de acceso de archivo a un certificado de cliente administrado por el sistema operativo. Algunas bibliotecas requieren 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 CertStore API deben habilitar los archivos de encabezado adecuados y agregar la funcionalidad CertStore al manifiesto de aplicación.

Archivos de encabezado

Incluya el encabezado CertStore en el proyecto:

 #include <applibs\certstore.h>

Configuración del manifiesto de aplicación

Para usar las API del almacén de certificados, debe agregar la funcionalidad de aplicación CertStore al manifiesto de aplicación y establecer el valor en true. El tema Manifiesto de aplicación de Azure Sphere contiene más detalles sobre el manifiesto de 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 identificador de certificado es una cadena de 1-16 caracteres que identifica de forma única el certificado en el dispositivo. Los caracteres válidos son 'a'-'z', 'A'-'Z', '0'-'9', el guion (-) y el carácter de subrayado (_). Cada identificador de certificado debe ser único en todo 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: por la API CertStore , la API WifiConfig y la CLI de azsphere. Por lo tanto, si carga un certificado desde la línea de comandos, las aplicaciones que consultan, mueven o eliminan ese certificado deben utilizar el mismo identificador. Del mismo modo, si una aplicación carga el certificado, cualquier comando azsphere que manipule el certificado debe usar el mismo identificador. Si instala un nuevo certificado con el mismo identificador que un certificado existente del tipo que sea, el nuevo certificado sobrescribirá el existente.

Precaución

Dado que los identificadores de certificado tienen como ámbito todo el sistema, tanto para los certificados de cliente como para los de CA raíz, un comando azsphere o una llamada de función que agrega un certificado nuevo pueden sobrescribir un certificado agregado por un comando o una llamada de función anteriores, lo que podría producir errores de conexión de red. Se recomienda que desarrolle unos procedimientos de actualización de certificados claros y elija cuidadosamente los identificadores de certificado.

Incorporación de un nuevo 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 consta de un certificado público y de una clave privada.
• CertStore_InstallRootCACertificate instala un certificado de CA raíz que consta de un certificado público.

El certificado debe estar presente en el dispositivo antes de que la aplicación pueda instalarlo. Los certificados deben seguir la sintaxis PKCS1 o PKCS8 y tener el formato .pem para cargarse en el dispositivo Azure Sphere. En Adquisición e implementación de certificados para redes EAP-TLS se describe cómo adquirir certificados y cargarlos en un dispositivo. Microsoft no proporciona certificados.

La instalación de un certificado lo agrega al almacén de certificados y hace que esté disponible para la autenticación. En el almacén de certificados, estos se administran por índice y se pueden recuperar por índice. El intervalo de valores de índice va de 0 a (CertStore_GetCertificateCount-1).

Una aplicación puede obtener el identificador del certificado en un índice determinado mediante una llamada a la función CertStore_GetCertificateIdentifierAt. Después, puede usar el identificador de certificado en las llamadas para obtener información sobre el certificado, para moverlo o eliminarlo, y usar un certificado para la autenticación.

Obtención de información sobre certificados

CertStore API incluye varias funciones que devuelven información acerca de un certificado almacenado:

• CertStore_GetCertificateNotBefore obtiene la hora a la que el certificado pasa a ser válido.
• CertStore_GetCertificateNotAfter obtiene la hora a la 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 protege el certificado.

Las horas no anteriores y no posteriores son útiles para administrar la duración y las actualizaciones de los certificados. Consulte Ciclo de vida y renovación del certificado para más información.

Cambio de nombre o eliminación de un certificado

Para cambiar el nombre o eliminar un certificado, una aplicación llama a CertStore_MoveCertificate o CertStore_DeleteCertificate.

CertStore_MoveCertificate cambia el nombre de un certificado al modificar su identificador de certificado. Como los identificadores de certificado deben ser únicos en un dispositivo, si cambia el nombre de un certificado asignándole el mismo identificador que el de otro certificado, se eliminará dicho certificado. Por ejemplo, si el almacén de certificados contiene MyCert y YourCert, al mover MyCert a YourCert, se obtiene un certificado único con el identificador YourCert, que contiene los datos del valor MyCert anterior. No se devuelve ningún error.

CertStore_DeleteCertificate elimina un único certificado. Al eliminar un certificado, se vuelven a indexar los certificados restantes, empezando por 0. Por lo tanto, para eliminar todos los certificados del almacén de certificados, debe crear un bucle en función del número de certificados, así como eliminar el certificado en el índice 0 en cada iteración. Si intenta eliminar un certificado de un índice que ya no está en uso, CertStore_GetCertificateIdentifierAt devuelve ERANGE.

El método siguiente funciona correctamente:

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

Uso de un certificado para la autenticación de red

WifiConfig API proporciona funciones que establecen y devuelven los certificados que están habilitados para una configuración de Wi-Fi concreta. Consulte Configuración de una red EAP-TLS en una aplicación para más información sobre cómo puede configurar una aplicación de alto nivel una red EAP-TLS que utilice certificados para la autenticación.

Ejemplo de certificado

La aplicación de ejemplos de certificados muestra cómo puede una aplicación usar las funciones CertStore.