NCryptImportKey, fonction (ncrypt.h)

La fonction NCryptImportKey importe une API de chiffrement : nouvelle génération (CNG) à partir d’un objet BLOB 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 vers la même clé que celle passée dans le paramètre hExportKey de la fonction NCryptExportKey . Si ce paramètre est 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 le 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 retournée

Retourne un code d’état qui indique la réussite ou l’échec de la fonction.

Les codes de retour possibles incluent, mais ne sont pas limités, les éléments suivants :

Remarques

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 interblocage 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
• KSP de carte à puce Microsoft

Microsoft Software KSP

Reportez-vous à NCryptImportKey pour plus d’informations sur la plupart des paramètres pszBlobType pris en charge par le KSP logiciel Microsoft.

Si un nom de clé n’est pas fourni, le KSP logiciel Microsoft 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 lorsqu’il est exporté. Pour les 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 qu’objets blob d’enveloppe PKCS #7 (NCRYPT_PKCS7_ENVELOPE_BLOB) ou PKCS #8 objets blob privés (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.

KSP de carte à puce Microsoft

L’ensemble de formats et d’indicateurs BLOB clés 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 KSP de carte à puce Microsoft importe toutes les clés dans le KSP logiciel Microsoft. Par conséquent, les clés ne peuvent pas être conservées sur une carte à puce à l’aide de cette API, et les instructions de la section ci-dessus s’appliquent lors de la tentative de persistance des clés dans le KSP logiciel Microsoft.

Sur Windows Server 2008 R2 et Windows 7, le fournisseur de stockage de clé 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és 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 sont définies sur un DWORD de 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 KSP logiciel Microsoft.

Configuration matérielle requise supplémentaire pour les clés VBS

Bien que vous ayez peut-être installé le système d’exploitation approprié sur votre ordinateur, la configuration matérielle supplémentaire suivante doit être remplie pour utiliser VBS pour générer et protéger des clés.

• VBS activé (voir Sécurité basée sur la virtualisation (VBS))
• Module de plateforme sécurisée activée
  • Pour les environnements nus, TPM 2.0 est requis.
  • Pour les environnements de machine virtuelle, vTPM (Virtual TPM) 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. Vous trouverez ici la liste complète des exigences matérielles VBS.
• Vous trouverez ici les conditions requises pour un appareil hautement sécurisé.

Spécifications

Voir aussi

NCryptBuffer

NCryptCreatePersistedKey