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 de 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 usado 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 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. A continuación se indican 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 de pdwSigLenDWORD. |
|
El identificador |
|
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. |
Observaciones
Antes de llamar a esta función, se debe llamar a la función
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 llamando 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 de la DigestInfo elemento 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 haya 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.
- Destruya el objeto hash mediante CryptDestroyHash.
Ejemplos
En el ejemplo siguiente se muestran los datos de firma mediante el hash inicial de los datos que se van a firmar y, a continuación, se firma 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows XP [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows Server 2003 [solo aplicaciones de escritorio] |
| de la plataforma de destino de |
Windows |
| encabezado de |
wincrypt.h |
| biblioteca de |
Advapi32.lib |
| DLL de |
Advapi32.dll |
Consulte también