Fonction CryptAcquireCertificatePrivateKey (wincrypt.h)

Article
08/27/2023

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
CRYPT_ACQUIRE_CACHE_FLAG	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.
CRYPT_ACQUIRE_COMPARE_KEY_FLAG	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.
CRYPT_ACQUIRE_NO_HEALING	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.
CRYPT_ACQUIRE_SILENT_FLAG	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.
CRYPT_ACQUIRE_USE_PROV_INFO_FLAG	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.
CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG	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.

Valeur	Signification
CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG	Cette fonction tente d’obtenir la clé à l’aide de CryptoAPI. En cas d’échec, cette fonction tente d’obtenir la clé à l’aide de l’API de chiffrement : Nouvelle génération (CNG). La variable pdwKeySpec reçoit l’indicateur CERT_NCRYPT_KEY_SPEC si CNG est utilisé pour obtenir la clé.
CRYPT_ACQUIRE_ONLY_NCRYPT_KEY_FLAG	Cette fonction tente uniquement d’obtenir la clé à l’aide de CNG et n’utilise pas CryptoAPI pour obtenir la clé. La variable pdwKeySpec reçoit l’indicateur CERT_NCRYPT_KEY_SPEC si CNG est utilisé pour obtenir la clé.
CRYPT_ACQUIRE_PREFER_NCRYPT_KEY_FLAG	Cette fonction tente d’obtenir la clé à l’aide de CNG. En cas d’échec, cette fonction tente d’obtenir la clé à l’aide de CryptoAPI. La variable pdwKeySpec reçoit l’indicateur CERT_NCRYPT_KEY_SPEC si CNG est utilisé pour obtenir la clé. Note CryptoAPI ne prend pas en charge les algorithmes asymétriques CNG Diffie-Hellman ou DSA. CryptoAPI prend uniquement en charge les clés publiques Diffie-Hellman et DSA via les fournisseurs de services cloud hérités. Si cet indicateur est défini pour un certificat qui contient une clé publique Diffie-Hellman ou DSA, cette fonction modifie implicitement cet indicateur en CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG à essayer d’abord d’utiliser CryptoAPI pour obtenir la clé.

[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.

Valeur	Signification
AT_KEYEXCHANGE	La paire de clés est une paire d’échange de clés.
AT_SIGNATURE	La paire de clés est une paire de signatures.
CERT_NCRYPT_KEY_SPEC	La clé est une clé CNG. Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.

[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 FALSE, l’application appelante ne doit pas libérer le handle retourné dans la variable phCryptProvOrNCryptKey . Le handle sera libéré lors de la dernière action gratuite du contexte de certificat.

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
NTE_BAD_PUBLIC_KEY	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.
NTE_SILENT_CONTEXT	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

Voir aussi

CRYPT_KEY_PROV_INFO

CertSetCertificateContextProperty

CryptReleaseContext

Fonctions De génération de clés et Exchange