Función CryptSignHashA (wincrypt.h)

Sintaxis

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

Parámetros

[in] hHash

Identificador del objeto hash que se va a firmar.

[in] dwKeySpec

Identifica la clave privada que se va a usar desde el contenedor del proveedor. Puede ser AT_KEYEXCHANGE o AT_SIGNATURE.

El algoritmo de firma utilizado se especifica cuando se crea originalmente el par de claves.

El único algoritmo de firma que admite el proveedor criptográfico base de Microsoft es el algoritmo de clave pública RSA.

[in] szDescription

Este parámetro ya no se usa y debe establecerse en NULL para evitar vulnerabilidades de seguridad. Sin embargo, todavía se admite para la compatibilidad con versiones anteriores en el proveedor criptográfico base de Microsoft.

[in] dwFlags

Se definen los siguientes valores de marca.

[out] pbSignature

Puntero a un búfer que recibe los datos de firma.

Este parámetro puede ser NULL para establecer el tamaño del búfer con fines de asignación de memoria. Para obtener más información, vea Recuperar datos de longitud desconocida.

[in, out] pdwSigLen

Puntero a un valor DWORD que especifica el tamaño, en bytes, del búfer pbSignature . Cuando la función devuelve, el valor DWORD contiene el número de bytes almacenados en el búfer.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve TRUE.

Si se produce un error en la función, devuelve FALSE. Para obtener información de error extendida, llame a GetLastError.

Los códigos de error precedidos por "NTE" se generan mediante el CSP concreto que usa. Siguen algunos códigos de error posibles.

Comentarios

Antes de llamar a esta función, se debe llamar a la función CryptCreateHash para obtener un identificador de un objeto hash. La función CryptHashData o CryptHashSessionKey se usa para agregar los datos o claves de sesión al objeto hash. La función CryptSignHash completa el hash.

Aunque el CSP de DSS admite hash con los algoritmos hash MD5 y SHA, el CSP de DSS solo admite hashes sha de firma.

Después de llamar a esta función, no se pueden agregar más datos al hash. Se producen errores en llamadas adicionales a CryptHashData o CryptHashSessionKey .

Cuando la aplicación termine de usar el hash, destruya el objeto hash mediante una llamada a la función CryptDestroyHash .

De forma predeterminada, los proveedores RSA de Microsoft usan el método de relleno PKCS #1 para la firma. El OID hash del elemento DigestInfo de la firma se establece automáticamente en el OID del algoritmo asociado al objeto hash. El uso de la marca CRYPT_NOHASHOID hará que este OID se omita de la firma.

En ocasiones, se debe firmar un valor hash que se ha generado en otro lugar. Esto se puede hacer mediante la siguiente secuencia de operaciones:

1. Cree un objeto hash mediante CryptCreateHash.
2. Establezca el valor hash en el objeto hash mediante el valor HP_HASHVAL del parámetro dwParam en CryptSetHashParam.
3. Firme el valor hash mediante CryptSignHash y obtenga un bloque de firma digital.
4. Destruye el objeto hash mediante CryptDestroyHash.

Ejemplos

En el ejemplo siguiente se muestran los datos de firma mediante el algoritmo hash de los datos que se van a firmar y, a continuación, firmando el hash mediante la función 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);

Para obtener un ejemplo completo, incluido el contexto de este código, vea Programa C de ejemplo: Firma de un hash y Comprobación de la firma hash.

Requisitos

Consulte también

CryptCreateHash

CryptDestroyHash

CryptHashData

CryptHashSessionKey

CryptVerifySignature

Funciones hash y firma digital