Fonction CryptSetKeyParam (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 CryptSetKeyParam personnalise différents aspects des opérations d’une clé de session. Les valeurs définies par cette fonction ne sont pas conservées en mémoire et ne peuvent être utilisées que dans une seule session.

Le fournisseur de chiffrement de base Microsoft n’autorise pas la définition de valeurs pour l’échange de clés ou les clés de signature ; toutefois, les fournisseurs personnalisés peuvent définir des valeurs qui peuvent être définies pour ses clés.

Syntaxe

BOOL CryptSetKeyParam(
  [in] HCRYPTKEY  hKey,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

Paramètres

[in] hKey

Handle de la clé pour laquelle les valeurs doivent être définies.

[in] dwParam

Les tableaux suivants contiennent des valeurs prédéfinies qui peuvent être utilisées.

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

Valeur	Signification
KP_ALGID	pbData pointe vers un ALG_ID approprié. Il est utilisé lors de l’échange de clés de session avec Microsoft Base Digital Signature Standard (DSS), Diffie-Hellman fournisseur de chiffrement ou des fournisseurs de solutions cloud compatibles. Une fois qu’une clé est convenue avec la fonction CryptImportKey , la clé de session est activée pour l’utilisation en définissant son type d’algorithme.
KP_CERTIFICATE	pbData est l’adresse d’une mémoire tampon qui contient 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_PERMISSIONS	pbData pointe vers une valeur DWORD qui spécifie zéro ou plusieurs indicateurs d’autorisation. Pour obtenir une description de ces indicateurs, consultez CryptGetKeyParam.
KP_SALT	pbData pointe vers un tableau BYTE qui spécifie une nouvelle valeur de sel à intégrer à la clé de session. La taille de la valeur de sel varie en fonction du csp utilisé. Avant de définir cette valeur, déterminez la taille de la valeur salt en appelant la fonction CryptGetKeyParam . Les valeurs salt sont utilisées pour rendre les clés de session plus uniques, ce qui rend les attaques par dictionnaire plus difficiles. La valeur salt est zéro par défaut pour le fournisseur de chiffrement de base Microsoft.
KP_SALT_EX	pbData pointe vers une structure CRYPT_INTEGER_BLOB qui contient le sel. Pour plus d’informations, consultez Spécification d’une valeur de sel.

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_G	pbData pointe vers le générateur G à partir de l’objet BLOB de clé DSS. Les données sont sous la forme d’une structure CRYPT_INTEGER_BLOB , où le membre pbData est la valeur et le membre cbData est la longueur de la valeur. La valeur est attendue sans informations d’en-tête et sous forme de petit endian .
KP_P	pbData pointe vers le module P premier d’un objet BLOB de clé DSS. Les données sont sous la forme d’une structure CRYPT_INTEGER_BLOB . Le membre pbData est la valeur et le membre cbData est la longueur de la valeur. La valeur est attendue sans informations d’en-tête et sous forme de petit endian .
KP_Q	pbData pointe vers le Q premier d’un objet BLOB de clé DSS. Les données sont sous la forme d’une structure CRYPT_INTEGER_BLOB où le membre pbData est la valeur et le membre cbData est la longueur de la valeur. La valeur est attendue sans informations d’en-tête et sous forme de petit endian .
KP_X	Une fois les valeurs P, Q et G définies, un appel qui spécifie la valeur KP_X pour dwParam et NULL pour le paramètre pbData peut être effectué à la fonction CryptSetKeyParam . Cela entraîne la génération des valeurs X et Y.

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 l’une des valeurs suivantes.

Valeur	Signification
KP_CMS_DH_KEY_INFO	Définit les informations d’une clé Diffie-Hellman importée. Le paramètre pbData est l’adresse d’une structure CMS_DH_KEY_INFO qui contient les informations clés à définir.
KP_PUB_PARAMS	Définit les paramètres publics (P, Q, G, etc.) d’une clé DSS ou Diffie-Hellman. Le handle de clé de cette clé doit être à l’état PREGEN, généré avec l’indicateur CRYPT_PREGEN. Le paramètre pbData doit être un pointeur vers une structure DATA_BLOB où les données de cette structure sont un DHPUBKEY_VER3 ou DSSPUBKEY_VER3 BLOB. La fonction copie les paramètres publics de cette structure CRYPT_INTEGER_BLOB vers le handle de clé. Une fois cet appel effectué, la valeur du paramètre KP_X doit être utilisée avec CryptSetKeyParam pour créer la clé privée réelle. Le paramètre KP_PUB_PARAMS est utilisé comme un appel plutôt que plusieurs appels avec les valeurs de paramètre KP_P, KP_Q et KP_G.

Valeur

Signification

KP_CMS_DH_KEY_INFO

Définit les informations d’une clé Diffie-Hellman importée. Le paramètre pbData est l’adresse d’une structure CMS_DH_KEY_INFO qui contient les informations clés à définir.

KP_PUB_PARAMS

Définit les paramètres publics (P, Q, G, etc.) d’une clé DSS ou Diffie-Hellman. Le handle de clé de cette clé doit être à l’état PREGEN, généré avec l’indicateur CRYPT_PREGEN. Le paramètre pbData doit être un pointeur vers une structure DATA_BLOB où les données de cette structure sont un DHPUBKEY_VER3 ou DSSPUBKEY_VER3 BLOB. La fonction copie les paramètres publics de cette structure CRYPT_INTEGER_BLOB vers le handle de clé. Une fois cet appel effectué, la valeur du paramètre KP_X doit être utilisée avec CryptSetKeyParam pour créer la clé privée réelle. Le paramètre KP_PUB_PARAMS est utilisé comme un appel plutôt que plusieurs appels avec les valeurs de paramètre KP_P, KP_Q et KP_G.

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	Ce type de valeur ne peut être utilisé qu’avec des clés RC2 et a été ajouté en raison de l’implémentation de la fonction CryptSetKeyParam dans le fournisseur de chiffrement microsoft amélioré avant Windows 2000. Dans l’implémentation précédente, les clés RC2 du fournisseur amélioré étaient de 128 bits, mais la longueur effective des clés utilisée pour développer les clés dans la table de clés était de seulement 40 bits. Cela a réduit la force de l’algorithme à 40 bits. Pour maintenir la compatibilité descendante, l’implémentation précédente reste en l’état. Toutefois, la longueur effective de la clé peut être définie pour être supérieure à 40 bits à l’aide de KP_EFFECTIVE_KEYLEN dans l’appel CryptSetKeyParam . La longueur de clé effective est passée dans le paramètre pbData en tant que pointeur vers une valeur DWORD avec la valeur de longueur de clé effective. La longueur minimale de clé effective sur le fournisseur de chiffrement de base Microsoft est une et le maximum est de 40. Dans le fournisseur de chiffrement microsoft amélioré, le minimum est un et le maximum est 1 024. La longueur de la clé doit être définie avant le chiffrement ou le déchiffrement avec la clé.
KP_HIGHEST_VERSION	Définit la version TLS ( Transport Layer Security ) la plus élevée autorisée. Cette propriété s’applique uniquement aux clés SSL et TLS. Le paramètre pbData est l’adresse d’une variable DWORD qui contient le numéro de version TLS le plus élevé pris en charge.
KP_IV	pbData pointe vers un tableau BYTE qui spécifie le vecteur d’initialisation. Ce tableau doit contenir des éléments BlockLength/8. Par exemple, si la longueur du bloc est de 64 bits, le vecteur d’initialisation se compose de 8 octets. Le vecteur d’initialisation est défini sur zéro par défaut pour le fournisseur de chiffrement de base Microsoft.
KP_KEYVAL	Définissez la valeur de clé pour une clé DES ( Data Encryption Standard ). Le paramètre pbData est l’adresse d’une mémoire tampon qui contient la clé. Cette mémoire tampon doit avoir la même longueur que la clé. Cette propriété s’applique uniquement aux clés DES.
KP_PADDING	Définissez 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 un nombre aléatoire. 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	pbData pointe vers une valeur DWORD qui spécifie le mode de chiffrement à utiliser. Pour obtenir la liste des modes de chiffrement définis, consultez CryptGetKeyParam. Le mode de chiffrement est défini sur CRYPT_MODE_CBC par défaut pour le fournisseur de chiffrement de base Microsoft.
KP_MODE_BITS	pbData pointe vers une valeur DWORD qui indique le nombre de bits traités par cycle lorsque le mode de chiffrement de commentaires de sortie (OFB) ou CFB ( Cipher Feedback ) est utilisé. Le nombre de bits traités par cycle est défini sur 8 par défaut pour le fournisseur de chiffrement de base Microsoft.

Si une clé RSA est spécifiée dans le paramètre hKey , la valeur du paramètre dwParam peut être la valeur suivante.

Valeur	Signification
KP_OAEP_PARAMS	Définissez les paramètres OAEP (Optimal Asymmetric Encryption Padding) (PKCS #1 version 2) pour la clé. Le paramètre pbData est l’adresse d’une structure CRYPT_DATA_BLOB qui contient l’étiquette OAEP. Cette propriété s’applique uniquement aux clés RSA.

Notez que les valeurs suivantes ne sont pas utilisées :

KP_ADMIN_PIN
KP_CMS_KEY_INFO
KP_INFO
KP_KEYEXCHANGE_PIN
KP_PRECOMP_MD5
KP_PRECOMP_SHA
KP_PREHASH
KP_PUB_EX_LEN
KP_PUB_EX_VAL
KP_RA
KP_RB
KP_ROUNDS
KP_RP
KP_SIGNATURE_PIN
KP_Y

[in] pbData

Pointeur vers une mémoire tampon initialisée avec la valeur à définir avant d’appeler CryptSetKeyParam. La forme de ces données varie en fonction de la valeur de dwParam.

[in] dwFlags

Utilisé uniquement lorsque dwParam est KP_ALGID. Le paramètre dwFlags est utilisé pour passer des valeurs d’indicateur pour la clé activée. Le paramètre dwFlags peut contenir des valeurs telles que la taille de clé et les autres valeurs d’indicateur autorisées lors de la génération du même type de clé avec CryptGenKey. Pour plus d’informations sur les valeurs d’indicateur autorisées, consultez CryptGenKey.

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_BUSY	Le contexte CSP est actuellement utilisé par un autre processus.
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.
NTE_BAD_FLAGS	Le paramètre dwFlags est différent de zéro, ou la mémoire tampon pbData contient une valeur qui n’est pas valide.
NTE_BAD_TYPE	Le paramètre dwParam spécifie un paramètre inconnu.
NTE_BAD_UID	Le contexte CSP qui a été spécifié lors de la création de la clé hKey est introuvable.
NTE_FAIL	La fonction a échoué d’une manière inattendue.
NTE_FIXEDPARAMETER	Certains fournisseurs de solutions cloud ont des valeurs P, Q et G codées en dur. Si c’est le cas, l’utilisation de KP_P, KP_Q et KP_G pour la valeur de dwParam provoque cette erreur.

Remarques

Si les paramètres KP_Q, KP_P ou KP_X sont définis sur une clé PREGEN Diffie-Hellman ou DSS, les longueurs de clé doivent être compatibles avec la longueur de clé définie à l’aide des 16 bits supérieurs du paramètre dwFlags lors de la création de la clé à l’aide de CryptGenKey. Si aucune longueur de clé n’a été définie dans CryptGenKey, la longueur de clé par défaut a été utilisée. Cela crée une erreur si une longueur de clé non définie par défaut est utilisée pour définir P, Q ou X.

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Exemple de programme C : duplication d’une clé de session. Pour plus d’informations sur le code qui utilise cette fonction, consultez Exemple de programme C : Définition et obtention de paramètres de clé de session .

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