Fonction CryptCreateHash (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 CryptCreateHash lance le hachage d’un flux de données. Il crée et retourne à l’application appelante un handle à un objet de hachage fournisseur de services de chiffrement (CSP). Ce handle est utilisé dans les appels suivants à CryptHashData et CryptHashSessionKey à des clés de session de hachage et à d’autres flux de données.

Syntaxe

BOOL CryptCreateHash(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  HCRYPTKEY  hKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTHASH *phHash
);

Paramètres

[in] hProv

Handle d’un fournisseur de services cloud créé par un appel à CryptAcquireContext.

[in] Algid

Valeur ALG_ID qui identifie l’algorithme de hachage à utiliser.

Les valeurs valides pour ce paramètre varient en fonction du fournisseur de solutions cloud utilisé. Pour obtenir la liste des algorithmes par défaut, consultez Remarques.

[in] hKey

Si le type d’algorithme de hachage est un hachage à clé, tel que l’algorithme HMAC ( Hash-Based Message Authentication Code ) ou MAC (Message Authentication Code ), la clé du hachage est transmise dans ce paramètre. Pour les algorithmes non clés, ce paramètre doit être défini sur zéro.

Pour les algorithmes à clé, la clé doit être vers une clé de chiffrement de bloc , telle que RC2, qui a un mode de chiffrement de Chaînage de blocs de chiffrement (CBC).

[in] dwFlags

La valeur d’indicateur suivante est définie.

Valeur	Signification
CRYPT_SECRETDIGEST 0x00000001	Cet indicateur n’est pas utilisé.

[out] phHash

Adresse vers laquelle la fonction copie un handle vers le nouvel objet de hachage. Une fois que vous avez terminé d’utiliser l’objet de hachage, relâchez le handle en appelant la fonction CryptDestroyHash .

Valeur retournée

Si la fonction réussit, la fonction retourne TRUE.

Si la fonction échoue, elle retourne 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 que vous utilisez. Le tableau suivant présente certains des 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_NOT_ENOUGH_MEMORY	Le système d’exploitation a manqué de mémoire pendant l’opération.
NTE_BAD_ALGID	Le paramètre Algid spécifie un algorithme que ce csp ne prend pas en charge.
NTE_BAD_FLAGS	Le paramètre dwFlags est différent de zéro.
NTE_BAD_KEY	Un algorithme de hachage à clé, tel que CALG_MAC, est spécifié par Algid, et le paramètre hKey est égal à zéro ou spécifie un handle de clé non valide. Ce code d’erreur est également retourné si la clé est à un chiffrement de flux ou si le mode de chiffrement est autre que CBC.
NTE_NO_MEMORY	Le fournisseur de solutions cloud a manqué de mémoire pendant l’opération.

Remarques

Pour obtenir la liste des fournisseurs de services Microsoft et des algorithmes qu’ils implémentent, consultez Fournisseurs de services de chiffrement Microsoft.

Le calcul du hachage réel est effectué avec les fonctions CryptHashData et CryptHashSessionKey . Ceux-ci nécessitent un handle pour l’objet de hachage. Une fois que toutes les données ont été ajoutées à l’objet de hachage, l’une des opérations suivantes peut être effectuée :

La valeur de hachage peut être récupérée à l’aide de CryptGetHashParam.
Une clé de session peut être dérivée à l’aide de CryptDeriveKey.
Le hachage peut être signé à l’aide de CryptSignHash.
Une signature peut être vérifiée à l’aide de CryptVerifySignature.

Une fois l’une des fonctions de cette liste appelée, CryptHashData et CryptHashSessionKey ne peuvent pas être appelées.

Exemples

L’exemple suivant montre comment lancer le hachage d’un flux de données. Il crée et retourne à l’application appelante un handle à un objet de hachage. Ce handle est utilisé dans les appels suivants à CryptHashData et à CryptHashSessionKey pour hacher n’importe quel flux de données. Pour obtenir un exemple qui inclut le contexte complet de cet exemple, consultez Exemple de programme C : création et hachage d’une clé de session. Pour un autre exemple qui utilise cette fonction, consultez Exemple de programme C : signature d’un hachage et vérification de la signature de hachage.

//--------------------------------------------------------------------
//  Declare variables.

HCRYPTPROV hCryptProv;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// Get a handle to a cryptography provider context.


if(CryptAcquireContext(
   &hCryptProv, 
   NULL, 
   NULL, 
   PROV_RSA_FULL, 
   0)) 
{
    printf("CryptAcquireContext complete. \n");
}
else
{
     printf("Acquisition of context failed.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Acquire a hash object handle.

if(CryptCreateHash(
   hCryptProv, 
   CALG_MD5, 
   0, 
   0, 
   &hHash)) 
{
    printf("An empty hash object has been created. \n");
}
else
{
    printf("Error during CryptBeginHash!\n");
    exit(1);
}

// Insert code that uses the hash object here.

//--------------------------------------------------------------------
// After processing, hCryptProv and hHash must be released.

if(hHash) 
   CryptDestroyHash(hHash);
if(hCryptProv) 
   CryptReleaseContext(hCryptProv,0);

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