2 out of 2 rated this helpful - Rate this topic

DsAddSidHistory function

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

C++


DWORD WINAPI DsAddSidHistory(
  _In_  HANDLE hDS,
  _In_  DWORD Flags,
  _In_  LPCTSTR SrcDomain,
  _In_  LPCTSTR SrcPrincipal,
  _In_  LPCTSTR SrcDomainController,
  _In_  RPC_AUTH_IDENTITY_HANDLE SrcDomainCreds,
  _In_  LPCTSTR DstDomain,
  _In_  LPCTSTR DstPrincipal
);

Parameters

hDS [in]

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

Flags [in]

Reserved for future use. Set to NULL.

SrcDomain [in]

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 2003 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.

If the source domain is Windows 2000, SrcDomain must be a DNS name.

If the source domain is Windows NT 4.0, SrcDomain must be a NetBIOS name.

SrcPrincipal [in]

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.

SrcDomainController [in]

Pointer to a null-terminated string that specifies the name of the primary domain controller (PDC) (PDC for Windows NT 4.0, PDC Emulator for Windows 2000, or Windows Server 2003) 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.

If the source domain controller runs on Windows Server 2003 operating systems, SrcDomainController can be either a DNS name or a flat NetBIOS name. DNS names should be used when possible.

If the source domain is Windows 2000, SrcDomainController must be a DNS name.

If the source domain is Windows NT 4.0, SrcDomainController must be a NetBIOS name.

SrcDomainCreds [in]

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.

DstDomain [in]

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.

DstPrincipal [in]

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.

Return code	Description
NO_ERROR	The function succeeded.
ERROR_DEV_NOT_EXIST	The source domain controller is a Windows 2000 server and SrcDomain contains a NetBIOS name.
ERROR_DS_CANT_FIND_DC_FOR_SRC_DOMAIN	The operation cannot locate a domain controller for the source domain.
ERROR_DS_DESTINATION_AUDITING_NOT_ENABLED	Auditing was not enabled prior to operation. The operation requires that destination domain auditing be enabled for Success/Failure auditing of account management operations.
ERROR_DS_DST_DOMAIN_NOT_NATIVE	The destination domain must be in Windows 2000 native mode.
ERROR_DS_INAPPROPRIATE_AUTH	Inappropriate authorization credentials were supplied. This typically means that a call to ldap_bind_s to the Windows 2000 source domain controller failed.
ERROR_DS_INSUFF_ACCESS_RIGHTS	The caller has insufficient access rights to perform the operation. This error typically occurs because the caller is not a member of the Domain Administrators group in the destination domain.
ERROR_DS_INTERNAL_FAILURE	The directory service encountered an internal error.
ERROR_DS_MASTERDSA_REQUIRED	The operation must be performed at a master directory service agent (DSA) (writable DC).
ERROR_DS_MUST_BE_RUN_ON_DST_DC	For security purposes, the operation must be run on a destination DC. Specifically, the connection between the client and server (destination domain controller) requires 128-bit encryption when credentials for the source domain are supplied. 128 bit encryption is the same as 128-bit Kerberos encryption. This value may also be returned if the 128-bit support is not installed on both client and server. This value may also be returned if hDC was bound with NTLM instead of Kerberos; possibly because the server DNS name was not used for the call to DSBind or DSBindWithCred.
ERROR_DS_NAME_ERROR_NOT_UNIQUE	The input name mapped to more than one output name. Typically, the destination principal mapped to more than one fully qualified domain name in the destination domain.
ERROR_DS_NO_PKT_PRIVACY_ON_CONNECTION	The connection between client and server requires packet privacy or better.
ERROR_DS_OBJ_CLASS_VIOLATION	The requested operation did not satisfy one or more constraints associated with the class of the object. Typically, the destination principal is not a user or group.
ERROR_DS_OBJ_NOT_FOUND	Directory object not found. Typically, the fully qualified domain name of the destination principal cannot be found in the destination domain.
ERROR_DS_SOURCE_AUDITING_NOT_ENABLED	The operation requires that source domain auditing be enabled for Success/Failure auditing of account management operations.
ERROR_DS_SOURCE_DOMAIN_IN_FOREST	The source domain is not in the same forest as the destination domain.
ERROR_DS_SRC_AND_DST_OBJECT_CLASS_MISMATCH	The source and destination object must be of the same type.
ERROR_DS_SRC_DC_MUST_BE_SP4_OR_GREATER	For security reasons, the source domain controller must be Windows NT 4.0 with SP4 and later.
ERROR_DS_SRC_OBJ_NOT_GROUP_OR_USER	The source object must be a group or user.
ERROR_DS_SRC_SID_EXISTS_IN_FOREST	The source object SID exists in the destination forest.
ERROR_DS_UNAVAILABLE	The directory service is unavailable. Typically, the ldap_open to the Windows 2000 source DC failed.
ERROR_DS_UNWILLING_TO_PERFORM	The user account is not one of the following: UF_NORMAL_ACCOUNT, UF_WORKSTATION_TRUST_ACCOUNT, or UF_SERVER_TRUST_ACCOUNT. This error can also occur because the source principal is a well-known relative identifier added to a destination principal that has a different relative identifier. Administrators of the source domain can be assigned only to the Administrators group of the destination domain.
ERROR_INVALID_HANDLE	The secure connection to the source domain controller requires that the following registry value on the source domain controller is a REG_DWORD with a value of 1. HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\TcpipClientSupport
ERROR_INVALID_PARAMETER	One or more parameters are invalid.

Remarks

If SrcDomain is Windows NT 4.0 and SrcDomainCreds is NULL, then hDS must be bound to the NetBIOS name of the destination domain controller. The source domain must trust the destination domain. This call must be run on the destination domain controller.

If SrcDomain is Windows NT 4.0 and SrcDomainCreds is not NULL, then no trust is required between the source domain and the destination domain.

Requirements

Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Redistributable	Active Directory Client Extension on Windows NT 4.0 and Windows Me/98/95
Header	Ntdsapi.h
Library	Ntdsapi.lib
DLL	Ntdsapi.dll
Unicode and ANSI names	DsAddSidHistoryW (Unicode) and DsAddSidHistoryA (ANSI)

Community Additions

ADD