Export (0) Print
Expand All

DsInheritSecurityIdentity function

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.

Syntax


DWORD WINAPI DsInheritSecurityIdentity(
  _In_  HANDLE hDS,
  _In_  DWORD Flags,
  _In_  LPCTSTR SrcPrincipal,
  _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. 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 value

Returns a system or RPC error code including the following.

Return codeDescription
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:

  • Verifies that SrcPrincipal and DstPrincipal are in the same domain.
  • Verifies that the domain is writable at the bind to the server.
  • Verifies that auditing is enabled for the domain.
  • Verifies that the caller is a member of the domain administrators for the domain.
  • Verifies that 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 for the principals, with a populated sidHistory, to obtain 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 that 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 fails if the caller does not have delete rights or if 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 operation if the audit fails.
  • Enters events into the Directory Service Log. Do not confuse this with the Security Audit Log.

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

DsInheritSecurityIdentityW (Unicode) and DsInheritSecurityIdentityA (ANSI)

See also

Domain Controller and Replication Management Functions
DSBind
DSBindWithCred

 

 

Show:
© 2014 Microsoft