Fonction NCryptCreatePersistedKey (ncrypt.h)
La fonction NCryptCreatePersistedKey crée une clé et la stocke dans le fournisseur de stockage de clés spécifié. Après avoir créé une clé à l’aide de cette fonction, vous pouvez utiliser la fonction NCryptSetProperty pour définir ses propriétés ; toutefois, la clé ne peut pas être utilisée tant que la fonction NCryptFinalizeKey n’est pas appelée.
Syntaxe
SECURITY_STATUS NCryptCreatePersistedKey(
[in] NCRYPT_PROV_HANDLE hProvider,
[out] NCRYPT_KEY_HANDLE *phKey,
[in] LPCWSTR pszAlgId,
[in, optional] LPCWSTR pszKeyName,
[in] DWORD dwLegacyKeySpec,
[in] DWORD dwFlags
);
Paramètres
[in] hProvider
Handle du fournisseur de stockage de clés dans lequel créer la clé. Ce handle est obtenu à l’aide de la fonction NCryptOpenStorageProvider .
[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 . Pour supprimer le fichier de clé sur le disque, passez le handle à la fonction NCryptDeleteKey . Cela libère également le handle. Les applications peuvent donc passer le handle à NCryptFreeObject ou À NCryptDeleteKey, mais pas aux deux.
[in] pszAlgId
Pointeur vers une chaîne Unicode terminée par null qui contient l’identificateur de l’algorithme de chiffrement pour créer la clé. Il peut s’agir de l’un des identificateurs d’algorithme CNG standard ou de l’identificateur d’un autre algorithme inscrit.
[in, optional] pszKeyName
Pointeur vers une chaîne Unicode terminée par null qui contient le nom de la clé. Si ce paramètre a la valeur NULL, cette fonction crée une clé éphémère qui n’est pas persistante.
[in] dwLegacyKeySpec
Identificateur hérité qui spécifie le type de clé. Il peut s’agir de l’une des valeurs suivantes :
| Valeur | Signification |
|---|---|
| AT_KEYEXCHANGE | La clé est une clé d’échange de clé. |
| AT_SIGNATURE | La clé est une clé de signature. |
| 0 | La clé n’est pas des types ci-dessus. |
[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 |
|---|---|
| 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_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é 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. |
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.
Si vous créez une paire de clés RSA, vous pouvez également avoir la clé stockée dans le stockage hérité afin qu’elle puisse être utilisée avec cryptoAPI en passant l’indicateur NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG à la fonction NCryptFinalizeKey lorsque la clé est finalisée.
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.
Configuration matérielle supplémentaire requise pour les clés VBS
Bien que vous ayez le système d’exploitation approprié 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 de la configuration matérielle requise pour VBS est disponible ici.
- Vous trouverez les conditions requises pour un appareil hautement sécurisé 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 |