Função CryptUnprotectData (dpapi.h)

Artigo
02/26/2024

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.

Valor	Significado
CRYPTPROTECT_UI_FORBIDDEN	Esse sinalizador é usado para situações remotas em que a interface do usuário (interface do usuário) não é uma opção. Quando esse sinalizador é definido e a interface do usuário é especificada para a operação de proteção ou desprotegimento, a operação falha e GetLastError retorna o código ERROR_PASSWORD_RESTRICTION.
CRYPTPROTECT_VERIFY_PROTECTION	Esse sinalizador verifica a proteção de um BLOB protegido. Se o nível de proteção padrão configurado do host for maior que o nível de proteção atual para o BLOB, a função retornará CRYPT_I_NEW_PROTECTION_REQUIRED para aconselhar o chamador a proteger novamente o texto sem formatação contido no BLOB.

[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

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	dpapi.h
Biblioteca	Crypt32.lib
DLL	Crypt32.dll