Partager via


Fonction CryptGetProvParam (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 CryptGetProvParam récupère les paramètres qui régissent les opérations d’un fournisseur de services de chiffrement (CSP).

Syntaxe

BOOL CryptGetProvParam(
  [in]      HCRYPTPROV hProv,
  [in]      DWORD      dwParam,
  [out]     BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwFlags
);

Paramètres

[in] hProv

Handle de la cible CSP de la requête. Ce handle doit avoir été créé à l’aide de la fonction CryptAcquireContext .

[in] dwParam

Nature de la requête. Les requêtes suivantes sont définies.

Valeur Signification
PP_ADMIN_PIN
31 (0x1F)
Retourne le numéro d’identification personnel (PIN) administrateur dans le paramètre pbData en tant que LPSTR.
PP_APPLI_CERT
18 (0x12)
Cette constante n’est pas utilisée.
PP_CHANGE_PASSWORD
7 (0x7)
Cette constante n’est pas utilisée.
PP_CERTCHAIN
9 (0x9)
Retourne la chaîne de certificats associée au handle hProv . La chaîne de certificats retournée est X509_ASN_ENCODING encodée.
PP_CONTAINER
6 (0x6)
Nom du conteneur de clé actuel en tant que chaîne CHAR terminée par null. Cette chaîne est exactement la même que celle passée dans le paramètre pszContainer de la fonction CryptAcquireContext pour spécifier le conteneur de clé à utiliser. Le paramètre pszContainer peut être lu pour déterminer le nom du conteneur de clés par défaut.
PP_CRYPT_COUNT_KEY_USE
41 (0x29)
Non implémenté par les fournisseurs de services cloud Microsoft. Ce comportement peut être implémenté par d’autres csp.

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

PP_ENUMALGS
1 (0x1)
Structure PROV_ENUMALGS qui contient des informations sur un algorithme pris en charge par le fournisseur de solutions Cloud interrogé.

La première fois que cette valeur est lue, le paramètre dwFlags doit contenir l’indicateur CRYPT_FIRST . Cette opération entraîne la récupération du premier élément de l’énumération par cette fonction. Les éléments suivants peuvent ensuite être récupérés en définissant l’indicateur CRYPT_NEXT dans le paramètre dwFlags . Lorsque cette fonction échoue avec le code d’erreur ERROR_NO_MORE_ITEMS, la fin de l’énumération est atteinte.

Cette fonction n’est pas thread-safe, et tous les algorithmes disponibles peuvent ne pas être énumérés si cette fonction est utilisée dans un contexte multithread.

PP_ENUMALGS_EX
22 (0x16)
Structure PROV_ENUMALGS_EX qui contient des informations sur un algorithme pris en charge par le fournisseur de solutions Cloud interrogé. La structure retournée contient plus d’informations sur l’algorithme que la structure retournée pour PP_ENUMALGS.

La première fois que cette valeur est lue, le paramètre dwFlags doit contenir l’indicateur CRYPT_FIRST . Cette opération entraîne la récupération du premier élément de l’énumération par cette fonction. Les éléments suivants peuvent ensuite être récupérés en définissant l’indicateur CRYPT_NEXT dans le paramètre dwFlags . Lorsque cette fonction échoue avec le code d’erreur ERROR_NO_MORE_ITEMS, la fin de l’énumération est atteinte.

Cette fonction n’est pas thread-safe et tous les algorithmes disponibles peuvent ne pas être énumérés si cette fonction est utilisée dans un contexte multithread.

PP_ENUMCONTAINERS
2 (0x2)
Nom de l’un des conteneurs de clés gérés par le fournisseur de solutions Cloud sous la forme d’une chaîne CHAR terminée par null.

La première fois que cette valeur est lue, le paramètre dwFlags doit contenir l’indicateur CRYPT_FIRST . Cette opération entraîne la récupération du premier élément de l’énumération par cette fonction. Les éléments suivants peuvent ensuite être récupérés en définissant l’indicateur CRYPT_NEXT dans le paramètre dwFlags . Lorsque cette fonction échoue avec le code d’erreur ERROR_NO_MORE_ITEMS, la fin de l’énumération est atteinte.

Pour énumérer les conteneurs de clés associés à un ordinateur, appelez d’abord CryptAcquireContext à l’aide de l’indicateur CRYPT_MACHINE_KEYSET , puis utilisez le handle retourné par CryptAcquireContext comme paramètre hProv dans l’appel à CryptGetProvParam.

Cette fonction n’est pas thread-safe et tous les algorithmes disponibles peuvent ne pas être énumérés si cette fonction est utilisée dans un contexte multithread.

PP_ENUMELECTROOTS
26 (0x1A)
Cette constante n’est pas utilisée.
PP_ENUMEX_SIGNING_PROT
40 (0x28)
Indique que le fournisseur de solutions Cloud actuel prend en charge le membre dwProtocols de la structure PROV_ENUMALGS_EX . Si cette fonction réussit, le fournisseur de solutions Cloud prend en charge le membre dwProtocols de la structure PROV_ENUMALGS_EX . Si cette fonction échoue avec un code d’erreur NTE_BAD_TYPE , le fournisseur de solutions Cloud ne prend pas en charge le membre dwProtocols .
PP_ENUMMANDROOTS
25 (0x19)
Cette constante n’est pas utilisée.
PP_IMPTYPE
3 (0x3)
Valeur DWORD qui indique comment le fournisseur de solutions Cloud est implémenté. Pour obtenir une table des valeurs possibles, consultez Remarques.
PP_KEY_TYPE_SUBTYPE
10 (0xA)
Cette requête 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 confidentiel est représenté sous la forme d’une chaîne ASCII terminée par un caractère Null.
PP_KEYSET_SEC_DESCR
8 (0x8)
Récupère le descripteur de sécurité pour le conteneur de stockage de clés. Le paramètre pbData est l’adresse d’une structure de SECURITY_DESCRIPTOR qui reçoit le descripteur de sécurité pour le conteneur de stockage de clés. Le descripteur de sécurité est retourné au format auto-relatif.
PP_KEYSET_TYPE
27 (0x1B)
Détermine si le paramètre hProv est un jeu de clés d’ordinateur. Le paramètre pbData doit être un DWORD ; L’indicateur DWORD est défini sur l’indicateur CRYPT_MACHINE_KEYSET si cet indicateur a été passé à la fonction CryptAcquireContext .
PP_KEYSPEC
39 (0x27)
Retourne des informations sur les valeurs du spécificateur de clé pris en charge par le fournisseur de solutions Cloud. Les valeurs du spécificateur de clé sont jointes dans un OR logique et retournées dans le paramètre pbData de l’appel en tant que DWORD. Par exemple, le fournisseur de chiffrement de base Microsoft version 1.0 retourne une valeur DWORD de AT_SIGNATURE | AT_KEYEXCHANGE.
PP_KEYSTORAGE
17 (0x11)
Retourne une valeur DWORD de CRYPT_SEC_DESCR.
PP_KEYX_KEYSIZE_INC
35 (0x23)
Nombre de bits pour la longueur d’incrément de AT_KEYEXCHANGE. Ces informations sont utilisées avec les informations retournées dans la valeur PP_ENUMALGS_EX. Avec les informations retournées lors de l’utilisation de PP_ENUMALGS_EX et de PP_KEYX_KEYSIZE_INC, les longueurs de clé valides pour AT_KEYEXCHANGE peuvent être déterminées. Ces longueurs de clé peuvent ensuite être utilisées avec CryptGenKey. Par exemple, si un fournisseur de solutions cloud énumère CALG_RSA_KEYX (AT_KEYEXCHANGE) avec une longueur de clé minimale de 512 bits et un maximum de 1 024 bits, et retourne la longueur d’incrément sous la forme de 64 bits, les longueurs de clé valides sont de 512, 576, 640,... 1024.
PP_NAME
4 (0x4)
Nom du fournisseur de solutions cloud sous la forme d’une chaîne CHAR terminée par null. Cette chaîne est identique à celle passée dans le paramètre pszProvider de la fonction CryptAcquireContext pour spécifier que le fournisseur de solutions cloud actuel doit être utilisé.
PP_PROVTYPE
16 (0x10)
Valeur DWORD qui indique le type de fournisseur du fournisseur csp.
PP_ROOT_CERTSTORE
46 (0x2E)
Obtient le magasin de certificats racine pour le carte intelligent. Ce magasin de certificats contient tous les certificats racine stockés sur le carte intelligent.

Le paramètre pbData est l’adresse d’une variable HCERTSTORE qui reçoit le handle du magasin de certificats. 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_SESSION_KEYSIZE
20 (0x14)
Taille, en bits, de la clé de session.
PP_SGC_INFO
37 (0x25)
Utilisé avec le chiffrement fermé du serveur.
PP_SIG_KEYSIZE_INC
34 (0x22)
Nombre de bits pour la longueur d’incrément de AT_SIGNATURE. Ces informations sont utilisées avec les informations retournées dans la valeur PP_ENUMALGS_EX. Avec les informations retournées lors de l’utilisation de PP_ENUMALGS_EX et de PP_SIG_KEYSIZE_INC, les longueurs de clé valides pour AT_SIGNATURE peuvent être déterminées. Ces longueurs de clé peuvent ensuite être utilisées avec CryptGenKey.

Par exemple, si un fournisseur de solutions cloud énumère CALG_RSA_SIGN (AT_SIGNATURE) avec une longueur de clé minimale de 512 bits et un maximum de 1 024 bits, et retourne la longueur d’incrément de 64 bits, les longueurs de clé valides sont de 512, 576, 640,... 1024.

PP_SIGNATURE_PIN
33 (0x21)
Spécifie que le code pin de signature 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_SMARTCARD_GUID
45 (0x2D)
Obtient l’identificateur du carte intelligent. Le paramètre pbData est l’adresse d’une structure GUID qui reçoit l’identificateur du carte intelligent.

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

PP_SMARTCARD_READER
43 (0x2B)
Obtient le nom du lecteur smart carte. Le paramètre pbData est l’adresse d’un tableau de caractères ANSI qui reçoit une chaîne ANSI terminée par null qui contient le nom du lecteur smart carte. La taille de cette mémoire tampon, contenue dans la variable pointée par le paramètre pdwDataLen , doit inclure la terminaison NULL .

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

PP_SYM_KEYSIZE
19 (0x13)
Taille de la clé symétrique.
PP_UI_PROMPT
21 (0x15)
Cette requête n’est pas utilisée.
PP_UNIQUE_CONTAINER
36 (0x24)
Nom de conteneur unique du conteneur de clé actuel sous la forme d’une chaîne CHAR terminée par null. Pour de nombreux fournisseurs de solutions cloud, ce nom est le même que celui retourné lorsque la valeur PP_CONTAINER est utilisée. La fonction CryptAcquireContext doit fonctionner avec ce nom de conteneur.
PP_USE_HARDWARE_RNG
38 (0x26)
Indique si un générateur de nombres aléatoires matériel (RNG) est pris en charge. Lorsque PP_USE_HARDWARE_RNG est spécifié, la fonction réussit et retourne TRUE si un RNG matériel est pris en charge. La fonction échoue et retourne FALSE si un RNG matériel n’est pas pris en charge. Si un RNG est pris en charge, PP_USE_HARDWARE_RNG peut être défini dans CryptSetProvParam pour indiquer que le fournisseur de solutions cloud doit utiliser exclusivement le RNG matériel pour ce contexte de fournisseur. Lorsque PP_USE_HARDWARE_RNG est utilisé, le paramètre pbData doit être NULL et dwFlags doit être égal à zéro.

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

PP_USER_CERTSTORE
42 (0x2A)
Obtient 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 l’adresse d’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_VERSION
5 (0x5)
Numéro de version du fournisseur de solutions cloud. L’octet le moins significatif contient le numéro de version mineure et l’octet le plus significatif suivant le numéro de version principale. La version 2.0 est représentée en tant que 0x00000200. Pour maintenir la compatibilité descendante avec les versions antérieures du fournisseur de chiffrement de base Microsoft et du fournisseur de chiffrement microsoft amélioré, les noms des fournisseurs conservent la désignation « v1.0 » dans les versions ultérieures.

[out] pbData

Pointeur vers une mémoire tampon pour recevoir les données. La forme de ces données varie en fonction de la valeur de dwParam. Lorsque dwParam est défini sur PP_USE_HARDWARE_RNG, pbData doit avoir la valeur NULL.

Ce paramètre peut avoir la valeur NULL pour définir la taille de ces informations à des fins d’allocation de mémoire. Pour plus d’informations, consultez Récupération de données de longueur inconnue.

[in, out] pdwDataLen

Pointeur vers une valeur DWORD qui spécifie la taille, en octets, de la mémoire tampon pointée vers le paramètre pbData . Lorsque la fonction retourne, la valeur DWORD contient le nombre d’octets stockés ou à stocker dans la mémoire tampon.

Note Lors du traitement des données retournées dans la mémoire tampon, les applications doivent utiliser la taille réelle des données retournées. La taille réelle peut être légèrement inférieure à la taille de la mémoire tampon spécifiée lors de l’entrée. (En entrée, les tailles de mémoire tampon sont généralement spécifiées suffisamment grandes pour garantir que les données de sortie les plus volumineuses possibles s’intègrent dans la mémoire tampon.) En sortie, la variable pointée par ce paramètre est mise à jour pour refléter la taille réelle des données copiées dans la mémoire tampon.

Si PP_ENUMALGS ou PP_ENUMALGS_EX est défini, le paramètre pdwDataLen fonctionne quelque peu différemment. Si pbData a la valeur NULL ou si la valeur indiquée par pdwDataLen est trop petite, la valeur retournée dans ce paramètre correspond à la taille du plus grand élément de la liste d’énumération au lieu de la taille de l’élément en cours de lecture.

Si PP_ENUMCONTAINERS est défini, le premier appel à la fonction retourne la taille du conteneur clé maximal autorisé par le fournisseur actuel. Cela contraste avec d’autres comportements possibles, comme le retour de la longueur du conteneur existant le plus long ou de la longueur du conteneur actuel. Les appels d’énumération suivants ne modifient pas le paramètre dwLen . Pour chaque conteneur énuméré, l’appelant peut déterminer la longueur de la chaîne terminée par null par programmation, si vous le souhaitez. Si l’une des valeurs d’énumération est lue et que le paramètre pbData a la valeur NULL, l’indicateur CRYPT_FIRST doit être spécifié pour que les informations de taille soient récupérées correctement.

 

[in] dwFlags

Si dwParam est PP_KEYSET_SEC_DESCR, le descripteur de sécurité sur le conteneur de clés où les clés sont stockées est récupéré. Dans ce cas, dwFlags est utilisé pour passer les indicateurs de bits SECURITY_INFORMATION qui indiquent les informations de sécurité demandées, comme défini dans le Kit de développement logiciel (SDK) de plateforme. SECURITY_INFORMATION indicateurs de bits peuvent être combinés avec une opération OR au niveau du bit.

Les valeurs suivantes sont définies pour une utilisation avec PP_KEYSET_SEC_DESCR.

Valeur Signification
OWNER_SECURITY_INFORMATION
L’identificateur du propriétaire de l’objet est référencé.
GROUP_SECURITY_INFORMATION
L’identificateur de groupe principal de l’objet est référencé.
DACL_SECURITY_INFORMATION
L’ACL discrétionnaire de l’objet est référencée.
SACL_SECURITY_INFORMATION
La liste de contrôle d’accès système de l’objet est référencée.
 

Les valeurs suivantes sont définies pour une utilisation avec PP_ENUMALGS, PP_ENUMALGS_EX et PP_ENUMCONTAINERS.

Valeur Signification
CRYPT_FIRST
1 (0x1)
Récupérez le premier élément de l’énumération. Cela a le même effet que la réinitialisation de l’énumérateur.
CRYPT_NEXT
2 (0x2)
Récupérez l’élément suivant dans l’énumération. Lorsqu’il n’y a plus d’éléments à récupérer, cette fonction échoue et définit la dernière erreur sur ERROR_NO_MORE_ITEMS.
CRYPT_SGC_ENUM
4 (0x4)
Récupérez les certificats SGC ( Server-Gated Cryptography ). Les certificats activés pour SGC ne sont plus pris en charge.
CRYPT_SGC
Cet indicateur n’est pas utilisé.
CRYPT_FASTSGC
Cet indicateur n’est pas utilisé.

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 particulier utilisé. Certains codes d’erreur possibles suivent.

Code de retour Description
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.
ERROR_MORE_DATA
Si la mémoire tampon spécifiée par le paramètre pbData n’est pas assez grande pour contenir les données retournées, la fonction définit le code ERROR_MORE_DATA et stocke la taille de mémoire tampon requise, en octets, dans la variable pointée par pdwDataLen.
ERROR_NO_MORE_ITEMS
La fin de la liste d’énumération a été atteinte. Aucune donnée valide n’a été placée dans la mémoire tampon pbData . Ce code d’erreur est retourné uniquement lorsque dwParam est égal à PP_ENUMALGS ou PP_ENUMCONTAINERS.
NTE_BAD_FLAGS
Le paramètre dwFlags spécifie un indicateur non valide.
NTE_BAD_TYPE
Le paramètre dwParam spécifie un nombre de valeurs inconnue.
NTE_BAD_UID
Le contexte CSP spécifié par hProv n’est pas valide.

Remarques

Cette fonction ne doit pas être utilisée sur un thread d’un programme multithread.

Les valeurs suivantes sont retournées dans pbData si dwParam est PP_IMPTYPE.

Valeur Signification
CRYPT_IMPL_HARDWARE
0x01
L’implémentation est dans le matériel.
CRYPT_IMPL_SOFTWARE
0x02
L’implémentation est dans le logiciel.
CRYPT_IMPL_MIXED
0x03
L’implémentation implique à la fois le matériel et les logiciels.
CRYPT_IMPL_UNKNOWN
0x04
Le type d’implémentation est inconnu.
CRYPT_IMPL_REMOVABLE
0x08
L’implémentation est dans un média amovible.
 

Le paramètre dwFlags est utilisé pour passer les indicateurs de bits SECURITY_INFORMATION qui indiquent les informations de sécurité demandées. Le pointeur vers le descripteur de sécurité est retourné dans le paramètre pbData et la longueur du descripteur de sécurité est retournée dans le paramètre pdwDataLen . La sécurité des conteneurs de clés est gérée avec SetFileSecurity et GetFileSecurity.

La classe d’un algorithme énuméré avec dwParam défini sur PP_ENUMALGS ou PP_ENUMALGS_EX peut être déterminée. Cela peut être fait pour afficher une liste des algorithmes de chiffrement pris en charge et pour ignorer le reste. La macro GET_ALG_CLASS(x) prend un identificateur d’algorithme comme argument et retourne un code indiquant la classe générale de cet algorithme. Les valeurs de retour possibles sont les suivantes :

  • ALG_CLASS_DATA_ENCRYPT
  • ALG_CLASS_HASH
  • ALG_CLASS_KEY_EXCHANGE
  • ALG_CLASS_SIGNATURE

Le tableau suivant répertorie les algorithmes pris en charge par le fournisseur de chiffrement de base Microsoft, ainsi que la classe de chaque algorithme.

Nom Identificateur Classe
« MD2 » CALG_MD2 ALG_CLASS_HASH
« MD5 » CALG_MD5 ALG_CLASS_HASH
« SHA » CALG_SHA ALG_CLASS_HASH
« MAC » CALG_MAC ALG_CLASS_HASH
« RSA_SIGN » CALG_RSA_SIGN ALG_CLASS_SIGNATURE
« RSA_KEYX » CALG_RSA_KEYX ALG_CLASS_KEY_EXCHANGE
« RC2 » CALG_RC2 ALG_CLASS_DATA_ENCRYPT
« RC4 » CALG_RC4 ALG_CLASS_DATA_ENCRYPT
 

Les applications ne doivent pas utiliser un algorithme avec un identificateur d’algorithme qui n’est pas reconnu. L’utilisation d’un algorithme de chiffrement inconnu peut produire des résultats imprévisibles.

Exemples

L’exemple suivant montre comment trouver le nom du fournisseur de solutions Cloud associé à un handle de fournisseur de services de chiffrement et le nom du conteneur de clés associé au handle. Pour obtenir le contexte complet de cet exemple, consultez Exemple de programme C : utilisation de CryptAcquireContext.

Pour obtenir un autre exemple qui utilise cette fonction, consultez Exemple de programme C : Énumération des fournisseurs CSP et des types de fournisseurs.

//-----------------------------------------------------------------
//  Declare and initialize variables.

HCRYPTPROV hCryptProv;
BYTE       pbData[1000];       // 1000 will hold the longest 
                               // key container name.
DWORD cbData;

//-------------------------------------------------------------------
// An HCRYPTPROV must be acquired before using code like that in 
// "Example C Program Using CryptAcquireContext."

//-------------------------------------------------------------------
// Read the name of the default CSP.

cbData = 1000;
if(CryptGetProvParam(
    hCryptProv, 
    PP_NAME, 
    pbData, 
    &cbData, 
    0))
{
    printf("CryptGetProvParam succeeded.\n");
    printf("Provider name: %s\n", pbData);
}
else
{
    printf("Error reading CSP name. \n");
    exit(1);
}
//--------------------------------------------------------------------
// Read the name of the default key container.

cbData = 1000;
if(CryptGetProvParam(
    hCryptProv, 
    PP_CONTAINER, 
    pbData, 
    &cbData, 
    0))
{
    printf("CryptGetProvParam succeeded. \n");
    printf("Key Container name: %s\n", pbData);
}
else
{
    printf("Error reading key container name. \n");
    exit(1);
}

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

Descripteurs de sécurité absolus et Self-Relative

CryptAcquireContext

CryptCreateHash

CryptDeriveKey

CryptGenKey

CryptGetKeyParam

CryptSetProvParam

Fonctions du fournisseur de services