Fonction CryptGetKeyParam (wincrypt.h)

Article
08/27/2023

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 CryptGetKeyParam récupère les données qui régissent les opérations d’une clé. Si le fournisseur de services de chiffrement Microsoft est utilisé, le matériel de keying symétrique de base n’est pas disponible par cette fonction ou toute autre fonction.

Syntaxe

BOOL CryptGetKeyParam(
  [in]      HCRYPTKEY hKey,
  [in]      DWORD     dwParam,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen,
  [in]      DWORD     dwFlags
);

Paramètres

[in] hKey

Handle de la clé interrogée.

[in] dwParam

Spécifie le type de requête en cours d’exécution.

Pour tous les types de clés, ce paramètre peut contenir l’une des valeurs suivantes.

Valeur	Signification
KP_ALGID	Récupérez l’algorithme de clé. Le paramètre pbData est un pointeur vers une valeur ALG_ID qui reçoit l’identificateur de l’algorithme spécifié lors de la création de la clé. Lorsque AT_KEYEXCHANGE ou AT_SIGNATURE est spécifié pour le paramètre Algid de la fonction CryptGenKey , les identificateurs d’algorithme utilisés pour générer la clé dépendent du fournisseur utilisé. Pour plus d’informations, consultez ALG_ID.
KP_BLOCKLEN	Si une clé de session est spécifiée par le paramètre hKey , récupérez la longueur de bloc du chiffrement de clé. Le paramètre pbData est un pointeur vers une valeur DWORD qui reçoit la longueur de bloc, en bits. Pour les chiffrements de flux, cette valeur est toujours égale à zéro. Si une paire de clés publique/privée est spécifiée par hKey, récupérez la granularité de chiffrement de la paire de clés. Le paramètre pbData est un pointeur vers une valeur DWORD qui reçoit la granularité de chiffrement, en bits. Par exemple, le fournisseur de chiffrement de base Microsoft génère des paires de clés RSA 512 bits, de sorte qu’une valeur de 512 est retournée pour ces clés. Si l’algorithme de clé publique ne prend pas en charge le chiffrement, la valeur récupérée n’est pas définie.
KP_CERTIFICATE	pbData est l’adresse d’une mémoire tampon qui reçoit le certificat X.509 qui a été encodé à l’aide de Distinguished Encoding Rules (DER). La clé publique dans le certificat doit correspondre à la signature ou à la clé d’échange correspondante.
KP_GET_USE_COUNT	Cette valeur n'est pas utilisée.
KP_KEYLEN	Récupérez la longueur réelle de la clé. Le paramètre pbData est un pointeur vers une valeur DWORD qui reçoit la longueur de clé, en bits. KP_KEYLEN peut être utilisé pour obtenir la longueur de n’importe quel type de clé. Les fournisseurs de services de chiffrement Microsoft retournent une longueur de clé de 64 bits pour CALG_DES, 128 bits pour CALG_3DES_112 et 192 bits pour CALG_3DES. Ces longueurs sont différentes des longueurs retournées lorsque vous énumérez des algorithmes avec la valeur dwParam de la fonction CryptGetProvParam définie sur PP_ENUMALGS. La longueur retournée par cet appel est la taille réelle de la clé, y compris les bits de parité inclus dans la clé. Les fournisseurs de solutions cloud Microsoft qui prennent en charge les CALG_CYLINK_MEK ALG_ID retournent 64 bits pour cet algorithme. CALG_CYLINK_MEK est une clé 40 bits, mais a la parité et les bits clés à zéro pour que la longueur de la clé soit de 64 bits.
KP_SALT	Récupérez la valeur salt de la clé. Le paramètre pbData est un pointeur vers un tableau BYTE qui reçoit la valeur salt sous forme de petit endian . La taille de la valeur de sel varie en fonction du fournisseur de solutions cloud et de l’algorithme utilisé. Les valeurs salt ne s’appliquent pas aux paires de clés publiques/privées.
KP_PERMISSIONS	Récupérez les autorisations de clé. Le paramètre pbData est un pointeur vers une valeur DWORD qui reçoit les indicateurs d’autorisation pour la clé. Les identificateurs d’autorisation suivants sont actuellement définis. Les autorisations de clé peuvent être égales à zéro ou à une combinaison d’une ou plusieurs des valeurs suivantes. CRYPT_ARCHIVE Autoriser l’exportation pendant la durée de vie du handle de la clé. Cette autorisation ne peut être définie que si elle est déjà définie dans le champ d’autorisations internes de la clé. Les tentatives d’effacement de cette autorisation sont ignorées. CRYPT_DECRYPT Autoriser le déchiffrement. CRYPT_ENCRYPT Autoriser le chiffrement. CRYPT_EXPORT Autorisez l’exportation de la clé. CRYPT_EXPORT_KEY Autorisez l’utilisation de la clé pour l’exportation de clés. CRYPT_IMPORT_KEY Autorisez l’utilisation de la clé pour l’importation de clés. CRYPT_MAC Autoriser l’utilisation de codes d’authentification de message (MAC) avec la clé. CRYPT_READ Autoriser la lecture des valeurs. CRYPT_WRITE Autoriser la définition de valeurs.

