3.2.4.17 NetrGetJoinableOUs2 (Opnum 26)

  • Article

The NetrGetJoinableOUs2 method returns a list of organizational units (OUs) in which the user can create an object.<94>

 unsigned long NetrGetJoinableOUs2(
   [in] handle_t RpcBindingHandle,
   [in, string, unique] wchar_t* ServerName,
   [in, string] wchar_t* DomainNameParam,
   [in, string, unique] wchar_t* AccountName,
   [in, unique] PJOINPR_ENCRYPTED_USER_PASSWORD Password,
   [in, out] unsigned long* OUCount,
   [out, string, size_is(, *OUCount)] 
     wchar_t*** OUs
 );

RpcBindingHandle: An RPC binding handle [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 protocol layer destination address of the RPC packets it transmits ([MS-RPCE] section 2.1.1.2). The server (2) MUST ignore this parameter.

DomainNameParam: A pointer to a string that specifies the root domain under which the method searches for OUs. This parameter is also the domain of the account that the AccountName parameter is in.

AccountName: A pointer to a string that specifies the account name 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 structure (section 2.2.5.18) that specifies the encrypted password to use with the AccountName parameter. If the AccountName parameter is NULL, the caller's security context MUST be used, and this parameter MUST be ignored.

OUCount: A pointer to the count of OUs that the method returns. The server MUST ignore this parameter on input.

OUs: A pointer to a pointer of size OUCount to a block of strings that are the joinable OUs that the method returns.

Return Values: When the message processing result matches 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_NOT_ENOUGH_MEMORY

0x00000008

Not enough storage is available to process this command.

ERROR_INVALID_PARAMETER

0x00000057

A parameter is incorrect.<95>

RPC_S_PROTSEQ_NOT_SUPPORTED

0x000006A7

The RPC protocol sequence is not supported.

NERR_InvalidAPI

0x0000085E

The requested API is not supported on domain controllers.

NERR_DefaultJoinRequired

0x00000A86

The destination domain controller does not support creating machine accounts in OUs.

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

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

  • PasswordString: A Unicode UTF-8 string containing a password in cleartext.

  • DomainControllerString: A UTF-8 string that contains the name of a domain controller in the domain that the server is joining.

  • DomainControllerConnection: An ADCONNECTION_HANDLE ([MS-DTYP] section 2.2.2) to a domain controller.

  • LdapResultMessages: A list of LDAPMessage ([RFC2251]) containing results from an operation performed on DomainControllerConnection.

  • ComputerAccountDN: A UTF-8 string that contains the DN of the computer account.

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.<96>

  2. The server SHOULD<97> ensure that the caller is local. Specifications for determining that the caller is local are in [MS-RPCE].

  3. 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_QUERY; if not, the server MUST return ERROR_ACCESS_DENIED.

  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. If Password is NULL then PasswordString MUST be NULL. Otherwise, the server MUST decrypt and decode the Password (section 2.2.5.18). 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_ PARAMETER.

  6. The server SHOULD<98> enforce that this call fails on a domain controller. Otherwise, message processing continues.

  7. The server MUST locate a domain controller in the domain, by invoking the DsrGetDcNameEx2 method on the local [MS-NRPC] server specifying the following parameters:

    • ComputerName = NULL

    • AccountName = NULL

    • AllowableAccountControlBits = 0

    • DomainName = DomainNameFQDN (section 3.2.1.5)

    • DomainGuid = NULL

    • SiteName = NULL

    • Flags = (J | B) ([MS-NRPC] section 3.5.4.3.1).

      If a domain controller cannot be located, the method MUST fail. Otherwise, DomainControllerString MUST equal the string name of the returned writable domain controller.

  8. The server invokes LDAP Bind (section 3.2.4.29.2) with the following parameters:

    • DomainControllerBindTarget: DomainControllerString

    • AccountNameForBind: AccountName

    • PasswordForBind: PasswordString

    • Encrypt: FALSE

      If this fails, the server MUST return NERR_DefaultJoinRequired; otherwise, the result is stored in DomainControllerConnection.

  9. The server invokes the "Performing an LDAP Operation on an ADConnection" task of [MS-ADTS] section 7.6.1.6 with the following parameters:

    • TaskInputADConnection: DomainControllerConnection

    • TaskInputRequestMessage: LDAP SearchRequest message [RFC2251] section 4.5.1 as follows:

      • baseObject: The root of the default naming context (NC)

      • scope: wholeSubtree

      • filter: ObjectClass=OrganizationalUnit

      • attributes: AllowedChildClassesEffective

      • derefAliases: neverDerefAliases

      • typesOnly: FALSE

    • TaskOutputResultMessages: LDAPResultMessages

  10. The server MUST process the results returned from the DC in LDAPResultMessages. For each entry (SearchResultEntry, [RFC2251] section 4.5.2) returned by the search in LDAPResultMessages, if the AllowedChildClassesEffective attribute contains the value "computer", the server MUST add the DN of that entry to the results to be returned in OUs as a NULL-terminated string, and increment the value in OUCount.

  11. The server invokes LDAP Unbind (section 3.2.4.29.3) with ADConnectionToUnbind set to DomainControllerConnection.

  12. 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.