Partager via


Fonction CryptSetProvParam (wincrypt.h)

Important Cette API est déconseillée. Les logiciels nouveaux et existants doivent commencer à utiliser les API de nouvelle génération de chiffrement. Microsoft peut supprimer cette API dans les versions ultérieures.
 
La fonction CryptSetProvParam personnalise les opérations d’un fournisseur de services de chiffrement (CSP). Cette fonction est couramment utilisée pour définir un descripteur de sécurité sur le conteneur de clés associé à un fournisseur de solutions cloud afin de contrôler l’accès aux clés privées dans ce conteneur de clés.

Syntaxe

BOOL CryptSetProvParam(
  [in] HCRYPTPROV hProv,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

Paramètres

[in] hProv

Handle d’un fournisseur de solutions cloud pour lequel définir des valeurs. Ce handle doit déjà avoir été créé à l’aide de la fonction CryptAcquireContext .

[in] dwParam

Spécifie le paramètre à définir. Il peut s’agir de l’une des valeurs suivantes.

Valeur Signification
PP_CLIENT_HWND
1 (0x1)
Définissez le handle de fenêtre que le fournisseur utilise comme parent de toutes les boîtes de dialogue qu’il crée. pbData contient un pointeur vers un HWND qui contient le handle de fenêtre parente.

Ce paramètre doit être défini avant d’appeler CryptAcquireContext , car de nombreux fournisseurs de solutions cloud affichent une interface utilisateur lorsque CryptAcquireContext est appelé. Vous pouvez passer la valeur NULL pour le paramètre hProv afin de définir ce handle de fenêtre pour tous les contextes de chiffrement acquis par la suite dans ce processus.

PP_DELETEKEY
24 (0x18)
Supprimez la clé éphémère associée à un contexte de hachage, de chiffrement ou de vérification. Cela libère de la mémoire et efface les paramètres de Registre associés à la clé.
PP_KEYEXCHANGE_ALG
Cette constante n’est pas utilisée.
PP_KEYEXCHANGE_PIN
32 (0x20)
Spécifie que le code pin d’échange de clé est contenu dans pbData. Le code pin est représenté sous la forme d’une chaîne ASCII terminée par une valeur Null.
PP_KEYEXCHANGE_KEYSIZE
Cette constante n’est pas utilisée.
PP_KEYSET_SEC_DESCR
8 (0x8)
Définit le descripteur de sécurité sur le conteneur de stockage de clé. Le paramètre pbData est l’adresse d’une structure de SECURITY_DESCRIPTOR qui contient le nouveau descripteur de sécurité pour le conteneur de stockage de clé.
PP_PIN_PROMPT_STRING
44 (0x2C)
Définit une autre chaîne d’invite à afficher à l’utilisateur lorsque le code confidentiel de l’utilisateur est demandé. Le paramètre pbData est un pointeur vers une chaîne Unicode terminée par null.
PP_ROOT_CERTSTORE
46 (0x2E)
Définit le magasin de certificats racine pour le carte intelligent. Le fournisseur copie les certificats racine de ce magasin sur le carte intelligent.

Le paramètre pbData est une variable HCERTSTORE qui contient le handle du nouveau magasin de certificats. Le fournisseur copiera les certificats du magasin pendant cet appel. Il est donc sûr de fermer ce magasin après l’appel de cette fonction.

Windows XP et Windows Server 2003 : Ce paramètre n’est pas pris en charge.

PP_SIGNATURE_ALG
Cette constante n’est pas utilisée.
PP_SIGNATURE_PIN
33 (0x21)
Spécifie le code pin de signature. Le paramètre pbData est une chaîne ASCII terminée par null qui représente le code pin.
PP_SIGNATURE_KEYSIZE
Cette constante n’est pas utilisée.
PP_UI_PROMPT
21 (0x15)
Pour un fournisseur de carte intelligent, définit la chaîne de recherche affichée à l’utilisateur en tant qu’invite à insérer le carte intelligent. Cette chaîne est transmise en tant que membre lpstrSearchDesc de la structure OPENCARDNAME_EX transmise à la fonction SCardUIDlgSelectCard . Cette chaîne est utilisée pendant la durée de vie du processus appelant.

Le paramètre pbData est un pointeur vers une chaîne Unicode terminée par null.

PP_USE_HARDWARE_RNG
38 (0x26)
Spécifie que le fournisseur de services cloud doit utiliser exclusivement le générateur de nombres aléatoires matériels (RNG). Lorsque PP_USE_HARDWARE_RNG est défini, les valeurs aléatoires sont extraites exclusivement du RNG matériel et aucune autre source n’est utilisée. Si un RNG matériel est pris en charge par le fournisseur de solutions cloud et qu’il peut être utilisé exclusivement, la fonction réussit et retourne TRUE ; sinon, la fonction échoue et retourne FALSE. Le paramètre pbData doit avoir la valeur NULL et dwFlags doit être égal à zéro lors de l’utilisation de cette valeur.

Aucun des fournisseurs de solutions cloud Microsoft ne prend actuellement en charge l’utilisation d’un RNG matériel.

PP_USER_CERTSTORE
42 (0x2A)
Spécifie le magasin de certificats utilisateur pour le carte intelligent. Ce magasin de certificats contient tous les certificats utilisateur stockés sur le carte intelligent. Les certificats de ce magasin sont encodés à l’aide d’un encodage PKCS_7_ASN_ENCODING ou X509_ASN_ENCODING et doivent contenir la propriété CERT_KEY_PROV_INFO_PROP_ID .

Le paramètre pbData est une variable HCERTSTORE qui reçoit le handle d’un magasin de certificats en mémoire. Lorsque ce handle n’est plus nécessaire, l’appelant doit le fermer à l’aide de la fonction CertCloseStore .

Windows Server 2003 et Windows XP : Ce paramètre n’est pas pris en charge.

PP_SECURE_KEYEXCHANGE_PIN
47 (0x2F)
Spécifie qu’un code pin d’échange de clé chiffré est contenu dans pbData. Le paramètre pbData contient une DATA_BLOB.
PP_SECURE_SIGNATURE_PIN
48 (0x30)
Spécifie qu’un code pin de signature chiffré est contenu dans pbData. Le paramètre pbData contient une DATA_BLOB.
PP_SMARTCARD_READER
43 (0x2B)
Spécifie le nom du lecteur smart carte. Le paramètre pbData est l’adresse d’un tableau de caractères ANSI qui contient une chaîne ANSI terminée par null qui contient le nom du lecteur smart carte.

Windows Server 2003 et Windows XP : Ce paramètre n’est pas pris en charge.

PP_SMARTCARD_GUID
45 (0x2D)
Spécifie l’identificateur du carte intelligent. Le paramètre pbData est l’adresse d’une structure GUID qui contient l’identificateur du carte intelligent.

Windows Server 2003 et Windows XP : Ce paramètre n’est pas pris en charge.

[in] pbData

Pointeur vers une mémoire tampon de données qui contient la valeur à définir en tant que paramètre de fournisseur. La forme de ces données varie en fonction de la valeur dwParam . Si dwParam contient PP_USE_HARDWARE_RNG, ce paramètre doit avoir la valeur NULL.

[in] dwFlags

Si dwParam contient PP_KEYSET_SEC_DESCR, dwFlags contient les SECURITY_INFORMATION indicateurs de bits applicables, tels que définis dans le Kit de développement logiciel (SDK) de plateforme. La sécurité du conteneur de clés est gérée à l’aide de SetFileSecurity et GetFileSecurity.

Ces indicateurs de bits peuvent être combinés à l’aide d’une opération OR au niveau du bit. Pour plus d’informations, consultez CryptGetProvParam.

Si dwParam est PP_USE_HARDWARE_RNG ou PP_DELETEKEY, dwFlags doit être défini sur zéro.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro (TRUE).

Si la fonction échoue, la valeur de retour est zéro (FALSE). Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Les codes d’erreur préfacés par « NTE » sont générés par le fournisseur de solutions cloud en cours d’utilisation. Les codes d’erreur incluent les éléments suivants.

Code de retour Description
ERROR_BUSY
Le contexte CSP est actuellement utilisé par un autre processus.
ERROR_INVALID_HANDLE
L’un des paramètres spécifie un handle qui n’est pas valide.
ERROR_INVALID_PARAMETER
L’un des paramètres contient une valeur qui n’est pas valide. Il s’agit le plus souvent d’un pointeur qui n’est pas valide.
NTE_BAD_FLAGS
Le paramètre dwFlags est différent de zéro ou la mémoire tampon pbData contient une valeur non valide.
NTE_BAD_TYPE
Le paramètre dwParam spécifie un paramètre inconnu.
NTE_BAD_UID
Le contexte CSP spécifié lors de la création de la clé hKey est introuvable.
NTE_FAIL
La fonction a échoué d’une manière inattendue.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
Plateforme cible Windows
En-tête wincrypt.h
Bibliothèque Advapi32.lib
DLL Advapi32.dll

Voir aussi

CryptAcquireContext

CryptGetProvParam

CryptSetKeyParam

Fonctions du fournisseur de services