Função CryptSignHashW (wincrypt.h)
Sintaxe
BOOL CryptSignHashW(
[in] HCRYPTHASH hHash,
[in] DWORD dwKeySpec,
[in] LPCWSTR 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 |
|---|---|
|
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. |
|
Esse sinalizador não é usado. |
|
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.
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 |
|---|---|
|
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. Geralmente, esse é 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 especifica um algoritmo ao qual esse CSP não dá suporte ou o parâmetro dwKeySpec tem um valor incorreto. |
|
O parâmetro dwFlags é diferente de 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. |
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:
- 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 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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de