Fonction CryptSignHashA (wincrypt.h)
Syntaxe
BOOL CryptSignHashA(
[in] HCRYPTHASH hHash,
[in] DWORD dwKeySpec,
[in] LPCSTR 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 |
|---|---|
|
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. |
|
Cet indicateur n’est pas utilisé. |
|
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.
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 |
|---|---|
|
L’un des paramètres spécifie un handle qui n’est pas valide. |
|
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. |
|
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 . |
|
Le handle hHash spécifie un algorithme que ce csp ne prend pas en charge, ou le paramètre dwKeySpec a une valeur incorrecte. |
|
Le paramètre dwFlags est différent de zéro. |
|
L’objet de hachage spécifié par le paramètre hHash n’est pas valide. |
|
Le contexte CSP spécifié lors de la création de l’objet de hachage est introuvable. |
|
La clé privée spécifiée par dwKeySpec n’existe pas. |
|
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 :
- Créez un objet de hachage à l’aide de CryptCreateHash.
- Définissez la valeur de hachage dans l’objet de hachage à l’aide de la valeur HP_HASHVAL du paramètre dwParam dans CryptSetHashParam.
- Signez la valeur de hachage à l’aide de CryptSignHash et obtenez un bloc de signature numérique.
- 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 |