DsInheritSecurityIdentity

The DsInheritSecurityIdentity API appends the objectSid and sidHistory of SrcPrincipal to the sidHistory of DstPrincipal and then deletes SrcPrincipal, all in a single transaction. To ensure atomicity, SrcPrincipal and DstPrincipal must be in the same domain and hDS must be a domain controller that has authority within that domain.

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

Parameters

hDS

[in] Directory service handle obtained using a call to DSBind or DSBindWithCred.

Flags

[in] Reserved for future use. Must be set to NULL.

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 the SrcPrincipal.

Return Values

Returns WIN32 error codes.

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.

The implementation of DsInheritSecurityIdentity is essentially as follows.

• Verifies SrcPrincipal and DstPrincipal are in the same domain.
• Verifies the domain is writeable at the bind to the server.
• Verifies auditing is enabled for the domain.
• Verifies the caller is a member of the domain admins for the domain.
• Verifies the domain is in the native mode. This operation is required because there may be Windows NT® 4.0 domain controllers present in the domain. If this operation was not required, it would be possible then for the principals with a populated sidHistory to get varying logon tokens and therefore cause unpredictable behavior.
• Verifies that SrcPrincipal exists, that it is a security principal and has read its objectSid and sidHistory properties.
• Verifies DstPrincipal exists, that it is a security principal, and has read certain properties required for auditing and verification.
• Deletes SrcPrincipal in the database only if the entire operation is committed at completion. This operation will also fail if the caller doesn't have delete rights or SrcPrincipal has children.
• Fails the operation if the objectSid of SrcPrincipal or DstPrincipal is a well known SID.
• Adds the objectSid and the sidHistory (if present) of SrcPrincipal to the sidHistory of DstPrincipal.
• Forces an audit event and fails the entire transaction if the audit fails.
• Enters events into the Directory Service Log. Do not confuse this with the Security Audit Log.

Requirements

  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.

See Also

DC and Replication Management Functions, DsAddSidHistory, DSBind, DSBindWithCred