Portabilidade da biblioteca corePKCS11

O Padrão de criptografia de chave pública #11 define uma API independente de plataforma para gerenciar e usar tokens criptográficos. O PKCS 11 se refere ao padrão e APIs definida por ele. A API criptográfica de PKCS #11 abstrai armazenamento de chaves, propriedades de obtenção/definição para objetos criptográficos e semântica de sessão. É amplamente usado para manipular objetos criptográficos comuns. Suas funções permitem que o software de aplicativo use, crie, modifique e exclua objetos criptográficos, sem expor esses objetos à memória do aplicativo.

As bibliotecas e integrações de referência do FreeRTOS usam um subconjunto do padrão de interface PCKS #11, com foco nas operações que envolvem chaves assimétricas, geração de números aleatórios e hashing. A tabela abaixo lista os casos de uso e as APIs de PKCS #11 necessárias para oferecer suporte.

Casos de uso
Caso de uso	Família de API com PKCS #11 necessária
Tudo	Initialize, Finalize, Open/Close Session, GetSlotList, Login
Provisionamento	GenerateKeyPair, CreateObject, DestroyObject, initToken, GetTokenInfo
TLS	Random, Sign, FindObject, GetAttributeValue
FreeRTOS+TCP	Random, Digest
OTA	Verificação, resumo, FindObject, GetAttributeValue

Quando implementar um módulo PKCS #11 completo

O armazenamento de chaves privadas na memória flash de uso geral pode ser conveniente em cenários de avaliação e de prototipagem rápida. Recomendamos o uso de hardware criptográfico dedicado para reduzir as ameaças de roubo de dados e duplicação de dispositivos em cenários de produção. O hardware criptográfico inclui componentes com recursos que impedem que as chaves secretas criptográficas sejam exportadas. Para oferecer suporte a isso, você precisará implementar um subconjunto de PKCS #11 necessário para trabalhar com bibliotecas FreeRTOS, conforme definido na tabela acima.

Quando usar a corePKCS11 do FreeRTOS

A biblioteca corePKCS11 contém uma implementação baseada em software da interface PKCS #11 (API) que usa a funcionalidade criptográfica fornecida pelo TLS Mbed. Isso é fornecido para cenários rápidos de prototipagem e avaliação em que o hardware não tem um hardware criptográfico dedicado. Nesse caso, você só precisa implementar a PAL corePKCS11 para fazer com que a implementação baseada em software corePKCS11 funcione com sua plataforma de hardware.

Portabilidade da corePKCS11

Será necessário ter implementações para ler e gravar objetos criptográficos na memória não volátil (NVM), como a memória flash integrada. Os objetos criptográficos precisam ser armazenados em uma seção da NVM que não tenha sido inicializada e não seja apagada na reprogramação do dispositivo. Os usuários da biblioteca corePKCS11 provisionarão dispositivos com credenciais e reprogramarão o dispositivo com um novo aplicativo que acesse essas credenciais por meio da interface corePKCS11. As portas PAL corePKCS11 devem fornecer um local para armazenar:

• O certificado de cliente do dispositivo

• A chave privada de cliente do dispositivo

• A chave pública de cliente do dispositivo

• Uma CA raiz confiável

• Uma chave pública de verificação de código (ou um certificado que contém a chave pública de verificação de código) para atualizações seguras do carregador de inicializações e sem fios

• Um certificado de provisionamento just-in-time

Inclua o arquivo de cabeçalho e implemente as APIs PAL definidas.

APIs PAL
Função	Descrição
PKCS11_PAL_Initialize	Inicializa a camada PAL. Chamado pela biblioteca corePKCS11 no início da sequência de inicialização.
PKCS11_PAL_SaveObject	Grava dados no armazenamento não volátil.
PKCS11_PAL_FindObject	Usa um CKA_LABEL PKCS #11 para procurar um objeto PKCS #11 correspondente no armazenamento não volátil e retorna o identificador desse objeto, se existir.
PKCS11_PAL_GetObjectValue	Recupera o valor de um objeto, considerando o identificador.
PKCS11_PAL_GetObjectValueCleanup	Limpeza da chamada PKCS11_PAL_GetObjectValue. Pode ser usada para liberar memória alocada em uma chamada PKCS11_PAL_GetObjectValue.

Testes

Se você usar a biblioteca corePKCS11 do FreeRTOS ou implementar o subconjunto necessário de APIs de PKCS11, deverá passar nos testes do PKCS11 do FreeRTOS. Eles testam se as funções necessárias para as bibliotecas FreeRTOS funcionam conforme o esperado.

Esta seção também descreve como você pode executar localmente os testes PKCS11 do FreeRTOS com os testes de qualificação.

Pré-requisitos

Para configurar os testes PKCS11 do FreeRTOS, deve-se implementar o seguinte.

• Uma porta compatível com as APIs PKCS11.

• Uma implementação das funções da plataforma de testes de qualificação do FreeRTOS, que incluem o seguinte:

  • FRTest_ThreadCreate

  • FRTest_ThreadTimedJoin

  • FRTest_MemoryAlloc

  • FRTest_MemoryFree

