Função CryptUnprotectData (dpapi.h)

A função CryptUnprotectData descriptografa e faz uma verificação de integridade dos dados em uma estrutura DATA_BLOB . Normalmente, o único usuário que pode descriptografar os dados é um usuário com as mesmas credenciais de logon que o usuário que criptografou os dados. Além disso, a criptografia e a descriptografia devem ser feitas no mesmo computador. Para obter informações sobre exceções, consulte a seção Comentários de CryptProtectData.

Sintaxe

DPAPI_IMP BOOL CryptUnprotectData(
  [in]            DATA_BLOB                 *pDataIn,
  [out, optional] LPWSTR                    *ppszDataDescr,
  [in, optional]  DATA_BLOB                 *pOptionalEntropy,
                  PVOID                     pvReserved,
  [in, optional]  CRYPTPROTECT_PROMPTSTRUCT *pPromptStruct,
  [in]            DWORD                     dwFlags,
  [out]           DATA_BLOB                 *pDataOut
);

Parâmetros

[in] pDataIn

Um ponteiro para uma estrutura de DATA_BLOB que contém os dados criptografados. O membro cbData da estrutura DATA_BLOB contém o comprimento da cadeia de caracteres de bytes do membro pbData que contém o texto a ser criptografado.

[out, optional] ppszDataDescr

Um ponteiro para uma descrição legível de cadeia de caracteres dos dados criptografados incluídos com os dados criptografados. Esse parâmetro pode ser definido como NULL. Quando terminar de usar ppszDataDescr, libere-o chamando a função LocalFree .

[in, optional] pOptionalEntropy

Um ponteiro para uma estrutura DATA_BLOB que contém uma senha ou outra entropia adicional usada quando os dados foram criptografados. Esse parâmetro pode ser definido como NULL; no entanto, se uma entropia opcional DATA_BLOB estrutura tiver sido usada na fase de criptografia, essa mesma estrutura DATA_BLOB deverá ser usada para a fase de descriptografia. Para obter informações sobre como proteger senhas, consulte Como lidar com senhas.

pvReserved

Esse parâmetro é reservado para uso futuro e deve ser definido como NULL.

[in, optional] pPromptStruct

Um ponteiro para uma estrutura de CRYPTPROTECT_PROMPTSTRUCT que fornece informações sobre onde e quando os prompts devem ser exibidos e qual deve ser o conteúdo desses prompts. Esse parâmetro pode ser definido como NULL.

[in] dwFlags

Um valor DWORD que especifica opções para essa função. Esse parâmetro pode ser zero, caso em que nenhuma opção está definida ou o sinalizador a seguir.

[out] pDataOut

Um ponteiro para uma estrutura DATA_BLOB em que a função armazena os dados descriptografados. Quando terminar de usar a estrutura DATA_BLOB , libere seu membro pbData chamando a função LocalFree .

Valor de retorno

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

Se a função falhar, ela retornará FALSE.

Observações

A função CryptProtectData cria uma chave de sessão quando os dados são criptografados. Essa chave é derivada novamente e usada para descriptografar o BLOB de dados.

O hash do MAC (Código de Autenticação de Mensagem) adicionado aos dados criptografados é usado para detectar se os dados criptografados foram alterados de alguma forma. No entanto, o código de erro específico retornado quando a adulteração é detectada pode variar dependendo da natureza da corrupção. A função pode retornar ERROR_INVALID_DATA, ERROR_INVALID_PARAMETER ou, em alguns casos, pode ter êxito com a saída corrompida. Os aplicativos não devem contar com um código de erro específico para detectar violação de dados. Para detecção robusta de adulteração, considere implementar verificações de integridade adicionais no nível do aplicativo.

Quando terminar de usar a estrutura DATA_BLOB , libere seu membro pbData chamando a função LocalFree . Qualquer ppszDataDescr que não seja NULL também deve ser liberado usando LocalFree.

Quando terminar de usar informações confidenciais, limpe-as da memória chamando a função SecureZeroMemory .

Exemplos

O exemplo a seguir mostra a descriptografia de dados criptografados em uma estrutura DATA_BLOB . Essa função faz a descriptografia usando uma chave de sessão que a função cria usando as credenciais de logon do usuário. Para outro exemplo que usa essa função, consulte Exemplo de Programa C: Usando CryptProtectData.

// Decrypt data from DATA_BLOB DataOut to DATA_BLOB DataVerify.

//--------------------------------------------------------------------
// Declare and initialize variables.

DATA_BLOB DataOut;
DATA_BLOB DataVerify;
LPWSTR pDescrOut =  NULL;
//--------------------------------------------------------------------
// The buffer DataOut would be created using the CryptProtectData
// function. If may have been read in from a file.

//--------------------------------------------------------------------
//   Begin unprotect phase.

if (CryptUnprotectData(
        &DataOut,
        &pDescrOut,
        NULL,                 // Optional entropy
        NULL,                 // Reserved
        NULL,                 // Here, the optional 
                              // prompt structure is not
                              // used.
        0,
        &DataVerify))
{
     printf("The decrypted data is: %s\n", DataVerify.pbData);
     printf("The description of the data was: %s\n",pDescrOut);
     LocalFree(DataVerify.pbData);
     LocalFree(pDescrOut);
}
else
{
    printf("Decryption error!");
}

Requirements

Consulte também

CryptProtectData

CryptUnprotectMemory

Funções de criptografia e descriptografia de dados

LocalFree

Provedor criptográfico base da Microsoft