Fonction CryptAcquireCertificatePrivateKey (wincrypt.h)
La fonction CryptAcquireCertificatePrivateKey obtient la clé privée d’un certificat. Cette fonction est utilisée pour obtenir l’accès à la clé privée d’un utilisateur lorsque le certificat de l’utilisateur est disponible, mais que le handle du conteneur de clés de l’utilisateur n’est pas disponible. Cette fonction ne peut être utilisée que par le propriétaire d’une clé privée et non par tout autre utilisateur.
Si un handle CSP et le conteneur de clés contenant la clé privée d’un utilisateur sont disponibles, la fonction CryptGetUserKey doit être utilisée à la place.
Syntaxe
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
);
Paramètres
[in] pCert
Adresse d’une structure de CERT_CONTEXT qui contient le contexte de certificat pour lequel une clé privée sera obtenue.
[in] dwFlags
Ensemble d’indicateurs qui modifient le comportement de cette fonction. Il peut s’agir de zéro ou d’une combinaison d’une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Si un handle est déjà acquis et mis en cache, ce même handle est retourné. Sinon, un nouveau handle est acquis et mis en cache à l’aide de la propriété CERT_KEY_CONTEXT_PROP_ID du certificat.
Lorsque cet indicateur est défini, le paramètre pfCallerFreeProvOrNCryptKey reçoit FALSE et l’application appelante ne doit pas libérer le handle. Le handle est libéré lorsque le contexte de certificat est libéré ; Toutefois, vous devez conserver le contexte de certificat référencé par le paramètre pCert tant que la clé est en cours d’utilisation, sinon les opérations qui s’appuient sur la clé échouent. |
|
La clé publique dans le certificat est comparée à la clé publique retournée par le fournisseur de services de chiffrement (CSP). Si les clés ne correspondent pas, l’opération d’acquisition échoue et le dernier code d’erreur est défini sur NTE_BAD_PUBLIC_KEY. Si un handle mis en cache est retourné, aucune comparaison n’est effectuée. |
|
Cette fonction ne tente pas de recréer la propriété CERT_KEY_PROV_INFO_PROP_ID dans le contexte de certificat si cette propriété ne peut pas être récupérée. |
|
Le fournisseur de solutions Cloud ne doit pas afficher d’interface utilisateur pour ce contexte. Si le fournisseur de solutions Cloud doit afficher l’interface utilisateur pour fonctionner, l’appel échoue et le code d’erreur NTE_SILENT_CONTEXT est défini comme dernière erreur. |
|
Utilise la propriété CERT_KEY_PROV_INFO_PROP_ID du certificat pour déterminer si la mise en cache doit être effectuée. Pour plus d’informations sur la propriété CERT_KEY_PROV_INFO_PROP_ID , consultez CertSetCertificateContextProperty.
Cette fonction utilise la mise en cache uniquement si, lors d’un appel précédent, le membre dwFlags de la structure CRYPT_KEY_PROV_INFO contenu CERT_SET_KEY_CONTEXT_PROP. |
|
Toute interface utilisateur nécessaire au fournisseur de solutions Cloud ou KSP est un enfant du HWND fourni dans le paramètre pvParameters . Pour une clé CSP, l’utilisation de cet indicateur entraîne l’appel de la fonction CryptSetProvParam avec l’indicateur PP_CLIENT_HWND l’utilisation de ce HWND avec NULL pour HCRYPTPROV. Pour une clé KSP, l’utilisation de cet indicateur entraîne l’appel de la fonction NCryptSetProperty avec l’indicateur NCRYPT_WINDOW_HANDLE_PROPERTY à l’aide du HWND.
N’utilisez pas cet indicateur avec CRYPT_ACQUIRE_SILENT_FLAG. |
Les indicateurs suivants déterminent quelle technologie est utilisée pour obtenir la clé. Si aucun de ces indicateurs n’est présent, cette fonction tente uniquement d’obtenir la clé à l’aide de CryptoAPI.
Windows Server 2003 et Windows XP : Ces indicateurs ne sont pas pris en charge.
[in, optional] pvParameters
Si le CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG est défini, il s’agit de l’adresse d’un HWND. Si le CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG n’est pas défini, ce paramètre doit être NULL.
Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Ce paramètre a été nommé pvReserved et réservé pour une utilisation ultérieure et doit être NULL.
[out] phCryptProvOrNCryptKey
Adresse d’une variable HCRYPTPROV_OR_NCRYPT_KEY_HANDLE qui reçoit le handle du fournisseur CryptoAPI ou de la clé CNG. Si la variable pdwKeySpec reçoit l’indicateur CERT_NCRYPT_KEY_SPEC , il s’agit d’un handle de clé CNG de type NCRYPT_KEY_HANDLE ; sinon, il s’agit d’un handle de fournisseur CryptoAPI de type HCRYPTPROV.
Pour plus d’informations sur le moment et la façon de libérer ce handle, consultez la description du paramètre pfCallerFreeProvOrNCryptKey .
[out] pdwKeySpec
Adresse d’une variable DWORD qui reçoit des informations supplémentaires sur la clé. Il peut s’agir de l’une des valeurs suivantes.
[out] pfCallerFreeProvOrNCryptKey
Adresse d’une variable BOOL qui reçoit une valeur qui indique si l’appelant doit libérer le handle retourné dans la variable phCryptProvOrNCryptKey . Cette opération reçoit FALSE si l’une des conditions suivantes est vraie :
- Échec de l’acquisition ou de la comparaison de clé publique.
- Le paramètre dwFlags contient l’indicateur CRYPT_ACQUIRE_CACHE_FLAG .
- Le paramètre dwFlags contient l’indicateur CRYPT_ACQUIRE_USE_PROV_INFO_FLAG , la propriété de contexte de certificat est définie sur CERT_KEY_PROV_INFO_PROP_ID avec la structure CRYPT_KEY_PROV_INFO et le membre dwFlags de la structure CRYPT_KEY_PROV_INFO est défini sur CERT_SET_KEY_CONTEXT_PROP_ID.
Si cette variable reçoit TRUE, l’appelant est chargé de libérer le handle retourné dans la variable phCryptProvOrNCryptKey . Si la variable pdwKeySpec reçoit la valeur CERT_NCRYPT_KEY_SPEC , le handle doit être libéré en le passant à la fonction NCryptFreeObject ; sinon, le handle est libéré en le passant à la fonction CryptReleaseContext .
Valeur retournée
Si la fonction réussit, la valeur de retour est différente de zéro (TRUE).
Si la fonction échoue, la valeur de retour est zéro (FALSE). Pour obtenir des informations d’erreur étendues, appelez GetLastError. Un code d’erreur possible est le suivant.
| Code de retour | Description |
|---|---|
|
La clé publique dans le certificat ne correspond pas à la clé publique retournée par le fournisseur de solutions Cloud. Ce code d’erreur est retourné si le CRYPT_ACQUIRE_COMPARE_KEY_FLAG est défini et que la clé publique dans le certificat ne correspond pas à la clé publique retournée par le fournisseur de chiffrement. |
|
Le paramètre dwFlags contenait l’indicateur CRYPT_ACQUIRE_SILENT_FLAG et le fournisseur de solutions Cloud ne pouvait pas poursuivre une opération sans afficher une interface utilisateur. |
Remarques
Lorsque CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG est défini, l’appelant doit s’assurer que le HWND est valide. Si le HWND n’est plus valide, pour csp, l’appelant doit appeler CryptSetProvParam à l’aide de l’indicateur PP_CLIENT_HWND avec NULL pour le HWND et NULL pour le HCRYPTPROV. Pour KSP, l’appelant doit définir la NCRYPT_WINDOW_HANDLE_PROPERTY de la clé ncrypt sur NULL. Lorsque CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG indicateur est défini pour KSP, le NCRYPT_WINDOW_HANDLE_PROPERTY est défini sur le fournisseur de stockage et la clé. Si les deux appels échouent, la fonction échoue. Si une seule échoue, la fonction réussit. Notez que la définition de HWND sur NULL supprime effectivement HWND de la clé HCRYPTPROV ou ncrypt.
Exemples
Pour obtenir un exemple qui utilise cette fonction, consultez Exemple de programme C : envoi et réception d’un message signé et chiffré.
Configuration requise
| Client minimal pris en charge | Windows XP [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | wincrypt.h |
| Bibliothèque | Crypt32.lib |
| DLL | Crypt32.dll |