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 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+TCP	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. 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 PKCS11. 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 e inalámbricas (OTA).

• Un certificado de aprovisionamiento justo a tiempo

Incluya el archivo de encabezado e implemente las API PAL definidas.

API PAL
Función	Descripción
PKCS11_PAL_Initialize	Inicializa la capa de PAL. La biblioteca corePKCS11 la llama al comienzo de su secuencia de inicialización.
PKCS11_PAL_SaveObject	Escribe datos en almacenamiento no volátil.
PKCS11_PAL_FindObject	Utiliza una etiqueta CKA_LABEL de PKCS #11 para buscar el objeto de PKCS # 11 correspondiente en el almacenamiento no volátil y devuelve un identificador del mismo, si existe.
PKCS11_PAL_GetObjectValue	Obtiene el valor de un objeto a partir del identificador.
PKCS11_PAL_GetObjectValueCleanup	Limpieza para la llamada PKCS11_PAL_GetObjectValue. Se puede utilizar para liberar la memoria asignada en una llamada PKCS11_PAL_GetObjectValue.

Pruebas

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 para ver las pruebas de integración de bibliotecas FreeRTOS para PKCS 11 en GitHub).

Portabilidad de pruebas

• Añada FreeRTOS-Libraries-Integration-Tests 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_TEST_RSA_KEY_SUPPORT	La portabilidad admite las funciones clave de RSA.
PKCS11_TEST_EC_KEY_SUPPORT	La portabilidad admite las funciones clave de EC.
PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT	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_TEST_GENERATE_KEYPAIR_SUPPORT	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_TEST_PREPROVISIONED_SUPPORT	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_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS	La etiqueta de la clave privada utilizada en la prueba.
PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS	La etiqueta de la clave pública utilizada en la prueba.
PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS	La etiqueta del certificado utilizado en la prueba.
PKCS11_TEST_JITP_CODEVERIFY_ROOT_CERT_SUPPORTED	La portabilidad admite el almacenamiento de JITP. Establézcalo en 1 para habilitar la prueba codeverify de JITP.
PKCS11_TEST_LABEL_CODE_VERIFICATION_KEY	La etiqueta de la clave de verificación de código utilizada en la prueba codeverify de JITP.
PKCS11_TEST_LABEL_JITP_CERTIFICATE	La etiqueta del certificado de JITP utilizado en la prueba codeverify de JITP.
PKCS11_TEST_LABEL_ROOT_CERTIFICATE	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_TEST_RSA_KEY_SUPPORT

  • PKCS11_TEST_EC_KEY_SUPPORT

• Al menos una de las siguientes configuraciones de aprovisionamiento de clave:

  • PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT

  • PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT

  • PKCS11_TEST_PREPROVISIONED_SUPPORT

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 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_PKCS11_TEST_ENABLED 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 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.