Directory Services

DsAddSidHistory

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's sIDHistory.

The DsAddSidHistory function performs a highly 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.

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

Parameters

hDS
[in] Contains a directory service handle obtained using a call to DSBind or DSBindWithCred.
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 family 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's 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 family 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 Values

Returns a Win32 error codes including the following.
Return Code Description
NO_ERROR The function suceeded.
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 Service Pack 4 (SP4) or 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

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 must trust the destination domain.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.
Header: Declared in Ntdsapi.h.
Library: Use Ntdsapi.lib.

See Also

DSBind, DSBindWithCred, DsMakePasswordCredentials, ldap_bind_s, ldap_open, Using DsAddSidHistory, Domain Controller and Replication Management Functions