DsAddSidHistoryA function (ntdsapi.h)

The DsAddSidHistory function retrieves the primary account security identifier (SID) of a security principal from one domain and adds it to the sIDHistory attribute of a security principal in another domain in a different forest. When the source domain is in Windows 2000 native mode, this function also retrieves the sIDHistory values of the source principal and adds them to the destination principal sIDHistory.

The DsAddSidHistory function performs a security-sensitive function by adding the primary account SID of an existing security principal to the sIDHistory of a principal in a domain in a different forest, effectively granting to the latter access to all resources accessible to the former. For more information about the use and security implications of this function, see Using DsAddSidHistory.

Syntax

NTDSAPI DWORD DsAddSidHistoryA(
  [in] HANDLE                   hDS,
  [in] DWORD                    Flags,
  [in] LPCSTR                   SrcDomain,
  [in] LPCSTR                   SrcPrincipal,
  [in] LPCSTR                   SrcDomainController,
  [in] RPC_AUTH_IDENTITY_HANDLE SrcDomainCreds,
  [in] LPCSTR                   DstDomain,
  [in] LPCSTR                   DstPrincipal
);

Parameters

[in] hDS

Contains a directory service handle obtained from either the DSBind or DSBindWithCred function.

[in] Flags

Reserved for future use. Set to NULL.

[in] SrcDomain

Pointer to a null-terminated string that specifies the name of the domain to query for the SID of SrcPrincipal.

If the source domain runs on Windows Server operating systems, SrcDomain can be either a domain name system (DNS) name, for example, fabrikam.com, or a flat NetBIOS, for example, Fabrikam, name. DNS names should be used when possible.

[in] SrcPrincipal

Pointer to a null-terminated string that specifies the name of a security principal, user or group, in the source domain. This name is a domain-relative Security Account Manager (SAM) name, for example: evacorets.

[in] SrcDomainController

Pointer to a null-terminated string that specifies the name of the primary domain controller (PDC) Emulator in the source domain to use for secure retrieval of the source principal SID and audit generation.

If this parameter is NULL, DSBindWithCred will select the primary domain controller.

SrcDomainController can be either a DNS name or a flat NetBIOS name. DNS names should be used when possible.

[in] SrcDomainCreds

Contains an identity handle that represents the identity and credentials of a user with administrative rights in the source domain. To obtain this handle, call DsMakePasswordCredentials. This user must be a member of either the Administrators or the Domain Administrators group. If this call is made from a remote computer to the destination DC, then both the remote computer and the destination DC must support 128-bit encryption to privacy-protect the credentials. If 128-bit encryption is unavailable and SrcDomainCreds are provided, then the call must be made on the destination DC.

If this parameter is NULL, the credentials of the caller are used for access to the source domain.

[in] DstDomain

Pointer to a null-terminated string that specifies the name of the destination domain in which DstPrincipal resides. This name can either be a DNS name, for example, fabrikam.com, or a NetBIOS name, for example, Fabrikam. The destination domain must run Windows 2000 native mode.

[in] DstPrincipal

Pointer to a null-terminated string that specifies the name of a security principal, user or group, in the destination domain. This domain-relative SAM name identifies the principal whose sIDHistory attribute is updated with the SID of the SrcPrincipal.

Return value

Returns a Win32 error codes including the following.

Remarks

Note

The ntdsapi.h header defines DsAddSidHistory 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

See also

DSBind

DSBindWithCred

Domain Controller and Replication Management Functions

DsMakePasswordCredentials

Using DsAddSidHistory

ldap_bind_s

ldap_open