Función CryptProtectData (dpapi.h)

La función CryptProtectData realiza el cifrado de los datos de una estructura de DATA_BLOB . Normalmente, solo un usuario con la misma credencial de inicio de sesión que el usuario que cifró los datos puede descifrar los datos. Además, el cifrado y el descifrado normalmente deben realizarse en el mismo equipo. Para obtener información sobre las excepciones, vea Comentarios.

Sintaxis

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

Puntero a una estructura DATA_BLOB que contiene el texto no cifrado que se va a cifrar.

[in, optional] szDataDescr

Cadena con una descripción legible de los datos que se van a cifrar. Esta cadena de descripción se incluye con los datos cifrados. Este parámetro es opcional y se puede establecer en NULL.

[in, optional] pOptionalEntropy

Puntero a una estructura de DATA_BLOB que contiene una contraseña u otra entropía adicional utilizada para cifrar los datos. La estructura de DATA_BLOB utilizada en la fase de cifrado también debe usarse en la fase de descifrado. Este parámetro se puede establecer en NULL para ninguna entropía adicional. Para obtener información sobre la protección de contraseñas, consulte Control de contraseñas.

[in] pvReserved

Reservado para uso futuro y debe establecerse en NULL.

[in, optional] pPromptStruct

Puntero a una estructura de CRYPTPROTECT_PROMPTSTRUCT que proporciona información sobre dónde y cuándo se mostrarán los mensajes y cuál debe ser el contenido de esas solicitudes. Este parámetro se puede establecer en NULL en las fases de cifrado y descifrado.

[in] dwFlags

Este parámetro puede ser una de las marcas siguientes.

Value Significado
CRYPTPROTECT_LOCAL_MACHINE
Cuando se establece esta marca, asocia los datos cifrados con el equipo actual en lugar de con un usuario individual. Cualquier usuario del equipo en el que se llama a CryptProtectData puede usar CryptUnprotectData para descifrar los datos.
CRYPTPROTECT_UI_FORBIDDEN
Esta marca se usa para situaciones remotas en las que la presentación de una interfaz de usuario (UI) no es una opción. Cuando se establece esta marca y se especifica una interfaz de usuario para la operación de protección o desprotección, se produce un error en la operación y GetLastError devuelve el código ERROR_PASSWORD_RESTRICTION.
CRYPTPROTECT_AUDIT
Esta marca genera una auditoría en las operaciones de protección y desprotección. Las entradas del registro de auditoría solo se registran si szDataDescr no es NULL y no está vacía.

[out] pDataOut

Puntero a una estructura DATA_BLOB que recibe los datos cifrados. Cuando haya terminado de usar la estructura DATA_BLOB , libere su miembro pbData llamando a la función LocalFree .

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve TRUE.

Si se produce un error en la función, devuelve FALSE. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Normalmente, solo un usuario con credenciales de inicio de sesión que coincidan con los del usuario que cifró los datos puede descifrar los datos. Además, el descifrado normalmente solo se puede realizar en el equipo donde se cifraron los datos. Sin embargo, un usuario con un perfil móvil puede descifrar los datos de otro equipo de la red.

Si la marca CRYPTPROTECT_LOCAL_MACHINE se establece cuando se cifran los datos, cualquier usuario del equipo en el que se realizó el cifrado puede descifrar los datos.

La función crea una clave de sesión para realizar el cifrado. La clave de sesión se deriva de nuevo cuando se descifran los datos.

La función también agrega un código de autenticación de mensajes (MAC) (comprobación de integridad con clave) a los datos cifrados para protegerse contra la manipulación de datos.

Para cifrar la memoria para su uso temporal en el mismo proceso o entre procesos, llame a la función CryptProtectMemory .

Ejemplos

En el ejemplo siguiente se muestra el cifrado de los datos en una estructura de DATA_BLOB . La función CryptProtectData realiza el cifrado mediante una clave de sesión que crea la función mediante las credenciales de inicio de sesión del usuario. Para obtener otro ejemplo que use esta función, vea Ejemplo de programa C: Uso de 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); 
}

Requisitos

   
Cliente mínimo compatible Windows XP [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado dpapi.h
Library Crypt32.lib
Archivo DLL Crypt32.dll

Consulte también

CryptProtectMemory

CryptUnprotectData

Funciones de cifrado y descifrado de datos

LocalFree