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.
| Valor | Significado |
|---|---|
|
Se usa con proveedores RSA. El identificador de objeto hash (OID) no se coloca en el cifrado de clave pública RSA. Si no se establece esta marca, el OID hash de la firma predeterminada se especifica en la definición de DigestInfo en PKCS #1. |
|
Esta marca no se usa. |
|
Use el método de relleno de firmas RSA especificado en el estándar ANSI X9.31. |
[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.
| Código devuelto | Descripción |
|---|---|
|
Uno de los parámetros especifica un identificador que no es válido. |
|
Uno de los parámetros contiene un valor que no es válido. Suele ser un puntero que no es válido. |
|
El búfer especificado por el parámetro pbSignature no es lo suficientemente grande como para contener los datos devueltos. El tamaño de búfer necesario, en bytes, está en el valor DWORD pdwSigLen. |
|
El identificador hHash especifica un algoritmo que este CSP no admite o que el parámetro dwKeySpec tiene un valor incorrecto. |
|
El parámetro dwFlags es distinto de cero. |
|
El objeto hash especificado por el parámetro hHash no es válido. |
|
No se encuentra el contexto de CSP que se especificó cuando se creó el objeto hash. |
|
La clave privada especificada por dwKeySpec no existe. |
|
El CSP se quedó sin memoria durante la operación. |
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:
- Cree un objeto hash mediante CryptCreateHash.
- Establezca el valor hash en el objeto hash mediante el valor HP_HASHVAL del parámetro dwParam en CryptSetHashParam.
- Firme el valor hash mediante CryptSignHash y obtenga un bloque de firma digital.
- 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.
Nota
El encabezado wincrypt.h define CryptSignHash como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | wincrypt.h |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |