DsMakePasswordCredentialsA function (ntdsapi.h)

Article
02/09/2023

The DsMakePasswordCredentials function constructs a credential handle suitable for use with the DsBindWithCred function.

Syntax

NTDSAPI DWORD DsMakePasswordCredentialsA(
  [in]  LPCSTR                   User,
  [in]  LPCSTR                   Domain,
  [in]  LPCSTR                   Password,
  [out] RPC_AUTH_IDENTITY_HANDLE *pAuthIdentity
);

Parameters

[in] User

Pointer to a null-terminated string that contains the user name to use for the credentials.

[in] Domain

Pointer to a null-terminated string that contains the domain that the user is a member of.

[in] Password

Pointer to a null-terminated string that contains the password to use for the credentials.

[out] pAuthIdentity

Pointer to an RPC_AUTH_IDENTITY_HANDLE value that receives the credential handle. This handle is used in a subsequent call to DsBindWithCred. This handle must be freed with the DsFreePasswordCredentials function when it is no longer required.

Return value

Returns a Windows error code, including the following.

Remarks

A null, default credential handle is created if User, Domain and Password are all NULL. Otherwise, User must be present. The Domain parameter may be NULL when User is fully qualified, such as a user in UPN format; for example, "someone@fabrikam.com".

When the handle returned in pAuthIdentity is passed to DsBindWithCred, DsUnBind must be called before freeing the handle with DsFreePasswordCredentials. The normal sequence is:

Call DsMakePasswordCredentials to obtain the credential handle.
Call DsBindWithCred, and pass the credential handle.
Call DsUnbind when the binding is no longer required.
Call DsFreePasswordCredentials to free the credential handle.

Note

The ntdsapi.h header defines DsMakePasswordCredentials as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	ntdsapi.h
Library	Ntdsapi.lib
DLL	Ntdsapi.dll