Función CryptUnprotectData (dpapi.h)

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.

[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 hashde 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

Consulte también

CryptProtectData

CryptUnprotectMemory

Funciones de cifrado y descifrado de datos

LocalFree

Proveedor criptográfico base de Microsoft