LsaStorePrivateData function (ntsecapi.h)

Article
02/22/2024

Do not use the LSA private data functions or generic data encryption and decryption. Instead, use the CryptProtectData and CryptUnprotectData functions. Only use the LSA private data functions when it is necessary to manipulate LSA secrets as documented in Secret Object Data Model

Syntax

NTSTATUS LsaStorePrivateData(
  [in] LSA_HANDLE          PolicyHandle,
  [in] PLSA_UNICODE_STRING KeyName,
  [in] PLSA_UNICODE_STRING PrivateData
);

Parameters

[in] PolicyHandle

A handle to a Policy object. The handle must have the POLICY_CREATE_SECRET access right if this is the first time data is being stored under the key specified by the KeyName parameter. For more information, see Opening a Policy Object Handle.

[in] KeyName

Pointer to an LSA_UNICODE_STRING structure containing the name of the key under which the private data is stored.

[in] PrivateData

Pointer to an LSA_UNICODE_STRING structure containing the private data to store. The function encrypts this data before storing it.

If this parameter is NULL, the function deletes any private data stored under the key and deletes the key. Subsequent attempts to retrieve data from the key will return the STATUS_OBJECT_NAME_NOT_FOUND error code.

Return value

If the function succeeds, the return value is STATUS_SUCCESS.

If the function fails, the return value is an NTSTATUS code. For more information, see LSA Policy Function Return Values.

You can use the LsaNtStatusToWinError function to convert the NTSTATUS code to a Windows error code.

Remarks

The LsaStorePrivateData function can be used by server applications to store client and machine passwords.

As described in Private Data Object, private data objects include three specialized types: local, global, and machine. Specialized objects are identified by a prefix in the key name: "L$" for local objects, "G$" for global objects, and "M$" for machine objects. Local objects cannot be accessed remotely. Machine objects can be accessed only by the operating system.

In addition to these prefixes, the following values also indicate local or machine objects. These values are supported for backward compatibility and should not be used when you create new local or machine objects. The key name of local private data objects may also be "$machine.acc", "SAC", "SAI", "SANSC", or start with "RasDialParms" or "RasCredentials". The key name for machine objects may also start with, "NL$" or "sc".

Private data objects which do not use any of the preceding key name conventions can be accessed remotely and are not replicated to other domains.

The data stored by the LsaStorePrivateData function is not absolutely protected. However, the data is encrypted before being stored, and the key has a DACL that allows only the creator and administrators to read the data.

Use the LsaRetrievePrivateData function to retrieve the value stored by LsaStorePrivateData.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	ntsecapi.h
Library	Advapi32.lib
DLL	Advapi32.dll