NCryptProtectSecret function

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

Syntax


NTSTATUS WINAPI NCryptProtectSecret(
  _In_      NCRYPT_DESCRIPTOR_HANDLE hDescriptor,
  _In_      DWORD dwFlags,
  _In_      const BYTE *pbData,
  _In_      ULONG cbData,
  _In_opt_  const NCRYPT_ALLOC_PARA pMemPara,
  _In_opt_  HWND hWnd,
  _Out_     BYTE **ppbProtectedBlob,
  _Out_     ULONG *pcbProtectedBlob
);

Parameters

hDescriptor [in]

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

dwFlags [in]

The flag can be zero or the following value.

ValueMeaning
NCRYPT_SILENT_FLAG

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

 

pbData [in]

Pointer to the byte array to be protected.

cbData [in]

Number of bytes in the binary array specified by the pbData parameter.

pMemPara [in, optional]

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.

hWnd [in, optional]

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

ppbProtectedBlob [out]

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

pcbProtectedBlob [out]

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 codeDescription
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

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

NCryptprotect.h

Library

NCrypt.lib

DLL

NCrypt.dll

See also

CNG DPAPI Functions
NCryptCreateProtectionDescriptor
NCryptUnprotectSecret

 

 

Community Additions

ADD
Show:
© 2014 Microsoft