Função CryptUnprotectData (dpapi.h)

A função CryptUnprotectData descriptografa e faz uma marcar 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 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 Manipulando senhas.

pvReserved

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

[in, optional] pPromptStruct

Um ponteiro para uma estrutura CRYPTPROTECT_PROMPTSTRUCT que fornece informações sobre onde e quando as solicitações devem ser exibidas 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 .

Retornar valor

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

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

Comentários

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 pode ser usado para determinar se os dados criptografados foram alterados de alguma forma. Qualquer violação resulta no retorno do código ERROR_INVALID_DATA.

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 obter 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!");
}

Requisitos

Confira também

CryptProtectData

CryptUnprotectMemory

Funções de criptografia e descriptografia de dados

Localfree

Provedor criptográfico base da Microsoft