Partager via


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