Función CryptProtectData (dpapi.h)
La función CryptProtectData realiza el cifrado en los datos de una estructura 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 de 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 usada para cifrar los datos. La estructura 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 cómo proteger las 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 las indicaciones y cuál debe ser el contenido de esas indicaciones. 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.
| Valor | Significado |
|---|---|
|
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. |
|
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 de ERROR_PASSWORD_RESTRICTION. |
|
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 de 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 donde 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 vuelve a derivar cuando se van a descifrar los datos.
La función también agrega un código de autenticación de mensajes (MAC) (comprobación de integridad con claves) 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 Programa C de ejemplo: 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 |