Si une clé DSS ( Digital Signature Standard ) est spécifiée par le paramètre hKey , la valeur dwParam peut également être définie sur l’une des valeurs suivantes.

Valeur	Signification
KP_P	Récupérez le nombre premier du module P de la clé DSS. Le paramètre pbData est un pointeur vers une mémoire tampon qui reçoit la valeur au format little endian. Le paramètre pdwDataLen contient la taille de la mémoire tampon, en octets.
KP_Q	Récupérez le nombre premier du module Q de la clé DSS. Le paramètre pbData est un pointeur vers une mémoire tampon qui reçoit la valeur au format little endian. Le paramètre pdwDataLen contient la taille de la mémoire tampon, en octets.
KP_G	Récupérez le générateur G de la clé DSS. Le paramètre pbData est un pointeur vers une mémoire tampon qui reçoit la valeur au format little endian. Le paramètre pdwDataLen contient la taille de la mémoire tampon, en octets.

Si une clé de session de chiffrement de bloc est spécifiée par le paramètre hKey, la valeur dwParam peut également être définie sur l’une des valeurs suivantes.

Valeur	Signification
KP_EFFECTIVE_KEYLEN	Récupérez la longueur de clé effective d’une clé RC2. Le paramètre pbData est un pointeur vers une valeur DWORD qui reçoit la longueur de clé effective.
KP_IV	Récupérez le vecteur d’initialisation de la clé. Le paramètre pbData est un pointeur vers un tableau BYTE qui reçoit le vecteur d’initialisation. La taille de ce tableau est la taille du bloc, en octets. Par exemple, si la longueur du bloc est de 64 bits, le vecteur d’initialisation se compose de 8 octets.
KP_PADDING	Récupérez le mode de remplissage. Le paramètre pbData est un pointeur vers une valeur DWORD qui reçoit un identificateur numérique qui identifie la méthode de remplissage utilisée par le chiffrement. Il peut s’agir de l’une des valeurs suivantes. PKCS5_PADDING Spécifie la méthode de remplissage PKCS 5 (s 6.2). RANDOM_PADDING Le remplissage utilise des nombres aléatoires. Cette méthode de remplissage n’est pas prise en charge par les fournisseurs de services cloud fournis par Microsoft. ZERO_PADDING Le remplissage utilise des zéros. Cette méthode de remplissage n’est pas prise en charge par les fournisseurs de services cloud fournis par Microsoft.
KP_MODE	Récupérez le mode de chiffrement. Le paramètre pbData est un pointeur vers une valeur DWORD qui reçoit un identificateur de mode de chiffrement. Pour plus d’informations sur les modes de chiffrement, consultez Chiffrement et déchiffrement des données. Les identificateurs de mode de chiffrement suivants sont actuellement définis. CRYPT_MODE_CBC Le mode de chiffrement est le chaînage de blocs de chiffrement. CRYPT_MODE_CFB Le mode de chiffrement est la rétroaction de chiffrement (BFC). Les fournisseurs de solutions Cloud Microsoft prennent actuellement en charge uniquement les commentaires 8 bits en mode de commentaires de chiffrement. CRYPT_MODE_ECB Le mode de chiffrement est le codebook électronique. CRYPT_MODE_OFB Le mode de chiffrement est La rétroaction de sortie (OFB). Les fournisseurs de services cloud Microsoft ne prennent actuellement pas en charge le mode de commentaires de sortie. CRYPT_MODE_CTS Le mode de chiffrement est le mode de vol de texte chiffré.
KP_MODE_BITS	Récupérez le nombre de bits à alimenter. Le paramètre pbData est un pointeur vers une valeur DWORD qui reçoit le nombre de bits traités par cycle lorsque les modes de chiffrement OFB ou CFB sont utilisés.

Si un algorithme Diffie-Hellman ou une clé DSA ( Digital Signature Algorithm ) est spécifié par hKey, la valeur dwParam peut également être définie sur la valeur suivante.

