Funzione CryptAcquireCertificatePrivateKey (wincrypt.h)
La funzione CryptAcquireCertificatePrivateKey ottiene la chiave privata per un certificato. Questa funzione viene usata per ottenere l'accesso alla chiave privata di un utente quando il certificato dell'utente è disponibile, ma l'handle del contenitore della chiave dell'utente non è disponibile. Questa funzione può essere usata solo dal proprietario di una chiave privata e non da qualsiasi altro utente.
Se sono disponibili un handle CSP e il contenitore di chiavi contenente la chiave privata di un utente, la funzione CryptGetUserKey deve essere invece usata.
Sintassi
BOOL CryptAcquireCertificatePrivateKey(
[in] PCCERT_CONTEXT pCert,
[in] DWORD dwFlags,
[in, optional] void *pvParameters,
[out] HCRYPTPROV_OR_NCRYPT_KEY_HANDLE *phCryptProvOrNCryptKey,
[out] DWORD *pdwKeySpec,
[out] BOOL *pfCallerFreeProvOrNCryptKey
);
Parametri
[in] pCert
Indirizzo di una struttura CERT_CONTEXT che contiene il contesto del certificato per cui verrà ottenuta una chiave privata.
[in] dwFlags
Set di flag che modificano il comportamento di questa funzione. Questo può essere zero o una combinazione di uno o più dei valori seguenti.
| Valore | Significato |
|---|---|
|
Se un handle è già acquisito e memorizzato nella cache, viene restituito lo stesso handle. In caso contrario, un nuovo handle viene acquisito e memorizzato nella cache usando la proprietà CERT_KEY_CONTEXT_PROP_ID del certificato.
Quando questo flag è impostato, il parametro pfCallerFreeProvOrNCryptKey riceve FALSE e l'applicazione chiamante non deve rilasciare l'handle. L'handle viene liberato quando il contesto del certificato viene liberato; Tuttavia, è necessario mantenere il contesto del certificato a cui fa riferimento il parametro pCert purché la chiave sia in uso, in caso contrario, le operazioni che si basano sulla chiave avranno esito negativo. |
|
La chiave pubblica nel certificato viene confrontata con la chiave pubblica restituita dal provider di servizi di crittografia (CSP). Se le chiavi non corrispondono, l'operazione di acquisizione ha esito negativo e l'ultimo codice di errore è impostato su NTE_BAD_PUBLIC_KEY. Se viene restituito un handle memorizzato nella cache, non viene eseguito alcun confronto. |
|
Questa funzione non tenterà di ricreare la proprietà CERT_KEY_PROV_INFO_PROP_ID nel contesto del certificato se questa proprietà non può essere recuperata. |
|
Il CSP non deve visualizzare alcuna interfaccia utente per questo contesto. Se il CSP deve visualizzare l'interfaccia utente per funzionare, la chiamata ha esito negativo e il codice di errore NTE_SILENT_CONTEXT viene impostato come ultimo errore. |
|
Usa la proprietà CERT_KEY_PROV_INFO_PROP_ID del certificato per determinare se è necessario eseguire la memorizzazione nella cache. Per altre informazioni sulla proprietà CERT_KEY_PROV_INFO_PROP_ID , vedere CertSetCertificateContextProperty.
Questa funzione userà la memorizzazione nella cache solo se durante una chiamata precedente, il membro dwFlags della struttura CRYPT_KEY_PROV_INFO contenuto CERT_SET_KEY_CONTEXT_PROP. |
|
Qualsiasi interfaccia utente necessaria da CSP o KSP sarà figlio del parametro HWND fornito nel parametro pvParameters . Per una chiave CSP, l'uso di questo flag causerà la funzione CryptSetProvParam con il flag PP_CLIENT_HWND usando questo HWND da chiamare con NULL per HCRYPTPROV. Per una chiave KSP, l'uso di questo flag causerà la chiamata della funzione NCryptSetProperty con il flag NCRYPT_WINDOW_HANDLE_PROPERTY tramite HWND.
Non usare questo flag con CRYPT_ACQUIRE_SILENT_FLAG. |
I flag seguenti determinano quale tecnologia viene usata per ottenere la chiave. Se nessuno di questi flag è presente, questa funzione tenterà solo di ottenere la chiave usando CryptoAPI.
Windows Server 2003 e Windows XP: Questi flag non sono supportati.
[in, optional] pvParameters
Se il CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG è impostato, si tratta dell'indirizzo di un HWND. Se il CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG non è impostato, questo parametro deve essere NULL.
Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo parametro è stato denominato pvReserved e riservato per l'uso futuro e deve essere NULL.
[out] phCryptProvOrNCryptKey
Indirizzo di una variabile HCRYPTPROV_OR_NCRYPT_KEY_HANDLE che riceve l'handle del provider CryptoAPI o della chiave CNG. Se la variabile pdwKeySpec riceve il flag di CERT_NCRYPT_KEY_SPEC , si tratta di un handle di chiavi CNG di tipo NCRYPT_KEY_HANDLE; in caso contrario, si tratta di un handle del provider CryptoAPI di tipo HCRYPTPROV.
Per altre informazioni su quando e come rilasciare questo handle, vedere la descrizione del parametro pfCallerFreeProvOrNCryptKey .
[out] pdwKeySpec
Indirizzo di una variabile DWORD che riceve informazioni aggiuntive sulla chiave. Questo può essere uno dei valori seguenti.
[out] pfCallerFreeProvOrNCryptKey
Indirizzo di una variabile BOOL che riceve un valore che indica se il chiamante deve liberare l'handle restituito nella variabile phCryptProvOrNCryptKey . Questo riceve FALSE se uno dei seguenti è true:
- L'acquisizione o il confronto delle chiavi pubbliche ha esito negativo.
- Il parametro dwFlags contiene il flag di CRYPT_ACQUIRE_CACHE_FLAG .
- Il parametro dwFlags contiene il flag CRYPT_ACQUIRE_USE_PROV_INFO_FLAG, la proprietà del contesto del certificato è impostata su CERT_KEY_PROV_INFO_PROP_ID con la struttura CRYPT_KEY_PROV_INFO e il membro dwFlagsdella struttura CRYPT_KEY_PROV_INFO è impostato su CERT_SET_KEY_CONTEXT_PROP_ID.
Se questa variabile riceve TRUE, il chiamante è responsabile del rilascio dell'handle restituito nella variabile phCryptProvOrNCryptKey . Se la variabile pdwKeySpec riceve il valore di CERT_NCRYPT_KEY_SPEC , l'handle deve essere rilasciato passandolo alla funzione NCryptFreeObject ; in caso contrario, l'handle viene rilasciato passandolo alla funzione CryptReleaseContext .
Valore restituito
Se la funzione ha esito positivo, il valore restituito è diverso da zero (TRUE).
Se la funzione ha esito negativo, il valore restituito è zero (FALSE). Per informazioni sull'errore estese, chiamare GetLastError. Un possibile codice di errore è il seguente.
| Codice restituito | Descrizione |
|---|---|
|
La chiave pubblica nel certificato non corrisponde alla chiave pubblica restituita dal CSP. Questo codice di errore viene restituito se il CRYPT_ACQUIRE_COMPARE_KEY_FLAG è impostato e la chiave pubblica nel certificato non corrisponde alla chiave pubblica restituita dal provider di crittografia. |
|
Il parametro dwFlags contiene il flag di CRYPT_ACQUIRE_SILENT_FLAG e il CSP non può continuare un'operazione senza visualizzare un'interfaccia utente. |
Commenti
Quando CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG è impostato, il chiamante deve assicurarsi che HWND sia valido. Se HWND non è più valido, per CSP il chiamante deve chiamare CryptSetProvParam usando il flag PP_CLIENT_HWND con NULL per HWND e NULL per HCRYPTPROV. Per KSP, il chiamante deve impostare la NCRYPT_WINDOW_HANDLE_PROPERTY della chiave ncrypt su NULL. Quando CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG flag è impostato per KSP, il NCRYPT_WINDOW_HANDLE_PROPERTY è impostato sul provider di archiviazione e sulla chiave. Se entrambe le chiamate hanno esito negativo, la funzione ha esito negativo. Se una sola operazione ha esito negativo, la funzione ha esito positivo. Si noti che l'impostazione di HWND su NULL rimuove in modo efficace HWND dalla chiave HCRYPTPROV o ncrypt.
Esempio
Per un esempio che usa questa funzione, vedere Esempio di programma C: invio e ricezione di un messaggio firmato e crittografato.
Requisiti
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | wincrypt.h |
| Libreria | Crypt32.lib |
| DLL | Crypt32.dll |