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á. # API de criptografia: próxima geração (CNG) e provedores de armazenamento de chaves (KSP) para AWS CloudHSM O AWS CloudHSM cliente para Windows inclui provedores de CNG e KSP. *Os provedores de armazenamento de chaves* (KSPs) permitem o armazenamento e a recuperação de chaves. Por exemplo, se você adicionar a função Microsoft Active Directory Certificate Services (AD CS) ao Windows Server e optar por criar uma nova chave privada da sua autoridade de certificação (CA), poderá escolher o KSP que gerenciará o armazenamento de chaves. Quando você configurar a função AD CS, poderá escolher este KSP. Para obter mais informações, consulte [Criar CA do Windows Server](win-ca-overview-sdk5.md#win-ca-setup-sdk5). *Cryptography API: Next Generation (CNG)* é uma API de criptografia específica para o sistema operacional Microsoft Windows. O CNG permite que os desenvolvedores usem técnicas de criptografia para proteger aplicativos baseados em Windows. Em um alto nível, a AWS CloudHSM implementação do CNG fornece as seguintes funcionalidades: + **Primitivos de criptografia**: permite que você execute operações de criptografia fundamentais. + **Importação e exportação de chave**: permite que você importe e exporte chaves assimétricas. + **API de proteção de dados (CNG DPAPI)**: permite que você facilmente criptografe e descriptografe os dados. + **Armazenamento e recuperação de chave**: permite armazenar com segurança e isolar a chave privada de um par de chaves assimétricas. **Topics** + [Verifique os provedores de KSP e CNG para AWS CloudHSM](ksp-v3-library-install.md) + [Pré-requisitos para usar o Windows Client AWS CloudHSM](ksp-library-prereq.md) + [Associar uma AWS CloudHSM chave a um certificado](ksp-library-associate-key-certificate.md) + [Exemplo de código para provedor de GNV para AWS CloudHSM](ksp-library-sample.md) # Verifique os provedores de KSP e CNG para AWS CloudHSM Os provedores KSP e CNG são instalados quando você instala o cliente Windows AWS CloudHSM . Você pode instalar o cliente seguindo as etapas em [Instalar o cliente (Windows)](kmu-install-and-configure-client-win.md). Use as seções a seguir para verificar a instalação dos provedores. ## Configurar e executar o AWS CloudHSM cliente Windows Para iniciar o cliente do Windows CloudHSM, primeiro você deve estar de acordo com o [Pré-requisitos](ksp-library-prereq.md). Depois, atualize os arquivos de configuração que os provedores usam e inicie o cliente concluindo as etapas abaixo. Você precisa executar essas etapas na primeira vez em que usar os provedores KSP e CNG e depois de adicionar ou remover HSMs no seu cluster. Dessa forma, AWS CloudHSM é capaz de sincronizar dados e manter a consistência em tudo HSMs no cluster. ### Etapa 1: interromper o AWS CloudHSM cliente Antes de atualizar os arquivos de configuração que os provedores usam, interrompa o AWS CloudHSM cliente. Se o cliente já estiver parado, executar o comando stop não terá efeitos. + Para clientes Windows 1.1.2\$1: ``` C:\Program Files\Amazon\CloudHSM>net.exe stop AWSCloudHSMClient ``` + Para o cliente Windows 1.1.1 e anterior: Use **Ctrl** \$1 **C** na janela de comando em que você iniciou o AWS CloudHSM cliente. ### Etapa 2: atualizar os arquivos AWS CloudHSM de configuração Essa etapa usa o `-a` parâmetro da [ferramenta Configure](configure-tool.md) para adicionar o endereço IP da elastic network interface (ENI) de um dos HSMs no cluster ao arquivo de configuração. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" -a ``` Para obter o endereço IP ENI de um HSM em seu cluster, navegue até o AWS CloudHSM console, escolha **clusters** e selecione o cluster desejado. Você também pode usar a [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html)operação, o comando [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html) ou o cmdlet. [Get-HSM2Cluster](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-HSM2Cluster.html) PowerShell Digite somente um endereço IP ENI. Não importa qual endereço IP ENI você utilize. ### Etapa 3: iniciar o AWS CloudHSM cliente Em seguida, inicie ou reinicie o AWS CloudHSM cliente. Quando o AWS CloudHSM cliente inicia, ele usa o endereço IP ENI em seu arquivo de configuração para consultar o cluster. Em seguida, ele adiciona os endereços IP ENI de todos HSMs no cluster ao arquivo de informações do cluster. + Para clientes Windows 1.1.2\$1: ``` C:\Program Files\Amazon\CloudHSM>net.exe start AWSCloudHSMClient ``` + Para o cliente Windows 1.1.1 e anterior: ``` C:\Program Files\Amazon\CloudHSM>start "cloudhsm_client" cloudhsm_client.exe C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg ``` ## Verificar os provedores KSP e CNG Você pode usar um dos seguintes comandos para determinar quais provedores são instalados no seu sistema. Os comandos listam os provedores de KSP e CNG registrados. O cliente do AWS CloudHSM não precisa estar em execução. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\ksp_config.exe" -enum ``` ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\cng_config.exe" -enum ``` Para verificar se os provedores KSP e CNG estão instalados na sua instância EC2 do Windows Server, você deve ver as seguintes entradas na lista: ``` Cavium CNG Provider Cavium Key Storage Provider ``` Se o provedor CNG estiver ausente, execute o comando a seguir. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\cng_config.exe" -register ``` Se o provedor KSP estiver ausente, execute o comando a seguir. ``` PS C:\> & "C:\Program Files\Amazon\CloudHSM\ksp_config.exe" -register ``` # Pré-requisitos para usar o Windows Client AWS CloudHSM Antes de iniciar o AWS CloudHSM cliente Windows e usar os provedores KSP e CNG, você deve definir as credenciais de login para o HSM em seu sistema. Você pode definir as credenciais por meio do Gerenciador de credenciais do Windows ou da variável de ambiente do sistema. Recomendamos que você use o Gerenciador de credenciais do Windows para armazenar as credenciais. Essa opção está disponível com a versão 2.0.4 e posterior do AWS CloudHSM cliente. O uso da variável de ambiente é mais fácil de configurar, mas é menos seguro do que o uso do Gerenciador de credenciais do Windows. ## Gerenciador de credenciais do Windows Você pode usar o utilitário `set_cloudhsm_credentials` ou a interface do Gerenciador de credenciais do Windows. + **Usar o utilitário `set_cloudhsm_credentials`**: O utilitário `set_cloudhsm_credentials` está incluído no instalador do Windows. É possível usar esse utilitário para passar convenientemente as credenciais de login do HSM para o Gerenciador de credenciais do Windows. Se desejar compilar esse utilitário a partir da origem, use o código Python que está incluído no instalador. 1. Acesse a pasta `C:\Program Files\Amazon\CloudHSM\tools\`. 1. Execute o arquivo `set_cloudhsm_credentials.exe` com os parâmetros de nome de usuário e senha do CU. ``` set_cloudhsm_credentials.exe --username --password ``` + **Usar a interface do Gerenciador de credenciais**: Você pode usar a interface do Gerenciador de credenciais para gerenciar manualmente suas credenciais. 1. Para abrir o Gerenciador de credenciais, digite `credential manager` na caixa de pesquisa na barra de tarefas e selecione **Credential Manager (Gerenciador de credenciais)**. 1. Selecione **Windows Credentials (Credenciais do Windows)** para gerenciar as credenciais do Windows. 1. Selecione **Add a generic credential (Adicionar uma credencial genérica)** e preencha os detalhes da seguinte forma: + Em **Internet ou Network Address (Endereço da Internet ou da rede)**, insira o nome de destino como `cloudhsm_client`. + Em **Username (Nome de usuário)** e **Password (Senha)**, insira as credenciais do CU. + Clique em **OK**. ## Variáveis de ambiente do sistema Você pode definir as variáveis de ambiente do sistema que identificam um HSM e um [crypto user (usuário de criptografia)](understanding-users-cmu.md#crypto-user-cmu) (CU) para seu aplicativo Windows. Você pode usar o comando [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx) para definir as variáveis de ambiente do sistema ou definir as variáveis de ambiente do sistema permanentes [de forma programática](https://msdn.microsoft.com/en-us/library/system.environment.setenvironmentvariable(v=vs.110).aspx) ou na guia **Advanced (Avançado)** do Painel de Controle nas **System Properties (Propriedades do Sistema)** do Windows. **Atenção** Quando você define as credenciais por meio de variáveis de ambiente do sistema, a senha fica disponível em texto simples no sistema de um usuário. Para resolver esse problema, use o Gerenciador de credenciais do Windows. Defina as seguintes variáveis de ambiente do sistema: **`n3fips_password=:`** Identifica um [crypto user (usuário de criptografia)](understanding-users-cmu.md#crypto-user-cmu) (CU) no HSM e fornece todas as informações de login necessárias. O aplicativo é autenticado e executado como esse CU. O aplicativo tem as permissões desse CU e pode visualizar e gerenciar apenas as chaves que o CU possui e compartilha. Para criar um novo CU, use [createUser](cloudhsm_mgmt_util-createUser.md). Para encontrar os existentes CUs, use [ListUsers](cloudhsm_mgmt_util-listUsers.md). Por exemplo: ``` setx /m n3fips_password test_user:password123 ``` # Associar uma AWS CloudHSM chave a um certificado Antes de usar AWS CloudHSM chaves com ferramentas de terceiros, como as da Microsoft [SignTool](https://docs.microsoft.com/en-us/windows/win32/seccrypto/signtool), você deve importar os metadados da chave para o repositório de certificados local e associar os metadados a um certificado. Para importar os metadados da chave, use o utilitário import\$1key.exe que está incluído no CloudHSM versão 3.0 e posterior. As etapas a seguir fornecem informações adicionais e saída de exemplo. ## Etapa 1: Importar certificado No Windows, você deve conseguir clicar duas vezes no certificado para importá-lo para o armazenamento de certificados local. No entanto, se clicar duas vezes não funcionar, use a [ferramenta Microsoft Certreq](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/dn296456%28v%3dws.11%29) para importar o certificado para o gerenciador de certificados. Por exemplo: ``` certreq -accept ``` Se essa ação falhar e você receber o erro `Key not found`, continue para a etapa 2. Se o certificado aparecer no repositório de chaves, você concluiu a tarefa e nenhuma ação adicional será necessária. ## Etapa 2: Coletar informações de identificação de certificado Se a etapa anterior não tiver sido bem-sucedida, você precisará associar sua chave privada a um certificado. No entanto, antes de criar a associação, você deve primeiro localizar o nome exclusivo do contêiner e o número de série do certificado. Use um utilitário, como **certutil**, para exibir as informações necessárias do certificado. A saída de exemplo a seguir de **certutil** mostra o nome do contêiner e o número de série. ``` ================ Certificate 1 ================ Serial Number: 72000000047f7f7a9d41851b4e000000000004Issuer: CN=Enterprise-CANotBefore: 10/8/2019 11:50 AM NotAfter: 11/8/2020 12:00 PMSubject: CN=www.example.com, OU=Certificate Management, O=Information Technology, L=Seattle, S=Washington, C=USNon-root CertificateCert Hash(sha1): 7f d8 5c 00 27 bf 37 74 3d 71 5b 54 4e c0 94 20 45 75 bc 65No key provider information Simple container name: CertReq-39c04db0-6aa9-4310-93db-db0d9669f42c Unique container name: CertReq-39c04db0-6aa9-4310-93db-db0d9669f42c ``` ## Etapa 3: associar a chave AWS CloudHSM privada ao certificado Para associar a chave ao certificado, primeiro certifique-se de [iniciar o daemon do AWS CloudHSM cliente](key_mgmt_util-setup.md#key_mgmt_util-start-cloudhsm-client). Em seguida, use import\$1key.exe (que está incluído no CloudHSM versão 3.0 e superior) para associar a chave privada ao certificado. Ao especificar o certificado, use seu nome de contêiner simples. O exemplo a seguir mostra o comando e a resposta. Esta ação copia apenas os metadados da chave, a chave permanece no HSM. ``` $> import_key.exe –RSA CertReq-39c04db0-6aa9-4310-93db-db0d9669f42c Successfully opened Microsoft Software Key Storage Provider : 0NCryptOpenKey failed : 80090016 ``` ## Etapa 4: Atualizar o armazenamento de certificados Certifique-se de que o daemon AWS CloudHSM do cliente ainda esteja em execução. Em seguida, use o verbo de **certutil**, **-repairstore**, para atualizar o número de série do certificado. O exemplo a seguir mostra o comando e a saída. Consulte a documentação da Microsoft para obter informações sobre o [verbo de **-repairstore**](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/cc732443(v=ws.11)?redirectedfrom=MSDN#-repairstore). ``` C:\Program Files\Amazon\CloudHSM>certutil -f -csp "Cavium Key Storage Provider"-repairstore my "72000000047f7f7a9d41851b4e000000000004" my "Personal" ================ Certificate 1 ================ Serial Number: 72000000047f7f7a9d41851b4e000000000004 Issuer: CN=Enterprise-CA NotBefore: 10/8/2019 11:50 AM NotAfter: 11/8/2020 12:00 PM Subject: CN=www.example.com, OU=Certificate Management, O=Information Technology, L=Seattle, S=Washington, C=US Non-root CertificateCert Hash(sha1): 7f d8 5c 00 27 bf 37 74 3d 71 5b 54 4e c0 94 20 45 75 bc 65 SDK Version: 3.0 Key Container = CertReq-39c04db0-6aa9-4310-93db-db0d9669f42c Provider = "Cavium Key Storage Provider" Private key is NOT exportableEncryption test passedCertUtil: -repairstore command completed successfully. ``` Depois de atualizar o número de série do certificado, você pode usar esse certificado e a chave AWS CloudHSM privada correspondente com qualquer ferramenta de assinatura de terceiros no Windows. # Exemplo de código para provedor de GNV para AWS CloudHSM **** \$1\$1 Somente código de exemplo – não se destina ao uso em produção \$1\$1 Esse exemplo de código é apenas para fins de ilustração. Não execute esse código na produção. O exemplo de código seguinte mostra como enumerar os provedores criptográficos registrados em seu sistema para encontrar o provedor de CNG instalado com o cliente CloudHSM para Windows. O exemplo também mostra como criar um par de chaves assimétricas e como usar o par de chaves para assinar os dados. **Importante** Antes de executar este exemplo, você deve configurar as credenciais do HSM conforme explicado nos pré-requisitos. Para obter mais detalhes, consulte [Pré-requisitos para usar o Windows Client AWS CloudHSM](ksp-library-prereq.md). ``` // CloudHsmCngExampleConsole.cpp : Console application that demonstrates CNG capabilities. // This example contains the following functions. // // VerifyProvider() - Enumerate the registered providers and retrieve Cavium KSP and CNG providers. // GenerateKeyPair() - Create an RSA key pair. // SignData() - Sign and verify data. // #include "stdafx.h" #include #ifndef NT_SUCCESS #define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0) #endif #define CAVIUM_CNG_PROVIDER L"Cavium CNG Provider" #define CAVIUM_KEYSTORE_PROVIDER L"Cavium Key Storage Provider" // Enumerate the registered providers and determine whether the Cavium CNG provider // and the Cavium KSP provider exist. // bool VerifyProvider() { NTSTATUS status; ULONG cbBuffer = 0; PCRYPT_PROVIDERS pBuffer = NULL; bool foundCng = false; bool foundKeystore = false; // Retrieve information about the registered providers. // cbBuffer - the size, in bytes, of the buffer pointed to by pBuffer. // pBuffer - pointer to a buffer that contains a CRYPT_PROVIDERS structure. status = BCryptEnumRegisteredProviders(&cbBuffer, &pBuffer); // If registered providers exist, enumerate them and determine whether the // Cavium CNG provider and Cavium KSP provider have been registered. if (NT_SUCCESS(status)) { if (pBuffer != NULL) { for (ULONG i = 0; i < pBuffer->cProviders; i++) { // Determine whether the Cavium CNG provider exists. if (wcscmp(CAVIUM_CNG_PROVIDER, pBuffer->rgpszProviders[i]) == 0) { printf("Found %S\n", CAVIUM_CNG_PROVIDER); foundCng = true; } // Determine whether the Cavium KSP provider exists. else if (wcscmp(CAVIUM_KEYSTORE_PROVIDER, pBuffer->rgpszProviders[i]) == 0) { printf("Found %S\n", CAVIUM_KEYSTORE_PROVIDER); foundKeystore = true; } } } } else { printf("BCryptEnumRegisteredProviders failed with error code 0x%08x\n", status); } // Free memory allocated for the CRYPT_PROVIDERS structure. if (NULL != pBuffer) { BCryptFreeBuffer(pBuffer); } return foundCng == foundKeystore == true; } // Generate an asymmetric key pair. As used here, this example generates an RSA key pair // and returns a handle. The handle is used in subsequent operations that use the key pair. // The key material is not available. // // The key pair is used in the SignData function. // NTSTATUS GenerateKeyPair(BCRYPT_ALG_HANDLE hAlgorithm, BCRYPT_KEY_HANDLE *hKey) { NTSTATUS status; // Generate the key pair. status = BCryptGenerateKeyPair(hAlgorithm, hKey, 2048, 0); if (!NT_SUCCESS(status)) { printf("BCryptGenerateKeyPair failed with code 0x%08x\n", status); return status; } // Finalize the key pair. The public/private key pair cannot be used until this // function is called. status = BCryptFinalizeKeyPair(*hKey, 0); if (!NT_SUCCESS(status)) { printf("BCryptFinalizeKeyPair failed with code 0x%08x\n", status); return status; } return status; } // Sign and verify data using the RSA key pair. The data in this function is hardcoded // and is for example purposes only. // NTSTATUS SignData(BCRYPT_KEY_HANDLE hKey) { NTSTATUS status; PBYTE sig; ULONG sigLen; ULONG resLen; BCRYPT_PKCS1_PADDING_INFO pInfo; // Hardcode the data to be signed (for demonstration purposes only). PBYTE message = (PBYTE)"d83e7716bed8a20343d8dc6845e57447"; ULONG messageLen = strlen((char*)message); // Retrieve the size of the buffer needed for the signature. status = BCryptSignHash(hKey, NULL, message, messageLen, NULL, 0, &sigLen, 0); if (!NT_SUCCESS(status)) { printf("BCryptSignHash failed with code 0x%08x\n", status); return status; } // Allocate a buffer for the signature. sig = (PBYTE)HeapAlloc(GetProcessHeap(), 0, sigLen); if (sig == NULL) { return -1; } // Use the SHA256 algorithm to create padding information. pInfo.pszAlgId = BCRYPT_SHA256_ALGORITHM; // Create a signature. status = BCryptSignHash(hKey, &pInfo, message, messageLen, sig, sigLen, &resLen, BCRYPT_PAD_PKCS1); if (!NT_SUCCESS(status)) { printf("BCryptSignHash failed with code 0x%08x\n", status); return status; } // Verify the signature. status = BCryptVerifySignature(hKey, &pInfo, message, messageLen, sig, sigLen, BCRYPT_PAD_PKCS1); if (!NT_SUCCESS(status)) { printf("BCryptVerifySignature failed with code 0x%08x\n", status); return status; } // Free the memory allocated for the signature. if (sig != NULL) { HeapFree(GetProcessHeap(), 0, sig); sig = NULL; } return 0; } // Main function. // int main() { NTSTATUS status; BCRYPT_ALG_HANDLE hRsaAlg; BCRYPT_KEY_HANDLE hKey = NULL; // Enumerate the registered providers. printf("Searching for Cavium providers...\n"); if (VerifyProvider() == false) { printf("Could not find the CNG and Keystore providers\n"); return 1; } // Get the RSA algorithm provider from the Cavium CNG provider. printf("Opening RSA algorithm\n"); status = BCryptOpenAlgorithmProvider(&hRsaAlg, BCRYPT_RSA_ALGORITHM, CAVIUM_CNG_PROVIDER, 0); if (!NT_SUCCESS(status)) { printf("BCryptOpenAlgorithmProvider RSA failed with code 0x%08x\n", status); return status; } // Generate an asymmetric key pair using the RSA algorithm. printf("Generating RSA Keypair\n"); GenerateKeyPair(hRsaAlg, &hKey); if (hKey == NULL) { printf("Invalid key handle returned\n"); return 0; } printf("Done!\n"); // Sign and verify [hardcoded] data using the RSA key pair. printf("Sign/Verify data with key\n"); SignData(hKey); printf("Done!\n"); // Remove the key handle from memory. status = BCryptDestroyKey(hKey); if (!NT_SUCCESS(status)) { printf("BCryptDestroyKey failed with code 0x%08x\n", status); return status; } // Close the RSA algorithm provider. status = BCryptCloseAlgorithmProvider(hRsaAlg, NULL); if (!NT_SUCCESS(status)) { printf("BCryptCloseAlgorithmProvider RSA failed with code 0x%08x\n", status); return status; } return 0; } ```