To Set the TcpipClientSupport Registry Key| Platform SDK: Active Directory, ADSI, and Directory Services |
The DsAddSidHistory function retrieves the primary account security identifier (SID) of a security principal from one domain (the source domain) and adds it to the sIDHistory attribute of a security principal in another (destination) domain in a different forest. When the source domain is in the Windows® 2000 native mode, this function also retrieves the sIDHistory values of the source principal and adds them to the destination principal's sIDHistory.
Adding SIDs to a security principal's sIDHistory is a highly security-sensitive operation that effectively grants to the destination principal access to all resources accessible to the source principal, provided that trusts exist from applicable resource domains to the destination domain.
In a native mode Windows 2000 domain a user logon creates an access token that contains the user's primary account SID and group SIDs, as well as the user's sIDHistory and the sIDHistory of the groups of which the user is a member. Having these former SIDs (sIDHistory values) in the user's token grants the user access to resources protected by access-control lists (ACLs) containing the former SIDs.
This operation facilitates certain Windows 2000 deployment scenarios. In particular, it supports a scenario in which accounts in a new Windows 2000 forest are created for users and groups that already exist in an Windows NT® 4.0 production environment. By placing the Windows NT 4.0 account SID in the Windows 2000 account's sIDHistory, access to network resources is preserved for the user logging onto his new Windows 2000 account.
DsAddSidHistory also supports migration of Windows NT 4.0 backup domain controllers (BDC) resource servers (or DCs and member servers in a native mode Windows 2000 domain) to a Windows 2000 domain as member servers. This migration requires the creation, in the destination Windows 2000 domain, of domain local groups that contain, in their sIDHistory, the primary SIDs of the local groups defined on the BDC (or domain local groups referenced in ACLs on the Windows 2000 servers) in the source domain. By creating a destination local group containing the sIDHistory and all members of the source local group, access to the migrated server resources, protected by ACLs referencing the source local group, is maintained for all members.
Note Use of DsAddSidHistory requires an understanding of its broader administrative and security implications in these and other scenarios. This information is available in the white paper "Planning Migration from Microsoft® Windows NT to Microsoft Windows 2000", delivered as dommig.doc in the Windows 2000 Support Tools. This documentation may also be found on the product CD under \support\tools.
NTDSAPI DWORD WINAPI DsAddSidHistory( HANDLE hDS, DWORD Flags, LPCTSTR SrcDomain, LPCTSTR SrcPrincipal, LPCTSTR SrcDomainController, RPC_AUTH_IDENTITY_HANDLE SrcDomainCreds, LPCTSTR DstDomain, LPCTSTR DstPrincipal );
Note: If SrcDomain is Windows NT 4.0 and SrcDomainCreds are NULL, then hDS must be bound to the NetBIOS name of the destination domain controller. The source domain must trust the destination domain. And, this call must be run on the destination domain controller.
Note: If the source DC is running Windows 2000, a DNS name must be used (example: microsoft.com). If the source DC is running Windows NT 4.0 (SP4 or higher), a NetBIOS name (example: Microsoft) must be used. If NULL, the implementation will select the PDC.
If NULL, the caller's credentials are used for access to the source domain.
Returns WIN32 error codes. Errors generated specifically by DsAddSidHistory include the following:
| Value | Description |
|---|---|
| ERROR_DS_CANT_FIND_DC_FOR_SRC_DOMAIN | The operation couldn't locate a domain controller (DC) 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_DESTINATION_DOMAIN_NOT_IN_FOREST | The destination domain must be in the same forest as the source domain. |
| ERROR_DS_DST_DOMAIN_NOT_NATIVE | Destination domain must be in the native mode. |
| ERROR_DS_INAPPROPRIATE_AUTH | Inappropriate authentication. Typically, the ldap_bind_sW() to the Windows 2000 source domain controller failed. |
| ERROR_DS_INSUFF_ACCESS_RIGHTS | Insufficient access rights to perform the operation. Typically, this error occurs because the caller is not a member of domain admins for 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) (writeable 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 the handle (hDs) was bound with NTLM instead of KERBEROS; perhaps because the server's DNS name was not used for the call to DsBind or DsBindWithCred. |
| ERROR_DS_NAME_ERROR_NOT_UNIQUE | Name Translation: Input name mapped to more than one output name. Typically, the destination principal mapped to more than one fully qualified domain name (FQDN) 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 (FQDN) of the destination principal could not 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 or greater. |
| 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's SID already exists in the destination forest. |
| ERROR_DS_UNAVAILABLE | The directory service is unavailable. Typically, the ldap_openW() to the Windows 2000 SRC DC failed. |
| ERROR_DS_UNWILLING_TO_PERFORM | This error return value is typically returned because the user account is not one of the following; UF_NORMAL_ACCOUNT, UF_WORKSTATION_TRUST_ ACCOUNT, or UF_SERVER_TRUST_ACCOUNT.
Or, because the source principal is a well-known relative identifier (RID) being added to a destination principal that has a different RID. Administrators of the source domain can only be assigned to Administrators of the destination domain. |
| ERROR_INVALID_HANDLE | The secure connection to the source domain controller (DC) requires that the following Registry key is set to REG_DWORD=1 on the source DC;
Machine\System\CurrentControlSet\Control\Lsa\TcpipClientSupport and that the DC is then subsequently rebooted. |
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 domain in a different forest, effectively granting to the latter access to all resources accessible to the former.
DsAddSidHistory requires administrator privileges in the source and destination domains. Specifically, the caller of this API must be a member of the Domain Administrators group in the destination domain. A hard-coded check for this membership is performed. Also, the caller or the account provided in the SrcDomainCreds parameter (if not NULL), must be a member of either the Administrators or Domain Administrators group in the source domain.
DsAddSidHistory requires that the destination domain be Windows 2000 native mode, since only this domain type supports the sIDHistory attribute. The source domain may be either Windows NT 4.0 or Windows 2000, mixed or native mode. The source and destination domains must NOT be in the same forest. (Windows NT 4.0 domains are by definition not in a forest.) This inter-forest constraint ensures that duplicate SIDs (whether appearing as primary SIDs or sIDHistory values) are not created in the same forest.
DsAddSidHistory requires an external trust from the source domain to the destination domain in the following cases:
However, there is no trust required between the source and destination domains if the source domain is Windows NT 4.0 and non-NULL SrcDomainCreds are passed into DsAddSidHistory.
DsAddSidHistory requires the domain controller, selected as the target for operations in the source domain, be the primary domain controller (PDC in Windows NT 4.0.domains, or PDC Emulator in Windows 2000 domains). Source domain auditing is generated by write operations. Therefore, the PDC is needed in Windows NT 4.0 source domains, and the PDC-only restriction ensures that DsAddSidHistory audits are generated on a single machine, reducing the need to review the audit logs of all DCs to monitor use of this powerful operation.
Note In Windows NT 4.0 source domains, the PDC (target of operations in the source domain) must be running Service Pack 4 (SP4) or later to ensure proper auditing support.
The TcpipClientSupport registry key must be created and set on the source domain controller for both Windows NT 4.0 and Windows 2000 source DCs. Setting this key enables RPC calls over TCP transport. This is necessary because, by default, SAMRPC interfaces are remotable only on named pipes. Using named pipes results in a credential management system that is suitable for interactively logged-on users making networked calls, but is not flexible for a system process that makes network calls with user-supplied credentials. RPC over TCP is more suitable for that purpose. Setting this key does not diminish system security in any way.
A new local group, <SrcDomainName>$$$, must be created in the source domain for auditing purposes.
Additional information and setup instructions are provided below.
DsAddSidHistory operations are audited to ensure that both source and destination domain administrators are able to detect when this function has been run. Auditing is mandatory in both the source and destination domains. DsAddSidHistory verifies that the Audit Mode is on in each domain and that Account Management auditing of Success/Failure events is on. In the destination domain, a unique "Add Sid History" audit event is generated for each successful or failed DsAddSidHistory operation.
Unique "Add Sid History" audit events are not available on Windows NT 4.0 systems. To generate audit events that unambiguously reflect use of DsAddSidHistory against the source domain, it performs operations on a special group whose name is the unique identifier in the audit log. A local group, <SrcDomainName>$$$, whose name is composed of the source domain's NetBIOS name appended with three dollar signs (ASCII code = 0x24 and Unicode = U+0024), must be created on the source domain controller prior to calling DsAddSidHistory. Each source user and global group that is a target of this operation is added to the membership of, and then removed from the membership of this group. This generates Add Member and Delete Member audit events in the source domain, which can be monitored by searching for events referencing the group name.
Notes DsAddSidHistory operations on local groups in an Windows NT 4.0, or Windows 2000 mixed-mode source domain cannot be audited because local groups cannot be made members of another local group and therefore cannot be added to the special SrcDomainName$$$ local group. This lack of auditing does not present a vulnerability to the source domain, because source domain resource access is not affected by this operation. Adding the SID of a source local group to a destination local group does not grant access to source resources, protected by that local group, to any additional users. Adding members to the destination local group does not grant them access to source resources. Added members are granted access only to servers in the destination domain that have been migrated from the source domain, which may have resources protected by the source local group's SID.
The following security measures are enforced by this operation:
The following table identifies the threats associated with the DsAddSidHistory call and addresses the security measures pertinent to the particular threat.
| Potential Threat | Security Measures |
|---|---|
| Man in the Middle Attack
The attacker intercepts the lookup SID of source object return call, replacing the source object's SID with an arbitrary SID for insertion into a target object's SIDhistory. |
The lookup SID of source object is an authenticated RPC (using the caller's administrator credentials) with packet integrity message protection, which ensures that the return call cannot be modified without detection. The destination domain controller creates a unique "AddSidhistory" audit event that reflects the SID added to the destination account sIDHistory. |
| Trojan Source Domain
An attacker creates a "Trojan" source domain (on a private network) that has the same domain SID and some of the same account SIDs as the legitimate source domain. The attacker then attempts to run DsAddSidHistory in a destination domain to "steal" the SID of a source account. This is done without the need for the real source domain Administrator credentials and without leaving an audit trail in the real source domain. The attacker's method for creating the Trojan source domain could be one of the following:
|
Although there are many ways for an attacker to retrieve or create a desired source object SID, the attacker cannot use it to update an account's sIDHistory without being a member of the destination Domain Administrators group. Because the check, on the destination domain controller, for Domain Administrator membership is hard-coded (on the target DC), there's no method for doing a disk modification to change the access control information protecting this function. The attacker's attempt to clone a "Trojan" source account will be audited in the destination domain. This attack is mitigated by reserving membership in the Domain Administrators group for only very highly trusted individuals. |
| On-disk Modification of SIDhistory
A sophisticated attacker with Domain Administrator credentials and with physical access to a DC in the destination domain could modify an account's sIDHistory value on disk. |
This attack is not enabled by use of DsAddSidHistory.This attack is mitigated by preventing physical access to domain controllers to all but highly trusted administrators. |
| Patch Code to Remove Protections
A highly sophisticated rogue administrator or attacker with physical access to the Directory Service code could create a patch that:
|
Someone with physical access to the DS code and knowledgeable enough to create code patches has the capability of arbitrarily modifying the sIDHistory attribute of an account. The DsAddSidHistory API does not increase this vulnerability. |
| Resources Vulnerable to Stolen SIDs
If an attacker has succeeded in using one of the methods described here to modify an account sIDHistory, and if the resource domains of interest trust the attacker's account domain, then the attacker can get unauthorized access to the stolen SID's resources, potentially without leaving an audit trail in the account domain from which the SID was stolen. |
Resource domain administrators protect their resources by setting up only those trust relationships that make sense from a security perspective. Use of DsAddSidHistory is restricted, in the trusted target domain, to Domain Administrators who already have broad powers within the scope of their responsibilities. |
| Rogue Target Domain
An attacker creates a Windows 2000 domain with an account whose SIDhistory contains a SID that has been stolen from a source domain. The attacker uses this account for unauthorized access to resources. |
The attacker requires Administrator credentials for the source domain in order to use DsAddSidHistory, and will leave an audit trail on the source domain controller (DC). The Rogue Target domain will gain unauthorized access only in other domains that trust the Rogue domain, which requires Administrator privileges in those resource domains. |
This section describes the operational constraints of using the DsAddSidHistory function.
The SID of SrcPrincipal must not already exist in the destination forest, either as a primary account SID or in the sIDHistory of an account. The exception is that DsAddSidHistory will not generate an error when attempting to add a SID to a sIDHistory that already contains an identical SID. This behavior allows DsAddSidHistory to be run multiple times with identical input, resulting in success and a consistent end state, for tool developer ease-of-use.
Note Global Catalog replication latency may provide a window during which duplicate SIDs may be created. However, duplicate SIDs can be easily deleted by an administrator.
SrcPrincipal and DstPrincipal must be of one of the following types:
The object types of SrcPrincipal and DstPrincipal must match.
SrcPrincipal and DstPrincipal may NOT be one of the following types:
(DsAddSidHistory will fail with an error in these cases)
If SrcPrincipal has a well-known relative identifier (RID) and a domain specific prefix (that is, Domain Admins, Domain Users, Domain Computers), then DstPrincipal must possess the same well-known RID in order for DsAddSidHistory to succeed.
To Set the TcpipClientSupport Registry Key
Create the following registry key and set its value to REG_DWORD=1 on the source domain controller:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\TcpipClientSupport
Then, reboot the source domain controller. This registry key and value makes the Security Account Manager (SAM) listen on TCP/IP. DsAddSidHistory will fail if this key isn't set on the source domain controller.
To Enable Auditing of User/Group Management Events
In a Windows 2000 source or destination domain:
In a Windows NT 4.0 domain:
In the Windows NT 4.0 or Windows 2000 source domain:
The DsAddSidHistory operation will fail if source and destination auditing aren't enabled as described here.
Windows NT/2000: Requires Windows 2000.
Header: Declared in Ntdsapi.h.
Library: Included as a resource in Ntdsapi.dll.
Unicode: Implemented as Unicode and ANSI versions on Windows 2000.
DC and Replication Management Functions, DSBind, DSBindWithCred