Partager via


Fonction CryptSignHashW (wincrypt.h)

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 CryptSignHash signe les données. Étant donné que tous les algorithmes de signature sont asymétriques et donc lents, CryptoAPI n’autorise pas la signature directe des données. Au lieu de cela, les données sont d’abord hachées et CryptSignHash est utilisé pour signer le hachage.

Syntaxe

BOOL CryptSignHashW(
  [in]      HCRYPTHASH hHash,
  [in]      DWORD      dwKeySpec,
  [in]      LPCWSTR    szDescription,
  [in]      DWORD      dwFlags,
  [out]     BYTE       *pbSignature,
  [in, out] DWORD      *pdwSigLen
);

Paramètres

[in] hHash

Handle de l’objet de hachage à signer.

[in] dwKeySpec

Identifie la clé privée à utiliser à partir du conteneur du fournisseur. Il peut être AT_KEYEXCHANGE ou AT_SIGNATURE.

L’algorithme de signature utilisé est spécifié lors de la création initiale de la paire de clés.

Le seul algorithme de signature pris en charge par le fournisseur de chiffrement de base Microsoft est l’algorithme de clé publique RSA.

[in] szDescription

Ce paramètre n’est plus utilisé et doit être défini sur NULL pour empêcher les vulnérabilités de sécurité. Toutefois, il est toujours pris en charge pour la compatibilité descendante dans le fournisseur de chiffrement de base Microsoft.

[in] dwFlags

Les valeurs d’indicateur suivantes sont définies.

Valeur Signification
CRYPT_NOHASHOID
0x00000001
Utilisé avec les fournisseurs RSA. L’identificateur d’objet de hachage (OID) n’est pas placé dans le chiffrement à clé publique RSA. Si cet indicateur n’est pas défini, l’OID de hachage dans la signature par défaut est celui spécifié dans la définition de DigestInfo dans PKCS #1.
CRYPT_TYPE2_FORMAT
0x00000002
Cet indicateur n’est pas utilisé.
CRYPT_X931_FORMAT
0x00000004
Utilisez la méthode de remplissage de signature RSA spécifiée dans la norme ANSI X9.31.

[out] pbSignature

Pointeur vers une mémoire tampon recevant les données de signature.

Ce paramètre peut avoir la valeur NULL pour définir la taille de la mémoire tampon à des fins d’allocation de mémoire. Pour plus d’informations, consultez Récupération de données de longueur inconnue.

[in, out] pdwSigLen

Pointeur vers une valeur DWORD qui spécifie la taille, en octets, de la mémoire tampon pbSignature . 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. (En entrée, les tailles de mémoire tampon sont généralement spécifiées suffisamment grandes pour garantir que les données de sortie les plus volumineuses possibles s’intègrent 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.
 

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. Certains codes d’erreur possibles suivent.

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
La mémoire tampon spécifiée par le paramètre pbSignature n’est pas assez grande pour contenir les données retournées. La taille de mémoire tampon requise, en octets, se trouve dans la valeur pdwSigLenDWORD .
NTE_BAD_ALGID
Le handle hHash spécifie un algorithme que ce csp ne prend pas en charge, ou le paramètre dwKeySpec a une valeur incorrecte.
NTE_BAD_FLAGS
Le paramètre dwFlags est différent de zéro.
NTE_BAD_HASH
L’objet de hachage spécifié par le paramètre hHash n’est pas valide.
NTE_BAD_UID
Le contexte CSP spécifié lors de la création de l’objet de hachage est introuvable.
NTE_NO_KEY
La clé privée spécifiée par dwKeySpec n’existe pas.
NTE_NO_MEMORY
Le fournisseur de solutions cloud a manqué de mémoire pendant l’opération.

Remarques

Avant d’appeler cette fonction, la fonction CryptCreateHash doit être appelée pour obtenir un handle à un objet de hachage. La fonction CryptHashData ou CryptHashSessionKey est ensuite utilisée pour ajouter les clés de données ou de session à l’objet de hachage. La fonction CryptSignHash termine le hachage.

Alors que le csp DSS prend en charge le hachage avec les algorithmes de hachage MD5 et SHA, le csp DSS prend uniquement en charge la signature de hachages SHA.

Une fois cette fonction appelée, plus aucune donnée ne peut être ajoutée au hachage. Les appels supplémentaires à CryptHashData ou CryptHashSessionKey échouent.

Une fois que l’application a terminé d’utiliser le hachage, détruisez l’objet de hachage en appelant la fonction CryptDestroyHash .

Par défaut, les fournisseurs Microsoft RSA utilisent la méthode de remplissage PKCS #1 pour la signature. L’OID de hachage dans l’élément DigestInfo de la signature est automatiquement défini sur l’algorithme OID associé à l’objet de hachage. L’utilisation de l’indicateur CRYPT_NOHASHOID entraîne l’omission de cet OID de la signature.

Parfois, une valeur de hachage qui a été générée ailleurs doit être signée. Pour ce faire, utilisez la séquence d’opérations suivante :

  1. Créez un objet de hachage à l’aide de CryptCreateHash.
  2. Définissez la valeur de hachage dans l’objet de hachage à l’aide de la valeur HP_HASHVAL du paramètre dwParam dans CryptSetHashParam.
  3. Signez la valeur de hachage à l’aide de CryptSignHash et obtenez un bloc de signature numérique.
  4. Détruisez l’objet de hachage à l’aide de CryptDestroyHash.

Exemples

L’exemple suivant montre comment signer des données en hachant d’abord les données à signer, puis en signant le hachage à l’aide de la fonction CryptSignHash .

//-------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV hProv;
BYTE *pbBuffer= (BYTE *)"Sample data that is to be signed.";
DWORD dwBufferLen = strlen((char *)pbBuffer)+1;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// This code assumes that a cryptographic context handle, hProv,
// and a hash handle, hHash, are available.
// For code needed to acquire the context, see "Example C Program: 
// Signing a Hash and Verifying the Hash Signature."

//--------------------------------------------------------------------
// Compute the cryptographic hash of the buffer.

if(CryptHashData(
   hHash, 
   pbBuffer, 
   dwBufferLen, 
   0)) 
{
     printf("The data buffer has been hashed.\n");
}
else
{
     printf("Error during CryptHashData.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Determine the size of the signature and allocate memory.

dwSigLen= 0;
if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   NULL, 
   &dwSigLen)) 
{
     printf("Signature length %d found.\n",dwSigLen);
}
else
{
     printf("Error during CryptSignHash\n");
     exit(1);
}
//--------------------------------------------------------------------
// Allocate memory for the signature buffer.

if(pbSignature = (BYTE *)malloc(dwSigLen))
{
     printf("Memory allocated for the signature.\n");
}
else
{
     printf("Out of memory\n");
     exit(1);
}
//--------------------------------------------------------------------
// Sign the hash object.

if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   pbSignature, 
   &dwSigLen)) 
{
     printf("pbSignature is the hash signature.\n");
}
else
{
     printf("Error during CryptSignHash.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Destroy the hash object.

if(hHash) 
  CryptDestroyHash(hHash);

Pour obtenir un exemple complet incluant le contexte de ce code, consultez Exemple de programme C : signature d’un hachage et vérification de la signature de hachage.

Notes

L’en-tête wincrypt.h définit CryptSignHash comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

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

CryptCreateHash

CryptDestroyHash

CryptHashData

CryptHashSessionKey

CryptVerifySignature

Fonctions de hachage et de signature numérique