Share via

3.2.4.23 NetrUnjoinDomain3 (Opnum 32)

  • Article

The NetrUnjoinDomain3 method uses encrypted credentials to unjoin a computer from a workgroup or domain.<140>

 unsigned long NetrUnjoinDomain3(
   [in] handle_t RpcBindingHandle,
   [in, string, unique] wchar_t* ServerName,
   [in, string, unique] wchar_t* AccountName,
   [in, unique] PJOINPR_ENCRYPTED_USER_PASSWORD_AES Password,
   [in] unsigned long Options
 );

RpcBindingHandle: An RPC binding handle (see [C706]).

ServerName: This parameter has no effect on message processing in any environment. The client MUST set this parameter to a value that resolves to the IP destination address of the RPC packets it transmits ([MS-RPCE] section 2.1.1.2). The server (1) MUST ignore this parameter.

AccountName: A pointer to a string that specifies the account name in the joined domain to use when connecting to a domain controller. This parameter is optional. If this parameter is NULL, the caller's account name MUST be used.

Password: An optional pointer to a JOINPR_ENCRYPTED_USER_PASSWORD_AES structure (section 2.2.5.19) that specifies the encrypted password to use with the AccountName parameter. If this parameter is NULL, the caller's security context MUST be used.

Options: A 32-bit bitfield specifying modifications to default message processing behavior.

Value/code

Meaning

NETSETUP_ACCT_DELETE

0x00000004

Disables the account when the unjoin operation occurs.

NETSETUP_IGNORE_UNSUPPORTED_FLAGS

0x10000000

The server ignores undefined flags when this bit is set.<141> This option is present to allow for the addition of future optional values.

Return Values: When the message processing result meets the description in column two of the following table, this method MUST return one of the following values ([MS-ERREF] section 2.2).

Value/code

Meaning

NERR_Success

0x00000000

The operation completed successfully.

ERROR_ACCESS_DENIED

0x00000005

Access is denied.

ERROR_INVALID_PASSWORD

0x00000056

The specified network password is not correct.

ERROR_INVALID_PARAMETER

0x00000057

One of the function parameters is not valid.

ERROR_INVALID_FLAGS

0x000003EC

Invalid option flags are specified.

RPC_S_PROTSEQ_NOT_SUPPORTED

0x000006A7

The RPC protocol sequence is not supported.

NERR_SetupNotJoined

0x00000A84

This computer is not currently joined to a domain.

NERR_SetupDomainController

0x00000A85

This computer is a domain controller and cannot be unjoined from a domain.

Any other return value MUST conform to the error code requirements in Protocol Details (section 3).

Unless otherwise noted, if the server encounters an error during message processing, the server SHOULD revert any state changes made, MUST stop message processing, and MUST return the error to the caller.<142>

The following definitions are used in the specification of message processing that follows.

  • DomainControllerString: A UTF-8 string containing the name of a domain controller in the domain to which the server is joined.

  • DomainObject: An object in the domain database ([MS-ADTS] section 6.4) having the value of ComputerNameNetBIOS (section 3.2.1.5) suffixed with a "$" character for the SamAccountName attribute.

  • PasswordString: A UTF-8 string that contains a password in cleartext.

The following statements define the sequence of message processing operations.

  1. The server MUST retrieve the RPC protocol sequence used for the current call ([MS-RPCE] section 3.1.3.4.1), specifying the server binding handle maintained by the RPC runtime ([C706] section 6.2.1). If that RPC protocol sequence is not NCACN_NP, the server SHOULD return RPC_S_PROTSEQ_NOT_SUPPORTED.<143>

  2. The server MUST check that the caller has been granted access rights using the algorithm in the Access Control Abstract Data Model (section 3.2.1.1), with Access Request mask initialized to WKSTA_NETAPI_CHANGE_CONFIG; if not, the server MUST return ERROR_ACCESS_DENIED.

  3. If Password is NULL, PasswordString MUST be NULL. Otherwise, the server MUST decrypt and decode the Password (section 2.2.5.19). PasswordString MUST equal the decrypted and decoded value. The decrypted buffer is represented as a JOINPR_USER_PASSWORD structure (section 2.2.5.17). The value of the Length member MUST be less than 513; otherwise, message processing is stopped, and the server MUST return ERROR_INVALID_PASSWORD.

  4. The server MUST impersonate the client by invoking the StartImpersonatingClient task (section 3.2.4.29.6). If this operation fails, the server MUST return an error.

  5. The server MUST stop message processing and return NERR_SetupNotJoined if DomainSid (section 3.2.1.6) is NULL.

  6. If any bits other than NETSETUP_ACCT_DELETE are set in Options, the server MUST check the NETSETUP_IGNORE_UNSUPPORTED_FLAGS bit. If it is not set, the server MUST stop message processing and return ERROR_INVALID_FLAGS. Otherwise, message processing continues.

  7. The server MUST stop message processing and return NERR_SetupDomainController if the server processing the message is a domain controller. Otherwise, message processing continues.

  8. The server MUST locate a domain controller in the joined domain. DomainControllerString MUST be equal to the string name of the located domain controller.

  9. The server MUST establish an authenticated (1) SMB session with the domain controller named by the value of DomainControllerString. The credentials that are supplied during authentication are those in PasswordString, and the security context that is established MUST be that of AccountName. If an error occurs, the server MUST stop message processing and return that error. Otherwise, message processing continues.

  10. The SMB session established in the previous step and the security context associated with it MUST be used for any higher layer RPC calls made to the domain controller over the SMB NCACN_NP protocol sequence ([MS-SMB] section 3.2.4.2.4).

  11. The server MUST configure the local Net Logon Remote Protocol ([MS-NRPC]) so that it is aware of no longer being joined to a domain.

  12. The server MUST configure the local W32Time ([WTSREF]) so that it is aware of no longer being joined to a domain.

  13. The server MUST set DomainSid to NULL.

  14. The server MUST delete the persisted password that was stored previously in the Password ADM element when processing a NetrJoinDomain3 message.

  15. If the NETSETUP_ACCT_DELETE bit is set in Options, the server MUST update the DomainObject userAccountControl attribute by setting the USER_ACCOUNT_DISABLED bit. See the userAccountControl Mapping Table ([MS-SAMR] section 3.1.5.14.2) for details on the mapping of these bits in LDAP.

    The security context provided to LDAP is AccountName, and the credential is PasswordString. For details on attributes and attribute names, see [MS-ADTS]. For details on LDAP, see [RFC2252] and [RFC2253].

  16. The server MUST configure the Certificate Auto Enrollment Service ([MSFT-AUTOENROLLMENT] and [MS-CERSOD] section 2.1.2.2.2) so that it is aware of no longer being joined to a domain.

  17. The server MUST configure the local Net Logon Remote Protocol [MS-NRPC] such that it is aware of no longer being joined to a domain.

  18. The server SHOULD store the Internet host name locally such that the DNS service unregisters name records for the local computer [NIS].<144>

  19. The server SHOULD remove the domain admins group from the local administrators group, and the server SHOULD remove the domain users group from the local users groups ([MS-SAMR]).

  20. The server MUST set the following ADM elements (section 3.2.1.6) to NULL: ClientName, DomainName, DomainSid, ForestNameFQDN, DomainGuid, SiteName, and Password.

  21. The server MUST stop impersonating the client by invoking the StopImpersonatingClient task (section 3.2.4.29.7).

If no errors occur, the server MUST return NERR_Success.