spnego.h

Go to the documentation of this file.

// Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file spnego.h
 * @brief SPNEGO (RFC 4178) GSS-API wrapping of the NTLMSSP tokens for the SMB2 client
 *        (DETWS_ENABLE_SMB).
 *
 * SMB2 SESSION_SETUP carries the NTLM handshake tokens inside a SPNEGO negotiation token. This is
 * the minimal ASN.1 DER layer that a client needs:
 *  - the first client token is a GSS-API InitialContextToken: `[APPLICATION 0] { SPNEGO-OID,
 *    NegTokenInit [0] { mechTypes [0] { NTLM-OID }, mechToken [2] OCTET STRING(NTLMSSP NEGOTIATE) } }`;
 *  - the server replies with a bare NegTokenResp `[1] { ..., responseToken [2] OCTET STRING(NTLMSSP
 *    CHALLENGE) }`, from which the client extracts the CHALLENGE;
 *  - the client's second token is a NegTokenResp `[1] { responseToken [2] OCTET STRING(NTLMSSP
 *    AUTHENTICATE) }`.
 *
 * Pure DER, zero heap, definite-length only. The NTLM tokens come from ntlmssp.h.
 *
 * @author  Douglas Quigg (dstroy0)
 * @date    2026
 */
 
#ifndef DETERMINISTICESPASYNCWEBSERVER_SPNEGO_H
#define DETERMINISTICESPASYNCWEBSERVER_SPNEGO_H
 
#include "ServerConfig.h"
 
#if DETWS_ENABLE_SMB
 
#include <stddef.h>
#include <stdint.h>
 
/**
 * @brief Wrap an NTLMSSP NEGOTIATE token in a SPNEGO GSS-API InitialContextToken (the first
 *        SESSION_SETUP security buffer).
 * @return the token length written to @p out, or 0 on overflow.
 */
size_t spnego_wrap_negotiate(const uint8_t *ntlm, size_t ntlm_len, uint8_t *out, size_t cap);
 
/**
 * @brief Extract the responseToken (the NTLMSSP CHALLENGE) from a server NegTokenResp.
 * @param resp_token receives a pointer INTO @p blob; @p resp_len its length.
 * @return true if a `[2]` responseToken OCTET STRING was found and is within bounds.
 */
bool spnego_parse_response(const uint8_t *blob, size_t len, const uint8_t **resp_token, size_t *resp_len);
 
/**
 * @brief Wrap an NTLMSSP AUTHENTICATE token in a SPNEGO NegTokenResp (the second SESSION_SETUP
 *        security buffer).
 * @return the token length written to @p out, or 0 on overflow.
 */
size_t spnego_wrap_authenticate(const uint8_t *ntlm, size_t ntlm_len, uint8_t *out, size_t cap);
 
#endif // DETWS_ENABLE_SMB
 
#endif // DETERMINISTICESPASYNCWEBSERVER_SPNEGO_H