Directory Services

DsInheritSecurityIdentity

The DsInheritSecurityIdentity function appends the objectSid and sidHistory attributes of SrcPrincipal to the sidHistory of DstPrincipal and then deletes SrcPrincipal, all in a single transaction. To ensure that this operation is atomic, SrcPrincipal and DstPrincipal must be in the same domain and hDS must be bound to a domain controller that the correct permissions within that domain.

DWORD WINAPI DsInheritSecurityIdentity(
  HANDLE hDS,
  DWORD Flags,
  LPCTSTR SrcPrincipal,
  LPCTSTR DstPrincipal
);

Parameters

hDS
[in] Contains a directory service handle obtained using a call to DSBind or DSBindWithCred.
Flags
[in] Reserved for future use. Must be zero.
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 SAM name.
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 will be updated with the SID of SrcPrincipal.

Return Values

Returns a Win32 or RPC error code including the following.

Return Code Description
NO_ERROR The function was successful.
ERROR_INVALID_PARAMETER One or more parameters are invalid.
ERROR_NOT_SUPPORTED The operation is not supported.

Remarks

With an operating system upgrade, as from Windows NT® 4.0 to Windows® 2000, domain applications, which span both upgraded and non-upgraded domains, may have security principals inside and outside the forest for the same logical entity at the same time.

When all upgraded domains have joined the same forest, DsInheritSecurityIdentity eliminates the duplicate objects while ensuring that the remaining objects have all the security rights and privileges belonging to their respective deleted object.

A DsInheritSecurityIdentity implementation:

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, Domain Controller and Replication Management Functions