NCryptUnprotectSecret function (ncryptprotect.h)

Article
02/22/2024

The NCryptUnprotectSecret function decrypts data to a specified protection descriptor. Call NCryptProtectSecret to encrypt the data.

Syntax

SECURITY_STATUS NCryptUnprotectSecret(
  [out, optional] NCRYPT_DESCRIPTOR_HANDLE *phDescriptor,
  [in]            DWORD                    dwFlags,
  [in]            const BYTE               *pbProtectedBlob,
                  ULONG                    cbProtectedBlob,
  [in, optional]  const NCRYPT_ALLOC_PARA  *pMemPara,
  [in, optional]  HWND                     hWnd,
  [out]           BYTE                     **ppbData,
  [out]           ULONG                    *pcbData
);

Parameters

[out, optional] phDescriptor

Pointer to the protection descriptor handle.

[in] dwFlags

The flag can be zero or a bitwise OR of the following values.

Value	Meaning
NCRYPT_SILENT_FLAG	Requests that the key service provider not display a user interface.
NCRYPT_UNPROTECT_NO_DECRYPT	Decodes only the header of the protected data blob. No actual decryption takes place.

[in] pbProtectedBlob

Pointer to an array of bytes that contains the data to decrypt.

cbProtectedBlob

The number of bytes in the array pointed to by the pbProtectedBlob parameter.

[in, optional] pMemPara

Pointer to an NCRYPT_ALLOC_PARA structure that you can use to specify custom memory management functions. If you set this argument to NULL, the LocalAlloc function is used internally to allocate memory and your application must call LocalFree to release memory pointed to by the ppbData parameter.

[in, optional] hWnd

Handle to the parent window of the user interface, if any, to be displayed.

[out] ppbData

Address of a variable that receives a pointer to the decrypted data.

[out] pcbData

Pointer to a ULONG variable that contains the size, in bytes, of the decrypted data pointed to by the ppbData variable.

Return value

Returns a status code that indicates the success or failure of the function. Possible return codes include, but are not limited to, the following.

Return code	Description
ERROR_SUCCESS	The function was successful.
NTE_BAD_FLAGS	The dwFlags parameter can only contain NCRYPT_SILENT_FLAG or NCRYPT_UNPROTECT_NO_DECRYPT.
NTE_INVALID_PARAMETER	The pbProtectedBlob, ppbData, and pcbData parameters cannot be NULL. The cbData parameter cannot be less than one.

Remarks

Use the NCryptUnprotectSecret function to decrypt keys, key material, and passwords. Use the NCryptStreamOpenToUnprotect and the NCryptStreamUpdate functions to decrypt larger messages.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	ncryptprotect.h
Library	NCrypt.lib
DLL	NCrypt.dll