As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Portabilidade da biblioteca corePKCS11 O Padrão de criptografia de chave pública \$111 define uma API independente de plataforma para gerenciar e usar tokens criptográficos. O [PKCS 11](https://en.wikipedia.org/wiki/PKCS_11) se refere ao padrão e APIs definida por ele. A API criptográfica de PKCS \$111 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 da aplicação use, crie, modifique e exclua objetos criptográficos, sem expor esses objetos à memória da aplicação. As bibliotecas e integrações de referência do FreeRTOS usam um subconjunto do padrão de interface PCKS \$111, 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 \$111 necessárias para oferecer suporte. **Casos de uso** | Caso de uso | Família de API com PKCS \$111 necessária | | --- | --- | | Todos | Initialize, Finalize, Open/Close Session, GetSlotList, Login | | Provisionamento | GenerateKeyPair, CreateObject, DestroyObject, initToken, GetTokenInfo | | TLS | Random, Sign, FindObject, GetAttributeValue | | FreeRTOS\$1TCP | Random, Digest | | OTA | Verificação, resumo, FindObject, GetAttributeValue | ## Quando implementar um módulo PKCS \$111 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 \$111 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 \$111 (API) que usa a funcionalidade criptográfica fornecida pelo [TLS Mbed](https://tls.mbed.org/). 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 uma nova aplicação 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](https://github.com/FreeRTOS/corePKCS11/blob/main/source/include/core_pkcs11_pal.h) e implemente as APIs PAL definidas. **APIs PAL** | Função | Descrição | | --- | --- | | PKCS11\$1PAL\$1Initialize | Inicializa a camada PAL. Chamado pela biblioteca corePKCS11 no início da sequência de inicialização. | | PKCS11\$1PAL\$1SaveObject | Grava dados no armazenamento não volátil. | | PKCS11\$1PAL\$1FindObject | Usa um `CKA_LABEL` PKCS \$111 para procurar um objeto PKCS \$111 correspondente no armazenamento não volátil e retorna o identificador desse objeto, se existir. | | PKCS11\$1PAL\$1GetObjectValue | Recupera o valor de um objeto, considerando o identificador. | | PKCS11\$1PAL\$1GetObjectValueCleanup | Limpeza da chamada `PKCS11_PAL_GetObjectValue`. Pode ser usada para liberar memória alocada em uma chamada `PKCS11_PAL_GetObjectValue`. | ## Testar 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](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11) para os testes de integração de bibliotecas FreeRTOS para PKCS \$111 no GitHub.) ### Testes de portabilidade + Adicione [ FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11) 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()` da aplicação. ### 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\$1TEST\$1RSA\$1KEY\$1SUPPORT | A portabilidade oferece suporte às funções de chave do RSA. | | PKCS11\$1TEST\$1EC\$1KEY\$1SUPPORT | A portabilidade oferece suporte às funções de chave de EC. | | PKCS11\$1TEST\$1IMPORT\$1PRIVATE\$1KEY\$1SUPPORT | 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\$1TEST\$1GENERATE\$1KEYPAIR\$1SUPPORT | 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\$1TEST\$1PREPROVISIONED\$1SUPPORT | 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\$1TEST\$1LABEL\$1DEVICE\$1PRIVATE\$1KEY\$1FOR\$1TLS | O rótulo da chave privada usada no teste. | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1PUBLIC\$1KEY\$1FOR\$1TLS | O rótulo da chave pública usada no teste. | | PKCS11\$1TEST\$1LABEL\$1DEVICE\$1CERTIFICATE\$1FOR\$1TLS | O rótulo do certificado usado no teste. | | PKCS11\$1TEST\$1JITP\$1CODEVERIFY\$1ROOT\$1CERT\$1SUPPORTED | A portabilidade oferece suporte ao armazenamento de JITP. Defina isso como 1 para ativar o teste `codeverify` de JITP. | | PKCS11\$1TEST\$1LABEL\$1CODE\$1VERIFICATION\$1KEY | O rótulo da chave de verificação de código usada no teste `codeverify` de JITP. | | PKCS11\$1TEST\$1LABEL\$1JITP\$1CERTIFICATE | O rótulo do certificado JITP usado no teste `codeverify` de JITP. | | PKCS11\$1TEST\$1LABEL\$1ROOT\$1CERTIFICATE | 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\$1TEST\$1RSA\$1KEY\$1SUPPORT + PKCS11\$1TEST\$1EC\$1KEY\$1SUPPORT + Pelo menos uma das configurações de provisionamento de chave a seguir: + PKCS11\$1TEST\$1IMPORT\$1PRIVATE\$1KEY\$1SUPPORT + PKCS11\$1TEST\$1GENERATE\$1KEYPAIR\$1SUPPORT + PKCS11\$1TEST\$1PREPROVISIONED\$1SUPPORT 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](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) 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\$1PKCS11\$1TEST\$1ENABLED** como 1. + Compile e atualize a aplicação em seu dispositivo para ser executada. 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](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) 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`.