Fonction CryptGetProvParam (wincrypt.h)
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 |
|---|---|
|
Retourne le numéro d’identification personnel (PIN) administrateur dans le paramètre pbData en tant que LPSTR. |
|
Cette constante n’est pas utilisée. |
|
Cette constante n’est pas utilisée. |
|
Retourne la chaîne de certificats associée au handle hProv . La chaîne de certificats retournée est X509_ASN_ENCODING encodée. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
Cette constante n’est pas utilisée. |
|
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 . |
|
Cette constante n’est pas utilisée. |
|
Valeur DWORD qui indique comment le fournisseur de solutions Cloud est implémenté. Pour obtenir une table des valeurs possibles, consultez Remarques. |
|
Cette requête n’est pas utilisée. |
|
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. |
|
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. |
|
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 . |
|
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. |
|
Retourne une valeur DWORD de CRYPT_SEC_DESCR. |
|
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. |
|
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é. |
|
Valeur DWORD qui indique le type de fournisseur du fournisseur csp. |
|
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. |
|
Taille, en bits, de la clé de session. |
|
Utilisé avec le chiffrement fermé du serveur. |
|
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. |
|
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. |
|
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. |
|
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. |
|
Taille de la clé symétrique. |
|
Cette requête n’est pas utilisée. |
|
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. |
|
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. |
|
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. |
|
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.
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.
Les valeurs suivantes sont définies pour une utilisation avec PP_ENUMALGS, PP_ENUMALGS_EX et PP_ENUMCONTAINERS.
| Valeur | Signification |
|---|---|
|
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. |
|
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. |
|
Récupérez les certificats SGC ( Server-Gated Cryptography ). Les certificats activés pour SGC ne sont plus pris en charge. |
|
Cet indicateur n’est pas utilisé. |
|
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 |
|---|---|
|
L’un des paramètres spécifie un handle qui n’est pas valide. |
|
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. |
|
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. |
|
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. |
|
Le paramètre dwFlags spécifie un indicateur non valide. |
|
Le paramètre dwParam spécifie un nombre de valeurs inconnue. |
|
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 |