Função CryptProtectData (dpapi.h)

A função CryptProtectData executa criptografia nos dados em uma estrutura de DATA_BLOB . Normalmente, somente um usuário com a mesma credencial de logon que o usuário que criptografou os dados pode descriptografar os dados. Além disso, a criptografia e a descriptografia geralmente devem ser feitas no mesmo computador. Para obter informações sobre exceções, consulte Comentários.

Sintaxe

DPAPI_IMP BOOL CryptProtectData(
  [in]           DATA_BLOB                 *pDataIn,
  [in, optional] LPCWSTR                   szDataDescr,
  [in, optional] DATA_BLOB                 *pOptionalEntropy,
  [in]           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 o texto sem formatação a ser criptografado.

[in, optional] szDataDescr

Uma cadeia de caracteres com uma descrição legível dos dados a serem criptografados. Essa cadeia de caracteres de descrição está incluída com os dados criptografados. Esse parâmetro é opcional e pode ser definido como NULL.

[in, optional] pOptionalEntropy

Um ponteiro para uma estrutura DATA_BLOB que contém uma senha ou outra entropia adicional usada para criptografar os dados. A estrutura de DATA_BLOB usada na fase de criptografia também deve ser usada na fase de descriptografia. Esse parâmetro pode ser definido como NULL para nenhuma entropia adicional. Para obter informações sobre como proteger senhas, consulte Como lidar com senhas.

[in] pvReserved

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 nas fases de criptografia e descriptografia.

[in] dwFlags

Esse parâmetro pode ser um dos sinalizadores a seguir. Se nenhum sinalizador for necessário, esse parâmetro poderá ser definido como 0.

[out] pDataOut

Um ponteiro para uma estrutura de DATA_BLOB que recebe os dados criptografados. 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. Para obter informações de erro estendidas, chame GetLastError.

Observações

Normalmente, somente um usuário com credenciais de logon que corresponda aos do usuário que criptografou os dados pode descriptografar os dados. Além disso, a descriptografia geralmente só pode ser feita no computador em que os dados foram criptografados. No entanto, um usuário com um perfil móvel pode descriptografar os dados de outro computador na rede.

Se o sinalizador CRYPTPROTECT_LOCAL_MACHINE for definido quando os dados forem criptografados, qualquer usuário no computador em que a criptografia foi feita poderá descriptografar os dados.

A função cria uma chave de sessão para executar a criptografia. A chave de sessão é derivada novamente quando os dados devem ser descriptografados.

A função também adiciona um MAC ( Código de Autenticação de Mensagem ) (verificação de integridade com chave) aos dados criptografados para proteger contra violação de dados.

Para criptografar a memória para uso temporário no mesmo processo ou em processos, chame a função CryptProtectMemory .

Exemplos

O exemplo a seguir mostra a criptografia dos dados em uma estrutura DATA_BLOB . A função CryptProtectData faz a criptografia 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.

// Encrypt data from DATA_BLOB DataIn to DATA_BLOB DataOut.

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

DATA_BLOB DataIn;
DATA_BLOB DataOut;
BYTE *pbDataInput =(BYTE *)"Hello world of data protection.";
DWORD cbDataInput = strlen((char *)pbDataInput)+1;

//--------------------------------------------------------------------
// Initialize the DataIn structure.

DataIn.pbData = pbDataInput;    
DataIn.cbData = cbDataInput;

//--------------------------------------------------------------------
//  Begin protect phase. Note that the encryption key is created
//  by the function and is not passed.

if(CryptProtectData(
     &DataIn,
     L"This is the description string.", // A description string
                                         // to be included with the
                                         // encrypted data. 
     NULL,                               // Optional entropy not used.
     NULL,                               // Reserved.
     NULL,                               // Pass NULL for the 
                                         // prompt structure.
     0,
     &DataOut))
{
     printf("The encryption phase worked.\n");
     LocalFree(DataOut.pbData);
}
else
{
    printf("Encryption error using CryptProtectData.\n");
    exit(1); 
}

Requirements

Consulte também

• CryptProtectMemory
• CryptUnprotectData
• Funções de criptografia e descriptografia de dados
• LocalFree