netlogon: public API for NTLM pass-through (implementation to follow)

/*******************************************************************************

Copyright (c) 2026, Jan Koester jan.koester@gmx.net

All rights reserved.

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright

      notice, this list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above copyright

      notice, this list of conditions and the following disclaimer in the

      documentation and/or other materials provided with the distribution.

    * Neither the name of the <organization> nor the

      names of its contributors may be used to endorse or promote products

      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND

ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY

DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES

(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;

LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*******************************************************************************/

/* A NETLOGON client over a secure channel (netsec schannel), just enough to

 * have a domain controller check the NTLM response of a domain user:

 * NetrLogonSamLogonEx with a network-logon info, as a domain member does for

 * SMB logins that don't use Kerberos. adconnectd uses it for ksmbd/sharedd

 * (see <sharedd/api.h>, the kernel's KSMBD_EVENT_NTLM_AUTHEN_REQUEST).

 *

 * The transport is ncacn_ip_tcp straight to the DC's RPC port (the computer

 * account's keys come from the join secret). The DCE/RPC, NDR and the netsec

 * AES sign+seal are built here on libnetplus (AES, HMAC-SHA256); see

 * research/netlogon for the prototype this grew from and the exact wire

 * details. Everything throws std::runtime_error on a protocol or I/O error;

 * an authentication result (good or bad password) comes back as a status. */

#pragma once

#include <cstdint>

#include <string>

namespace adconnect {

struct NetlogonConfig {

    std::string dcHost;            /* the domain controller to reach */

    int rpcPort = 0;               /* its RPC port (ncacn_ip_tcp); 0 is invalid */

    std::string domainNetbios;     /* e.g. "EXAMPLE" (short domain) */

    std::string computer;          /* our computer account's short name, e.g. "FENRIR1" */

    std::string machineAccount;    /* "FENRIR1$" */

    std::string machinePassword;   /* the join secret (its MD4 is the NT hash) */

    int timeoutMs = 10000;

};

struct NtlmPassthrough {

    std::string domain;            /* the logon domain the client named */

    std::string account;           /* the user */

    std::string workstation;       /* the client's workstation name (may be empty) */

    std::string serverChallenge;   /* 8 bytes: the challenge the SMB server gave the client */

    std::string ntResponse;        /* the client's NT response (NTLMv2: >= 24 bytes) */

    std::string lmResponse;        /* the client's LM response (may be empty) */

};

struct NtlmResult {

    uint32_t status = 0xC0000001;  /* NT_STATUS (0 == ok); default STATUS_UNSUCCESSFUL */

    std::string sessionKey;        /* 16-byte user session base key when status == 0 */

    std::string accountName;       /* the canonical account name from the DC */

    uint32_t rid = 0;

};

/* One SamLogonEx network logon against the DC in cfg. A fresh secure channel

 * is set up for the call (ReqChallenge/Authenticate3 then netsec schannel).

 * Throws std::runtime_error if the DC can't be reached or the protocol fails;

 * a refused password is NtlmResult.status != 0, not an exception. */

NtlmResult samLogonNetwork(const NetlogonConfig &cfg, const NtlmPassthrough &in);

} // namespace adconnect