NCryptUnprotectSecret function (ncryptprotect.h)

  • Article

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

See also

CNG DPAPI Functions

NCryptProtectSecret