Valeur	Signification
KP_VERIFY_PARAMS	Vérifie les paramètres d’un algorithme Diffie-Hellman ou d’une clé DSA. Le paramètre pbData n’est pas utilisé et la valeur pointée par pdwDataLen reçoit zéro. Cette fonction retourne une valeur différente de zéro si les paramètres de clé sont valides ou zéro dans le cas contraire.
KP_KEYVAL	Cette valeur n'est pas utilisée. Windows Vista, Windows Server 2003 et Windows XP : Récupérez la valeur du contrat secret à partir d’une clé d’algorithme Diffie-Hellman importée de type CALG_AGREEDKEY_ANY. Le paramètre pbData est l’adresse d’une mémoire tampon qui reçoit la valeur d’accord de secret, au format little endian. Cette mémoire tampon doit avoir la même longueur que la clé. Le paramètre dwFlags doit être défini sur 0xF42A19B6. Cette propriété ne peut être récupérée que par un thread s’exécutant sous le compte système local. Cette propriété peut être utilisée dans les systèmes d’exploitation répertoriés ci-dessus. Il sera peut-être modifié ou indisponible dans les versions ultérieures.

Valeur

Signification

KP_VERIFY_PARAMS

Vérifie les paramètres d’un algorithme Diffie-Hellman ou d’une clé DSA. Le paramètre pbData n’est pas utilisé et la valeur pointée par pdwDataLen reçoit zéro.

Cette fonction retourne une valeur différente de zéro si les paramètres de clé sont valides ou zéro dans le cas contraire.

KP_KEYVAL

Cette valeur n'est pas utilisée.

Windows Vista, Windows Server 2003 et Windows XP : Récupérez la valeur du contrat secret à partir d’une clé d’algorithme Diffie-Hellman importée de type CALG_AGREEDKEY_ANY. Le paramètre pbData est l’adresse d’une mémoire tampon qui reçoit la valeur d’accord de secret, au format little endian. Cette mémoire tampon doit avoir la même longueur que la clé. Le paramètre dwFlags doit être défini sur 0xF42A19B6. Cette propriété ne peut être récupérée que par un thread s’exécutant sous le compte système local. Cette propriété peut être utilisée dans les systèmes d’exploitation répertoriés ci-dessus. Il sera peut-être modifié ou indisponible dans les versions ultérieures.

Si un certificat est spécifié par hKey, la valeur dwParam peut également être définie sur la valeur suivante.

Valeur	Signification
KP_CERTIFICATE	Mémoire tampon qui contient le certificat X.509 encodé en DER. Le paramètre pbData n’est pas utilisé et la valeur pointée par pdwDataLen reçoit zéro. Cette fonction retourne une valeur différente de zéro si les paramètres de clé sont valides ou zéro dans le cas contraire.

[out] pbData

Pointeur vers une mémoire tampon qui reçoit les données. La forme de ces données dépend de la valeur de dwParam.

Si la taille de cette mémoire tampon n’est pas connue, la taille requise peut être récupérée au moment de l’exécution en passant la valeur NULL pour ce paramètre et en définissant la valeur pointée par pdwDataLen sur zéro. Cette fonction place la taille requise de la mémoire tampon, en octets, dans la valeur pointée par pdwDataLen. Pour plus d’informations, consultez Récupération de données de longueur inconnue.

[in, out] pdwDataLen

Pointeur vers une valeur DWORD qui, lors de l’entrée, contient la taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre pbData . Lorsque la fonction retourne, la valeur DWORD contient le nombre d’octets stockés 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. Lors de l’entrée, les tailles de mémoire tampon sont parfois spécifiées suffisamment grandes pour garantir que les données de sortie les plus volumineuses possibles tiennent 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.

[in] dwFlags

Ce paramètre est réservé à une utilisation ultérieure et doit être défini sur zéro.

Valeur retournée

Si la fonction réussit, la fonction retourne une valeur différente de zéro.

Si la fonction échoue, elle retourne zéro. 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é. Voici quelques codes d’erreur possibles.

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.
NTE_BAD_FLAGS	Le paramètre dwFlags est différent de zéro.
NTE_BAD_KEY ou NTE_NO_KEY	La clé spécifiée par le paramètre hKey n’est pas valide.
NTE_BAD_TYPE	Le paramètre dwParam spécifie un nombre de valeurs inconnue.
NTE_BAD_UID	Le contexte CSP qui a été spécifié lors de la création de la clé est introuvable.

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

CryptSetKeyParam

Génération de clés et fonctions Exchange