Função CryptSignHashA (wincrypt.h)

Importante Essa API foi preterida. O software novo e existente deve começar a usar APIs de Próxima Geração de Criptografia. A Microsoft pode remover essa API em versões futuras.
 
A função CryptSignHash assina dados. Como todos os algoritmos de assinatura são assimétricos e, portanto, lentos, a CryptoAPI não permite que os dados sejam assinados diretamente. Em vez disso, os dados são primeiro com hash e CryptSignHash é usado para assinar o hash.

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.

Valor Significado
CRYPT_NOHASHOID
0x00000001
Usado com provedores RSA. O OID ( identificador de objeto hash) não é colocado na criptografia de chave pública RSA. Se esse sinalizador não estiver definido, o OID de hash na assinatura padrão será conforme especificado na definição de DigestInfo no PKCS nº 1.
CRYPT_TYPE2_FORMAT
0x00000002
Esse sinalizador não é usado.
CRYPT_X931_FORMAT
0x00000004
Use o método de preenchimento de assinatura RSA especificado no padrão ANSI X9.31.

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

Nota Ao processar os dados retornados no buffer, os aplicativos devem usar o tamanho real dos dados retornados. O tamanho real pode ser ligeiramente menor do que o tamanho do buffer especificado na entrada. (Na entrada, os tamanhos de buffer geralmente são especificados grandes o suficiente para garantir que os maiores dados de saída possíveis caibam no buffer.) Na saída, a variável apontada por esse parâmetro é atualizada para refletir o tamanho real dos dados copiados para o 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.

Código de retorno Descrição
ERROR_INVALID_HANDLE
Um dos parâmetros especifica um identificador que não é válido.
ERROR_INVALID_PARAMETER
Um dos parâmetros contém um valor que não é válido. Geralmente, esse é um ponteiro que não é válido.
ERROR_MORE_DATA
O buffer especificado pelo parâmetro pbSignature não é grande o suficiente para manter os dados retornados. O tamanho do buffer necessário, em bytes, está no valor DWORD pdwSigLen.
NTE_BAD_ALGID
O identificador hHash especifica um algoritmo ao qual esse CSP não dá suporte ou o parâmetro dwKeySpec tem um valor incorreto.
NTE_BAD_FLAGS
O parâmetro dwFlags é diferente de zero.
NTE_BAD_HASH
O objeto hash especificado pelo parâmetro hHash não é válido.
NTE_BAD_UID
O contexto CSP especificado quando o objeto hash foi criado não pode ser encontrado.
NTE_NO_KEY
A chave privada especificada por dwKeySpec não existe.
NTE_NO_MEMORY
O CSP ficou sem memória durante a operação.

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.

Observação

O cabeçalho wincrypt.h define CryptSignHash como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho wincrypt.h
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

Cryptcreatehash

Cryptdestroyhash

Crypthashdata

Crypthashsessionkey

CryptVerifySignature

Funções hash e assinatura digital