Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Portabilidad de la biblioteca corePKCS11 El estándar de criptografía de clave pública 11 define una API independiente de la plataforma para administrar y usar tokens criptográficos. [PKCS 11](https://en.wikipedia.org/wiki/PKCS_11) hace referencia al estándar y a las API que define. La API criptográfica de PKCS 11 abstrae propiedades get/set, de almacenamiento de claves para objetos criptográficos y semántica de la sesión. Se usa ampliamente para manipular objetos criptográficos comunes. Sus funciones permiten al software de la aplicación utilizar, crear, modificar y eliminar objetos criptográficos sin exponerlos a la memoria de la aplicación. Las bibliotecas FreeRTOS y las integraciones de referencia utilizan un subconjunto del estándar de interfaz PCKS 11 y se centran en las operaciones que implican claves asimétricas, generación de números aleatorios y hash. En la siguiente tabla se enumeran los casos de uso y las API PKCS 11 necesarias para su compatibilidad. **Casos de uso** | Caso de uso | Familia de API PKCS 11 necesaria | | --- | --- | | Todos | Initialize, Finalize, Open/Close Session, GetSlotList, Login | | Aprovisionar | GenerateKeyPair, CreateObject, DestroyObject, InitToken, GetTokenInfo | | TLS | Random, Sign, FindObject, GetAttributeValue | | FreeRTOS\$1TCP | Random, Digest | | OTA | Verify, Digest, FindObject, GetAttributeValue | ## Cuándo implementar un módulo PKCS 11 completo Almacenar claves privadas en una memoria flash de uso general puede resultar práctico en entornos de evaluación y creación rápida de prototipos. Le recomendamos que utilice hardware criptográfico dedicado para reducir las amenazas de robo de datos y duplicación de dispositivos en escenarios de producción. El hardware criptográfico incluye componentes con características que impiden la exportación de las claves criptográficas secretas. Para ello, tendrá que implementar un subconjunto de PKCS 11 necesario para trabajar con las bibliotecas de FreeRTOS, tal y como se define en la tabla anterior. ## Cuándo se debe usar FreeRTOS corePKCS11 La biblioteca corePKCS11 contiene una implementación basada en software de la interfaz (API) PKCS 11 que utiliza la funcionalidad criptográfica proporcionada por [Mbed TLS](https://tls.mbed.org/). Se proporciona para escenarios de creación rápida de prototipos y evaluación en los que el hardware no tiene un hardware criptográfico dedicado. En este caso, solo tiene que implementar corePKCS11 PAL para que la implementación basada en software de corePKCS11 funcione con su plataforma de hardware. ## Portabilidad de corePKCS11 Deberá disponer de implementaciones para leer y escribir objetos criptográficos en la memoria no volátil (NVM), como la memoria flash integrada. Los objetos criptográficos deben almacenarse en una sección de la NVM que no esté inicializada y que no se borre en caso de reprogramación del dispositivo. Los usuarios de la biblioteca corePKCS11 deben poder aprovisionar los dispositivos con credenciales para reprogramarlos con una nueva aplicación que tendrá acceso a esas credenciales a través de la interfaz corePKCS11. Los puertos PAL de corePKCS11 deben proporcionar una ubicación para almacenar: + El certificado de cliente del dispositivo + La clave privada de cliente del dispositivo + La clave pública de cliente del dispositivo + Una CA raíz de confianza + Una clave pública de verificación de código (o un certificado que contenga la clave pública de verificación de código) para actualizaciones seguras del cargador de arranque y vía inalámbrica (OTA). + Un certificado de aprovisionamiento justo a tiempo Incluya [el archivo de encabezado](https://github.com/FreeRTOS/corePKCS11/blob/main/source/include/core_pkcs11_pal.h) e implemente las API PAL definidas. **API PAL** | Función | Descripción | | --- | --- | | PKCS11\$1PAL\$1Initialize | Inicializa la capa de PAL. La biblioteca corePKCS11 la llama al comienzo de su secuencia de inicialización. | | PKCS11\$1PAL\$1SaveObject | Escribe datos en almacenamiento no volátil. | | PKCS11\$1PAL\$1FindObject | Utiliza una etiqueta `CKA_LABEL` de PKCS \$111 para buscar el objeto de PKCS \$1 11 correspondiente en el almacenamiento no volátil y devuelve un identificador del mismo, si existe. | | PKCS11\$1PAL\$1GetObjectValue | Obtiene el valor de un objeto a partir del identificador. | | PKCS11\$1PAL\$1GetObjectValueCleanup | Limpieza para la llamada `PKCS11_PAL_GetObjectValue`. Se puede utilizar para liberar la memoria asignada en una llamada `PKCS11_PAL_GetObjectValue`. | ## Testeo Si usa la biblioteca corePKCS11 de FreeRTOS o implementa el subconjunto necesario de API de PKCS11, debe superar las pruebas de PKCS11 de FreeRTOS. Estas prueban si las funciones requeridas para las bibliotecas de FreeRTOS funcionan según lo esperado. En esta sección también se describe cómo puede probar localmente las pruebas de PKCS11 de FreeRTOS con las pruebas de calificación. ### Requisitos previos Para configurar las pruebas de PKCS11 de FreeRTOS, se debe implementar lo siguiente. + Un puerto compatible de las API PKCS11. + Una implementación de las funciones de la plataforma de pruebas de calificación de FreeRTOS, que incluye las siguientes: + `FRTest_ThreadCreate` + `FRTest_ThreadTimedJoin` + `FRTest_MemoryAlloc` + `FRTest_MemoryFree` (Consulte el archivo [ README.md](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11) para ver las pruebas de integración de bibliotecas FreeRTOS para PKCS 11 en GitHub). ### Portabilidad de pruebas + Añada [ FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11) como un submódulo al proyecto. El submódulo se puede colocar en cualquier directorio del proyecto, siempre que se pueda crear. + Copie `config_template/test_execution_config_template.h` y `config_template/test_param_config_template.h` en una ubicación del proyecto en la ruta de creación y cámbieles el nombre a `test_execution_config.h` y `test_param_config.h`. + Incluya los archivos relevantes en el sistema creación. Si utiliza `CMake`, `qualification_test.cmake` y `src/pkcs11_tests.cmake` se pueden usar para incluir los archivos relevantes. + Implemente `UNITY_OUTPUT_CHAR` de forma que los registros de salida de las pruebas y los registros del dispositivo no se intercalen. + Integre el MbedTLS, que verifica el resultado de la operación cryptoki. + Llame a `RunQualificationTest()` desde la aplicación. ### Configuración de las pruebas El conjunto de pruebas PKCS11 debe configurarse de acuerdo con la implementación de PKCS11. La siguiente tabla muestra la configuración requerida para las pruebas PKCS11 en el archivo de encabezado `test_param_config.h`. **Configuraciones de las pruebas PKSC11** | Configuración | Descripción | | --- | --- | | PKCS11\$1TEST\$1RSA\$1KEY\$1SUPPORT | La portabilidad admite las funciones clave de RSA. | | PKCS11\$1TEST\$1EC\$1KEY\$1SUPPORT | La portabilidad admite las funciones clave de EC. | | PKCS11\$1TEST\$1IMPORT\$1PRIVATE\$1KEY\$1SUPPORT | La portabilidad admite la importación de la clave privada. La importación de claves RSA y EC se valida en la prueba si las funciones clave auxiliares están habilitadas. | | PKCS11\$1TEST\$1GENERATE\$1KEYPAIR\$1SUPPORT | La portabilidad admite la generación de pares de claves. La importación de pares de claves EC se valida en la prueba si las funciones clave auxiliares están habilitadas. | | PKCS11\$1TEST\$1PREPROVISIONED\$1SUPPORT | La portabilidad tiene credenciales previamente aprovisionadas. `PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`, `PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS` y `PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS` son ejemplos de las credenciales. | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1PRIVATE\$1KEY\$1FOR\$1TLS | La etiqueta de la clave privada utilizada en la prueba. | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1PUBLIC\$1KEY\$1FOR\$1TLS | La etiqueta de la clave pública utilizada en la prueba. | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1CERTIFICATE\$1FOR\$1TLS | La etiqueta del certificado utilizado en la prueba. | | PKCS11\$1TEST\$1JITP\$1CODEVERIFY\$1ROOT\$1CERT\$1SUPPORTED | La portabilidad admite el almacenamiento de JITP. Establézcalo en 1 para habilitar la prueba `codeverify` de JITP. | | PKCS11\$1TEST\$1LABEL\$1CODE\$1VERIFICATION\$1KEY | La etiqueta de la clave de verificación de código utilizada en la prueba `codeverify` de JITP. | | PKCS11\$1TEST\$1LABEL\$1JITP\$1CERTIFICATE | La etiqueta del certificado de JITP utilizado en la prueba `codeverify` de JITP. | | PKCS11\$1TEST\$1LABEL\$1ROOT\$1CERTIFICATE | La etiqueta del certificado raíz utilizado en la prueba `codeverify` de JITP. | Las bibliotecas FreeRTOS y las integraciones de referencia deben admitir como mínimo una configuración de función de clave, como las claves de curva elíptica o RSA, y un mecanismo de aprovisionamiento de clave compatible con las API PKCS11. La prueba debe habilitar las siguientes configuraciones: + Al menos una de las siguientes configuraciones de funciones de clave: + PKCS11\$1TEST\$1RSA\$1KEY\$1SUPPORT + PKCS11\$1TEST\$1EC\$1KEY\$1SUPPORT + Al menos una de las siguientes configuraciones de aprovisionamiento de clave: + PKCS11\$1TEST\$1IMPORT\$1PRIVATE\$1KEY\$1SUPPORT + PKCS11\$1TEST\$1GENERATE\$1KEYPAIR\$1SUPPORT + PKCS11\$1TEST\$1PREPROVISIONED\$1SUPPORT La prueba de credenciales del dispositivo aprovisionada previamente debe ejecutarse en las siguientes condiciones: + `PKCS11_TEST_PREPROVISIONED_SUPPORT` debe estar activado y otros mecanismos de aprovisionamiento inhabilitados. + Solo debe estar habilitada una función: `PKCS11_TEST_RSA_KEY_SUPPORT` o `PKCS11_TEST_EC_KEY_SUPPORT`. + Configure las etiquetas de clave previamente aprovisionadas de acuerdo con su función de clave, incluidas `PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`, `PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS` y `PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS`. Estas credenciales deben existir antes de ejecutar la prueba. Es posible que la prueba deba ejecutarse varias veces con diferentes configuraciones, si la implementación admite credenciales previamente aprovisionadas y otros mecanismos de aprovisionamiento. **nota** Los objetos con las etiquetas `PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS`, `PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS` y `PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS` se destruyen durante la prueba si `PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT` o `PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT` está habilitada. ### Ejecución de pruebas En esta sección se describe cómo puede probar localmente la interfaz PKCS11 con las pruebas de calificación. También puede utilizar IDT para automatizar la ejecución. Consulte [AWS IoT Device Tester para FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) en la *Guía del usuario de FreeRTOS* para obtener más información. Las siguientes instrucciones describen cómo ejecutar las pruebas: + Abra `test_execution_config.h` y defina **CORE\$1PKCS11\$1TEST\$1ENABLED** en 1. + Cree e instale la aplicación en su dispositivo para ejecutarla. El resultado de la prueba se envía al puerto serie. A continuación se muestra un ejemplo del resultado de la prueba de salida. ``` TEST(Full_PKCS11_StartFinish, PKCS11_StartFinish_FirstTest) PASS TEST(Full_PKCS11_StartFinish, PKCS11_GetFunctionList) PASS TEST(Full_PKCS11_StartFinish, PKCS11_InitializeFinalize) PASS TEST(Full_PKCS11_StartFinish, PKCS11_GetSlotList) PASS TEST(Full_PKCS11_StartFinish, PKCS11_OpenSessionCloseSession) PASS TEST(Full_PKCS11_Capabilities, PKCS11_Capabilities) PASS TEST(Full_PKCS11_NoObject, PKCS11_Digest) PASS TEST(Full_PKCS11_NoObject, PKCS11_Digest_ErrorConditions) PASS TEST(Full_PKCS11_NoObject, PKCS11_GenerateRandom) PASS TEST(Full_PKCS11_NoObject, PKCS11_GenerateRandomMultiThread) PASS TEST(Full_PKCS11_RSA, PKCS11_RSA_CreateObject) PASS TEST(Full_PKCS11_RSA, PKCS11_RSA_FindObject) PASS TEST(Full_PKCS11_RSA, PKCS11_RSA_GetAttributeValue) PASS TEST(Full_PKCS11_RSA, PKCS11_RSA_Sign) PASS TEST(Full_PKCS11_RSA, PKCS11_RSA_FindObjectMultiThread) PASS TEST(Full_PKCS11_RSA, PKCS11_RSA_GetAttributeValueMultiThread) PASS TEST(Full_PKCS11_RSA, PKCS11_RSA_DestroyObject) PASS TEST(Full_PKCS11_EC, PKCS11_EC_GenerateKeyPair) PASS TEST(Full_PKCS11_EC, PKCS11_EC_CreateObject) PASS TEST(Full_PKCS11_EC, PKCS11_EC_FindObject) PASS TEST(Full_PKCS11_EC, PKCS11_EC_GetAttributeValue) PASS TEST(Full_PKCS11_EC, PKCS11_EC_Sign) PASS TEST(Full_PKCS11_EC, PKCS11_EC_Verify) PASS TEST(Full_PKCS11_EC, PKCS11_EC_FindObjectMultiThread) PASS TEST(Full_PKCS11_EC, PKCS11_EC_GetAttributeValueMultiThread) PASS TEST(Full_PKCS11_EC, PKCS11_EC_SignVerifyMultiThread) PASS TEST(Full_PKCS11_EC, PKCS11_EC_DestroyObject) PASS ----------------------- 27 Tests 0 Failures 0 Ignored OK ``` Las pruebas se completan cuando se superan todas. **nota** Para calificar oficialmente un dispositivo para FreeRTOS, debe validar el código fuente transferido del dispositivo con AWS IoT Device Tester. Siga las instrucciones de [Uso de AWS IoT Device Tester para FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) en la Guía del usuario de FreeRTOS para configurar AWS IoT Device Tester para la validación de la portabilidad. Para probar la portabilidad de una biblioteca concreta, se debe habilitar el grupo de pruebas correcto en el archivo `device.json` de la carpeta `configs` de AWS IoT Device Tester.