Função CryptSignHashA (wincrypt.h)

Sintaxe

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 do objeto hash a ser assinado.

[in] dwKeySpec

Identifica a chave privada a ser usada do contêiner do provedor. Pode ser AT_KEYEXCHANGE ou AT_SIGNATURE.

O algoritmo de assinatura usado é especificado quando o par de chaves é criado originalmente.

O único algoritmo de assinatura ao qual o Provedor Criptográfico Base da Microsoft dá suporte é o algoritmo chave pública RSA.

[in] szDescription

Esse parâmetro não é mais usado e deve ser definido como NULL para evitar vulnerabilidades de segurança. No entanto, ainda há suporte para compatibilidade com versões anteriores no Provedor Criptográfico Base da Microsoft.

[in] dwFlags

Os valores de sinalizador a seguir são definidos.

[out] pbSignature

Um ponteiro para um buffer que recebe os dados de assinatura.

Esse parâmetro pode ser NULL para definir o tamanho do buffer para fins de alocação de memória. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.

[in, out] pdwSigLen

Um ponteiro para um valor DWORD que especifica o tamanho, em bytes, do buffer pbSignature . Quando a função retorna, o valor DWORD contém o número de bytes armazenados no buffer.

Retornar valor

Se a função for bem-sucedida, a função retornará TRUE.

Se a função falhar, ela retornará FALSE. Para obter informações de erro estendidas, chame GetLastError.

Os códigos de erro precedidos por "NTE" são gerados pelo CSP específico que você está usando. Alguns códigos de erro possíveis seguem.

Comentários

Antes de chamar essa função, a função CryptCreateHash deve ser chamada para obter um identificador para um objeto hash. A função CryptHashData ou CryptHashSessionKey é usada para adicionar os dados ou as chaves de sessão ao objeto hash. A função CryptSignHash conclui o hash.

Embora o CSP do DSS dê suporte ao hash com os algoritmos de hash MD5 e SHA, o CSP do DSS dá suporte apenas à assinatura de hashes SHA.

Depois que essa função é chamada, não é possível adicionar mais dados ao hash. As chamadas adicionais para CryptHashData ou CryptHashSessionKey falham.

Depois que o aplicativo terminar de usar o hash, destrua o objeto hash chamando a função CryptDestroyHash .

Por padrão, os provedores do Microsoft RSA usam o método de preenchimento PKCS nº 1 para a assinatura. O OID de hash no elemento DigestInfo da assinatura é definido automaticamente como o OID do algoritmo associado ao objeto hash. Usar o sinalizador CRYPT_NOHASHOID fará com que esse OID seja omitido da assinatura.

Ocasionalmente, um valor de hash que foi gerado em outro lugar deve ser assinado. Isso pode ser feito usando a seguinte sequência de operações:

1. Crie um objeto hash usando CryptCreateHash.
2. Defina o valor de hash no objeto hash usando o valor HP_HASHVAL do parâmetro dwParam em CryptSetHashParam.
3. Assine o valor de hash usando CryptSignHash e obtenha um bloco de assinatura digital.
4. Destrua o objeto hash usando CryptDestroyHash.

Exemplos

O exemplo a seguir mostra a assinatura de dados primeiro fazendo hash dos dados a serem assinados e assinando o hash usando a função 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 obter um exemplo completo, incluindo o contexto desse código, consulte Exemplo de programa C: assinando um hash e verificando a assinatura de hash.

Requisitos

Confira também

Cryptcreatehash

Cryptdestroyhash

Crypthashdata

Crypthashsessionkey

CryptVerifySignature

Funções hash e assinatura digital