Partager via

PFXImportCertStore, fonction (wincrypt.h)

  • Article

La fonction PFXImportCertStore importe un objet BLOB PFX et retourne le handle d’un magasin qui contient des certificats et toutes les clés privées associées.

Syntaxe

HCERTSTORE PFXImportCertStore(
  [in] CRYPT_DATA_BLOB *pPFX,
  [in] LPCWSTR         szPassword,
  [in] DWORD           dwFlags
);

Paramètres

[in] pPFX

Pointeur vers une structure CRYPT_DATA_BLOB qui contient un paquet PFX avec les certificats et clés exportés et chiffrés.

[in] szPassword

Mot de passe de chaîne utilisé pour déchiffrer et vérifier le paquet PFX. Si elle est définie sur une chaîne de longueur supérieure à zéro ou définie sur une chaîne vide ou sur NULL, cette valeur doit être exactement la même que la valeur utilisée pour chiffrer le paquet.

À compter de Windows 8 et Windows Server 2012, si le paquet PFX a été créé dans la fonction PFXExportCertStoreEx à l’aide de l’indicateur PKCS12_PROTECT_TO_DOMAIN_SIDS, la fonction PFXImportCertStore tente de déchiffrer le mot de passe à l’aide du principal Active Directory (AD) utilisé pour le chiffrer. Le principal AD est spécifié dans le paramètre pvPara. Si le paramètre szPassword dans la fonction PFXExportCertStoreEx était une chaîne vide ou NULL et que le paramètre dwFlags a été défini sur PKCS12_PROTECT_TO_DOMAIN_SIDS, cette fonction a généré de façon aléatoire un mot de passe et l’a chiffrée sur le principal AD spécifié dans le paramètre pvPara. Dans ce cas, vous devez définir le mot de passe sur la valeur, une chaîne vide ou NULL, qui a été utilisé lors de la création du paquet PFX. La fonction PFXImportCertStore utilisera le principal AD pour déchiffrer le mot de passe aléatoire et le mot de passe généré de manière aléatoire sera utilisé pour déchiffrer le certificat PFX.

Lorsque vous avez terminé d’utiliser le mot de passe, effacez-le de la mémoire en appelant la fonction SecureZeroMemory. Pour plus d’informations sur la protection des mots de passe, consultez Gestion des mots de passe.

[in] dwFlags

Le paramètre dwFlags peut être l’une des valeurs suivantes :

Valeur Signification
CRYPT_EXPORTABLE
0x00000001
 Les clés importées sont marquées comme exportables. Si cet indicateur n’est pas utilisé, les appels à la fonction CryptExportKey avec le handle de clé échouent.
CRYPT_USER_PROTECTED
0x00000002
 L’utilisateur doit être averti par le biais d’une boîte de dialogue ou d’une autre méthode lorsque certaines tentatives d’utilisation de cette clé sont effectuées. Le comportement précis est spécifié par le fournisseur de services de chiffrement (CSP) utilisé.

Avant Internet Explorer 4.0, les fournisseurs de services de chiffrement Microsoft ont ignoré cet indicateur. À compter d’Internet Explorer 4.0, les fournisseurs Microsoft prennent en charge cet indicateur.

Si le contexte du fournisseur a été ouvert avec l’indicateur de CRYPT_SILENT défini, l’utilisation de cet indicateur provoque un échec et la dernière erreur est définie sur NTE_SILENT_CONTEXT.
CRYPT_MACHINE_KEYSET
0x00000020
 Les clés privées sont stockées sous l’ordinateur local et non sous l’utilisateur actuel.
CRYPT_USER_KEYSET
0x00001000
 Les clés privées sont stockées sous l’utilisateur actuel et non sous l’ordinateur local, même si l’objet BLOB PFX spécifie qu’ils doivent accéder à l’ordinateur local.
