3.1.5 Message Processing Events and Sequencing Rules
This section specifies the methods of the protocol along with their processing.
The return value space of all methods is the NTSTATUS type, specified in [MS-ERREF] section 2.3. Unless specifically called out, error codes are returned to the client of the protocol and are not handled by any special processing at the client; therefore, the exact error code is implementation-specific. Cases in which the client might handle a specific error code are called out. The set of such error codes are found in section 2.2.1.15.
Methods in RPC Opnum Order
|
Method |
Description |
|---|---|
|
Returns a handle to a server object. Opnum: 0 |
|
|
Closes any context handle obtained from this RPC interface. Opnum: 1 |
|
|
Sets the access control on a server, domain, user, group, or alias object. Opnum: 2 |
|
|
Queries the access control on a server, domain, user, group, or alias object. Opnum: 3 |
|
|
Opnum4NotUsedOnWire |
Reserved for local use. Opnum: 4 |
|
Obtains the SID of a domain object. Opnum: 5 |
|
|
Obtains a listing of all domains hosted by the server side. Opnum: 6 |
|
|
Obtains a handle to a domain object. Opnum: 7 |
|
|
Obtains attributes from a domain object. Opnum: 8 |
|
|
Updates attributes on a domain object. Opnum: 9 |
|
|
Creates a group object within a domain. Opnum: 10 |
|
|
Enumerates all groups. Opnum: 11 |
|
|
Creates a user. Opnum: 12 |
|
|
Enumerates all users. Opnum: 13 |
|
|
Creates an alias. Opnum: 14 |
|
|
Enumerates all aliases. Opnum: 15 |
|
|
Obtains the union of all aliases of which a given set of SIDs is a member. Opnum: 16 |
|
|
Translates a set of account names into a set of RIDs. Opnum: 17 |
|
|
Translates a set of RIDs into account names. Opnum: 18 |
|
|
Obtains a handle to a group. Opnum: 19 |
|
|
Obtains attributes from a group object. Opnum: 20 |
|
|
Updates attributes on a group object. Opnum: 21 |
|
|
Adds a member to a group. Opnum: 22 |
|
|
Removes a group object. Opnum: 23 |
|
|
Removes a member from a group. Opnum: 24 |
|
|
Reads the members of a group. Opnum: 25 |
|
|
Sets the attributes of a member relationship. Opnum: 26 |
|
|
Obtains a handle to an alias. Opnum: 27 |
|
|
Obtains attributes from an alias object. Opnum: 28 |
|
|
Updates attributes on an alias object. Opnum: 29 |
|
|
Removes an alias object. Opnum: 30 |
|
|
Adds a member to an alias. Opnum: 31 |
|
|
Removes a member from an alias. Opnum: 32 |
|
|
Obtains the membership list of an alias. Opnum: 33 |
|
|
Obtains a handle to a user. Opnum: 34 |
|
|
Removes a user object. Opnum: 35 |
|
|
Obtains attributes from a user object. Opnum: 36 |
|
|
Updates attributes on a user object. Opnum: 37 |
|
|
Changes the password of a user object. Opnum: 38 |
|
|
Obtains a list of groups of which a user is a member. Opnum: 39 |
|
|
Obtains a list of accounts in name-sorted order. Opnum: 40 |
|
|
Obtains an index into an account-name–sorted list of accounts. Opnum: 41 |
|
|
Opnum42NotUsedOnWire |
Reserved for local use. Opnum: 42 |
|
Opnum43NotUsedOnWire |
Reserved for local use. Opnum: 43 |
|
Obtains select password policy information. Opnum: 44 |
|
|
Removes a member from all aliases. Opnum: 45 |
|
|
Obtains attributes from a domain object. Opnum: 46 |
|
|
Obtains attributes from a user object. Opnum: 47 |
|
|
Obtains a list of accounts in name-sorted order. Opnum: 48 |
|
|
Obtains an index into an account-name–sorted list of accounts. Opnum: 49 |
|
|
Creates a user. Opnum: 50 |
|
|
Obtains a list of accounts in name-sorted order. Opnum: 51 |
|
|
Adds multiple members to an alias. Opnum: 52 |
|
|
Removes multiple members from an alias. Opnum: 53 |
|
|
Changes a user's password. Opnum: 54 |
|
|
Changes a user account's password. Opnum: 55 |
|
|
Obtains select password policy information. Opnum: 56 |
|
|
Obtains a handle to a server object (3). Opnum: 57 |
|
|
Updates attributes on a user object. Opnum: 58 |
|
|
Opnum59NotUsedOnWire |
Reserved for local use. Opnum: 59 |
|
Opnum60NotUsedOnWire |
Reserved for local use. Opnum: 60 |
|
Opnum61NotUsedOnWire |
Reserved for local use. Opnum: 61 |
|
Obtains a handle to a server object. Opnum: 62 |
|
|
Opnum63NotUsedOnWire |
Reserved for local use. Opnum: 63 |
|
Obtains a handle to a server object. Opnum: 64 |
|
|
Obtains the SID of an account. Opnum: 65 |
|
|
Sets a local recovery password. Opnum: 66 |
|
|
Validates an application password against the locally stored policy. Opnum: 67 |
|
|
Opnum68NotUsedOnWire |
Reserved for local use. Opnum: 68 |
|
Opnum69NotUsedOnWire |
Reserved for local use. Opnum: 69 |
|
Opnum70NotUsedOnWire |
Reserved for local use. Opnum 70 |
|
Opnum71NotUsedOnWire |
Reserved for local use. Opnum 71 |
|
Opnum72NotUsedOnWire |
Reserved for local use. Opnum 72 |
|
SamrUnicodeChangePasswordUser4 |
Changes a user account password. Opnum 73 |
|
SamrValidateComputerAccountReuseAttempt |
Validates whether clients can re-use a computer account. Opnum 74 |
|
Opnum75NotUsedOnWire |
Reserved for local use. Opnum 75 |
|
Opnum76NotUsedOnWire |
Reserved for local use. Opnum 76 |
|
SamrAccountIsDelegatedManagedServiceAccount |
Verifies whether a specified account is a Delegated Managed Service Account and whether the calling context is authorized to retrieve the managed password of the account. Opnum 77 |
In the preceding table, the phrase "Reserved for local use" means that the client MUST NOT send the opnum, and the server behavior is undefined<43> because it does not affect interoperability.
All methods MUST NOT throw exceptions.
The SAM Remote Protocol (Client-to-Server) recognizes five types of handles: Server, Domain, Group, Alias, and User. A handle of each type can be obtained only by calling one of a well-defined set of methods. These handles are listed in the following table.
|
Handle type |
Methods that return this type of handle |
|---|---|
|
Server |
SamrConnect SamrConnect2 SamrConnect4 SamrConnect5 |
|
Domain |
SamrOpenDomain |
|
Group |
SamrOpenGroup |
|
Alias |
SamrOpenAlias |
|
User |
SamrOpenUser |
For example, to obtain any context handle to the server, one of the following methods MUST be called: SamrConnect, SamrConnect2, SamrConnect4, or SamrConnect5. With the ServerHandle parameter returned from these methods, it is possible to obtain other context handles and call any associated methods on the handle. See section 4.1 for an example.
The server MUST keep track of all handles of each type that every caller opens, from the moment of creation until the handle has been closed (by calling SamrCloseHandle, SamrDeleteGroup, SamrDeleteAlias, or SamrDeleteUser) or until the client disconnects. The object referenced by a handle can be edited, queried, deleted, or closed for as long as the handle is open, but not before or after this state.
The RPC protocol provides a mechanism to clean up any resources related to a context handle if a client that is holding the context handle exits, dies, disconnects, or reboots. An implementation of this protocol SHOULD use this functionality, as specified in [C706] section 5.1.6, Context Handle Rundown.
Note Except for the methods listed in the preceding table, all other methods listed in this section can be called in any sequence to perform operations on the referenced object as long as its handle is open.
Note The following methods do not require a context handle and can be called directly; they also do not return any context handle:
SamrGetDomainPasswordInformation
SamrSetDSRMPassword
SamrValidatePassword
SamrOemChangePasswordUser2
SamrUnicodeChangePasswordUser2
Note A user account MUST be enabled by clearing the UF_ACCOUNTDISABLE bit from the userAccountControl attribute before that account will be able to authenticate, as specified in [MS-KILE] section 3.3.5.7.1.