Fonction CryptGetKeyParam (wincrypt.h)

important cette API est déconseillée. Les logiciels nouveaux et existants doivent commencer à utiliser 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 clé symétrique de base n’est pas obtenu par cette 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 du bloc du chiffrement de clé. Le paramètre pbData est un pointeur vers une valeur DWORD qui reçoit la longueur du bloc, en bits. Pour 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. Par conséquent, la valeur 512 est retournée pour ces clés. Si l’algorithme de clé publique ne prend pas en charge de 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 codé à l’aide de règles d’encodage unique (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 pouvez être utilisé pour obtenir la longueur de n’importe quel type de clé. Microsoft fournisseurs de services de chiffrement (CSP) retournent une longueur de clé de 64 bits pour CALG_DES, 128 bits pour CALG_3DES_112et 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 services cloud Microsoft qui prennent en charge le CALG_CYLINK_MEKALG_ID retournent 64 bits pour cet algorithme. CALG_CYLINK_MEK est une clé 40 bits, mais a une parité et des bits de clé zéro pour rendre la longueur de clé 64 bits.
KP_SALT	Récupérez la valeur de sel de la clé. Le paramètre pbData est un pointeur vers un tableau BYTE qui reçoit la valeur de sel sous forme de little-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 de 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 Autorisez 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 Autorisez codes d’authentification des messages (MACs) à utiliser avec la clé. CRYPT_READ Autoriser la lecture des valeurs. CRYPT_WRITE Autoriser la définition des valeurs.

 

Si une clé Digital Signature Standard (DSS) 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 principal de modulus de la clé DSS. Le paramètre pbData est un pointeur vers une mémoire tampon qui reçoit la valeur sous forme little-endian. Le paramètre pdwDataLen contient la taille de la mémoire tampon, en octets.
KP_Q	Récupérez le nombre principal de modulus Q de la clé DSS. Le paramètre pbData est un pointeur vers une mémoire tampon qui reçoit la valeur sous forme little-endian. Le paramètre pdwDataLen contient la taille de la mémoire tampon, en octets.
KP_G	Récupérez le G du générateur de la clé DSS. Le paramètre pbData est un pointeur vers une mémoire tampon qui reçoit la valeur sous forme little-endian. Le paramètre pdwDataLen contient la taille de la mémoire tampon, en octets.

 

Si une clé de sessionde 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 de 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 lede 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 chaînage de blocs de chiffrement. CRYPT_MODE_CFB Le mode de chiffrement est commentaires de chiffrement (CFB). Les fournisseurs de services 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 codebook électronique. CRYPT_MODE_OFB Le mode de chiffrement est retour de sortie (OFB). Actuellement, les fournisseurs de services cloud Microsoft ne prennent pas en charge le mode de commentaires de sortie. CRYPT_MODE_CTS Le mode de chiffrement est texte chiffré mode de vol.
KP_MODE_BITS	Récupérez le nombre de bits à renvoyer. 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 une clé d’algorithme Diffie-Hellman ou clé DSA (Digital Signature Algorithm) est spécifiée 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 indiqué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érer la valeur du contrat secret à partir d’un algorithme Diffie-Hellman importé clé de type CALG_AGREEDKEY_ANY. Le paramètre pbData est l’adresse d’une mémoire tampon qui reçoit la valeur du contrat secret, au format little-endian. Cette mémoire tampon doit être de 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é est disponible pour être utilisée dans les systèmes d’exploitation répertoriés ci-dessus. Il 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 codé en DER. Le paramètre pbData n’est pas utilisé et la valeur indiqué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 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 des 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 pointée par le paramètre pbData. Lorsque la fonction est retournée, la valeur DWORD contient le nombre d’octets stockés dans la mémoire tampon.

Remarque 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 s’assurer que les données de sortie les plus volumineuses possibles s’intègrent dans la mémoire tampon. Lors de la 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é pour une utilisation ultérieure et doit être défini sur zéro.

Valeur de retour

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écédés par « NTE » sont générés par le fournisseur de solutions Cloud en cours d’utilisation. Certains codes d’erreur possibles sont les suivants.

Retourner le code	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 suffisamment 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 n’est pas 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 numéro de valeur inconnu.
NTE_BAD_UID	Le contexte csp spécifié lorsque la clé a été créée est introuvable.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	wincrypt.h
bibliothèque	Advapi32.lib
DLL	Advapi32.dll

Voir aussi

CryptSetKeyParam

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