PKCS12_PREFER_CNG_KSP
0x00000100
 Indique que le fournisseur de stockage de clés CNG (KSP) est préféré. Si le fournisseur de solutions Cloud est spécifié dans le fichier PFX, le fournisseur de solutions Cloud est utilisé ; sinon, le fournisseur de services clés est préféré. Si le KSP CNG n’est pas disponible, la fonction PFXImportCertStore échoue.

Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
PKCS12_ALWAYS_CNG_KSP
0x00000200
Indique que le KSP CNG est toujours utilisé. Lorsqu’elle est spécifiée, PFXImportCertStore tente d’utiliser le KSP CNG, quelles que soient les informations du fournisseur dans le fichier PFX. Si le KSP CNG n’est pas disponible, l’importation ne échoue pas.

Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
PKCS12_ALLOW_OVERWRITE_KEY
0x00004000
Autoriser le remplacement de la clé existante. Spécifiez cet indicateur lorsque vous rencontrez un scénario dans lequel vous devez importer un fichier PFX qui contient un nom de clé qui existe déjà. Par exemple, lorsque vous importez un fichier PFX, il est possible qu’un conteneur du même nom soit déjà présent, car il n’existe aucun espace de noms unique pour les conteneurs de clés. Si vous avez créé un « TestKey » sur votre ordinateur, puis que vous importez un fichier PFX avec également « TestKey » comme conteneur de clés, le paramètre PKCS12_ALLOW_OVERWRITE_KEY permet le remplacement de la clé.

Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
PKCS12_NO_PERSIST_KEY
0x00008000
 Ne conservez pas la clé. Spécifiez cet indicateur lorsque vous ne souhaitez pas conserver la clé. Par exemple, s’il n’est pas nécessaire de stocker la clé après vérification, au lieu de créer un conteneur, puis de le supprimer, vous pouvez spécifier cet indicateur pour supprimer la clé immédiatement.
Remarque Si l’indicateur PKCS12_NO_PERSIST_KEY n’est pas* défini, les clés sont conservées sur le disque. Si vous ne souhaitez pas conserver les clés au-delà de leur utilisation, vous devez les supprimer en appelant la fonction CryptAcquireContext avec l’indicateur de CRYPT_DELETEKEYSET défini dans le paramètre dwFlags.
Remarque d’autres considérations :

  • Lorsque vous utilisez PKCS12_NO_PERSIST_KEY, la propriété CERT_KEY_CONTEXT_PROP_ID est définie en interne sur le certificat et contient la clé.

  • Si la PKCS12_NO_PERSIST_KEY n’est pas utilisée, la propriété CERT_KEY_PROV_INFO_PROP_ID est définie.

  • Si le certificat avec la clé non persistante est marshalé vers un autre processus, la propriété CERT_KEY_CONTEXT_PROP_ID ne sera pas marshalée.

  • Pour que NO_PERSIST fonctionne, il doit être dans le même processus et l’utilisateur du PCCERT_CONTEXT doit prendre en charge le CERT_KEY_CONTEXT_PROP_ID. Cela s’applique généralement lors d’une négociation TLS : si l’établissement d’une liaison est effectué en externe au processus appelant dans LSASS.exe, il n’est pas possible d’utiliser PKCS12_NO_PERSIST_KEY lors du passage du processus appelant à LSASS (car le NCRYPT_KEY_HANDLE est un pointeur vers une structure de données et non un handle de noyau).

 
Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
PKCS12_INCLUDE_EXTENDED_PROPERTIES
0x0010
 Importez toutes les propriétés étendues sur le certificat qui ont été enregistrées sur le certificat lors de son exportation.

Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
0x10000000
 Décompressez, mais ne conservez pas les résultats.

Valeur de retour

Si la fonction réussit, la fonction retourne un handle à un magasin de certificats qui contient les certificats importés, y compris les clés privées disponibles.

Si la fonction échoue, autrement dit, si le paramètre de mot de passe ne contient pas de correspondance exacte avec le mot de passe utilisé pour chiffrer le paquet exporté ou s’il existe d’autres problèmes lors du décodage du blob PFX, la fonction retourne NULL et un code d’erreur est trouvé en appelant la fonction GetLastError.

Remarques

La fonction PFXImportCertStore ouvre un magasin temporaire. Si la fonction réussit, vous devez fermer le handle du magasin en appelant la fonction CertCloseStore.

