ZakiPedio-BridgeHead/docs/mainpage.md

@mainpage BridgeHead

BridgeHead is a C++20 static library implementing the full Active Directory Web Services (ADWS) protocol stack directly over TCP — no WCF, no .NET runtime, no HTTP stack required.

Named after the AD BridgeHead server concept, it gives native C++ code direct access to the same port 9389 interface that PowerShell's Get-ADUser, Get-ADComputer, and related cmdlets use under the hood. Both NTLM and Kerberos authentication are supported on Windows, Linux, and macOS.

---

Protocol stack

Each layer wraps the one below via the bridgehead::transport::IByteStream interface:

AdwsClient     WS-Enumeration + WS-Transfer  [MS-ADDM]
  └── NbfseCodec     .NET Binary Format for SOAP  [MC-NBFSE]
        └── NmfFramer      .NET Message Framing       [MC-NMF]
              └── NnsSession     .NET NegotiateStream      [MS-NNS]
                    └── TcpSocket      raw TCP/IP

The entry point for consumers is bridgehead::adws::AdwsClient.

---

Quick start

Query users

#include "bridgehead/adws/AdwsClient.hpp"

auto client = bridgehead::adws::AdwsClient::EnumerationClient(
    "192.168.1.10",    // DC IP or hostname
    "dc01.corp.local", // DC FQDN
    "CORP",            // NetBIOS domain name
    "Administrator",   // username
    "Passw0rd"         // password
);

auto users = client.Query(
    "(objectClass=user)",
    {"sAMAccountName", "distinguishedName"}
);

for (auto& obj : users)
    std::cout << obj.FirstValue("sAMAccountName") << '\n';

Stream large result sets

client.Enumerate(
    "(objectClass=computer)",
    {"dNSHostName", "operatingSystem"},
    "",  // empty = domain root base DN
    [](const bridgehead::adws::LdapObject& obj) {
        std::cout << obj.FirstValue("dNSHostName") << '\n';
        return true;  // return false to stop early (sends wsen:Release)
    }
);

Modify an attribute

auto rc = bridgehead::adws::AdwsClient::ResourceClient(
    "192.168.1.10", "dc01.corp.local", "CORP", "Administrator", "Passw0rd");

rc.Put("CN=Alice,OU=Users,DC=corp,DC=local", {
    {"description", {"managed by bridgehead"}},
});

---

Integration

CMake subdirectory (no install needed):

add_subdirectory(bridgehead)
target_link_libraries(my_target PRIVATE bridgehead::bridgehead)

Installed package (find_package):

cmake --install build --prefix /usr/local

find_package(bridgehead REQUIRED)
target_link_libraries(my_target PRIVATE bridgehead::bridgehead)

pugixml, ws2_32, and secur32 (Windows) / gssapi_krb5 (Linux/macOS) are pulled in transitively.

---

Platform support

Platform	Auth backend	Status
Windows	SSPI (secur32.dll)	Working — NTLM and Kerberos
Linux / macOS	GSSAPI (libgssapi_krb5)	Compiled; not yet integration-tested

---

Key classes

Class	Header	Purpose
bridgehead::adws::AdwsClient	bridgehead/adws/AdwsClient.hpp	Single-connection synchronous ADWS client
bridgehead::adws::AdwsClientAsync	bridgehead/adws/AdwsClientAsync.hpp	std::future-based async wrapper
bridgehead::adws::AdwsClientPool	bridgehead/adws/AdwsClientPool.hpp	Thread-safe connection pool
bridgehead::adws::SecurityDescriptor	bridgehead/adws/SecurityDescriptor.hpp	nTSecurityDescriptor binary decoder

---

Protocol references

• [MS-ADDM] — Active Directory Web Services: Data Model and Common Elements
• [MS-NNS] — .NET NegotiateStream Protocol
• [MC-NMF] — .NET Message Framing
• [MC-NBFSE] — .NET Binary Format: SOAP Extension
• [MS-DTYP] — Windows Data Types (SECURITY_DESCRIPTOR, ACL, ACE, SID, GUID)
• [MS-ADTS] — Active Directory Technical Specification (LDAP filters / attributes)