Understanding the Active Directory RPC APIs
Before SDS.AD, Active Directory programmers were forced into different camps based on the programming language they used. The original design of the directory services APIs had some features of Active Directory available via LDAP, and others were available only by RPC calls. The LDAP features were (for the most part) available to the higher-level languages because they could use ADSI with the LDAP provider. However, the RPC calls were designed for C++ users only. While some of these APIs got explicit ADSI wrappers (for example, DsCrackNames and IADsNameTranslate), many did not.
As such, the high-level languages were second-class citizens. This tradition continued with .NET Framework version 1.x, as SDS really just wrapped ADSI functionality. While we had the ability to access the other APIs via P/Invoke, they were not packaged neatly for us.
The key design challenge for the SDS.AD namespace was to find a way to marry the LDAP and RPC functionality together into a cohesive design. In our opinion, this design is quite successful and is leaps and bounds better than what we had before or what we would likely have cobbled together on our own with a bunch of P/Invoke statements.
The purpose of this section is to briefly overview some of the other Active Directory RPC APIs to get a better feel for what they do. Table 9.1 breaks down most of them and categorizes them by use. We also show which ones SDS.AD uses directly.
|
Purpose |
RPC function |
Wrapped in SDS.AD |
|---|---|---|
|
These APIs are used to access the Locator services. With them, we can find the current domain, forest, global catalog servers, and all domain controllers. All of these methods allow anonymous credentials. |
DsGetDcName |
Yes |
|
DsGetDcOpen |
Yes |
|
|
DsGetDcNext |
Yes |
|
|
DsGetSiteName |
No |
|
|
DsGetDcSiteCoverage |
No |
|
|
DsGetDcClose |
Yes |
|
|
NetApiBufferFree |
Yes |
|
|
In order to use a number of the other Ds* APIs, we must have a handle to an RPC session with a domain controller. These APIs are used to bind to the directory and obtain the handle necessary for further Ds* API calls. |
DsBind |
No |
|
DsBindWithCred |
Yes |
|
|
DsBindWithSpn |
No |
|
|
DsBindWithSpnEx |
No |
|
|
DsMakePasswordCredentials |
Yes |
|
|
DsUnBind |
Yes |
|
|
DsFreePasswordCredentials |
Yes |
|
|
Once we have an established RPC session, we can use the handle we obtained to query for more information or to use utility functions. These methods use an authenticated session and return information that would be difficult to obtain without fairly complicated directory searches. |
DsGetDomainControllerInfo |
Yes |
|
DsListDomainsInSite |
Yes |
|
|
DsListInfoForServer |
No |
|
|
DsListRoles |
Yes |
|
|
DsListSites |
Yes |
|
|
DsListServersInSite |
No |
|
|
DsListServersForDomainInSite |
No |
|
|
DsCrackNames |
Yes |
|
|
DsFreeDomainControllerInfo |
Yes |
|
|
DsFreeNameResult |
Yes |
As Table 9.1 shows, SDS.AD uses quite a few of these API calls. We would need to wrap each method ourselves in order to achieve similar functionality. Since we know that this is a lot of work, we have created wrappers for a number of the methods listed in Table 9.1 for you and we included them on this book's web site for download.
Useful Shortcuts for Developers
|