Funzione CryptAcquireContextA (wincrypt.h)
Questa funzione tenta prima di tutto di trovare un provider di servizi di configurazione con le caratteristiche descritte nei parametri dwProvType e szProvider . Se viene trovato il provider di servizi di configurazione, la funzione tenta di trovare un contenitore di chiavi all'interno del CSP che corrisponde al nome specificato dal parametro szContainer . Per acquisire il contesto e il contenitore di chiavi di una chiave privata associata alla chiave pubblica di un certificato, usare CryptAcquireCertificatePrivateKey.
Con l'impostazione appropriata di dwFlags, questa funzione può anche creare ed eliminare contenitori di chiavi e può fornire l'accesso a un provider di servizi di configurazione con un contenitore di chiavi temporanee se l'accesso a una chiave privata non è necessario.
Sintassi
BOOL CryptAcquireContextA(
[out] HCRYPTPROV *phProv,
[in] LPCSTR szContainer,
[in] LPCSTR szProvider,
[in] DWORD dwProvType,
[in] DWORD dwFlags
);
Parametri
[out] phProv
Puntatore a un handle di un provider di servizi di configurazione. Al termine dell'uso del provider di servizi di configurazione, rilasciare l'handle chiamando la funzione CryptReleaseContext .
[in] szContainer
Nome del contenitore di chiavi. Si tratta di una stringa con terminazione Null che identifica il contenitore di chiavi nel CSP. Questo nome è indipendente dal metodo usato per archiviare le chiavi. Alcuni provider di servizi di configurazione archiviano i contenitori di chiavi internamente (in hardware), alcuni usano il Registro di sistema e altri usano il file system. Nella maggior parte dei casi, quando dwFlags è impostato su CRYPT_VERIFYCONTEXT, szContainer deve essere impostato su NULL. Tuttavia, per i provider di servizi di configurazione basati su hardware, ad esempio un provider di servizi di configurazione per smart card, è possibile accedere alle informazioni disponibili pubblicamente nel contenitore specificato.
Per altre informazioni sull'utilizzo del parametro szContainer , vedere Osservazioni.
[in] szProvider
Stringa con terminazione Null contenente il nome del provider di servizi di configurazione da usare.
Se questo parametro è NULL, viene usato il provider predefinito dell'utente. Per altre informazioni, vedere Contesti del provider di servizi di crittografia. Per un elenco dei provider di crittografia disponibili, vedere Cryptographic Provider Names.For a list of available cryptographic providers providers, see Cryptographic Provider Names.
Un'applicazione può ottenere il nome del CSP in uso usando la funzione CryptGetProvParam per leggere il valore PP_NAME CSP nel parametro dwParam .
Il provider di servizi di configurazione predefinito può cambiare tra le versioni del sistema operativo. Per garantire l'interoperabilità su piattaforme del sistema operativo diverse, il provider di servizi di configurazione deve essere impostato in modo esplicito usando questo parametro anziché usare il provider di servizi di configurazione predefinito.
[in] dwProvType
Specifica il tipo di provider da acquisire. I tipi di provider definiti sono descritti in Tipi di provider di crittografia.
[in] dwFlags
Contrassegna i valori. Questo parametro è in genere impostato su zero, ma alcune applicazioni impostano uno o più dei flag seguenti.
| Valore | Significato |
|---|---|
|
Questa opzione è destinata alle applicazioni che usano chiavi temporanee o applicazioni che non richiedono l'accesso a chiavi private persistenti, ad esempio applicazioni che eseguono solo la verifica dell'hashing, della crittografia e della firma digitale . Solo le applicazioni che creano firme o decrittografano i messaggi devono accedere a una chiave privata. Nella maggior parte dei casi, questo flag deve essere impostato.
Per i provider di servizi di configurazione basati su file, quando questo flag è impostato, il parametro szContainer deve essere impostato su NULL. L'applicazione non ha accesso alle chiavi private persistenti delle coppie di chiavi pubbliche/private. Quando questo flag è impostato, è possibile creare coppie di chiavi pubbliche/private temporanee , ma non persistenti. Per i provider di servizi di configurazione basati su hardware, ad esempio un provider di servizi di configurazione della smart card, se il parametro szContainer è NULL o vuoto, questo flag implica che non è necessario accedere ad alcuna chiave e che non deve essere presentata alcuna interfaccia utente all'utente. Questo modulo viene usato per connettersi al provider di servizi di configurazione per eseguire query sulle relative funzionalità, ma non per usare effettivamente le relative chiavi. Se il parametro szContainer non è NULL e non è vuoto, questo flag implica l'accesso solo alle informazioni disponibili pubblicamente all'interno del contenitore specificato. Il provider di servizi di configurazione non deve richiedere un PIN. I tentativi di accesso alle informazioni private (ad esempio, la funzione CryptSignHash ) avranno esito negativo. Quando viene chiamato CryptAcquireContext , molti provider di servizi di configurazione richiedono l'input dell'utente proprietario prima di concedere l'accesso alle chiavi private nel contenitore di chiavi. Ad esempio, le chiavi private possono essere crittografate, richiedendo una password dall'utente prima che possano essere usate. Tuttavia, se viene specificato il flag CRYPT_VERIFYCONTEXT , l'accesso alle chiavi private non è obbligatorio e l'interfaccia utente può essere ignorata. |
|
Crea un nuovo contenitore di chiavi con il nome specificato da szContainer. Se szContainer è NULL, viene creato un contenitore di chiavi con il nome predefinito. |
|
Per impostazione predefinita, le chiavi e i contenitori di chiavi vengono archiviati come chiavi utente. Per i provider di base, ciò significa che i contenitori di chiavi utente vengono archiviati nel profilo dell'utente. È possibile accedere a un contenitore di chiavi creato senza questo flag da un amministratore solo dall'utente che crea il contenitore di chiavi e un utente con privilegi di amministrazione.
Windows XP: È possibile accedere a un contenitore di chiavi creato senza questo flag da un amministratore solo dall'utente che crea il contenitore di chiavi e l'account di sistema locale. Un contenitore di chiavi creato senza questo flag da un utente che non è un amministratore può accedere solo dall'utente che crea il contenitore di chiavi e l'account di sistema locale. Il flag CRYPT_MACHINE_KEYSET può essere combinato con tutti gli altri flag per indicare che il contenitore di chiavi di interesse è un contenitore di chiavi computer e il CSP lo considera come tale. Per i provider di base, ciò significa che le chiavi vengono archiviate localmente nel computer che ha creato il contenitore di chiavi. Se un contenitore di chiavi deve essere un contenitore di computer, il flag CRYPT_MACHINE_KEYSET deve essere usato con tutte le chiamate a CryptAcquireContext che fanno riferimento al contenitore del computer. Il contenitore di chiavi creato con CRYPT_MACHINE_KEYSET da un amministratore può essere accessibile solo dal creatore e da un utente con privilegi di amministratore, a meno che non vengano concessi diritti di accesso al contenitore tramite CryptSetProvParam. Windows XP: Il contenitore di chiavi creato con CRYPT_MACHINE_KEYSET da un amministratore può essere accessibile solo dal creatore e dall'account di sistema locale, a meno che non vengano concessi diritti di accesso al contenitore usando CryptSetProvParam. Il contenitore di chiavi creato con CRYPT_MACHINE_KEYSET da un utente che non è un amministratore può accedere solo dal creatore e dall'account di sistema locale, a meno che non vengano concessi diritti di accesso al contenitore tramite CryptSetProvParam. Il flag CRYPT_MACHINE_KEYSET è utile quando l'utente accede da un servizio o da un account utente che non ha eseguito l'accesso in modo interattivo. Quando vengono creati i contenitori di chiavi, la maggior parte dei provider di servizi di configurazione non crea automaticamente coppie di chiavi pubbliche/private. Queste chiavi devono essere create come passaggio separato con la funzione CryptGenKey . |
|
Eliminare il contenitore di chiavi specificato da szContainer. Se szContainer è NULL, il contenitore di chiavi con il nome predefinito viene eliminato. Tutte le coppie di chiavi nel contenitore delle chiavi vengono eliminate definitivamente.
Quando questo flag viene impostato, il valore restituito in phProv non è definito e pertanto la funzione CryptReleaseContext non deve essere chiamata in seguito. |
|
L'applicazione richiede che il CSP non visualizzi alcuna interfaccia utente per questo contesto. Se il provider di servizi di configurazione deve visualizzare l'interfaccia utente per il funzionamento, la chiamata ha esito negativo e il codice di errore NTE_SILENT_CONTEXT viene impostato come ultimo errore. Inoltre, se vengono effettuate chiamate a CryptGenKey con il flag CRYPT_USER_PROTECTED con un contesto acquisito con il flag CRYPT_SILENT, le chiamate hanno esito negativo e il CSP imposta NTE_SILENT_CONTEXT.
CRYPT_SILENT è destinato all'uso con le applicazioni per cui l'interfaccia utente non può essere visualizzata dal provider di servizi di configurazione. |
|
Ottiene un contesto per un provider di servizi di configurazione della smart card che può essere usato per le operazioni di hashing e chiave simmetrica, ma non può essere usato per qualsiasi operazione che richiede l'autenticazione a una smart card usando un PIN. Questo tipo di contesto viene spesso usato per eseguire operazioni su una smart card vuota, ad esempio impostando il PIN usando CryptSetProvParam. Questo flag può essere usato solo con provider di servizi di configurazione della smart card.
Windows Server 2003 e Windows XP: Questo flag non è supportato. |
Valore restituito
Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero (TRUE).
Se la funzione non riesce, restituisce zero (FALSE). Per informazioni sugli errori estesi, chiamare GetLastError.
I codici di errore preceduti dall'NTE vengono generati dal CSP specifico usato. Di seguito sono riportati alcuni codici di errore possibili definiti in Winerror.h.
| Codice/valore restituito | Descrizione |
|---|---|
|
Alcuni provider di servizi di configurazione impostano questo errore se il valore del flag CRYPT_DELETEKEYSET è impostato e un altro thread o processo usa questo contenitore di chiavi. |
|
Il profilo dell'utente non viene caricato e non è stato trovato. Ciò si verifica quando l'applicazione rappresenta un utente, ad esempio l'account IUSR_ComputerName . |
|
Uno dei parametri contiene un valore non valido. Si tratta più spesso di un puntatore che non è valido. |
|
Il sistema operativo ha esaurito la memoria durante l'operazione. |
|
Il parametro dwFlags ha un valore non valido. |
|
La password utente è stata modificata dopo la crittografia delle chiavi private. |
|
Impossibile aprire il contenitore di chiavi. Una causa comune di questo errore è che il contenitore di chiavi non esiste. Per creare un contenitore di chiavi, chiamare CryptAcquireContext usando il flag CRYPT_NEWKEYSET. Questo codice di errore può anche indicare che l'accesso a un contenitore di chiavi esistente è negato. I diritti di accesso al contenitore possono essere concessi dall'autore del set di chiavi usando CryptSetProvParam. |
|
Il parametro szContainer o szProvider è impostato su un valore non valido. |
|
Il valore del parametro dwProvType non è compreso nell'intervallo. Tutti i tipi di provider devono essere compresi tra 1 e 999 inclusi. |
|
Impossibile verificare la firma della DLL del provider. La DLL o la firma digitale è stata manomessa. |
|
Il parametro dwFlags è CRYPT_NEWKEYSET, ma il contenitore di chiavi esiste già. |
|
Il contenitore di chiavi szContainer è stato trovato ma è danneggiato. |
|
Il provider richiesto non esiste. |
|
Il provider di servizi di configurazione ha esaurito la memoria durante l'operazione. |
|
Il file DLL del provider non esiste o non è presente nel percorso corrente. |
|
Il tipo di provider specificato da dwProvType è danneggiato. Questo errore può essere correlato all'elenco CSP predefinito dell'utente o all'elenco CSP predefinito del computer. |
|
Il tipo di provider specificato da dwProvType non corrisponde al tipo di provider trovato. Si noti che questo errore può verificarsi solo quando szProvider specifica un nome CSP effettivo. |
|
Non esiste alcuna voce per il tipo di provider specificato da dwProvType. |
|
Impossibile caricare il file DLL del provider o non è stato possibile inizializzare. |
|
Errore durante il caricamento dell'immagine del file DLL prima di verificarne la firma. |
Commenti
Il parametro szContainer specifica il nome del contenitore usato per contenere la chiave. Ogni contenitore può contenere una chiave. Se si specifica il nome di un contenitore esistente durante la creazione di chiavi, la nuova chiave sovrascriverà quella precedente.
La combinazione del nome CSP e del nome del contenitore di chiavi identifica in modo univoco una singola chiave nel sistema. Se un'applicazione tenta di modificare un contenitore di chiavi mentre un'altra applicazione la usa, può verificarsi un comportamento imprevedibile.
Se si imposta il parametro szContainer su NULL, viene usato il nome del contenitore di chiavi predefinito. Quando i CSP software Microsoft vengono chiamati in questo modo, viene creato un nuovo contenitore ogni volta che viene chiamata la funzione CryptAcquireContext . Tuttavia, i diversi provider di servizi di configurazione possono comportarsi in modo diverso in questo senso. In particolare, un provider di servizi di configurazione può avere un singolo contenitore predefinito condiviso da tutte le applicazioni che accedono al provider di servizi di configurazione. Pertanto, le applicazioni non devono usare il contenitore di chiavi predefinito per archiviare le chiavi private. In alternativa, impedire l'archiviazione delle chiavi passando il flag CRYPT_VERIFYCONTEXT nel parametro dwFlags o usando un contenitore specifico dell'applicazione che probabilmente verrà usato da un'altra applicazione.
Un'applicazione può ottenere il nome del contenitore di chiavi in uso usando la funzione CryptGetProvParam per leggere il valore PP_CONTAINER.
Per motivi di prestazioni, è consigliabile impostare il parametro szContainer su NULL e il parametro dwFlags su CRYPT_VERIFYCONTEXT in tutte le situazioni in cui non è necessaria una chiave persistente. In particolare, è consigliabile impostare il parametro szContainer su NULL e il parametro dwFlags su CRYPT_VERIFYCONTEXT per gli scenari seguenti:
- Si sta creando un hash.
- Si sta generando una chiave simmetrica per crittografare o decrittografare i dati.
- Si sta derivando una chiave simmetrica da un hash per crittografare o decrittografare i dati.
- Si sta verificando una firma. È possibile importare una chiave pubblica da un PUBLICKEYBLOB o da un certificato usando CryptImportKey o CryptImportPublicKeyInfo. È possibile acquisire un contesto usando il flag CRYPT_VERIFYCONTEXT se si prevede di importare solo la chiave pubblica.
- Si prevede di esportare una chiave simmetrica, ma non importarla entro la durata del contesto di crittografia. È possibile acquisire un contesto usando il flag CRYPT_VERIFYCONTEXT se si prevede di importare solo la chiave pubblica per gli ultimi due scenari.
- Si eseguono operazioni di chiave privata, ma non si usa una chiave privata persistente archiviata in un contenitore di chiavi.
Esempio
L'esempio seguente illustra l'acquisizione di un contesto di crittografia e l'accesso a coppie di chiavi pubbliche/private in un contenitore di chiavi. Se il contenitore di chiavi richiesto non esiste, viene creato.
Per un esempio che include il contesto completo per questo esempio, vedere Esempio di programma C: Creazione di un contenitore di chiavi e generazione di chiavi. Per altri esempi, vedere Esempio di programma C: Uso di CryptAcquireContext.
//-------------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv = NULL; // handle for a cryptographic
// provider context
LPCSTR UserName = "MyKeyContainer"; // name of the key container
// to be used
//-------------------------------------------------------------------
// Attempt to acquire a context and a key
// container. The context will use the default CSP
// for the RSA_FULL provider type. DwFlags is set to zero
// to attempt to open an existing key container.
if(CryptAcquireContext(
&hCryptProv, // handle to the CSP
UserName, // container name
NULL, // use the default provider
PROV_RSA_FULL, // provider type
0)) // flag values
{
printf("A cryptographic context with the %s key container \n",
UserName);
printf("has been acquired.\n\n");
}
else
{
//-------------------------------------------------------------------
// An error occurred in acquiring the context. This could mean
// that the key container requested does not exist. In this case,
// the function can be called again to attempt to create a new key
// container. Error codes are defined in Winerror.h.
if (GetLastError() == NTE_BAD_KEYSET)
{
if(CryptAcquireContext(
&hCryptProv,
UserName,
NULL,
PROV_RSA_FULL,
CRYPT_NEWKEYSET))
{
printf("A new key container has been created.\n");
}
else
{
printf("Could not create a new key container.\n");
exit(1);
}
}
else
{
printf("A cryptographic service handle could not be "
"acquired.\n");
exit(1);
}
} // End of else.
//-------------------------------------------------------------------
// A cryptographic context and a key container are available. Perform
// any functions that require a cryptographic provider handle.
//-------------------------------------------------------------------
// When the handle is no longer needed, it must be released.
if (CryptReleaseContext(hCryptProv,0))
{
printf("The handle has been released.\n");
}
else
{
printf("The handle could not be released.\n");
}
Nota
L'intestazione wincrypt.h definisce CryptAcquireContext come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | wincrypt.h |
| Libreria | Advapi32.lib |
| DLL | Advapi32.dll |
Vedi anche
Funzioni del provider di servizi
Problemi di threading con i provider del servizio di crittografia