Lorsque vous importez un certificat à partir du paquet PFX, Le nom du conteneur CSP/KSP est déterminé à l’aide de l’AttributeId avec OID 1.3.6.1.1.311.17.1 de l’élément PKCS8ShroudedKeyBag SafeBag [bagId : 1 .2.840.113549.1.12.10.1.2] (voir PKCS #12 pour plus d’informations sur la structure ASN.1 de cette structure).

  • AttributeId : 1.3.6.1.4.1.311.17.1
  • valeur : nom du fournisseur de services clés ou du fournisseur de solutions cloud

Si l’AttributeId n’est pas présent et que l’indicateur PREFER_CNG est passé, MS_KEY_STORAGE_PROVIDER est sélectionné. Si l’AttributeId n’est pas présent et que l’indicateur PREFER_CNG n’est pas passé, le nom du fournisseur est déterminé en fonction de l’algorithme de clé publique (autrement dit, l’algorithme de clé publique est déterminé par AlgorithmIdentifier dans PKCS #8) :

  • RSA : MS_ENHANCED_PROV_W
  • DSA : MS_DEF_DSS_DH_PROV_W

De même, la spécification de clé est déterminée à l’aide de l’AttributeId avec OID 2.5.29.15 (szOID_KEY_USAGE) comme suit :

Si une clé CAPI est utilisée :

  • Si KEY_ENCIPHERMENT ou DATA_ENCIPHERMENT est défini, la spécification de clé est définie sur AT_KEYEXCHANGE.
  • Si DIGITAL_SIGNATURE ou CERT_SIGN ou CRL_SIGN est défini, la spécification clé est définie sur AT_SIGNATURE.

Si une clé CNG est utilisée :

  • Si KEY_ENCIPHERMENT ou DATA_ENCIPHERMENT ou ENCIPHER_ONLY ou DECIPHER_ONLY est défini, l’utilisation de la clé ncrypt est définie sur ALLOW_DECRYPT.
  • Si DIGITAL_SIGNATURE ou CERT_SIGN ou CRL_SIGN est défini, l’utilisation de la clé ncrypt est définie sur ALLOW_SIGN.
  • Si KEY_AGREEMENT est définie, l’utilisation de la clé ncrypt est définie sur ALLOW_KEY_AGREEMENT.

Si l’AttributeId n’est pas présent, la valeur de clé CAPI est définie sur AT_KEYEXCHANGE pour RSA ou DH et l’algorithme est déterminé par AlgorithmIdentifier dans PKCS #8 ; sinon, l’algorithme est défini sur AT_SIGNATURE. Pour la valeur de clé CNG, l’utilisation de toutes les clés ncrypt est définie.

Note

Si un nom de fournisseur non valide est présent dans le paquet PFX, ou si le fournisseur de chiffrement de base ou amélioré n’est pas présent dans cette clé de Registre : HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider, une recherche de fournisseur est effectuée par le type de fournisseur à l’aide de cette sous-clé de Registre : HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types.

Microsoft prend uniquement en charge deux algorithmes de chiffrement/hachage pour l’importation d’un PFX :

  • TripleDES-SHA1
  • AES256-SHA256

Pour l’un des algorithmes ci-dessus, le chiffrement des certificats est facultatif.

Microsoft peut exporter un PFX à partir d’un magasin de certificats via la sélection All Tasks>Yes, export the private key. Vous pouvez sélectionner l’algorithme de chiffrement/hachage pour qu’il corresponde à l’un de ces deux choix.

Vous pouvez utiliser PowerShell pour exporter un PFX via les éléments suivants :

Export-PfxCertificate
[-CryptoAlgorithmOption <CryptoAlgorithmOptions>]

-CryptoAlgorithmOption spécifie l’algorithme permettant de chiffrer des clés privées dans le fichier PFX. Si ce paramètre n’est pas spécifié, la valeur par défaut est TripleDES_SHA1. Les valeurs acceptables pour ce paramètre sont les suivantes :

Valeur Description
TripleDES_SHA1 Les clés privées seront chiffrées dans le fichier PFX à l’aide du chiffrement Triple DES.
AES256_SHA256 Les clés privées seront chiffrées dans le fichier PFX à l’aide du chiffrement AES-256.

OpenSSL prend en charge les deux algorithmes ci-dessus via les commandes suivantes :

  • openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt
  • openssl pkcs12 -keypbe AES-256-CBC -certpbe AES-256-CBC -macalg sha256 -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt

Les commandes suivantes sont équivalentes aux deux précédentes, mais elles ne chiffrent pas les certificats :

  • openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe NONE -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt
  • openssl pkcs12 -keypbe AES-256-CBC -certpbe NONE -macalg sha256 -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt

Exigences

Exigence Valeur
client minimum pris en charge Windows XP [applications de bureau | Applications UWP]
serveur minimum pris en charge Windows Server 2003 [applications de bureau | Applications UWP]
plateforme cible Windows
d’en-tête wincrypt.h
bibliothèque Crypt32.lib
DLL Crypt32.dll

Voir aussi

PFXExportCertStore

PFXExportCertStoreEx