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 de 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. Qu’elle soit définie sur une chaîne de longueur supérieure à zéro ou 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é au principal AD spécifié dans le paramètre pvPara . Dans ce cas, vous devez définir le mot de passe sur la valeur, chaîne vide ou NULL, qui a été utilisée lors de la création du paquet PFX. La fonction PFXImportCertStore utilise 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 avoir l’une des valeurs suivantes :

Valeur Signification
CRYPT_EXPORTABLE
0x00000001
 Les clés importées sont marquées comme étant 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 ignoraient 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 CRYPT_SILENT défini, l’utilisation de cet indicateur entraîne 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’elles 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 de configuration est préférable. 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’il est spécifié, PFXImportCertStore tente d’utiliser le KSP CNG, quelles que soient les informations de fournisseur dans le fichier PFX. Si le KSP CNG n’est pas disponible, l’importation n’é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éé une « TestKey » sur votre ordinateur, puis que vous importez un fichier PFX qui a également « TestKey » comme conteneur de clés, le paramètre PKCS12_ALLOW_OVERWRITE_KEY permet de remplacer 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 la vérification, au lieu de créer un conteneur, puis de le supprimer, vous pouvez spécifier cet indicateur pour supprimer immédiatement la clé.
Note Si l’indicateur de PKCS12_NO_PERSIST_KEY est *not* 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 CRYPT_DELETEKEYSET défini dans le paramètre dwFlags .
Note Voici d’autres considérations à prendre en compte :

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

  • Si le PKCS12_NO_PERSIST_KEY n’est pas utilisé, 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 fonctionnent, il doit être dans le même processus et l’utilisateur de l’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 la négociation est effectuée en externe avec le 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 du 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 retournée

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, c’est-à-dire si le paramètre password ne contient pas de correspondance exacte avec le mot de passe utilisé pour chiffrer le paquet exporté ou s’il y a eu d’autres problèmes de décodage de l’objet BLOB PFX, la fonction retourne NULL et un code d’erreur peut être trouvé en appelant la fonction GetLastError .

Remarques

La fonction PFXImportCertStore ouvre un magasin temporaire. Si la fonction réussit, vous devez fermer le handle au 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.4.1.311.17.1 du PKCS8ShroudedKeyBag SafeBag [bag]Id : 1.2.840.113549.1.12.10.1.2] (voir PKCS #12 pour plus d’informations sur la structure ASN.1 de ce).

  • AttributeId : 1.3.6.1.4.1.311.17.1
  • Valeur: Nom du fournisseur de services clés ou du fournisseur de services 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 l’algorithme 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, CERT_SIGN ou CRL_SIGN est défini, la spécification de clé est définie sur AT_SIGNATURE.

Si une clé CNG est utilisée :

  • Si KEY_ENCIPHERMENT ou DATA_ENCIPHERMENT, ENCIPHER_ONLY ou DECIPHER_ONLY est défini, l’utilisation de la clé ncrypt est définie sur ALLOW_DECRYPT.
  • Si DIGITAL_SIGNATURE, 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éfini, l’utilisation de la clé ncrypt est définie sur ALLOW_KEY_AGREEMENT.

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

Notes

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 All Tasks>Yes, export the private key sélection. Vous pouvez sélectionner l’algorithme de chiffrement/hachage qui correspond à 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 de chiffrement 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 valides pour ce paramètre sont :

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

Configuration requise

Condition requise Valeur
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

PFXExportCertStore

PFXExportCertStoreEx