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 \#11 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 PKCS \#11 abstrai o armazenamento de chaves, get/set as propriedades dos objetos criptográficos e a semântica da 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 \#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 | | --- | --- | | Todos | Inicializar, finalizar, Open/Close sessão, login GetSlotList | | Provisionamento | GenerateKeyPair, CreateObject, DestroyObject, InitToken, GetTokenInfo | | TLS | Aleatório, sinal FindObject, GetAttributeValue | | FreeRTOS\+TCP | Random, Digest | | OTA | Verificar, digerir, 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](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 Just-In-Time aprovisionamento 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 | Description | | --- | --- | | 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`. | ## Teste 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` (Veja o [ README.md](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/tree/main/src/pkcs11)arquivo dos Testes de Integração de Bibliotecas FreeRTOS para PKCS \#11 em.) 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 ao 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 | Description | | --- | --- | | 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](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\_PKCS11\_TEST\_ENABLED** 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 FreeRTOS, você deve validar o código-fonte portado do dispositivo com. AWS IoT Device Tester Siga as instruções em [Usando o FreeRTOS no Guia do Usuário do FreeRTOS AWS IoT Device Tester para](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) configurar a validação de portas. AWS IoT Device Tester Para testar a porta de uma biblioteca específica, o grupo de teste correto deve estar habilitado no `device.json` arquivo na AWS IoT Device Tester `configs` pasta.