Edit

Share via

NCryptProtectSecret function (ncryptprotect.h)

  • Article

The NCryptProtectSecret function encrypts data to a specified protection descriptor. Call NCryptUnprotectSecret to decrypt the data.

Syntax

SECURITY_STATUS NCryptProtectSecret(
  [in]           NCRYPT_DESCRIPTOR_HANDLE hDescriptor,
  [in]           DWORD                    dwFlags,
  [in]           const BYTE               *pbData,
  [in]           ULONG                    cbData,
  [in, optional] const NCRYPT_ALLOC_PARA  *pMemPara,
  [in, optional] HWND                     hWnd,
  [out]          BYTE                     **ppbProtectedBlob,
  [out]          ULONG                    *pcbProtectedBlob
);

Parameters

[in] hDescriptor

Handle of the protection descriptor object. Create the handle by calling NCryptCreateProtectionDescriptor.

[in] dwFlags

The flag can be zero or the following value.

Value Meaning
NCRYPT_SILENT_FLAG
 Requests that the key service provider not display a user interface.

[in] pbData

Pointer to the byte array to be protected.

[in] cbData

Number of bytes in the binary array specified by the pbData 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 ppbProtectedBlob parameter.

[in, optional] hWnd

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

[out] ppbProtectedBlob

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

[out] pcbProtectedBlob

Pointer to a ULONG variable that contains the size, in bytes, of the encrypted data pointed to by the ppbProtectedBlob 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_INVALID_PARAMETER
 The pbData, ppbProtectedBlob, and pcbProtectedBlob parameters cannot be NULL.

The cbData parameter cannot be less than one.
NTE_NO_MEMORY
 Insufficient memory exists to allocate the content encryption key.
NTE_INVALID_HANDLE
 The handle specified by the hDescriptor parameter is not valid.

Remarks

Use the NCryptProtectSecret function to protect keys, key material, and passwords. Use the NCryptStreamOpenToProtect and the NCryptStreamUpdate functions to encrypt 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

NCryptCreateProtectionDescriptor

NCryptUnprotectSecret