From: Amos Jeffries Date: Mon, 31 May 2010 12:20:10 +0000 (+1200) Subject: Document libntlm.la library API X-Git-Tag: SQUID_3_2_0_1~171 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=dac46b89c26f7c81c690d7f3400dd4094564eaef;p=thirdparty%2Fsquid.git Document libntlm.la library API --- diff --git a/include/ntlmauth.h b/include/ntlmauth.h index 5701c4ffd5..5cf479ba49 100644 --- a/include/ntlmauth.h +++ b/include/ntlmauth.h @@ -53,11 +53,9 @@ #ifndef SQUID_NTLMAUTH_H #define SQUID_NTLMAUTH_H -/* int*_t */ #include "config.h" -/* All of this cruft is little endian */ -#include "squid_endian.h" +/* NP: All of this cruft is little endian */ /* Used internally. Microsoft seems to think this is right, I believe them. * Right. */ @@ -99,60 +97,58 @@ #define REQUEST_NON_NT_SESSION_KEY 0x400000 -/* String header. String data resides at the end of the request */ +/** String header. String data resides at the end of the request */ typedef struct _strhdr { - int16_t len; /* Length in bytes */ - int16_t maxlen; /* Allocated space in bytes */ - int32_t offset; /* Offset from start of request */ + int16_t len; /**< Length in bytes */ + int16_t maxlen; /**< Allocated space in bytes */ + int32_t offset; /**< Offset from start of request */ } strhdr; -/* We use this to keep data/lenght couples. Only used internally. */ +/** We use this to keep data/lenght couples. Only used internally. */ typedef struct _lstring { - int32_t l; /* length, -1 if empty */ - char *str; /* the string. NULL if not initialized */ + int32_t l; /**< length, -1 if empty */ + char *str; /**< the string. NULL if not initialized */ } lstring; -/* This is an header common to all signatures, it's used to discriminate - * among the different signature types. */ +/** This is an header common to all signatures, it's used to discriminate + * among the different signature types. + */ typedef struct _ntlmhdr { - char signature[8]; /* "NTLMSSP" */ - int32_t type; /* One of the NTLM_* types above. */ + char signature[8]; /**< "NTLMSSP" */ + int32_t type; /**< One of the NTLM_* types above. */ } ntlmhdr; -/* Negotiation request sent by client */ +/** Negotiation request sent by client */ typedef struct _ntlm_negotiate { - char signature[8]; /* "NTLMSSP" */ - int32_t type; /* LSWAP(0x1) */ - u_int32_t flags; /* Request flags */ - strhdr domain; /* Domain we wish to authenticate in */ - strhdr workstation; /* Client workstation name */ - char payload[256]; /* String data */ + ntlmhdr hdr; /**< "NTLMSSP" , LSWAP(0x1) */ + u_int32_t flags; /**< Request flags */ + strhdr domain; /**< Domain we wish to authenticate in */ + strhdr workstation; /**< Client workstation name */ + char payload[256]; /**< String data */ } ntlm_negotiate; -/* Challenge request sent by server. */ +/** Challenge request sent by server. */ typedef struct _ntlm_challenge { - char signature[8]; /* "NTLMSSP" */ - int32_t type; /* LSWAP(0x2) */ - strhdr target; /* Authentication target (domain/server ...) */ - u_int32_t flags; /* Request flags */ - u_char challenge[NONCE_LEN]; /* Challenge string */ - u_int32_t context_low; /* LS part of the server context handle */ - u_int32_t context_high; /* MS part of the server context handle */ - char payload[256]; /* String data */ + ntlmhdr hdr; /**< "NTLMSSP" , LSWAP(0x2) */ + strhdr target; /**< Authentication target (domain/server ...) */ + u_int32_t flags; /**< Request flags */ + u_char challenge[NONCE_LEN]; /**< Challenge string */ + u_int32_t context_low; /**< LS part of the server context handle */ + u_int32_t context_high; /**< MS part of the server context handle */ + char payload[256]; /**< String data */ } ntlm_challenge; -/* Authentication request sent by client in response to challenge */ +/** Authentication request sent by client in response to challenge */ typedef struct _ntlm_authenticate { - char signature[8]; /* "NTLMSSP" */ - int32_t type; /* LSWAP(0x3) */ - strhdr lmresponse; /* LANMAN challenge response */ - strhdr ntresponse; /* NT challenge response */ - strhdr domain; /* Domain to authenticate against */ - strhdr user; /* Username */ - strhdr workstation; /* Workstation name */ - strhdr sessionkey; /* Session key for server's use */ - int32_t flags; /* Request flags */ - char payload[256 * 6]; /* String data */ + ntlmhdr hdr; /**< "NTLMSSP" , LSWAP(0x3) */ + strhdr lmresponse; /**< LANMAN challenge response */ + strhdr ntresponse; /**< NT challenge response */ + strhdr domain; /**< Domain to authenticate against */ + strhdr user; /**< Username */ + strhdr workstation; /**< Workstation name */ + strhdr sessionkey; /**< Session key for server's use */ + int32_t flags; /**< Request flags */ + char payload[256 * 6]; /**< String data */ } ntlm_authenticate; const char *ntlm_make_challenge(char *domain, char *domain_controller, diff --git a/lib/ntlmauth.c b/lib/ntlmauth.c index 8eaf1e5fc4..82afd1ab56 100644 --- a/lib/ntlmauth.c +++ b/lib/ntlmauth.c @@ -31,11 +31,10 @@ #endif #include "ntlmauth.h" -#include "squid_endian.h" #include "util.h" /* for base64-related stuff */ #if UNUSED_CODE -/* Dumps NTLM flags to standard error for debugging purposes */ +/** Dumps NTLM flags to standard error for debugging purposes */ void ntlm_dump_ntlmssp_flags(u_int32_t flags) { @@ -61,16 +60,16 @@ ntlm_dump_ntlmssp_flags(u_int32_t flags) (flags & REQUEST_NON_NT_SESSION_KEY ? "Req_nonnt_sesskey " : "") ); } - #endif #define lstring_zero(s) s.str=NULL; s.l=-1; -/* fetches a string from the authentication packet. +/** + * Fetches a string from the authentication packet. * The lstring data-part points to inside the packet itself. * It's up to the user to memcpy() that if the value needs to - * be used in any way that requires a tailing \0. (he can check whether the - * value is there though, in that case lstring.length==-1). + * be used in any way that requires a tailing \0. (can check whether the + * value is there though, in that case lstring.length == -1). */ lstring ntlm_fetch_string(char *packet, int32_t length, strhdr * str) @@ -95,7 +94,8 @@ ntlm_fetch_string(char *packet, int32_t length, strhdr * str) return rv; } -/* Adds something to the payload. The caller must guarrantee that +/** + * Adds something to the payload. The caller must guarrantee that * there is enough space in the payload string to accommodate the * added value. * payload_length and hdr will be modified as a side-effect. @@ -117,9 +117,10 @@ ntlm_add_to_payload(char *payload, int *payload_length, } -/* prepares a base64-encode challenge packet to be sent to the client - * note: domain should be upper_case - * note: the storage type for the returned value depends on +/** + * Prepares a base64-encode challenge packet to be sent to the client + * \note domain should be upper_case + * \note the storage type for the returned value depends on * base64_encode_bin. Currently this means static storage. */ const char * @@ -130,8 +131,8 @@ ntlm_make_challenge(char *domain, char *domain_controller, int pl = 0; const char *encoded; memset(&ch, 0, sizeof(ntlm_challenge)); /* reset */ - memcpy(ch.signature, "NTLMSSP", 8); /* set the signature */ - ch.type = htole32(NTLM_CHALLENGE); /* this is a challenge */ + memcpy(ch.hdr.signature, "NTLMSSP", 8); /* set the signature */ + ch.hdr.type = htole32(NTLM_CHALLENGE); /* this is a challenge */ ntlm_add_to_payload(ch.payload, &pl, &ch.target, domain, strlen(domain), NTLM_CHALLENGE_HEADER_OFFSET); ch.flags = htole32(