(Consulte o arquivo README.md para os testes de integração de bibliotecas FreeRTOS para PKCS #11 no GitHub.)

Testes de portabilidade

• Adicione FreeRTOS-Libraries-Integration-Tests como um submódulo em seu projeto. O submódulo pode ser colocado em qualquer diretório do projeto, desde que possa ser compilado.

• Copie config_template/test_execution_config_template.h e config_template/test_param_config_template.h para um local do projeto no caminho de compilação e renomeie-os para test_execution_config.h e test_param_config.h.

• Inclua os arquivos relevantes no sistema de compilação. Se estiver usando CMake, qualification_test.cmake e src/pkcs11_tests.cmake podem ser usados para incluir os arquivos relevantes.

• Implemente UNITY_OUTPUT_CHAR para que os logs de saída do teste e logs do dispositivo não se intercalem.

• Integre o MbedTLS, que verifica o resultado da operação cryptoki.

• Chame RunQualificationTest() do aplicativo.

Configuração de testes

O conjunto de testes PKCS11 deve ser configurado de acordo com a implementação do PKCS11. A tabela a seguir lista a configuração exigida pelos testes PKCS11 no arquivo de cabeçalho test_param_config.h.

Configurações de teste PKSC11
Configuração	Descrição
PKCS11_TEST_RSA_KEY_SUPPORT	A portabilidade oferece suporte às funções de chave do RSA.
PKCS11_TEST_EC_KEY_SUPPORT	A portabilidade oferece suporte às funções de chave de EC.
PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT	A portabilidade oferece suporte à importação da chave privada. A importação de chaves RSA e EC é validada no teste se o suporte às funções de chave estiver habilitado.
PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT	A portabilidade oferece suporte às geração de pares de chaves. A geração de pares de chaves EC é validada no teste se o suporte às funções de chave estiver habilitado.
PKCS11_TEST_PREPROVISIONED_SUPPORT	A portabilidade tem credenciais pré-provisionadas. PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS, PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS e PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS, são exemplos das credenciais.
PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS	O rótulo da chave privada usada no teste.
PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS	O rótulo da chave pública usada no teste.
PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS	O rótulo do certificado usado no teste.
PKCS11_TEST_JITP_CODEVERIFY_ROOT_CERT_SUPPORTED	A portabilidade oferece suporte ao armazenamento de JITP. Defina isso como 1 para ativar o teste codeverify de JITP.
PKCS11_TEST_LABEL_CODE_VERIFICATION_KEY	O rótulo da chave de verificação de código usada no teste codeverify de JITP.
PKCS11_TEST_LABEL_JITP_CERTIFICATE	O rótulo do certificado JITP usado no teste codeverify de JITP.
PKCS11_TEST_LABEL_ROOT_CERTIFICATE	O rótulo do certificado raiz usado no teste codeverify de JITP.

As bibliotecas e integrações de referência do FreeRTOS devem oferecer suporte a no mínimo uma configuração de função de chave, como chaves de Curva elíptica ou RSA, e um mecanismo de provisionamento de teclas compatível com as APIs de PKCS11. O teste deve habilitar as seguintes configurações:

• Pelo menos uma das configurações de função de chave a seguir:

  • PKCS11_TEST_RSA_KEY_SUPPORT

  • PKCS11_TEST_EC_KEY_SUPPORT

• Pelo menos uma das configurações de provisionamento de chave a seguir:

  • PKCS11_TEST_IMPORT_PRIVATE_KEY_SUPPORT

  • PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT

  • PKCS11_TEST_PREPROVISIONED_SUPPORT

O teste de credencial do dispositivo pré-provisionado deve ser executado sob as seguintes condições:

• PKCS11_TEST_PREPROVISIONED_SUPPORT devem estar habilitados e outros mecanismos de provisionamento desativados.

• Ter somente uma função de chave, PKCS11_TEST_RSA_KEY_SUPPORT ou PKCS11_TEST_EC_KEY_SUPPORT está ativada.

• Configure os rótulos de chave pré-provisionados de acordo com a função de chave, incluindo PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS, PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS e PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS. Essas credenciais devem existir antes de executar o teste.

É aconselhável executar o teste várias vezes em configurações diferentes, se a implementação oferecer suporte a credenciais pré-provisionadas e outros mecanismos de provisionamento.

nota

Os objetos com rótulos PKCS11_TEST_LABEL_DEVICE_PRIVATE_KEY_FOR_TLS, PKCS11_TEST_LABEL_DEVICE_PUBLIC_KEY_FOR_TLS e PKCS11_TEST_LABEL_DEVICE_CERTIFICATE_FOR_TLS serão destruídos durante o teste se PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT ou PKCS11_TEST_GENERATE_KEYPAIR_SUPPORT estiverem habilitados.

Execução de testes

Esta seção descreve como você pode testar localmente a interface de PKCS11 com os testes de qualificação. Como alternativa, você também pode usar o IDT para automatizar a execução. Consulte o AWS IoT Device Tester para o FreeRTOS no Guia do usuário do FreeRTOS para obter detalhes.

As instruções a seguir descrevem como executar os testes:

• Abra test_execution_config.h e defina CORE_PKCS11_TEST_ENABLED como 1.

• Compile e atualize o aplicativo em seu dispositivo para ser executado. Os resultados do teste são enviados para a porta serial.

Confira a seguir um exemplo do resultado do teste de saída.

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
    

O teste será concluído quando todos os testes forem aprovados.

nota

Para qualificar oficialmente um dispositivo para o FreeRTOS, é necessário validar o código-fonte transferido do dispositivo com o AWS IoT Device Tester. Siga as instruções em Usar o AWS IoT Device Tester para FreeRTOS no Guia do usuário do FreeRTOS para configurar o AWS IoT Device Tester para validação de porta. Para testar a portabilidade de uma biblioteca específica, o grupo de testes correto deve ser habilitado no arquivo device.json na pasta do AWS IoT Device Tester configs.