NCryptImportKey, fonction (ncrypt.h)
La fonction NCryptImportKey importe une clé d’API de chiffrement : nouvelle génération (CNG) à partir d’un objet BLOB de mémoire.
Syntaxe
SECURITY_STATUS NCryptImportKey(
[in] NCRYPT_PROV_HANDLE hProvider,
[in, optional] NCRYPT_KEY_HANDLE hImportKey,
[in] LPCWSTR pszBlobType,
[in, optional] NCryptBufferDesc *pParameterList,
[out] NCRYPT_KEY_HANDLE *phKey,
[in] PBYTE pbData,
[in] DWORD cbData,
[in] DWORD dwFlags
);
Paramètres
[in] hProvider
Handle du fournisseur de stockage de clés.
[in, optional] hImportKey
Handle de la clé de chiffrement avec laquelle les données de clé dans l’objet BLOB de clé importée ont été chiffrées. Il doit s’agir d’un handle de la clé qui a été passée dans le paramètre hExportKey de la fonction NCryptExportKey . Si ce paramètre a la valeur NULL, l’objet BLOB de clé est supposé ne pas être chiffré.
[in] pszBlobType
Chaîne Unicode terminée par null qui contient un identificateur qui spécifie le format de l’objet BLOB de clé. Ces formats sont spécifiques à un fournisseur de stockage de clés particulier. Pour connaître les formats BLOB pris en charge par les fournisseurs Microsoft, consultez Remarques.
[in, optional] pParameterList
Adresse d’une structure NCryptBufferDesc qui pointe vers un tableau de mémoires tampons qui contiennent des informations de paramètre pour la clé.
[out] phKey
Adresse d’une variable NCRYPT_KEY_HANDLE qui reçoit le handle de la clé. Une fois que vous avez terminé d’utiliser ce handle, relâchez-le en le transmettant à la fonction NCryptFreeObject .
[in] pbData
Adresse d’une mémoire tampon qui contient l’objet BLOB de clé à importer. Le paramètre cbData contient la taille de cette mémoire tampon.
[in] cbData
Taille, en octets, de la mémoire tampon pbData .
[in] dwFlags
Indicateurs qui modifient le comportement de la fonction. Il peut s’agir de zéro ou d’une combinaison d’une ou plusieurs des valeurs suivantes. L’ensemble d’indicateurs valides est spécifique à chaque fournisseur de stockage de clés.
| Valeur | Signification |
|---|---|
| NCRYPT_SILENT_FLAG | Demande que le fournisseur de services de clé (KSP) n’affiche aucune interface utilisateur. Si le fournisseur doit afficher l’interface utilisateur pour fonctionner, l’appel échoue et le KSP doit définir le code d’erreur NTE_SILENT_CONTEXT comme dernière erreur. |
| NCRYPT_REQUIRE_VBS_FLAG | Indique qu’une clé doit être protégée avec la sécurité basée sur la virtualisation (VBS). Par défaut, cela crée une clé persistante de démarrage croisé stockée sur le disque qui persiste entre les cycles de redémarrage. L’opération échoue si VBS n’est pas disponible. (*Voir remarques) |
| NCRYPT_PREFER_VBS_FLAG | Indique qu’une clé doit être protégée avec la sécurité basée sur la virtualisation (VBS). Par défaut, cela crée une clé persistante de démarrage croisé stockée sur le disque qui persiste entre les cycles de redémarrage. L’opération génère une clé isolée du logiciel si VBS n’est pas disponible. (*Voir remarques) |
| NCRYPT_USE_PER_BOOT_KEY_FLAG | Indicateur supplémentaire qui peut être utilisé avec NCRYPT_REQUIRE_VBS_FLAG ou NCRYPT_PREFER_VBS_FLAG. Demande à la sécurité basée sur la virtualisation (VBS) de protéger la clé client avec une clé par démarrage qui est stockée sur le disque mais qui ne peut pas être réutilisée entre les cycles de démarrage. (*Voir remarques) |
Valeur retournée
Retourne un code d’état qui indique la réussite ou l’échec de la fonction.
Les codes de retour possibles incluent, sans s’y limiter, les suivants :
| Code de retour | Description |
|---|---|
| ERROR_SUCCESS | La fonction a réussi. |
| NTE_BAD_FLAGS | Le paramètre dwFlags contient une valeur qui n’est pas valide. |
| NTE_EXISTS | Une clé portant le nom spécifié existe déjà et le NCRYPT_OVERWRITE_KEY_FLAG n’a pas été spécifié. |
| NTE_INVALID_HANDLE | Le paramètre hProvider n’est pas valide. |
| NTE_INVALID_PARAMETER | Un ou plusieurs paramètres ne sont pas valides. |
| NTE_NO_MEMORY | Un échec d’allocation de mémoire s’est produit. |
| NTE_VBS_UNAVAILABLE | VBS n’est pas disponible. |
| NTE_VBS_CANNOT_DECRYPT_KEY | Échec de l’opération de déchiffrement VBS. |
Remarques
Important
Les informations relatives aux indicateurs VBS concernent le produit de préversion qui peut être sensiblement modifié avant sa commercialisation. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.
Un service ne doit pas appeler cette fonction à partir de sa fonction StartService. Si un service appelle cette fonction à partir de sa fonction StartService , un blocage peut se produire et le service peut cesser de répondre.
Les sections suivantes décrivent les comportements spécifiques aux fournisseurs de stockage de clés Microsoft :
- Microsoft Software KSP
- Carte à puce Microsoft KSP
Microsoft Software KSP
Les constantes suivantes sont prises en charge par le logiciel Microsoft KSP pour le paramètre pszBlobType .
Si aucun nom de clé n’est fourni, microsoft Software KSP traite la clé comme éphémère et ne la stocke pas de manière permanente. Pour le type NCRYPT_OPAQUETRANSPORT_BLOB , le nom de clé est stocké dans l’objet BLOB lors de son exportation. Pour d’autres formats BLOB, le nom peut être fourni dans un paramètre de mémoire tampon NCRYPTBUFFER_PKCS_KEY_NAME dans le paramètre pParameterList .
Sur Windows Server 2008 et Windows Vista, seules les clés importées en tant que BLOB d’enveloppe PKCS #7 (NCRYPT_PKCS7_ENVELOPE_BLOB) ou PKCS #8 (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) peuvent être conservées à l’aide de la méthode ci-dessus. Pour conserver les clés importées via d’autres types d’objets blob sur ces plateformes, utilisez la méthode documentée dans Key Import and Export.
Les indicateurs suivants sont pris en charge par ce KSP.
| Terme | Description |
|---|---|
| NCRYPT_NO_KEY_VALIDATION | Ne validez pas la partie publique de la paire de clés. Cet indicateur s’applique uniquement aux paires de clés publiques/privées. |
| NCRYPT_DO_NOT_FINALIZE_FLAG | Ne finalisez pas la clé. Cette option est utile lorsque vous devez ajouter ou modifier des propriétés de la clé après l’avoir importée. Vous devez finaliser la clé avant de pouvoir l’utiliser en passant le handle de clé à la fonction NCryptFinalizeKey . Cet indicateur est pris en charge pour les clés privées PKCS #7 et PKCS #8, mais pas pour les clés publiques. |
| NCRYPT_MACHINE_KEY_FLAG | La clé s’applique à l’ordinateur local. Si cet indicateur n’est pas présent, la clé s’applique à l’utilisateur actuel. |
| NCRYPT_OVERWRITE_KEY_FLAG | Si une clé existe déjà dans le conteneur avec le nom spécifié, la clé existante est remplacée. Si cet indicateur n’est pas spécifié et qu’une clé portant le nom spécifié existe déjà, cette fonction retourne NTE_EXISTS. |
| NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG | Enregistrez également la clé dans le stockage hérité. Cela permet d’utiliser la clé avec cryptoAPI. Cet indicateur s’applique uniquement aux clés RSA. |
Microsoft Smart Card KSP
L’ensemble des principaux formats et indicateurs BLOB pris en charge par ce KSP est identique à l’ensemble pris en charge par le KSP logiciel Microsoft.
Sur Windows Server 2008 et Windows Vista, le fournisseur de services KSP de carte à puce Microsoft importe toutes les clés dans le fournisseur de clés microsoft software. Par conséquent, les clés ne peuvent pas être conservées sur une carte à puce à l’aide de cette API, et les conseils de la section ci-dessus s’appliquent lorsque vous essayez de conserver des clés dans le KSP logiciel Microsoft.
Sur Windows Server 2008 R2 et Windows 7, le fournisseur de stockage de clés de carte à puce Microsoft peut importer une clé privée dans une carte à puce, à condition que les conditions suivantes soient remplies :
- Le nom du conteneur de clé sur la carte est valide.
- L’importation de clés privées est prise en charge par la carte à puce.
- Les deux clés de Registre suivantes ont la valeur DWORD :
0x1- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateExchangeKeyImport
- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateSignatureKeyImport
Si le nom du conteneur de clé est NULL, le KSP de la carte à puce Microsoft traite la clé comme éphémère et l’importe dans le fournisseur de clés microsoft software.
Configuration matérielle supplémentaire requise pour les clés VBS
Bien que le système d’exploitation approprié puisse être installé sur votre ordinateur, les exigences matérielles supplémentaires suivantes doivent être remplies pour utiliser VBS pour générer et protéger des clés.
- VBS activé (consultez Sécurité basée sur la virtualisation (VBS))
- TPM activé
- Pour les environnements nus, TPM 2.0 est requis.
- Pour les environnements de machine virtuelle, vTPM (TPM virtuel) est pris en charge.
- Le BIOS doit être mis à niveau vers UEFI avec le profil SecureBoot
Pour plus d’informations sur la configuration matérielle requise :
- VBS a plusieurs exigences matérielles à exécuter, notamment Hyper-V (hyperviseur Windows), l’architecture 64 bits et la prise en charge de IOMMU. La liste complète des exigences matérielles VBS est disponible ici.
- La configuration requise pour un appareil hautement sécurisé est disponible ici.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | ncrypt.h |
| Bibliothèque | Ncrypt.lib |
| DLL | Ncrypt.dll |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour