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

O identificador do objeto hash a ser assinado.

[in] dwKeySpec

Identifica a chave privada a ser usada no 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 que o Provedor Criptográfico base da Microsoft dá suporte é o algoritmo de 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 dede comprimento desconhecido.

[in, out] pdwSigLen

Um ponteiro para um DWORD valor 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.

Valor de retorno

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

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.

Observações

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 falhar.

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 é automaticamente definido como o OID do algoritmo associado ao objeto hash. O uso do sinalizador CRYPT_NOHASHOID fará com que essa OID seja omitida 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 hash dos dados a serem assinados e, em seguida, 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

Consulte também

CryptCreateHash

CryptDestroyHash

CryptHashData

CryptHashSessionKey

CryptVerifySignature

Funções de hash e assinatura digital