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. The caller user then needs administrative rights in 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 that 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 is 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
Domain Controller and Replication Management Functions
ldap_open