Función CryptUnprotectData (dpapi.h)

Artículo
02/29/2024

La función CryptUnprotectData descifra y realiza una comprobación de integridad de los datos en una estructura de DATA_BLOB . Normalmente, el único usuario que puede descifrar los datos es un usuario con las mismas credenciales de inicio de sesión que el usuario que cifró los datos. Además, el cifrado y el descifrado deben realizarse en el mismo equipo. Para obtener información sobre las excepciones, vea la sección Comentarios de CryptProtectData.

Sintaxis

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

Puntero a una estructura DATA_BLOB que contiene los datos cifrados. El miembro cbData de la estructura DATA_BLOB contiene la longitud de la cadena de bytes del miembro pbData que contiene el texto que se va a cifrar.

[out, optional] ppszDataDescr

Puntero a una descripción legible de cadena de los datos cifrados incluidos con los datos cifrados. Este parámetro se puede establecer en NULL. Cuando haya terminado de usar ppszDataDescr, álele una llamada a la función LocalFree .

[in, optional] pOptionalEntropy

Puntero a una estructura DATA_BLOB que contiene una contraseña u otra entropía adicional utilizada cuando se cifraron los datos. Este parámetro se puede establecer en NULL; Sin embargo, si se usó una estructura opcional DATA_BLOB en la fase de cifrado, esa misma estructura DATA_BLOB debe usarse para la fase de descifrado. Para obtener información sobre la protección de contraseñas, consulte Control de contraseñas.

pvReserved

Este parámetro está 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 muestran las indicaciones y cuál debe ser el contenido de esas solicitudes. Este parámetro se puede establecer en NULL.

[in] dwFlags

Valor DWORD que especifica las opciones de esta función. Este parámetro puede ser cero, en cuyo caso no se establece ninguna opción o la marca siguiente.

Valor	Significado
CRYPTPROTECT_UI_FORBIDDEN	Esta marca se usa para situaciones remotas en las que la interfaz de usuario (UI) no es una opción. Cuando se establece esta marca y se especifica la 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_VERIFY_PROTECTION	Esta marca comprueba la protección de un BLOB protegido. Si el nivel de protección predeterminado configurado del host es mayor que el nivel de protección actual para el BLOB, la función devuelve CRYPT_I_NEW_PROTECTION_REQUIRED para avisar al autor de la llamada para volver a proteger el texto no cifrado contenido en el BLOB.

[out] pDataOut

Puntero a una estructura DATA_BLOB donde la función almacena los datos descifrados. 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.

Comentarios

La función CryptProtectData crea una clave de sesión cuando se cifran los datos. Esa clave se deriva de nuevo y se usa para descifrar los datos BLOB.

El hash de código de autenticación de mensajes (MAC) agregado a los datos cifrados se puede usar para determinar si los datos cifrados se modificaron de cualquier manera. Cualquier alteración da como resultado la devolución del código de ERROR_INVALID_DATA.

Cuando haya terminado de usar la estructura DATA_BLOB , libere su miembro pbData llamando a la función LocalFree . Cualquier ppszDataDescr que no sea NULL también debe liberarse mediante LocalFree.

Cuando haya terminado de usar información confidencial, desactive la memoria mediante una llamada a la función SecureZeroMemory .

Ejemplos

En el ejemplo siguiente se muestra el descifrado de datos cifrados en una estructura de DATA_BLOB . Esta función realiza el descifrado 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.

// 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	Value
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