Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# API di crittografia: Next Generation (CNG) e provider di archiviazione delle chiavi (KSP) per AWS CloudHSM
Il AWS CloudHSM client per Windows include provider CNG e KSP.
*I provider di archiviazione delle chiavi* (KSPs) consentono l'archiviazione e il recupero delle chiavi. Ad esempio, se aggiungi i Servizi certificati Active Directory (AD CS) di Microsoft al server Windows e decidi di creare una nuova chiave privata per l'autorità di certificazione (CA), potrai scegliere il provider KSP che gestirà l'archiviazione delle chiavi. Quando configuri il ruolo AD CS, puoi scegliere questo KSP. Per ulteriori informazioni, consulta [Creare un'autorità di certificazione (CA) Windows Server](win-ca-overview-sdk5.md#win-ca-setup-sdk5).
*Cryptography API: Next Generation (CNG)* è un'API di crittografia specifica per il sistema operativo Microsoft Windows. CNG consente agli sviluppatori di utilizzare tecniche di crittografia per proteggere le applicazioni basate su Windows. Ad alto livello, l' AWS CloudHSM implementazione di CNG offre le seguenti funzionalità:
+ **Primitive crittografiche**: consentono di eseguire operazioni crittografiche fondamentali.
+ **Importazione ed esportazione di chiavi**: consente di importare ed esportare chiavi asimmetriche.
+ **Data Protection API (CNG DPAPI): consente di crittografare e decrittografare facilmente i** dati.
+ **Archiviazione e recupero delle chiavi**: consente di archiviare e isolare in modo sicuro la chiave privata di una coppia di chiavi asimmetrica.
**Topics**
+ [Verifica i fornitori KSP e CNG per AWS CloudHSM](ksp-v3-library-install.md)
+ [Prerequisiti per l'utilizzo del client AWS CloudHSM Windows](ksp-library-prereq.md)
+ [Associare una AWS CloudHSM chiave a un certificato](ksp-library-associate-key-certificate.md)
+ [Esempio di codice per il fornitore di CNG per AWS CloudHSM](ksp-library-sample.md)
# Verifica i fornitori KSP e CNG per AWS CloudHSM
I provider KSP e CNG vengono installati quando si installa il client Windows AWS CloudHSM . È possibile installare il client seguendo i passaggi descritti in [Installare il client (Windows)](kmu-install-and-configure-client-win.md).
Utilizza le seguenti sezioni per verificare l'installazione dei provider.
## Configura ed esegui il AWS CloudHSM client Windows
Per avviare il client Windows CloudHSM, è necessario soddisfare per prima cosa i [Prerequisiti](ksp-library-prereq.md). Quindi, aggiorna i file di configurazione utilizzati dai provider e avvia il client completando i passaggi seguenti. È necessario eseguire questi passaggi la prima volta che si utilizzano i provider KSP e CNG e dopo averli aggiunti o rimossi HSMs nel cluster. In questo modo, AWS CloudHSM è in grado di sincronizzare i dati e mantenere la coerenza HSMs in tutto il cluster.
### Fase 1: Arrestare il client AWS CloudHSM
Prima di aggiornare i file di configurazione utilizzati dai provider, arrestate il AWS CloudHSM client. Se il client è già stato arrestato, eseguire il comando stop non ha alcun effetto.
+ Per client Windows dalla versione 1.1.2 in poi:
```
C:\Program Files\Amazon\CloudHSM>net.exe stop AWSCloudHSMClient
```
+ Per client Windows 1.1.1 e versioni precedenti:
Usa **Ctrl** \$1 **C** nella finestra di comando in cui hai avviato il AWS CloudHSM client.
### Fase 2: Aggiornare i AWS CloudHSM file di configurazione
Questo passaggio utilizza il `-a` parametro dello [strumento Configure](configure-tool.md) per aggiungere l'indirizzo IP ENI (elastic network interface) di uno dei HSMs componenti del cluster al file di configurazione.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\configure.exe" -a
```
Per ottenere l'indirizzo IP ENI di un HSM nel cluster, accedi alla AWS CloudHSM console, scegli **i cluster** e seleziona il cluster desiderato. È inoltre possibile utilizzare l'[DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html)operazione, il comando [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html) o il cmdlet. [Get-HSM2Cluster](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-HSM2Cluster.html) PowerShell Digitare solo un indirizzo IP ENI. Non importa l'indirizzo IP ENI utilizzato.
### Passaggio 3: avviare il client AWS CloudHSM
Quindi, avvia o riavvia il AWS CloudHSM client. All'avvio, il AWS CloudHSM client utilizza l'indirizzo IP ENI nel suo file di configurazione per interrogare il cluster. Quindi aggiunge gli indirizzi IP ENI di tutti i membri HSMs del cluster al file di informazioni sul cluster.
+ Per client Windows dalla versione 1.1.2\$1:
```
C:\Program Files\Amazon\CloudHSM>net.exe start AWSCloudHSMClient
```
+ Per client Windows 1.1.1 e versioni precedenti:
```
C:\Program Files\Amazon\CloudHSM>start "cloudhsm_client" cloudhsm_client.exe C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg
```
## Controllo dei provider KSP e CNG
È possibile utilizzare uno dei seguenti comandi per determinare quali provider sono installati nel sistema. I comandi elencano i provider KSP e CNG registrati. Il client AWS CloudHSM non deve essere in esecuzione.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\ksp_config.exe" -enum
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\cng_config.exe" -enum
```
Per verificare che i provider KSP e CNG siano installati sulla tua istanza di Windows Server EC2, dovresti vedere le seguenti voci nell'elenco:
```
Cavium CNG Provider
Cavium Key Storage Provider
```
Se il provider CNG manca, esegui il comando seguente.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\cng_config.exe" -register
```
Se il provider CNG manca, esegui il comando seguente.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\ksp_config.exe" -register
```
# Prerequisiti per l'utilizzo del client AWS CloudHSM Windows
Prima di avviare il AWS CloudHSM client Windows e utilizzare i provider KSP e CNG, è necessario impostare le credenziali di accesso per l'HSM sul sistema. Puoi impostare le credenziali tramite Gestione credenziali di Windows o la variabile di ambiente di sistema. Ti consigliamo di utilizzare Gestione credenziali di Windows per archiviare le credenziali. Questa opzione è disponibile con la versione AWS CloudHSM del client 2.0.4 e successive. L'utilizzo della variabile di ambiente è più semplice da configurare, ma meno sicura rispetto all'utilizzo di Gestione credenziali di Windows.
## Gestione credenziali di Windows
Puoi utilizzare l'utility `set_cloudhsm_credentials` o l'interfaccia di Gestione credenziali di Windows.
+ **Utilizzo dell'utility `set_cloudhsm_credentials`**:
L'utility `set_cloudhsm_credentials` è inclusa nel programma di installazione di Windows. Puoi utilizzare questa utility per trasferire le credenziali di accesso HSM a Gestione credenziali di Windows. Se desideri compilare questa utility dall'origine, puoi utilizzare il codice Python incluso nel programma di installazione.
1. Passare alla cartella `C:\Program Files\Amazon\CloudHSM\tools\`.
1. Esegui il file `set_cloudhsm_credentials.exe` con il nome utente e i parametri della password del CU.
```
set_cloudhsm_credentials.exe --username --password
```
+ **Utilizzo dell'interfaccia di gestione delle credenziali**:
Puoi utilizzare l'interfaccia di gestione delle credenziali per gestire manualmente le credenziali.
1. Per aprire Credential Manager, digita `credential manager` nella casella di ricerca sulla barra delle applicazioni e seleziona **Gestione delle credenziali**.
1. Seleziona **Credenziali di Windows** per gestire le credenziali di Windows.
1. Seleziona **Aggiungi una credenziale generica** e compila i dettagli come segue:
+ In **Indirizzo Internet o di rete**, immetti il nome della destinazione come `cloudhsm_client`.
+ In **Nome utente** e **Password** immettere le credenziali CU.
+ Fai clic su **OK**.
## Variabili di ambiente del sistema
Puoi impostare variabili di ambiente di sistema che identificano un HSM e un [crypto user](understanding-users-cmu.md#crypto-user-cmu) (CU) per l'applicazione Windows. Puoi eseguire il [comando **setx**](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx) per impostare le variabili di ambiente del sistema temporanee o definitive [in modo programmatico](https://msdn.microsoft.com/en-us/library/system.environment.setenvironmentvariable(v=vs.110).aspx) oppure nella scheda **Avanzate** del pannello di controllo **Proprietà di sistema** di Windows.
**avvertimento**
Quando imposti le credenziali tramite variabili di ambiente di sistema, la password è disponibile in testo normale nel sistema di un utente. Per risolvere questo problema, utilizza Gestione credenziali di Windows.
Imposta le seguenti variabili di ambiente del sistema:
**`n3fips_password=:`**
Identifica un [crypto user](understanding-users-cmu.md#crypto-user-cmu) (CU) nell'HSM e fornisce tutte le informazioni di login richieste. La tua applicazione viene autenticata ed eseguita come questo CU. L'applicazione dispone delle autorizzazioni di questo CU e può visualizzare e gestire solo le chiavi di proprietà del CU e quelle con questi condivise. Per creare un nuovo CU, utilizza [createUser](cloudhsm_mgmt_util-createUser.md). Per trovare quelli esistenti CUs, usa [ListUsers](cloudhsm_mgmt_util-listUsers.md).
Esempio:
```
setx /m n3fips_password test_user:password123
```
# Associare una AWS CloudHSM chiave a un certificato
Prima di poter utilizzare AWS CloudHSM le chiavi con strumenti di terze parti, come Microsoft [SignTool](https://docs.microsoft.com/en-us/windows/win32/seccrypto/signtool), devi importare i metadati della chiave nell'archivio certificati locale e associarli a un certificato. Per importare i metadati della chiave, utilizza l'utilità import\$1key.exe inclusa in CloudHSM versione 3.0 e successive. La procedura seguente fornisce informazioni aggiuntive e un esempio output.
## Passaggio 1: importare il certificato
In Windows, dovresti essere in grado di fare doppio clic sul certificato per importarlo nell'archivio certificati locale.
Tuttavia, se il doppio clic non funziona, utilizza lo [strumento Microsoft Certreq](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/dn296456%28v%3dws.11%29) per importare il certificato nel gestore certificati. Esempio:
```
certreq -accept
```
Se questa azione non riesce e viene visualizzato l'errore `Key not found`, passa al passaggio 2. Se il certificato viene visualizzato nell'archivio chiavi, l'attività è stata completata con successo e non sono necessarie ulteriori azioni.
## Passaggio 2: raccogliere informazioni sull'identificazione dei certificati
Se il passaggio precedente non ha avuto esito positivo, dovrai associare la chiave privata a un certificato. Tuttavia, prima di poter creare l'associazione, devi innanzitutto trovare il nome del container univoco e il numero di serie del certificato. Utilizzate un'utilità, ad esempio**certutil**, per visualizzare le informazioni necessarie sul certificato. Il seguente esempio di output di **certutil** mostra il nome del contenitore e il numero di serie.
```
================ 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
```
## Fase 3: Associare la chiave AWS CloudHSM privata al certificato
Per associare la chiave al certificato, assicurati innanzitutto di [avviare il demone AWS CloudHSM client](key_mgmt_util-setup.md#key_mgmt_util-start-cloudhsm-client). Quindi, utilizza import\$1key.exe (incluso in CloudHsm versione 3.0 e successive) per associare la chiave privata al certificato. Quando si specifica il certificato, utilizzare il nome del contenitore semplice. L'esempio seguente mostra il comando e la risposta. Questa azione copia solo i metadati della chiave; la chiave rimane sull'HSM.
```
$> import_key.exe –RSA CertReq-39c04db0-6aa9-4310-93db-db0d9669f42c
Successfully opened Microsoft Software Key Storage Provider : 0NCryptOpenKey failed : 80090016
```
## Passaggio 4: aggiornare l'archivio certificati
Assicurati che il daemon AWS CloudHSM client sia ancora in esecuzione. Quindi, utilizzate il **certutil** verbo,**-repairstore**, per aggiornare il numero di serie del certificato. L'esempio seguente mostra il comando e l'output. Per informazioni sul [**-repairstore**verbo](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/cc732443(v=ws.11)?redirectedfrom=MSDN#-repairstore), consulta la documentazione Microsoft.
```
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.
```
Dopo aver aggiornato il numero di serie del certificato, puoi utilizzare questo certificato e la chiave AWS CloudHSM privata corrispondente con qualsiasi strumento di firma di terze parti su Windows.
# Esempio di codice per il fornitore di CNG per AWS CloudHSM
****
\$1\$1 Solo codice di esempio, non per uso in produzione\$1\$1
Questo codice di esempio è solo a scopo illustrativo. Non eseguire questo codice in fase di produzione.
Il seguente esempio mostra come enumerare i provider di crittografia registrati nel sistema per trovare il provider CNG installato con il client CloudHSM per Windows. L'esempio mostra inoltre come creare una coppia di chiavi asimmetriche e come utilizzare la coppia di chiavi per firmare i dati.
**Importante**
Prima di eseguire questo esempio, devi configurare le credenziali HSM come descritto nei prerequisiti. Per informazioni dettagliate, vedi [Prerequisiti per l'utilizzo del client AWS CloudHSM Windows](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;
}
```