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
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.
| Código de retorno | Descrição |
|---|---|
|
Um dos parâmetros especifica um identificador que não é válido. |
|
Um dos parâmetros contém um valor que não é válido. Isso geralmente é um ponteiro que não é válido. |
|
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. |
|
O identificador hHash |
|
O parâmetro dwFlags não é zero. |
|
O objeto hash especificado pelo parâmetro hHash não é válido. |
|
O contexto CSP especificado quando o objeto hash foi criado não pode ser encontrado. |
|
A chave privada especificada por dwKeySpec não existe. |
|
O CSP ficou sem memória durante a operação. |
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:
- Crie um objeto hash usando CryptCreateHash.
- Defina o valor de hash no objeto hash usando o valor HP_HASHVAL do parâmetro dwParam em CryptSetHashParam.
- Assine o valor de hash usando CryptSignHash e obtenha um bloco de assinatura digital.
- 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.
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2003 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | wincrypt.h |
| biblioteca | Advapi32.lib |
| de DLL |
Advapi32.dll |
Consulte também